## install4j API documentation

## com.install4j.api.screens
Interface Screen

All Superinterfaces:
  Bean

All Known Subinterfaces:
  InstallerScreen, UninstallerScreen

All Known Implementing Classes:
  AbstractInstallerOrUninstallerScreen, AbstractInstallerScreen, AbstractUninstallerScreen

    public interface Screen

extends Bean

The base interface for all screens. Do not implement this interface directly, only the derived interfaces are functional. It is recommended that you choose one of the derived abstract classes as a super class. The life-cycle of screens is controlled by the framework.

Author:
  ej-technologies GmbH

Method Summary
`void` | `activated()` Called by the framework just after the screen has been activated.
`boolean` | `cancel()` Called when the user clicks the "Cancel" button for this screen.
`javax.swing.JComponent` | `createComponent()` Return the visual component that is displayed for the screen.
`void` | `deactivated()` Called by the framework just after the screen has been deactivated.
`ProgressInterface` | `getProgressInterface(ProgressInterface defaultProgressInterface)` Replace the default prorgess interface for actions with a custom progress interface.
`java.lang.String` | `getSubTitle()` Returns the subtitle of this custom screen which is displayed at the top of the installer wizard just below the title of the screen.
`java.lang.String` | `getTitle()` Returns the title of this custom screen which is displayed at the top of the installer wizard.
`boolean` | `handleConsole(Console console)` Handle the console mode.
`boolean` | `handleUnattended()` Handle the unattended mode.
`boolean` | `hasTitlePanel()` This method is called by the framework to determine if this screen wants a title area or not.
`boolean` | `isCancelVisible()` Returns whether the "Cancel" button is visible or not for this screen.
`boolean` | `isFillHorizontal()` Returns whether this screen wants to grow in the horizontal direction.
`boolean` | `isFillVertical()` Returns whether this screen wants to grow in the vertical direction.
`boolean` | `isHidden()` Returns whether this screen should be hidden.
`boolean` | `isHiddenForNext()` Returns whether this screen should be hidden when the user traverses screens in the forward direction.
`boolean` | `isHiddenForPrevious()` Returns whether this screen should be hidden when the user traverses screens in the backward direction.
`boolean` | `isNextVisible()` Returns whether the "Next" button is visible or not for this screen.
`boolean` | `isPreviousVisible()` Returns whether the "Back" button is visible or not for this screen.
`boolean` | `next()` Called when the user clicks the "Next" button for this screen.
`boolean` | `previous()` Called when the user clicks the "Back" button for this screen.
`void` | `willActivate()` Called by the framework just before the screen is activated.

Method Detail

### createComponent

    javax.swing.JComponent createComponent()

  Return the visual component that is displayed for the screen. This method is only called once, so the result does not have to be cached.

  In console or unattended mode, this method is never called.

  Returns:
    the component

### getTitle

    java.lang.String getTitle()

  Returns the title of this custom screen which is displayed at the top of the installer wizard.

  In console or unattended mode, this method is never called.

  Returns:
    the title.

### getSubTitle

    java.lang.String getSubTitle()

  Returns the subtitle of this custom screen which is displayed at the top of the installer wizard just below the title of the screen.

  In unattended mode, this method is never called. In console mode, the result of this method will be displayed for each screen.

  Returns:
    the title.

### isFillVertical

    boolean isFillVertical()

  Returns whether this screen wants to grow in the vertical direction. If not, the screen will be aligned at the top of the available space and be sized at its preferred vertical size. If, for example, you have a list in your layout that should use as much vertical space as possible, you should return `true` here. In that case you would also want to return `true` in `isFillHorizontal`. If all your components are fixed-size components, return `false`.

  In console or unattended mode, this method is never called.

  Returns:
    `true` or `false`.
  See Also:
    `isFillHorizontal()`

### isFillHorizontal

    boolean isFillHorizontal()

  Returns whether this screen wants to grow in the horizontal direction. If not, the screen will be aligned at the left of the available space and be sized at its preferred horizontal size. If, for example, you have text fields in your layout that should use as much horizontal space as possible, you should return `true` here. If all your components are fixed-size components, return `false`.

  In console or unattended mode, this method is never called.

  Returns:
    `true` or `false`.
  See Also:
    `isFillVertical()`

### isNextVisible

    boolean isNextVisible()

  Returns whether the "Next" button is visible or not for this screen. If you just want to disable the button initially, please override `activate` and invoke `setNextButtonEnabled` in the `WizardContext` that is available from the `Context` in GUI mode.

  In console or unattended mode, this method is never called.

  Returns:
    `true` or `false`. Default is `true`.
  See Also:
    `WizardContext`

