ScreenHandle (install4j API)
Description: declaration: package: com.install4j.api.test.ui, interface: ScreenHandle

# Interface ScreenHandle

All Superinterfaces:
  `UiContainer`

public interface ScreenHandle extends UiContainer
The currently active wizard screen. Adds install4j form-component access by id and the wizard navigation methods on top of the generic widget lookup from `UiContainer`.

Every form-component accessor comes in two flavors: a single-arg form that takes the configured form-component id, and a no-arg form that returns the unique handle of that type on this screen. The no-arg form throws `FormComponentNotFoundException` if the screen contains zero matching form component or `FormComponentNotUniqueException` if more than one matching form components were found.

Reach this handle via `Session.currentScreen()`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `ButtonHandle`
  `button()`
  `ButtonHandle`
  `button(String id)`
  Handle for the "Button" form component with the given id.
  `void`
  `cancel()`
  Press the Cancel button.
  `void`
  `cancel(Runnable handler)`
  Press Cancel, then run `handler` (typically catching the "Are you sure?" dialog).
  `CheckBoxHandle`
  `checkBox()`
  `CheckBoxHandle`
  `checkBox(String id)`
  Handle for the "Check box" form component with the given id.
  `ComboBoxHandle`
  `comboBox()`
  `ComboBoxHandle`
  `comboBox(String id)`
  Handle for the "Combo box" form component with the given id.
  `ComponentSelectorHandle`
  `componentSelector()`
  `ComponentSelectorHandle`
  `componentSelector(String id)`
  Handle for the "Installation components selector" form component with the given id.
  `DarkModeSwitcherHandle`
  `darkModeSwitcher()`
  `DarkModeSwitcherHandle`
  `darkModeSwitcher(String id)`
  Handle for the "Dark mode switcher" form component with the given id.
  `DateSpinnerHandle`
  `dateSpinner()`
  `DateSpinnerHandle`
  `dateSpinner(String id)`
  Handle for the "Spinner of dates" form component with the given id.
  `DateTextFieldHandle`
  `dateTextField()`
  `DateTextFieldHandle`
  `dateTextField(String id)`
  Handle for the "Text field with date format" form component with the given id.
  `DirectoryChooserHandle`
  `directoryChooser()`
  `DirectoryChooserHandle`
  `directoryChooser(String id)`
  Handle for the "Directory chooser" or "Installation directory chooser" form component with the given id.
  `DropdownListHandle`
  `dropdownList()`
  `DropdownListHandle`
  `dropdownList(String id)`
  Handle for the "Drop-down list" form component with the given id.
  `FileAssociationsHandle`
  `fileAssociations()`
  `FileAssociationsHandle`
  `fileAssociations(String id)`
  Handle for the "File associations selector" form component with the given id.
  `FileEditorHandle`
  `fileEditor()`
  `FileEditorHandle`
  `fileEditor(String id)`
  Handle for the "Text file editor" form component with the given id.
  `void`
  `finish()`
  Press the Finish button on a terminal screen.
  `void`
  `finish(Runnable handler)`
  Press Finish, then run `handler` (typically catching a final alert).
  `FormComponentHandle`
  `formComponent(String id)`
  Generic handle over any form component, including user-defined ones.
  `FormFileChooserHandle`
  `formFileChooser()`
  `FormFileChooserHandle`
  `formFileChooser(String id)`
  Handle for the "File chooser" form component with the given id.
  `String`
  `getCancelButtonText()`
  The current label of the Cancel button.
  `List<String>`
  `getFormComponentIds()`
  Every install4j form-component id present on this screen, in document order.
  `String`
  `getId()`
  The configured screen id.
  `String`
  `getNextButtonText()`
  The current label of the Next button.
  `String`
  `getPreviousButtonText()`
  The current label of the Previous button.
  `String`
  `getSubtitle()`
  The screen's subtitle.
  `String`
  `getTitle()`
  The screen's title.
  `boolean`
  `hasFormComponent(String id)`
  Whether this screen carries a form component with the given id.
  `HtmlDisplayHandle`
  `htmlDisplay()`
  `HtmlDisplayHandle`
  `htmlDisplay(String id)`
  Handle for the "HTML or text display" form component with the given id.
  `HyperlinkActionLabelHandle`
  `hyperlinkActionLabel()`
  `HyperlinkActionLabelHandle`
  `hyperlinkActionLabel(String id)`
  Handle for the "Hyperlink action label" form component with the given id.
  `HyperlinkLabelHandle`
  `hyperlinkLabel()`
  `HyperlinkLabelHandle`
  `hyperlinkLabel(String id)`
  Handle for the "Hyperlink URL label" form component with the given id.
  `InstallationScopeChooserHandle`
  `installationScopeChooser()`
  `InstallationScopeChooserHandle`
  `installationScopeChooser(String id)`
  Handle for the "Installation scope chooser" form component with the given id.
  `InstallationTypeSelectorHandle`
  `installationTypeSelector()`
  Handle for the "Installation type" system screen.
  `IntegerTextFieldHandle`
  `integerTextField()`
  `IntegerTextFieldHandle`
  `integerTextField(String id)`
  Handle for the "Text field with integer format" form component with the given id.
  `boolean`
  `isCancelEnabled()`
  Whether the Cancel button is currently enabled.
  `boolean`
  `isNextEnabled()`
  Whether the Next button is currently enabled.
  `boolean`
  `isPreviousEnabled()`
  Whether the Previous button is currently enabled.
  `KeyValuePairHandle`
  `keyValuePair()`
  `KeyValuePairHandle`
  `keyValuePair(String id)`
  Handle for the "Key value pair label" form component with the given id.
  `LabelHandle`
  `label()`
  `LabelHandle`
  `label(String id)`
  Handle for the "Label" form component with the given id.
  `LicenseHandle`
  `license()`
  `LicenseHandle`
  `license(String id)`
  Handle for the "License agreement" form component with the given id.
  `ListHandle`
  `list()`
  `ListHandle`
  `list(String id)`
  Handle for the "List" form component with the given id.
  `ListSpinnerHandle`
  `listSpinner()`
  `ListSpinnerHandle`
  `listSpinner(String id)`
  Handle for the "Spinner of enumerated values" form component with the given id.
  `LogFileViewerHandle`
  `logFileViewer()`
  `LogFileViewerHandle`
  `logFileViewer(String id)`
  Handle for the "Log file viewer" form component with the given id.
  `MaskTextFieldHandle`
  `maskTextField()`
  `MaskTextFieldHandle`
  `maskTextField(String id)`
  Handle for the "Text field with format mask" form component with the given id.
  `MultilineHtmlLabelHandle`
  `multilineHtmlLabel()`
  `MultilineHtmlLabelHandle`
  `multilineHtmlLabel(String id)`
  Handle for the "Multi-line HTML label" form component with the given id.
  `MultilineLabelHandle`
  `multilineLabel()`
  `MultilineLabelHandle`
  `multilineLabel(String id)`
  Handle for the "Multi-line label" form component with the given id.
  `void`
  `nextScreen()`
  Press the Next button and wait for the next screen to activate.
  `void`
  `nextScreen(Runnable handler)`
  Press the Next button, then run `handler` (typically catching a dialog or alert the click triggers), then return without an implicit screen-change wait.
  `NumberSpinnerHandle`
  `numberSpinner()`
  `NumberSpinnerHandle`
  `numberSpinner(String id)`
  Handle for the "Spinner of integer values" form component with the given id.
  `PasswordFieldHandle`
  `passwordField()`
  `PasswordFieldHandle`
  `passwordField(String id)`
  Handle for the "Password field" form component with the given id.
  `void`
  `previousScreen()`
  Press the Previous button and wait for the previous screen to activate.
  `void`
  `previousScreen(Runnable handler)`
  Like `nextScreen(Runnable)` but for Previous.
  `ProgramGroupHandle`
  `programGroup()`
  `ProgramGroupHandle`
  `programGroup(String id)`
  Handle for the "Program group selector" form component with the given id.
  `ProgressHandle`
  `progress()`
  `ProgressHandle`
  `progress(String id)`
  Handle for the "Progress display" form component with the given id.
  `RadioButtonHandle`
  `radioButton()`
  `RadioButtonHandle`
  `radioButton(String id)`
  Handle for the "Single radio button" form component with the given id.
  `RadioButtonsHandle`
  `radioButtons()`
  `RadioButtonsHandle`
  `radioButtons(String id)`
  Handle for the "Radio button group" form component with the given id.
  `SimpleLeadingLabelHandle`
  `simpleLeadingLabel()`
  `SimpleLeadingLabelHandle`
  `simpleLeadingLabel(String id)`
  Handle for the "Leading label" form component with the given id.
  `SliderHandle`
  `slider()`
  `SliderHandle`
  `slider(String id)`
  Handle for the "Slider" form component with the given id.
  `StandardProgramGroupHandle`
  `standardProgramGroup()`
  Handle for the "Create program group" system screen..
  `StreamlinedInstallationChooserHandle`
  `streamlinedInstallationChooser()`
  `StreamlinedInstallationChooserHandle`
  `streamlinedInstallationChooser(String id)`
  Handle for the "Streamlined installation chooser" form component with the given id.
  `TextAreaHandle`
  `textArea()`
  `TextAreaHandle`
  `textArea(String id)`
  Handle for the "Text area" form component with the given id.
  `TextFieldHandle`
  `textField()`
  `TextFieldHandle`
  `textField(String id)`
  Handle for the "Text field" form component with the given id.
  `UpdateScheduleSelectorHandle`
  `updateScheduleSelector()`
  `UpdateScheduleSelectorHandle`
  `updateScheduleSelector(String id)`
  Handle for the "Update schedule selector" form component with the given id.
  `UserSelectorHandle`
  `userSelector()`
  `UserSelectorHandle`
  `userSelector(String id)`
  Handle for the "Windows user selector" form component with the given id.

  ### Methods inherited from interface UiContainer

  `dumpAsString, saveScreenshot`

