Package com.install4j.api.formcomponents

Interface FormComponent

All Superinterfaces:
Bean
All Known Implementing Classes:
AbstractFormComponent
public interface FormComponent extends Bean
All form components must implement this interface. You have to override all methods and provide a public constructor with no arguments. It is recommended that you choose AbstractFormComponent as as a superclass.

Form components are configurable in the install4j GUI for screens that return true in their hasFormPanel method. Their life-cycle is controlled by the framework.

See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    checkCompleted()
    This method is called by the framework when the user advances to the next screen in GUI or console mode.
    JComponent
    createCenterComponent()
    Create the main component in the center.
    JComponent
    createLeftComponent()
    Create the leading component to the left of the center component.
    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.
    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.
    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.
    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 inputs.
    void
    initialize()
    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
    isFillCenterHorizontal()
    Determine whether the center component created by createCenterComponent should fill all available horizontal space.
    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(Map<String,String> oldIdToNewId)
    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.

  • Method Details

    • setContext

      void setContext(Context context)
      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 whether the form screen is part of an installer or uninstaller.
      Parameters:
      context - the context.

    • setFormEnvironment

      void setFormEnvironment(FormEnvironment formEnvironment)
      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. Secondly, 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.

      Parameters:
      formEnvironment - the FormEnvironment
      See Also:

    • createLeftComponent

      JComponent createLeftComponent()
      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.

      Returns:
      the leading component or null if no leading component should be created.

    • createCenterComponent

      JComponent createCenterComponent()
      Create the main component in the center. Depending on the return value of the isFillCenterHorizontal method, the component grows to fill all available horizontal space. If you return null, the form component will not be added to the layout grid.

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

      Returns:
      the main component
      See Also:

    • isFillCenterHorizontal

      boolean isFillCenterHorizontal()
      Determine whether the center component created by createCenterComponent should fill all available horizontal space. Note that you can configure the form not to grow horizontally in the install4j GUI, so the center component may be displayed with its preferred horizontal size in any case.
      Returns:
      true or false.
      See Also:

    • isFillCenterVertical

      boolean isFillCenterVertical()
      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.
      Returns:
      true or false.
      See Also:

    • createRightComponent

      JComponent createRightComponent()
      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.

      Returns:
      the trailing component or null if no trailing component should be created.

    • getConfigurationObjectClass

      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. 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.

      Returns:
      the class of the configuration object or null if no configuration object should be exposed.
      See Also:

    • getConfigurationObject

      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.

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

      Returns:
      the configuration object or null if getConfigurationObjectClass returns null as well.
      See Also:

    • checkCompleted

      boolean checkCompleted()
      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.
      Returns:
      whether to allow advancing to the next screen or not.
      See Also:

    • initialize

      void initialize()
      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.

      See Also:

    • formWillActivate

      void formWillActivate()
      This method is called by the framework just before the containing screen will be activated.
      See Also:

    • formActivated

      void formActivated()
      This method is called by the framework just after the containing screen has been activated.
      See Also:

    • formDeactivated

      void formDeactivated()
      This method is called by the framework just after the containing screen has been deactivated.
      See Also:

    • handleConsole

      boolean handleConsole(Console console) throws UserCanceledException
      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.

      Parameters:
      console - the Console object
      Returns:
      whether the installer or uninstaller can proceed with the next form component or whether the process should be canceled.
      Throws:
      UserCanceledException - if the user cancels a question or notice. These exceptions are thrown by methods in the Console object.
      See Also:

    • handleUnattended

      boolean handleUnattended()
      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.
      Returns:
      whether the installer or uninstaller can proceed with the next form component or whether the process should be canceled.

    • setEnabled

      void setEnabled(boolean enabled)
      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 getConfigurationObject(), saves the "enabled" flag and returns it in the isEnabled method.

      Parameters:
      enabled - whether to enable this form component or not
      See Also:

    • isEnabled

      boolean isEnabled()
      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.

      Returns:
      true or false.
      See Also:

    • setVisible

      void setVisible(boolean visible)
      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.

      Parameters:
      visible - whether this form component should be visible or not
      See Also:

    • isVisible

      boolean isVisible()
      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.

      Returns:
      true or false.
      See Also:

    • migrateIds

      void migrateIds(Map<String,String> oldIdToNewId)
      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 for other form components should migrate those IDs in this method.
      Parameters:
      oldIdToNewId - a map that maps the old IDs to the new IDs. An ID is of type java.lang.String.
      See Also:

    • requestFocus

      void requestFocus()
      Transfer the focus to this form component.

    • hasUserInput

      boolean hasUserInput()
      This method is called in situations where the installer must disable all user inputs. If your form component takes user input, such as for a checkbox or a text field, you should return true.
      Returns:
      if the component has user input