FormEnvironment (install4j help)
Date: 2009-06-17

## install4j API documentation

## com.install4j.api.formcomponents
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.

Author:
  ej-technologies GmbH
See Also:
  `FormPanelContainer.setFormPanel(javax.swing.JPanel, FormEnvironment)`, `FormComponent.setFormEnvironment(FormEnvironment)`

Method Summary
`void` | `addDesignTimeChangeListener(javax.swing.event.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.
`ComponentTuple` | `getComponentTuple(FormComponent formComponent)` Get the `ComponentTuple` associated with a form component.
`java.lang.String` | `getDesignTimeName(FormComponent formComponent)` At design time, the install4j GUI allows the user to name instances of form components in a form.
`FormComponent` | `getFormComponentById(java.lang.String id)` Get the form component of a certain ID.
`FormComponent[]` | `getFormComponents()` Returns all form components that are contained in the same form.
`java.lang.String` | `getId(FormComponent formComponent)` Get the ID that the framework associates with a form component.
`Screen` | `getScreen()` Get the form screen associated with this form environment.
`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.
`void` | `removeDesignTimeChangeListener(javax.swing.event.ChangeListener changeListener)` Remove a change listener added with `addDesignTimeChangeListener`.
`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.

Method Detail

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

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

### getId

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

### getFormComponentById

    FormComponent getFormComponentById(java.lang.String id)

  Get the form component of a certain ID. See the `getId` 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.
  See Also:
    `getId(FormComponent)`

### 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`

### 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(com.install4j.api.screens.Console)`, `Screen.handleConsole(com.install4j.api.screens.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(javax.swing.event.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(javax.swing.event.ChangeListener changeListener)

  Remove a change listener added with `addDesignTimeChangeListener`.

  This method has no effect at runtime.

  Parameters:
    `changeListener` - the listener

### getDesignTimeName

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

### 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()

### 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 save the form componments to variables whil 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 sucessful. If `false`, only form components up to the offending form component are saved.