## install4j API documentation

## com.install4j.api.formcomponents
Class AbstractFormComponent

    java.lang.Object
      com.install4j.api.beans.AbstractBean
          com.install4j.api.formcomponents.AbstractFormComponent

All Implemented Interfaces:
  Bean, FormComponent

    public abstract class AbstractFormComponent

extends AbstractBean
implements FormComponent

Abstract base class for form components. All methods that have a reasonable default answer are overridden in the class. This class saves the context and the form environment that are set by the framework and provides getters for them. In addition the "enabled" and "visible" properties are handled by invoking the corsponding setters on all components in the `ComponentTuple` of the form component.

Author:
  ej-technologies GmbH

Constructor Summary
`AbstractFormComponent()`

Method Summary
`boolean` | `checkCompleted()` This method is called by the framework when the user advances to the next screen in GUI or console mode.
`javax.swing.JComponent` | `createLeftComponent()` Create the leading component to the left of the center component.
`javax.swing.JComponent` | `createRightComponent()` Create the trailing component to the right of the center component.
`void` | `formActivated()` This method is called by the framework just after the containing screen has been activated.
`void` | `formDeactivated()` This method is called by the framework just after the containing screen has been deactivated.
`void` | `formWillActivate()` This method is called by the framework just before the containing screen will be activated.
`java.lang.Object` | `getConfigurationObject()` If the `getConfigurationObjectClass` method returns `null`, this method is not called, otherwise a non-null value of the type returned by `getConfigurationObjectClass` has to be returned by this method.
`java.lang.Class` | `getConfigurationObjectClass()` A form component can expose a well-known configuration object that is passed as a parameter to the "Initialization script" property of every form component.
`Context` | `getContext()` Returns the `Context` that the framework has associated with this form component in `setContext`.
`FormEnvironment` | `getFormEnvironment()` Returns the `FormEnvironment` that the framework has associated with this form component in `setFormEnvironment`.
`protected java.lang.Object` | `getInitValue(java.lang.Object defaultValue, java.lang.String variableName, java.lang.Class valueClass)` Helper method to get an init value.
`boolean` | `handleConsole(Console console)` Handle the console mode.
`boolean` | `handleUnattended()` Handle the unattended mode.
`boolean` | `hasUserInput()` This method is called in situations where the installer must disable all user input.
`void` | `initalize()` This method is called by the framework when the initial state of the component should be evaluated.
`boolean` | `isEnabled()` Returns whether the form component is enabled or not.
`boolean` | `isFillCenterVertical()` Determine how the center component created by `createCenterComponent` should should fill all available vertical space.
`boolean` | `isVisible()` Returns whether the form component is visible or not.
`void` | `migrateIds(java.util.Map oldItToNewId)` This method is only called at design time when a user pastes form components or a screen with form components from the clipboard.
`void` | `requestFocus()` Transfer the focus to this form component.
`void` | `setContext(Context context)` This method is called by the framework to set the `Context` just after the form component has been constructed.
`void` | `setEnabled(boolean enabled)` Sets whether the form component is enabled or not.
`void` | `setFormEnvironment(FormEnvironment formEnvironment)` At runtime, this method is called twice by the framework.
`void` | `setVisible(boolean visible)` Sets whether the form component is visible or not.

Methods inherited from class com.install4j.api.beans.AbstractBean
`replaceVariables, replaceVariables, replaceVariables, replaceVariables`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Methods inherited from interface com.install4j.api.formcomponents.FormComponent
`createCenterComponent, isFillCenterHorizontal`

Constructor Detail

### AbstractFormComponent

    public AbstractFormComponent()

Method Detail

### setContext

    public void setContext(Context context)

  Description copied from interface: `FormComponent`
  This method is called by the framework to set the `Context` just after the form component has been constructed. This is either an `InstallerContext` or an `UninstallerContext`, depending on the whether the form screen is part of an installer or uninstaller.

  Specified by:
    `setContext` in interface `FormComponent`
  Parameters:
    `context` - the context.

### getContext

    public Context getContext()

  Returns the `Context` that the framework has associated with this form component in `setContext`.

  Returns:
    the installer context.

### setFormEnvironment

    public void setFormEnvironment(FormEnvironment formEnvironment)

  Description copied from interface: `FormComponent`
  At runtime, this method is called twice by the framework. Once, to set the `FormEnvironment` just after the screen has been constructed. The `getFormComponents()` method will return an empty array for that instance. Second, after all form components have been instantiated, a new `FormEnvironment` is set whose `getFormComponents()` method returns all form components in the form.

  At design time, this method is called repeatedly and the result of a call to `getFormComponents()` may be different over time.

  Specified by:
    `setFormEnvironment` in interface `FormComponent`
  Parameters:
    `formEnvironment` - the `FormEnvironment`
  See Also:
    `FormEnvironment.getFormComponents()`

