# ScreenHandle

Import: `import com.install4j.api.test.ui.ScreenHandle;`

```java
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`](UiContainer.md).

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`](../exceptions/FormComponentNotFoundException.md) if the screen contains
zero matching form component or [`FormComponentNotUniqueException`](../exceptions/FormComponentNotUniqueException.md)
if more than one matching form components were found.

Reach this handle via [`Session.currentScreen`](../session/Session.md#currentscreen).

## Inherited from

- [UiContainer](UiContainer.md) — 2 methods

## Methods

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

### getId()

```java
String getId()
```

The configured screen id.

### getTitle()

```java
String getTitle()
```

The screen's title.

### getSubtitle()

```java
String getSubtitle()
```

The screen's subtitle.

### getFormComponentIds()

```java
List<String> getFormComponentIds()
```

Every install4j form-component id present on this screen, in document order.

### hasFormComponent(String)

```java
boolean hasFormComponent(String id)
```

Whether this screen carries a form component with the given id.

### formComponent(String)

```java
FormComponentHandle formComponent(String id)
```

Generic handle over any form component, including user-defined ones.

### textField(String)

```java
TextFieldHandle textField(String id)
```

Handle for the "Text field" form component with the given id.

### textField()

```java
TextFieldHandle textField()
```

### passwordField(String)

```java
PasswordFieldHandle passwordField(String id)
```

Handle for the "Password field" form component with the given id.

### passwordField()

```java
PasswordFieldHandle passwordField()
```

### textArea(String)

```java
TextAreaHandle textArea(String id)
```

Handle for the "Text area" form component with the given id.

### textArea()

```java
TextAreaHandle textArea()
```

### integerTextField(String)

```java
IntegerTextFieldHandle integerTextField(String id)
```

Handle for the "Text field with integer format" form component with the given id.

### integerTextField()

```java
IntegerTextFieldHandle integerTextField()
```

### maskTextField(String)

```java
MaskTextFieldHandle maskTextField(String id)
```

Handle for the "Text field with format mask" form component with the given id.

### maskTextField()

```java
MaskTextFieldHandle maskTextField()
```

### dateTextField(String)

```java
DateTextFieldHandle dateTextField(String id)
```

Handle for the "Text field with date format" form component with the given id.

### dateTextField()

```java
DateTextFieldHandle dateTextField()
```

### radioButton(String)

```java
RadioButtonHandle radioButton(String id)
```

Handle for the "Single radio button" form component with the given id.

### radioButton()

```java
RadioButtonHandle radioButton()
```

### checkBox(String)

```java
CheckBoxHandle checkBox(String id)
```

Handle for the "Check box" form component with the given id.

### checkBox()

```java
CheckBoxHandle checkBox()
```

### multilineLabel(String)

```java
MultilineLabelHandle multilineLabel(String id)
```

Handle for the "Multi-line label" form component with the given id.

### multilineLabel()

```java
MultilineLabelHandle multilineLabel()
```

### multilineHtmlLabel(String)

```java
MultilineHtmlLabelHandle multilineHtmlLabel(String id)
```

Handle for the "Multi-line HTML label" form component with the given id.

### multilineHtmlLabel()

```java
MultilineHtmlLabelHandle multilineHtmlLabel()
```

### hyperlinkLabel(String)

```java
HyperlinkLabelHandle hyperlinkLabel(String id)
```

Handle for the "Hyperlink URL label" form component with the given id.

### hyperlinkLabel()

```java
HyperlinkLabelHandle hyperlinkLabel()
```

### hyperlinkActionLabel(String)

```java
HyperlinkActionLabelHandle hyperlinkActionLabel(String id)
```

Handle for the "Hyperlink action label" form component with the given id.

### hyperlinkActionLabel()

```java
HyperlinkActionLabelHandle hyperlinkActionLabel()
```

### logFileViewer(String)

```java
LogFileViewerHandle logFileViewer(String id)
```

Handle for the "Log file viewer" form component with the given id.

### logFileViewer()

```java
LogFileViewerHandle logFileViewer()
```

### label(String)

```java
LabelHandle label(String id)
```

Handle for the "Label" form component with the given id.

### label()

```java
LabelHandle label()
```

### button(String)

```java
ButtonHandle button(String id)
```

Handle for the "Button" form component with the given id.

### button()

```java
ButtonHandle button()
```

### radioButtons(String)

```java
RadioButtonsHandle radioButtons(String id)
```

Handle for the "Radio button group" form component with the given id.

### radioButtons()

```java
RadioButtonsHandle radioButtons()
```

### comboBox(String)

```java
ComboBoxHandle comboBox(String id)
```

Handle for the "Combo box" form component with the given id.

### comboBox()

```java
ComboBoxHandle comboBox()
```

### dropdownList(String)

```java
DropdownListHandle dropdownList(String id)
```

Handle for the "Drop-down list" form component with the given id.

### dropdownList()

```java
DropdownListHandle dropdownList()
```

### list(String)

```java
ListHandle list(String id)
```

Handle for the "List" form component with the given id.

### list()

```java
ListHandle list()
```

### numberSpinner(String)

```java
NumberSpinnerHandle numberSpinner(String id)
```

Handle for the "Spinner of integer values" form component with the given id.

### numberSpinner()

```java
NumberSpinnerHandle numberSpinner()
```

### slider(String)

```java
SliderHandle slider(String id)
```

Handle for the "Slider" form component with the given id.

### slider()

```java
SliderHandle slider()
```

### listSpinner(String)

```java
ListSpinnerHandle listSpinner(String id)
```

Handle for the "Spinner of enumerated values" form component with the given id.

### listSpinner()

```java
ListSpinnerHandle listSpinner()
```

### dateSpinner(String)

```java
DateSpinnerHandle dateSpinner(String id)
```

Handle for the "Spinner of dates" form component with the given id.

### dateSpinner()

```java
DateSpinnerHandle dateSpinner()
```

### license(String)

```java
LicenseHandle license(String id)
```

Handle for the "License agreement" form component with the given id.

### license()

```java
LicenseHandle license()
```

### directoryChooser(String)

```java
DirectoryChooserHandle directoryChooser(String id)
```

Handle for the "Directory chooser" or "Installation directory chooser" form component
with the given id.

### directoryChooser()

```java
DirectoryChooserHandle directoryChooser()
```

### progress(String)

```java
ProgressHandle progress(String id)
```

Handle for the "Progress display" form component with the given id.

### progress()

```java
ProgressHandle progress()
```

### installationScopeChooser(String)

```java
InstallationScopeChooserHandle installationScopeChooser(String id)
```

Handle for the "Installation scope chooser" form component with the given id.

### installationScopeChooser()

```java
InstallationScopeChooserHandle installationScopeChooser()
```

### componentSelector(String)

```java
ComponentSelectorHandle componentSelector(String id)
```

Handle for the "Installation components selector" form component with the given id.

### componentSelector()

```java
ComponentSelectorHandle componentSelector()
```

### htmlDisplay(String)

```java
HtmlDisplayHandle htmlDisplay(String id)
```

Handle for the "HTML or text display" form component with the given id.

### htmlDisplay()

```java
HtmlDisplayHandle htmlDisplay()
```

### keyValuePair(String)

```java
KeyValuePairHandle keyValuePair(String id)
```

Handle for the "Key value pair label" form component with the given id.

### keyValuePair()

```java
KeyValuePairHandle keyValuePair()
```

### formFileChooser(String)

```java
FormFileChooserHandle formFileChooser(String id)
```

Handle for the "File chooser" form component with the given id. Named
`formFileChooser` to disambiguate from [`Session.fileChooser`](../session/Session.md#filechooser),
which returns the modal `javax.swing.JFileChooser` dialog handle.

### formFileChooser()

```java
FormFileChooserHandle formFileChooser()
```

### programGroup(String)

```java
ProgramGroupHandle programGroup(String id)
```

Handle for the "Program group selector" form component with the given id.

### programGroup()

```java
ProgramGroupHandle programGroup()
```

### updateScheduleSelector(String)

```java
UpdateScheduleSelectorHandle updateScheduleSelector(String id)
```

Handle for the "Update schedule selector" form component with the given id.

### updateScheduleSelector()

```java
UpdateScheduleSelectorHandle updateScheduleSelector()
```

### streamlinedInstallationChooser(String)

```java
StreamlinedInstallationChooserHandle streamlinedInstallationChooser(String id)
```

Handle for the "Streamlined installation chooser" form component with the given id.

### streamlinedInstallationChooser()

```java
StreamlinedInstallationChooserHandle streamlinedInstallationChooser()
```

### darkModeSwitcher(String)

```java
DarkModeSwitcherHandle darkModeSwitcher(String id)
```

Handle for the "Dark mode switcher" form component with the given id.

### darkModeSwitcher()

```java
DarkModeSwitcherHandle darkModeSwitcher()
```

### fileEditor(String)

```java
FileEditorHandle fileEditor(String id)
```

Handle for the "Text file editor" form component with the given id.

### fileEditor()

```java
FileEditorHandle fileEditor()
```

### fileAssociations(String)

```java
FileAssociationsHandle fileAssociations(String id)
```

Handle for the "File associations selector" form component with the given id.

### fileAssociations()

```java
FileAssociationsHandle fileAssociations()
```

### userSelector(String)

```java
UserSelectorHandle userSelector(String id)
```

Handle for the "Windows user selector" form component with the given id.

### userSelector()

```java
UserSelectorHandle userSelector()
```

### simpleLeadingLabel(String)

```java
SimpleLeadingLabelHandle simpleLeadingLabel(String id)
```

Handle for the "Leading label" form component with the given id.

### simpleLeadingLabel()

```java
SimpleLeadingLabelHandle simpleLeadingLabel()
```

### installationTypeSelector()

```java
InstallationTypeSelectorHandle installationTypeSelector()
```

Handle for the "Installation type" system screen.

### standardProgramGroup()

```java
StandardProgramGroupHandle standardProgramGroup()
```

Handle for the "Create program group" system screen..

### nextScreen()

```java
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 [`ScreenHandle.nextScreen`](ScreenHandle.md#nextscreen-runnable) to handle it.

### nextScreen(Runnable)

```java
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. 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()

```java
void previousScreen()
```

Press the Previous button and wait for the previous screen to activate.

### previousScreen(Runnable)

```java
void previousScreen(Runnable handler)
```

Like [`ScreenHandle.nextScreen`](ScreenHandle.md#nextscreen-runnable) but for Previous.

### cancel()

```java
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(Runnable)

```java
void cancel(Runnable handler)
```

Press Cancel, then run `handler` (typically catching the "Are you sure?" dialog).

### finish()

```java
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(Runnable)

```java
void finish(Runnable handler)
```

Press Finish, then run `handler` (typically catching a final alert).

### isNextEnabled()

```java
boolean isNextEnabled()
```

Whether the Next button is currently enabled.

### isPreviousEnabled()

```java
boolean isPreviousEnabled()
```

Whether the Previous button is currently enabled.

### isCancelEnabled()

```java
boolean isCancelEnabled()
```

Whether the Cancel button is currently enabled.

### getNextButtonText()

```java
String getNextButtonText()
```

The current label of the Next button.

### getPreviousButtonText()

```java
String getPreviousButtonText()
```

The current label of the Previous button.

### getCancelButtonText()

```java
String getCancelButtonText()
```

The current label of the Cancel button.