### isPreviousVisible

    boolean isPreviousVisible()

  Returns whether the "Back" button is visible or not for this screen. If you just want to disable the button initially, please override `activate` and invoke `setPreviousButtonEnabled` in the `WizardContext` that is available from the `Context` in GUI mode.

  In console or unattended mode, this method is never called.

  Returns:
    `true` or `false`. Default is `true`.
  See Also:
    `WizardContext`

### isCancelVisible

    boolean isCancelVisible()

  Returns whether the "Cancel" button is visible or not for this screen. If you just want to disable the button initially, please override `activate` and invoke `setCancelButtonEnabled` in the `WizardContext` that is available from the `Context` in GUI mode.

  In console or unattended mode, this method is never called.

  Returns:
    `true` or `false`. Default is `true`.
  See Also:
    `WizardContext`

### willActivate

    void willActivate()

  Called by the framework just before the screen is activated. Override this method to perform any special initialization.

  In console or unattended mode, this method is never called.

### activated

    void activated()

  Called by the framework just after the screen has been activated. Override this method to perform any special initialization.

  In console or unattended mode, this method is never called.

### deactivated

    void deactivated()

  Called by the framework just after the screen has been deactivated. Override this method to perform any special cleanup.

  In console or unattended mode, this method is never called.

### next

    boolean next()

  Called when the user clicks the "Next" button for this screen. You can veto the change to the next screen if you return `false`.

  In console or unattended mode, this method is never called.

  Returns:
    whether the screen change is accepted or not.

### previous

    boolean previous()

  Called when the user clicks the "Back" button for this screen. You can veto the change to the previous screen if you return `false`.

  In console or unattended mode, this method is never called.

  Returns:
    whether the screen change is accepted or not.

### cancel

    boolean cancel()

  Called when the user clicks the "Cancel" button for this screen. You can veto the cancel action if you return `false`.

  Returns:
    whether the cancellation is accepted or not.

    In console or unattended mode, this method is never called.

### isHiddenForNext

    boolean isHiddenForNext()

  Returns whether this screen should be hidden when the user traverses screens in the forward direction.

  This method is also called in console or unattended mode.

  Returns:
    `true` or `false`.

### isHiddenForPrevious

    boolean isHiddenForPrevious()

  Returns whether this screen should be hidden when the user traverses screens in the backward direction.

  This method is also called in console or unattended mode.

  Returns:
    `true` or `false`.

### isHidden

    boolean isHidden()

  Returns whether this screen should be hidden. If this method returns `true`, it overrides the results of `isHiddenForNext` and `isHiddenForPrevious`.

  This method is also called in console or unattended mode.

  Returns:
    `true` or `false`.
  See Also:
    `isHiddenForNext()`, `isHiddenForPrevious()`

### handleUnattended

    boolean handleUnattended()

  Handle the unattended mode. This method is called when the screen is traversed in unattended mode. There is no way to interact with the user. This method might be necessary to mirror some behavior from the GUI mode, such as setting installer variables or configuring actions.

  Returns:
    whether the installer or uninstaller can proceed with the next screen or whether the process should be cancelled.

### handleConsole

    boolean handleConsole(Console console)
                          throws UserCanceledException

  Handle the console mode. This method is called when the screen is entered in console mode. You can use the `Console` object to interact with the user and replicate the GUI functionality on the terminal.

  If this screen has a form panel (i.e. `hasFormPanel()` returns `true`), you should call `FormEnvironment.handleConsole` in this method to handle console mode for the contained form components.

  Parameters:
    `console` - the `Console` object
  Returns:
    whether the installer or uninstaller can proceed with the next screen or whether the process should be cancelled.
  Throws:
    `UserCanceledException` - if the user cancels a question or notice. These exceptions are thrown by methods in the `Console` object.
  See Also:
    `FormEnvironment.handleConsole(Console)`

### getProgressInterface

    ProgressInterface getProgressInterface(ProgressInterface defaultProgressInterface)

  Replace the default prorgess interface for actions with a custom progress interface. When associated actions are run for a screen, a default progress interface is passed to them. If your screen has the possibility to show progress information, you can return a different progress interface here. Typically you would only implement methods regarding status and detail messages as well as methods that apply to a progress bar, other methods can be delegated to the default progress interface. This is the strategy emplyed by the "Installation screen" and the customizable "Progress screens".

  Parameters:
    `defaultProgressInterface` - the default progress interface
  Returns:
    the replaced progress interface

### hasTitlePanel

    boolean hasTitlePanel()

  This method is called by the framework to determine if this screen wants a title area or not.

  Returns:
    `true` or `false`.