### getFormEnvironment

    public FormEnvironment getFormEnvironment()

  Returns the `FormEnvironment` that the framework has associated with this form component in `setFormEnvironment`.

  Returns:
    the installer context.

### isEnabled

    public boolean isEnabled()

  Description copied from interface: `FormComponent`
  Returns whether the form component is enabled or not. This must reflect the value set with `setEnabled`.

  `AbstractFormComponent` provides a default implementation for both `isEnabled` and `setEnabled`.

  Specified by:
    `isEnabled` in interface `FormComponent`
  Returns:
    `true` or `false`.
  See Also:
    `FormComponent.setEnabled(boolean)`

### setEnabled

    public void setEnabled(boolean enabled)

  Description copied from interface: `FormComponent`
  Sets whether the form component is enabled or not. This method is primarily intended for use in the "Initialization script" property in the install4j GUI.

  It can also be used for the case where another form component wants to control the state of this form component. For example the "Check box" form component holds a list of coupled form components that are enabled and disabled with calls to this method.

  `AbstractFormComponent` provides a default implementation that calls `setEnabled` on the component returned by `FormComponent.getConfigurationObject()`, saves the "enabled" flag and returns it in the `isEnabled` method.

  Specified by:
    `setEnabled` in interface `FormComponent`
  Parameters:
    `enabled` - whether to enable this form component or not
  See Also:
    `AbstractFormComponent`, `ComponentTuple`, `FormComponent.isEnabled()`

### setVisible

    public void setVisible(boolean visible)

  Description copied from interface: `FormComponent`
  Sets whether the form component is visible or not. This method is primarily intended for the "Initialization script" property in the install4j GUI.

  It can also be used for the case where another form component wants to control the state of this form component.

  `AbstractFormComponent` provides a default implementation that calls `setVisible` on all components in the `ComponentTuple`, saves the "visible" flag and returns it in the `isVisible` method.

  Specified by:
    `setVisible` in interface `FormComponent`
  Parameters:
    `visible` - whether this form component should be visible or not
  See Also:
    `AbstractFormComponent`, `ComponentTuple`, `FormComponent.isVisible()`

### isVisible

    public boolean isVisible()

  Description copied from interface: `FormComponent`
  Returns whether the form component is visible or not. This must reflect the value set with `setVisible`.

  `AbstractFormComponent` provides a default implementation for both `isVisible` and `setVisible`.

  Specified by:
    `isVisible` in interface `FormComponent`
  Returns:
    `true` or `false`.
  See Also:
    `FormComponent.setVisible(boolean)`

### migrateIds

    public void migrateIds(java.util.Map oldItToNewId)

  Description copied from interface: `FormComponent`
  This method is only called at design time when a user pastes form components or a screen with form components from the clipboard. When form components are pasted, their IDs as returned by `FormEnvironment.getId` change. Form components that keep a list of IDs of other form components should migrate those IDs in this method.

  Specified by:
    `migrateIds` in interface `FormComponent`
  Parameters:
    `oldItToNewId` - a map that maps the old IDs to the new IDs. An ID is of type `java.lang.String`.
  See Also:
    `FormEnvironment.getId(FormComponent)`, `FormEnvironment.getFormComponentById(String)`

### requestFocus

    public void requestFocus()

  Description copied from interface: `FormComponent`
  Transfer the focus to this form component.

  Specified by:
    `requestFocus` in interface `FormComponent`

### hasUserInput

    public boolean hasUserInput()

  Description copied from interface: `FormComponent`
  This method is called in situations where the installer must disable all user input. If your form component takes user input, such as for a check box or a text field, you should return true.

  Specified by:
    `hasUserInput` in interface `FormComponent`
  Returns:
    if the component has user input

### createLeftComponent

    public javax.swing.JComponent createLeftComponent()

  Description copied from interface: `FormComponent`
  Create the leading component to the left of the center component. This component will not grow beyond its preferred horizontal size.

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

  Specified by:
    `createLeftComponent` in interface `FormComponent`
  Returns:
    the leading component or `null` if no leading component should be created.

### isFillCenterVertical

    public boolean isFillCenterVertical()

  Description copied from interface: `FormComponent`
  Determine how the center component created by `createCenterComponent` should should fill all available vertical space. If there are multiple form components on a form that return true for this method, the excess vertical space will be distributed evenly. Note that you can configure the form not to grow vertically in the install4j GUI, so the center component may be displayed with its preferred height in any case.

  Specified by:
    `isFillCenterVertical` in interface `FormComponent`
  Returns:
    `true` or `false`.
  See Also:
    `FormComponent.createCenterComponent()`

