public interface FormEnvironment
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.
Modifier and Type | Method and 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 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.
|
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.
|
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 with
addDesignTimeChangeListener . |
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.
|
FormComponent[] getFormComponents()
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.
FormComponent.setFormEnvironment(FormEnvironment)
java.util.List<?> getFormComponentTree()
FormComponent
and LayoutGroup
.
Deeper levels can be accessed with LayoutGroup.getChildren()
on the LayoutGroup
objects.java.lang.String getId(FormComponent formComponent)
The ID can be transformed back to the form component with the
getFormComponentById
method.
formComponent
- the form component whose ID should be returnedgetFormComponentById(String)
<T> T[] getFormComponents(java.lang.Class<T> formComponentClass)
formComponentClass
- the class of the form component.<T> T getFirstFormComponent(java.lang.Class<T> formComponentClass) throws NotSupportedInElevationException
getFormComponents(Class)
should be used.formComponentClass
- the class of the screen.null
if no form component of this class could be found.NotSupportedInElevationException
getFormComponents(Class)
FormComponent getFormComponentById(java.lang.String id)
getId(FormComponent)
method for more details.id
- the ID of the form componentnull
if no such ID can be found.LayoutGroup getLayoutGroupById(java.lang.String id)
LayoutGroup.getId()
for more details.id
- the ID of the layout groupnull
if no such ID can be found.ComponentTuple getComponentTuple(FormComponent formComponent)
ComponentTuple
associated with a form component.formComponent
- the form component whose ComponentTuple
should be returnedComponentTuple
boolean handleConsole(Console console) throws UserCanceledException
handleConsole
method
of the containing screen, otherwise the handleConsole
method of the
FormComponent
will not be called.console
- the Console
object as passed to the handleConsole
method of the containing screen.handleConsole
method of the containing screen which is the only place where this method should be called.UserCanceledException
- if the user cancels a question or notice. This exception can be passed on to the framework.FormComponent.handleConsole(Console)
,
Screen.handleConsole(Console)
boolean isDesignTime()
null
.true
or false
.void addDesignTimeChangeListener(javax.swing.event.ChangeListener changeListener)
This method has no effect at runtime.
changeListener
- the listenervoid removeDesignTimeChangeListener(javax.swing.event.ChangeListener changeListener)
addDesignTimeChangeListener
.
This method has no effect at runtime.
changeListener
- the listenerjava.lang.String getDesignTimeName(FormComponent formComponent)
formComponent
- the form component whose name should be returned.null
if called at runtimejava.lang.String getDesignTimeName(LayoutGroup layoutGroup)
layoutGroup
- the layout group whose name should be returned.null
if called at runtimeScreen getScreen()
void resetFormComponents()
String screenId = ...
// must be a form screen for the cast to work
FormPanelContainer formPanelContainer = (FormPanelContainer)context.getScreenById(id);
formPanelContainer.getFormEnvironment().resetFormComponents()
void reinitializeFormComponents()
boolean saveFormComponents()
false
, only form components up to the offending form component
are saved.void makeParentGroupVisible(FormComponent formComponent)
formComponent
- the form component whose parent group should be made visible.void bindTextWithVariables(java.lang.String textWithVariables, javax.swing.JComponent componentWithText)
textWithVariables
- the text with the unresolved variables.componentWithText
- a JLabel or a JTextComponentjava.lang.Object getFormVariable(java.lang.String variableName)
variableName
- the name of the variable.null
if the form variable with the specified name was not defined.setFormVariable(String, Object)
void setFormVariable(java.lang.String variableName, java.lang.Object value)
variableName
- the form variable namevalue
- the variable valuefor more information
java.util.Set<java.lang.String> getFormVariableNames()
java.lang.String
.getFormVariable(String)
java.lang.String replaceFormVariables(java.lang.String value, ReplacementMode replacementMode, VariableErrorHandlingDescriptor errorHandlingDescriptor) throws UndefinedVariableException
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.
value
- the original stringreplacementMode
- the replacement modeerrorHandlingDescriptor
- describes how missing variables should be treated for each variable typeUndefinedVariableException
- if a variable name cannot be found and the error handling is set to
VariableErrorHandling.EXCEPTION
for the variable type.