- ## Method Details

  - ### getId

    @NotNull String getId()
    The configured screen id.

  - ### getTitle

    @NotNull String getTitle()
    The screen's title.

  - ### getSubtitle

    @NotNull String getSubtitle()
    The screen's subtitle.

  - ### getFormComponentIds

    @NotNull List<String> getFormComponentIds()
    Every install4j form-component id present on this screen, in document order.

  - ### hasFormComponent

    boolean hasFormComponent(@NotNull String id)
    Whether this screen carries a form component with the given id.

  - ### formComponent

    @NotNull FormComponentHandle formComponent(@NotNull String id)
    Generic handle over any form component, including user-defined ones.

  - ### textField

    @NotNull TextFieldHandle textField(@NotNull String id)
    Handle for the "Text field" form component with the given id.

  - ### textField

    @NotNull TextFieldHandle textField()

  - ### passwordField

    @NotNull PasswordFieldHandle passwordField(@NotNull String id)
    Handle for the "Password field" form component with the given id.

  - ### passwordField

    @NotNull PasswordFieldHandle passwordField()

  - ### textArea

    @NotNull TextAreaHandle textArea(@NotNull String id)
    Handle for the "Text area" form component with the given id.

  - ### textArea

    @NotNull TextAreaHandle textArea()

  - ### integerTextField

    @NotNull IntegerTextFieldHandle integerTextField(@NotNull String id)
    Handle for the "Text field with integer format" form component with the given id.

  - ### integerTextField

    @NotNull IntegerTextFieldHandle integerTextField()

  - ### maskTextField

    @NotNull MaskTextFieldHandle maskTextField(@NotNull String id)
    Handle for the "Text field with format mask" form component with the given id.

  - ### maskTextField

    @NotNull MaskTextFieldHandle maskTextField()

  - ### dateTextField

    @NotNull DateTextFieldHandle dateTextField(@NotNull String id)
    Handle for the "Text field with date format" form component with the given id.

  - ### dateTextField

    @NotNull DateTextFieldHandle dateTextField()

  - ### radioButton

    @NotNull RadioButtonHandle radioButton(@NotNull String id)
    Handle for the "Single radio button" form component with the given id.

  - ### radioButton

    @NotNull RadioButtonHandle radioButton()

  - ### checkBox

    @NotNull CheckBoxHandle checkBox(@NotNull String id)
    Handle for the "Check box" form component with the given id.

  - ### checkBox

    @NotNull CheckBoxHandle checkBox()

  - ### multilineLabel

    @NotNull MultilineLabelHandle multilineLabel(@NotNull String id)
    Handle for the "Multi-line label" form component with the given id.

  - ### multilineLabel

    @NotNull MultilineLabelHandle multilineLabel()

  - ### multilineHtmlLabel

    @NotNull MultilineHtmlLabelHandle multilineHtmlLabel(@NotNull String id)
    Handle for the "Multi-line HTML label" form component with the given id.

  - ### multilineHtmlLabel

    @NotNull MultilineHtmlLabelHandle multilineHtmlLabel()

  - ### hyperlinkLabel

    @NotNull HyperlinkLabelHandle hyperlinkLabel(@NotNull String id)
    Handle for the "Hyperlink URL label" form component with the given id.

  - ### hyperlinkLabel

    @NotNull HyperlinkLabelHandle hyperlinkLabel()

  - ### hyperlinkActionLabel

    @NotNull HyperlinkActionLabelHandle hyperlinkActionLabel(@NotNull String id)
    Handle for the "Hyperlink action label" form component with the given id.

  - ### hyperlinkActionLabel

    @NotNull HyperlinkActionLabelHandle hyperlinkActionLabel()

  - ### logFileViewer

    @NotNull LogFileViewerHandle logFileViewer(@NotNull String id)
    Handle for the "Log file viewer" form component with the given id.

  - ### logFileViewer

    @NotNull LogFileViewerHandle logFileViewer()

  - ### label

    @NotNull LabelHandle label(@NotNull String id)
    Handle for the "Label" form component with the given id.

  - ### label

    @NotNull LabelHandle label()

  - ### button

    @NotNull ButtonHandle button(@NotNull String id)
    Handle for the "Button" form component with the given id.

  - ### button

    @NotNull ButtonHandle button()

  - ### radioButtons

    @NotNull RadioButtonsHandle radioButtons(@NotNull String id)
    Handle for the "Radio button group" form component with the given id.

  - ### radioButtons

    @NotNull RadioButtonsHandle radioButtons()

  - ### comboBox

    @NotNull ComboBoxHandle comboBox(@NotNull String id)
    Handle for the "Combo box" form component with the given id.

  - ### comboBox

    @NotNull ComboBoxHandle comboBox()

  - ### dropdownList

    @NotNull DropdownListHandle dropdownList(@NotNull String id)
    Handle for the "Drop-down list" form component with the given id.

  - ### dropdownList

    @NotNull DropdownListHandle dropdownList()

  - ### list

    @NotNull ListHandle list(@NotNull String id)
    Handle for the "List" form component with the given id.

  - ### list

    @NotNull ListHandle list()

  - ### numberSpinner

    @NotNull NumberSpinnerHandle numberSpinner(@NotNull String id)
    Handle for the "Spinner of integer values" form component with the given id.

  - ### numberSpinner

    @NotNull NumberSpinnerHandle numberSpinner()

  - ### slider

    @NotNull SliderHandle slider(@NotNull String id)
    Handle for the "Slider" form component with the given id.

  - ### slider

    @NotNull SliderHandle slider()

  - ### listSpinner

    @NotNull ListSpinnerHandle listSpinner(@NotNull String id)
    Handle for the "Spinner of enumerated values" form component with the given id.

  - ### listSpinner

    @NotNull ListSpinnerHandle listSpinner()

  - ### dateSpinner

    @NotNull DateSpinnerHandle dateSpinner(@NotNull String id)
    Handle for the "Spinner of dates" form component with the given id.

  - ### dateSpinner

    @NotNull DateSpinnerHandle dateSpinner()

  - ### license

    @NotNull LicenseHandle license(@NotNull String id)
    Handle for the "License agreement" form component with the given id.

  - ### license

    @NotNull LicenseHandle license()

  - ### directoryChooser

    @NotNull DirectoryChooserHandle directoryChooser(@NotNull String id)
    Handle for the "Directory chooser" or "Installation directory chooser" form component with the given id.

  - ### directoryChooser

    @NotNull DirectoryChooserHandle directoryChooser()

  - ### progress

    @NotNull ProgressHandle progress(@NotNull String id)
    Handle for the "Progress display" form component with the given id.

  - ### progress

    @NotNull ProgressHandle progress()

  - ### installationScopeChooser

    @NotNull InstallationScopeChooserHandle installationScopeChooser(@NotNull String id)
    Handle for the "Installation scope chooser" form component with the given id.

  - ### installationScopeChooser

    @NotNull InstallationScopeChooserHandle installationScopeChooser()

  - ### componentSelector

    @NotNull ComponentSelectorHandle componentSelector(@NotNull String id)
    Handle for the "Installation components selector" form component with the given id.

  - ### componentSelector

    @NotNull ComponentSelectorHandle componentSelector()

  - ### htmlDisplay

    @NotNull HtmlDisplayHandle htmlDisplay(@NotNull String id)
    Handle for the "HTML or text display" form component with the given id.

  - ### htmlDisplay

    @NotNull HtmlDisplayHandle htmlDisplay()

  - ### keyValuePair

    @NotNull KeyValuePairHandle keyValuePair(@NotNull String id)
    Handle for the "Key value pair label" form component with the given id.

  - ### keyValuePair

    @NotNull KeyValuePairHandle keyValuePair()

  - ### formFileChooser

    @NotNull FormFileChooserHandle formFileChooser(@NotNull String id)
    Handle for the "File chooser" form component with the given id. Named `formFileChooser` to disambiguate from `Session.fileChooser()`, which returns the modal `JFileChooser` dialog handle.

  - ### formFileChooser

    @NotNull FormFileChooserHandle formFileChooser()

  - ### programGroup

    @NotNull ProgramGroupHandle programGroup(@NotNull String id)
    Handle for the "Program group selector" form component with the given id.

  - ### programGroup

    @NotNull ProgramGroupHandle programGroup()

  - ### updateScheduleSelector

    @NotNull UpdateScheduleSelectorHandle updateScheduleSelector(@NotNull String id)
    Handle for the "Update schedule selector" form component with the given id.

  - ### updateScheduleSelector

    @NotNull UpdateScheduleSelectorHandle updateScheduleSelector()

  - ### streamlinedInstallationChooser

    @NotNull StreamlinedInstallationChooserHandle streamlinedInstallationChooser(@NotNull String id)
    Handle for the "Streamlined installation chooser" form component with the given id.

  - ### streamlinedInstallationChooser

    @NotNull StreamlinedInstallationChooserHandle streamlinedInstallationChooser()

  - ### darkModeSwitcher

    @NotNull DarkModeSwitcherHandle darkModeSwitcher(@NotNull String id)
    Handle for the "Dark mode switcher" form component with the given id.

  - ### darkModeSwitcher

    @NotNull DarkModeSwitcherHandle darkModeSwitcher()

  - ### fileEditor

    @NotNull FileEditorHandle fileEditor(@NotNull String id)
    Handle for the "Text file editor" form component with the given id.

  - ### fileEditor

    @NotNull FileEditorHandle fileEditor()

  - ### fileAssociations

    @NotNull FileAssociationsHandle fileAssociations(@NotNull String id)
    Handle for the "File associations selector" form component with the given id.

  - ### fileAssociations

    @NotNull FileAssociationsHandle fileAssociations()

  - ### userSelector

    @NotNull UserSelectorHandle userSelector(@NotNull String id)
    Handle for the "Windows user selector" form component with the given id.

  - ### userSelector

    @NotNull UserSelectorHandle userSelector()

  - ### simpleLeadingLabel

    @NotNull SimpleLeadingLabelHandle simpleLeadingLabel(@NotNull String id)
    Handle for the "Leading label" form component with the given id.

  - ### simpleLeadingLabel

    @NotNull SimpleLeadingLabelHandle simpleLeadingLabel()

  - ### installationTypeSelector

    @NotNull InstallationTypeSelectorHandle installationTypeSelector()
    Handle for the "Installation type" system screen.

  - ### standardProgramGroup

    @NotNull StandardProgramGroupHandle standardProgramGroup()
    Handle for the "Create program group" system screen..

  - ### nextScreen

    void nextScreen()
    Press the Next button and wait for the next screen to activate. The common navigation primitive. If the click triggers a dialog or alert (e.g. validation failure, running-process check) instead of advancing, use `nextScreen(Runnable)` to handle it.

  - ### nextScreen

    void nextScreen(@NotNull Runnable handler)
    Press the Next button, then run `handler` (typically catching a dialog or alert the click triggers), then return without an implicit screen-change wait. The caller's next `onScreen(...)` / `waitForScreenChange()` provides any further wait if the wizard does eventually advance.

    Use this for any click whose immediate consequence is something other than navigation: a running-processes dialog, a validation alert, a confirmation prompt.

  - ### previousScreen

    void previousScreen()
    Press the Previous button and wait for the previous screen to activate.

  - ### previousScreen

    void previousScreen(@NotNull Runnable handler)
    Like `nextScreen(Runnable)` but for Previous.

  - ### cancel

    void cancel()
    Press the Cancel button. Does not wait — cancel may either exit the wizard or pop a confirmation dialog. Follow with `awaitExit()` or `onAlert { ... }` as needed.

  - ### cancel

    void cancel(@NotNull Runnable handler)
    Press Cancel, then run `handler` (typically catching the "Are you sure?" dialog).

  - ### finish

    void finish()
    Press the Finish button on a terminal screen. Does not wait — there is no next screen; the wizard tears down. Follow with `awaitExit()` to confirm the installer exited.

  - ### finish

    void finish(@NotNull Runnable handler)
    Press Finish, then run `handler` (typically catching a final alert).

  - ### isNextEnabled

    boolean isNextEnabled()
    Whether the Next button is currently enabled.

  - ### isPreviousEnabled

    boolean isPreviousEnabled()
    Whether the Previous button is currently enabled.

  - ### isCancelEnabled

    boolean isCancelEnabled()
    Whether the Cancel button is currently enabled.

  - ### getNextButtonText

    @NotNull String getNextButtonText()
    The current label of the Next button.

  - ### getPreviousButtonText

    @NotNull String getPreviousButtonText()
    The current label of the Previous button.

  - ### getCancelButtonText

    @NotNull String getCancelButtonText()
    The current label of the Cancel button.