FormEnvironment (install4j API)
Description: declaration: package: com.install4j.api.formcomponents, interface: FormEnvironment

# Interface FormEnvironment

public interface FormEnvironment
The form environment gives access to form components in a form panel as well as to other design time or runtime services related to form components.

It provides access to the `ComponentTuple` of a form component as well as to the IDs that the framework assigns to form components. Furthermore, the form environment contains utility methods that can be used at design time. This class is passed to the containing screen as well as to every form component.

See Also:
  - `FormPanelContainer.setFormPanel(JPanel, FormEnvironment)`
  - `FormComponent.setFormEnvironment(FormEnvironment)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addDesignTimeChangeListener(ChangeListener changeListener)`
  If your form component would like to be notified when the list of form components changes at design time, you can add a change listener here.
  `void`
  `bindTextWithVariables(String textWithVariables, JComponent componentWithText)`
  Set text with unresolved variables on a JLabel or JTextComponent.
  `ComponentTuple`
  `getComponentTuple(FormComponent formComponent)`
  Get the `ComponentTuple` associated with a form component.
  `String`
  `getDesignTimeName(FormComponent formComponent)`
  At design time, the install4j GUI allows the user to name instances of form components in a form.
  `String`
  `getDesignTimeName(LayoutGroup layoutGroup)`
  At design time, the install4j GUI allows the user to name instances of layout groups in a form.
  `<T> T`
  `getFirstFormComponent(Class<T> formComponentClass)`
  Get the form component for a given class or interface.
  `FormComponent`
  `getFormComponentById(String id)`
  Get the form component for a specified ID.
  `FormComponent[]`
  `getFormComponents()`
  Returns all form components that are contained in the same form.
  `<T> T[]`
  `getFormComponents(Class<T> formComponentClass)`
  Get all form components for a given class or interface.
  `List<?>`
  `getFormComponentTree()`
  Returns the top level of the form component tree.
  `Object`
  `getFormVariable(String variableName)`
  Get the value of a form variable.
  `Set<String>`
  `getFormVariableNames()`
  Get the names of all defined form variables.
  `String`
  `getId(FormComponent formComponent)`
  Get the ID that the framework associates with a form component.
  `LayoutGroup`
  `getLayoutGroupById(String id)`
  Get the layout group of a certain ID.
  `Screen`
  `getScreen()`
  Get the form screen associated with this form environment.
  `WidgetStyleHandler`
  `getWidgetStyleHandler()`
  Get the widget style handler for applying widget styles to UI components.
  `boolean`
  `handleConsole(Console console)`
  Handle console mode for all form components in a form.
  `boolean`
  `isDesignTime()`
  Returns whether the form component has been instantiated at design time.
  `boolean`
  `isInitialized()`
  Check if the form panel is fully initialized.
  `void`
  `makeParentGroupVisible(FormComponent formComponent)`
  Makes the parent group of a form component visible.
  `void`
  `reinitializeFormComponents()`
  All form components, including those that do not have their "Reset initialization on previous" property selected, are initialized again.
  `void`
  `removeDesignTimeChangeListener(ChangeListener changeListener)`
  Remove a change listener added with `addDesignTimeChangeListener`.
  `String`
  `replaceFormVariables(String value, ReplacementMode replacementMode, VariableErrorHandlingDescriptor errorHandlingDescriptor)`
  Replace all form variables, installer variables and localization keys in a string.
  `void`
  `resetFormComponents()`
  All form components whose "Reset initialization on previous" property is selected, will be initialized again when the screen is shown the next time.
  `boolean`
  `saveFormComponents()`
  All form components will be validated and their variables will be saved.
  `void`
  `scrollComponentToVisible(FormComponent formComponent)`
  Scroll the form panel so that the specified form component becomes visible.
  `void`
  `setFormVariable(String variableName, Object value)`
  Set a form variable.