### createRightComponent

    public javax.swing.JComponent createRightComponent()

  Description copied from interface: `FormComponent`
  Create the trailing component to the right of the center component. This component will not grow beyond its preferred horizontal size.

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

  Specified by:
    `createRightComponent` in interface `FormComponent`
  Returns:
    the trailing component or `null` if no trailing component should be created.

### getConfigurationObject

    public java.lang.Object getConfigurationObject()

  Description copied from interface: `FormComponent`
  If the `getConfigurationObjectClass` method returns `null`, this method is not called, otherwise a non-null value of the type returned by `getConfigurationObjectClass` has to be returned by this method.

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

  Specified by:
    `getConfigurationObject` in interface `FormComponent`
  Returns:
    the configuration object or `null` if `getConfigurationObjectClass` returns null as well.
  See Also:
    `FormComponent.getConfigurationObjectClass()`

### getConfigurationObjectClass

    public java.lang.Class getConfigurationObjectClass()

  Description copied from interface: `FormComponent`
  A form component can expose a well-known configuration object that is passed as a parameter to the "Initialization script" property of every form component. Typically, you expose the main component contained in this form component, such as a `JCheckBox` or a `JTextField`. If you return a non-null value in the method, the `getConfigurationObject` method must return an object of that class.

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

  Specified by:
    `getConfigurationObjectClass` in interface `FormComponent`
  Returns:
    the class of the configuration object or `null` if no configuration object should be exposed.
  See Also:
    `FormComponent.getConfigurationObject()`

### checkCompleted

    public boolean checkCompleted()

  Description copied from interface: `FormComponent`
  This method is called by the framework when the user advances to the next screen in GUI or console mode. If your form component expects user-input, this is the place to save it to an installer variable. You can veto the screen change by returning `false` in this method.

  Specified by:
    `checkCompleted` in interface `FormComponent`
  Returns:
    whether to allow advancing to the next screen or not.
  See Also:
    `Context.setVariable(String, Object)`

### initalize

    public void initalize()

  Description copied from interface: `FormComponent`
  This method is called by the framework when the initial state of the component should be evaluated. This happens when the user first enters the screen that contains the form component. Whether repeated entries to this screen will cause this method to be called depends on the value of the "Reset initialization on previous" property that can be configured in the install4j GUI.

  Initialization often involves replacing variables in user-configured property values.

  Specified by:
    `initalize` in interface `FormComponent`
  See Also:
    `AbstractBean.replaceVariables(String)`

### formWillActivate

    public void formWillActivate()

  Description copied from interface: `FormComponent`
  This method is called by the framework just before the containing screen will be activated.

  Specified by:
    `formWillActivate` in interface `FormComponent`
  See Also:
    `Screen.willActivate()`

### formActivated

    public void formActivated()

  Description copied from interface: `FormComponent`
  This method is called by the framework just after the containing screen has been activated.

  Specified by:
    `formActivated` in interface `FormComponent`
  See Also:
    `Screen.activated()`

### formDeactivated

    public void formDeactivated()

  Description copied from interface: `FormComponent`
  This method is called by the framework just after the containing screen has been deactivated.

  Specified by:
    `formDeactivated` in interface `FormComponent`
  See Also:
    `Screen.deactivated()`

### handleConsole

    public boolean handleConsole(Console console)
                          throws UserCanceledException

  Description copied from interface: `FormComponent`
  Handle the console mode. This method is called when the form component is processed in console mode. You can use the `Console` object to interact with the user and replicate the GUI functionality on the terminal.

  Note: Screens with form panels have to call `FormEnvironment.handleConsole` in their `handleConsole` method, otherwise this method will not be invoked. All pre-defined screens in install4j comply with this requirement.

  Specified by:
    `handleConsole` in interface `FormComponent`
  Parameters:
    `console` - the `Console` object
  Returns:
    whether the installer or uninstaller can proceed with the next form component 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:
    `Screen.handleConsole(com.install4j.api.screens.Console)`, `FormEnvironment.handleConsole(com.install4j.api.screens.Console)`

### handleUnattended

    public boolean handleUnattended()

  Description copied from interface: `FormComponent`
  Handle the unattended mode. This method is called when the form component is processed 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 an installer variable.

  Specified by:
    `handleUnattended` in interface `FormComponent`
  Returns:
    whether the installer or uninstaller can proceed with the next form component or whether the process should be cancelled.

### getInitValue

    protected java.lang.Object getInitValue(java.lang.Object defaultValue,
                                            java.lang.String variableName,
                                            java.lang.Class valueClass)

  Helper method to get an init value. If the variable is defined and of class valueClass, the variable value is used. Otherwise the default value is used.

  Parameters:
    `defaultValue` - the default value. Can be null.
    `variableName` - the installer variable name the value will be assigned to later on
    `valueClass` - the desired class of the variable content
  Returns:
    the init value to be used