Package 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.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description 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.void
bindTextWithVariables(java.lang.String textWithVariables, javax.swing.JComponent componentWithText)
Set text with unresolved variables on a JLabel or JTextComponent.ComponentTuple
getComponentTuple(FormComponent formComponent)
Get theComponentTuple
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.java.lang.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(java.lang.Class<T> formComponentClass)
Get the form component for a given class or interface.FormComponent
getFormComponentById(java.lang.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(java.lang.Class<T> formComponentClass)
Get all form components for a given class or interface.java.util.List<?>
getFormComponentTree()
Returns the top level of the tree of form components.java.lang.Object
getFormVariable(java.lang.String variableName)
Get the value of a form variable.java.util.Set<java.lang.String>
getFormVariableNames()
Get the names of all defined form variables.java.lang.String
getId(FormComponent formComponent)
Get the ID that the framework associates with a form component.LayoutGroup
getLayoutGroupById(java.lang.String id)
Get the layout group of a certain ID.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.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(javax.swing.event.ChangeListener changeListener)
Remove a change listener added withaddDesignTimeChangeListener
.java.lang.String
replaceFormVariables(java.lang.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
setFormVariable(java.lang.String variableName, java.lang.Object value)
Set a form variable.
-
-
-
Method Detail
-
getFormComponents
FormComponent[] getFormComponents()
Returns all form components that are contained in the same form. Note that thesetFormEnvironment
is called twice at runtime and that only the second invocation passes aFormEnvironment
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
java.util.List<?> getFormComponentTree()
Returns the top level of the tree of form components. The list contains objects of two different classes:FormComponent
andLayoutGroup
. Deeper levels can be accessed withLayoutGroup.getChildren()
on the LayoutGroup objects.- Returns:
- a list with the top level form components and layout groups
-
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)
-
getFormComponents
<T> T[] getFormComponents(java.lang.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(java.lang.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(java.lang.String id)
Get the form component for a specified ID. SeegetId(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(java.lang.String id)
Get the layout group of a certain ID. SeeLayoutGroup.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 theComponentTuple
associated with a form component.- Parameters:
formComponent
- the form component whoseComponentTuple
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 thehandleConsole
method of the containing screen, otherwise thehandleConsole
method of theFormComponent
will not be called.- Parameters:
console
- theConsole
object as passed to thehandleConsole
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 isnull
.- Returns:
true
orfalse
.
-
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 withaddDesignTimeChangeListener
.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
-
getDesignTimeName
java.lang.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 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 than the parent tab of the form component.- Parameters:
formComponent
- the form component whose parent group should be made visible.
-
bindTextWithVariables
void bindTextWithVariables(java.lang.String textWithVariables, javax.swing.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
java.lang.Object getFormVariable(java.lang.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(java.lang.String variableName, java.lang.Object value)
Set a form variable.- Parameters:
variableName
- the form variable namevalue
- the variable value- See Also:
for more information
-
getFormVariableNames
java.util.Set<java.lang.String> getFormVariableNames()
Get the names of all defined form variables.- Returns:
- a set of variables names of type
java.lang.String
. - See Also:
getFormVariable(String)
-
replaceFormVariables
java.lang.String replaceFormVariables(java.lang.String value, ReplacementMode replacementMode, VariableErrorHandlingDescriptor errorHandlingDescriptor) throws UndefinedVariableException
Replace all form variables, installer variables and localization keys in a string. This methods is the same asAbstractBean.replaceVariables(String, ReplacementMode, VariableErrorHandlingDescriptor)
only that it also replaces all form variables before replacing other variable types. There are several convenience methods namedreplaceFormVariables
onAbstractFormComponent
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 stringreplacementMode
- the replacement modeerrorHandlingDescriptor
- 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 toVariableErrorHandling.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
-
-