- ## Method Details

  - ### getFormComponents

    FormComponent[] getFormComponents()
    Returns all form components that are contained in the same form. Note that the `setFormEnvironment` is called twice at runtime and that only the second invocation passes a `FormEnvironment` that returns all form components when calling this method.

    If you need to access layout groups, please see `getFormComponentTree()` instead.

    Returns:
      an array of all form components or the empty array if the form is not fully initialized
    See Also:
      - `FormComponent.setFormEnvironment(FormEnvironment)`

  - ### getFormComponentTree

    List<?> getFormComponentTree()
    Returns the top level of the form component tree. The list contains objects of two different classes: `FormComponent` and `LayoutGroup`. Deeper levels can be accessed with `LayoutGroup.getChildren()` on the LayoutGroup objects.
    Returns:
      a list with the top level form components and layout groups

  - ### getId

    String getId(FormComponent formComponent)
    Get the ID that the framework associates with a form component. When form components refer to other form components and wish to transfer those associations between design time and runtime, they have to store a IDs rather than the form components themselves. The translation between IDs and form components is provided by the form environment.

    The ID can be transformed back to the form component with the `getFormComponentById` method.

    Parameters:
      `formComponent` - the form component whose ID should be returned
    Returns:
      the ID
    See Also:
      - `getFormComponentById(String)`

  - ### getFormComponents

    <T> T[] getFormComponents(Class<T> formComponentClass)
    Get all form components for a given class or interface.
    Parameters:
      `formComponentClass` - the class of the form component.
    Returns:
      the form components or an empty array if no form components of this class could be found.

  - ### getFirstFormComponent

    <T> T getFirstFormComponent(Class<T> formComponentClass) throws NotSupportedInElevationException
    Get the form component for a given class or interface. If multiple form components of the same class are registered, the first occurrence is returned. In that case, `getFormComponents(Class)` should be used.
    Parameters:
      `formComponentClass` - the class of the screen.
    Returns:
      the form component or `null` if no form component of this class could be found.
    Throws:
      `NotSupportedInElevationException`
    See Also:
      - `getFormComponents(Class)`

  - ### getFormComponentById

    FormComponent getFormComponentById(String id)
    Get the form component for a specified ID. See `getId(FormComponent)` method for more details.
    Parameters:
      `id` - the ID of the form component
    Returns:
      the form component or `null` if no such ID can be found.

  - ### getLayoutGroupById

    LayoutGroup getLayoutGroupById(String id)
    Get the layout group of a certain ID. See `LayoutGroup.getId()` for more details.
    Parameters:
      `id` - the ID of the layout group
    Returns:
      the layout group or `null` if no such ID can be found.

  - ### getComponentTuple

    ComponentTuple getComponentTuple(FormComponent formComponent)
    Get the `ComponentTuple` associated with a form component.
    Parameters:
      `formComponent` - the form component whose `ComponentTuple` should be returned
    Returns:
      the `ComponentTuple`

  - ### scrollComponentToVisible

    void scrollComponentToVisible(FormComponent formComponent)
    Scroll the form panel so that the specified form component becomes visible. A form panel has a scroll panel only if the `FormPanelContainer.isScrollFormPanel()` of the parent `FormPanelContainer` returns `true`. This is the default setting for empty form screens.
    Parameters:
      `formComponent` - the form component that should be shown

  - ### handleConsole

    boolean handleConsole(Console console) throws UserCanceledException
    Handle console mode for all form components in a form. This method has to be called at some point in the `handleConsole` method of the containing screen, otherwise the `handleConsole` method of the `FormComponent` will not be called.
    Parameters:
      `console` - the `Console` object as passed to the `handleConsole` method of the containing screen.
    Returns:
      whether the installer should continue or not. This value should be passed on in the `handleConsole` method of the containing screen which is the only place where this method should be called.
    Throws:
      `UserCanceledException` - if the user cancels a question or notice. This exception can be passed on to the framework.
    See Also:
      - `FormComponent.handleConsole(Console)`
      - `Screen.handleConsole(Console)`

  - ### isDesignTime

    boolean isDesignTime()
    Returns whether the form component has been instantiated at design time. At design time, the context passed to a form component is `null`.
    Returns:
      `true` or `false`.

  - ### addDesignTimeChangeListener

    void addDesignTimeChangeListener(ChangeListener changeListener)
    If your form component would like to be notified when the list of form components changes at design time, you can add a change listener here. Only a weak reference to the listener is held, so the garbage collection of your form component is not influenced.

    This method has no effect at runtime.

    Parameters:
      `changeListener` - the listener

  - ### removeDesignTimeChangeListener

    void removeDesignTimeChangeListener(ChangeListener changeListener)
    Remove a change listener added with `addDesignTimeChangeListener`.

    This method has no effect at runtime.

    Parameters:
      `changeListener` - the listener

  - ### getDesignTimeName

    String getDesignTimeName(FormComponent formComponent)
    At design time, the install4j GUI allows the user to name instances of form components in a form. You can retrieve that name with this method.
    Parameters:
      `formComponent` - the form component whose name should be returned.
    Returns:
      name the design time name or `null` if called at runtime

  - ### getDesignTimeName

    String getDesignTimeName(LayoutGroup layoutGroup)
    At design time, the install4j GUI allows the user to name instances of layout groups in a form. You can retrieve that name with this method.
    Parameters:
      `layoutGroup` - the layout group whose name should be returned.
    Returns:
      name the design time name or `null` if called at runtime

  - ### getScreen

    Screen getScreen()
    Get the form screen associated with this form environment.
    Returns:
      the screen

  - ### resetFormComponents

    void resetFormComponents()
    All form components whose "Reset initialization on previous" property is selected, will be initialized again when the screen is shown the next time. Usually, initialization is only reset when the user presses the "Back button" on the form screen. If you implement a loop and want to reset the initialization, you have to call this method. The following code retrieves a form screen by ID and resets its form components:

        String screenId = ...
        // must be a form screen for the cast to work
        FormPanelContainer formPanelContainer = (FormPanelContainer)context.getScreenById(id);
        formPanelContainer.getFormEnvironment().resetFormComponents()

  - ### reinitializeFormComponents

    void reinitializeFormComponents()
    All form components, including those that do not have their "Reset initialization on previous" property selected, are initialized again. This is useful for implementing a "Reset" button that brings the form to its original state.

  - ### saveFormComponents

    boolean saveFormComponents()
    All form components will be validated and their variables will be saved. This is what happens automatically when the user clicks "Next" just before the validation expression of the screen is evaluated. If you need to save the form components to variables while the screen is being shown, you can use this method. For example, a button form component might require some variables of other form components to be set to the currently entered values.
    Returns:
      if the validation was successful. If `false`, only form components up to the offending form component are saved.

  - ### makeParentGroupVisible

    void makeParentGroupVisible(FormComponent formComponent)
    Makes the parent group of a form component visible. This is useful if a form component is located beneath a tabbed pane group, and the currently displayed tab is different from the parent tab of the form component.
    Parameters:
      `formComponent` - the form component whose parent group should be made visible.

  - ### bindTextWithVariables

    void bindTextWithVariables(String textWithVariables, JComponent componentWithText)
    Set text with unresolved variables on a JLabel or JTextComponent. Whenever one of the installer or form variables changes, the text is updated automatically.
    Parameters:
      `textWithVariables` - the text with the unresolved variables.
      `componentWithText` - a JLabel or a JTextComponent

  - ### getFormVariable

    Object getFormVariable(String variableName)
    Get the value of a form variable. Form variables are only accessible in the current form and have their own namespace. They can be used to coordinate between different form components or between a screen and its form components.
    Parameters:
      `variableName` - the name of the variable.
    Returns:
      the variable value or `null` if the form variable with the specified name was not defined.
    See Also:
      - `setFormVariable(String, Object)`

  - ### setFormVariable

    void setFormVariable(String variableName, Object value)
    Set a form variable.
    Parameters:
      `variableName` - the form variable name
      `value` - the variable value
    See Also:
      - for more information

  - ### getFormVariableNames

    Set<String> getFormVariableNames()
    Get the names of all defined form variables.
    Returns:
      a set of variable names of type `java.lang.String`.
    See Also:
      - `getFormVariable(String)`

  - ### replaceFormVariables

    String replaceFormVariables(String value, ReplacementMode replacementMode, VariableErrorHandlingDescriptor errorHandlingDescriptor) throws UndefinedVariableException
    Replace all form variables, installer variables and localization keys in a string. This method is the same as `AbstractBean.replaceVariables(String, ReplacementMode, VariableErrorHandlingDescriptor)` only that it also replaces all form variables before replacing other variable types. There are several convenience methods named `replaceFormVariables` on `AbstractFormComponent` that call this method.

    Note: compiler variables in the project are replaced at compile time. Compiler variables in external files, such as a custom localization file, are not replaced at a compile time.

    Parameters:
      `value` - the original string
      `replacementMode` - the replacement mode
      `errorHandlingDescriptor` - describes how missing variables should be treated for each variable type
    Returns:
      the string with all variables replaced.
    Throws:
      `UndefinedVariableException` - if a variable name cannot be found and the error handling is set to `VariableErrorHandling.EXCEPTION` for the variable type.

  - ### isInitialized

    boolean isInitialized()
    Check if the form panel is fully initialized. If that is not the case, accessing other form components will not be possible.
    Returns:
      if the construction of the form panel has been completed

  - ### getWidgetStyleHandler

    WidgetStyleHandler getWidgetStyleHandler()
    Get the widget style handler for applying widget styles to UI components.
    Returns:
      the widget style handler