Package com.install4j.api.formcomponents

Class AbstractFormComponent

java.lang.Object

com.install4j.api.beans.AbstractBean

com.install4j.api.formcomponents.AbstractFormComponent

All Implemented Interfaces:

Bean, FormComponent, com.install4j.runtime.beans.formcomponents.FormEnvironmentContainer

public abstract class AbstractFormComponent
extends AbstractBean
implements FormComponent, com.install4j.runtime.beans.formcomponents.FormEnvironmentContainer

Abstract base class for form components. All methods that have a reasonable default answer are overridden in the class. This class saves the context and the form environment that are set by the framework and provides getters for them. In addition, the "enabled" and "visible" properties are handled by invoking the corresponding setters on all components in the ComponentTuple of the form component.

Field Summary

Fields

Modifier and Type	Field	Description
static final Pattern	MNEMONIC_PATTERN

Constructor Summary

Constructors

Constructor	Description
AbstractFormComponent()

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	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.
Context	getContext()	Returns the Context that the framework has associated with this form component in setContext.
FormEnvironment	getFormEnvironment()	Returns the FormEnvironment that the framework has associated with this form component in setFormEnvironment.
protected Object	getInitValue(Object defaultValue, String variableName, Class<?> valueClass)	Helper method to get an init value.
static int	getMnemonicCharIndex(String text)
static String	getTextWithoutMnemonics(String text)
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.
protected final void	initalize()	Deprecated.
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	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.
String	replaceFormVariables(String value)	Same as AbstractBean.replaceVariables(String), only with the additional replacement of form variables.
String[]	replaceFormVariables(String[] values)	Same as AbstractBean.replaceVariables(String[]), only with the additional replacement of form variables.
String[]	replaceFormVariables(String[] values, VariableErrorHandlingDescriptor errorHandlingDescriptor)	Same as AbstractBean.replaceVariables(String[], VariableErrorHandlingDescriptor), only with the additional replacement of form variables.
String	replaceFormVariables(String value, ReplacementMode replacementMode)	Same as AbstractBean.replaceVariables(String, ReplacementMode), only with the additional replacement of form variables.
String	replaceFormVariables(String value, ReplacementMode replacementMode, VariableErrorHandlingDescriptor errorHandlingDescriptor)	Same as AbstractBean.replaceVariables(String, ReplacementMode, VariableErrorHandlingDescriptor), only with the additional replacement of form variables.
String	replaceFormVariables(String value, VariableErrorHandlingDescriptor errorHandlingDescriptor)	Same as AbstractBean.replaceVariables(String, VariableErrorHandlingDescriptor), only with the additional replacement of form variables.
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.

Methods inherited from class com.install4j.api.beans.AbstractBean

executeActionListAsync, executeActionListSync, getTextOverrideValue, replaceVariables, replaceVariables, replaceVariables, replaceVariables, replaceVariables, replaceVariables, replaceVariables, replaceVariables, replaceWithTextOverride, replaceWithTextOverride, replaceWithTextOverride, replaceWithTextOverride, replaceWithTextOverride, replaceWithTextOverride, replaceWithTextOverride, replaceWithTextOverride, replaceWithTextOverride, replaceWithTextOverride, rollbackActionList

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.install4j.api.formcomponents.FormComponent

createCenterComponent, isFillCenterHorizontal

Field Details

MNEMONIC_PATTERN

public static final Pattern MNEMONIC_PATTERN

Constructor Details

AbstractFormComponent

public AbstractFormComponent()

Method Details

getTextWithoutMnemonics

public static String getTextWithoutMnemonics(String text)

getMnemonicCharIndex

public static int getMnemonicCharIndex(String text)

setContext

public void setContext(Context context)

Description copied from interface: FormComponent

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.

Specified by:

setContext in interface FormComponent

Parameters:

context - the context.

getContext

public Context getContext()

Returns the Context that the framework has associated with this form component in setContext.

Returns:

the installer context.

setFormEnvironment

public void setFormEnvironment(FormEnvironment formEnvironment)

Description copied from interface: FormComponent

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.

Specified by:

setFormEnvironment in interface FormComponent

Specified by:

setFormEnvironment in interface com.install4j.runtime.beans.formcomponents.FormEnvironmentContainer

Parameters:

formEnvironment - the FormEnvironment

See Also:

• FormEnvironment.getFormComponents()

getFormEnvironment

public FormEnvironment getFormEnvironment()

Returns the FormEnvironment that the framework has associated with this form component in setFormEnvironment.

Specified by:

getFormEnvironment in interface com.install4j.runtime.beans.formcomponents.FormEnvironmentContainer

Returns:

the installer context.

isEnabled

public boolean isEnabled()

Description copied from interface: FormComponent

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.

Specified by:

isEnabled in interface FormComponent

Returns:

true or false.

See Also:

• FormComponent.setEnabled(boolean)

setEnabled

public void setEnabled(boolean enabled)

Description copied from interface: FormComponent

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

Specified by:

setEnabled in interface FormComponent

Parameters:

enabled - whether to enable this form component or not

See Also:

• AbstractFormComponent
• ComponentTuple
• FormComponent.isEnabled()

setVisible

public void setVisible(boolean visible)

Description copied from interface: FormComponent

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.

Specified by:

setVisible in interface FormComponent

Parameters:

visible - whether this form component should be visible or not

See Also:

• AbstractFormComponent
• ComponentTuple
• FormComponent.isVisible()

isVisible

public boolean isVisible()

Description copied from interface: FormComponent

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.

Specified by:

isVisible in interface FormComponent

Returns:

true or false.

See Also:

• FormComponent.setVisible(boolean)

migrateIds

public void migrateIds(Map<String,String> oldIdToNewId)

Description copied from interface: FormComponent

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.

Specified by:

migrateIds in interface FormComponent

Parameters:

oldIdToNewId - a map that maps the old IDs to the new IDs. An ID is of type java.lang.String.

See Also:

• FormEnvironment.getId(FormComponent)
• FormEnvironment.getFormComponentById(String)

requestFocus

public void requestFocus()

Description copied from interface: FormComponent

Transfer the focus to this form component.

Specified by:

requestFocus in interface FormComponent

hasUserInput

public boolean hasUserInput()

Description copied from interface: FormComponent

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.

Specified by:

hasUserInput in interface FormComponent

Returns:

if the component has user input

createLeftComponent

public JComponent createLeftComponent()

Description copied from interface: FormComponent

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.

Specified by:

createLeftComponent in interface FormComponent

Returns:

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

isFillCenterVertical

public boolean isFillCenterVertical()

Description copied from interface: FormComponent

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.

Specified by:

isFillCenterVertical in interface FormComponent

Returns:

true or false.

See Also:

• FormComponent.createCenterComponent()

createRightComponent

public JComponent createRightComponent()

Description copied from interface: FormComponent

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.

Specified by:

createRightComponent in interface FormComponent

Returns:

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

getConfigurationObject

public Object getConfigurationObject()

Description copied from interface: FormComponent

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.

Specified by:

getConfigurationObject in interface FormComponent

Returns:

the configuration object or null if getConfigurationObjectClass returns null as well.

See Also:

• FormComponent.getConfigurationObjectClass()

getConfigurationObjectClass

public Class<?> getConfigurationObjectClass()

Description copied from interface: FormComponent

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.

Specified by:

getConfigurationObjectClass in interface FormComponent

Returns:

the class of the configuration object or null if no configuration object should be exposed.

See Also:

• FormComponent.getConfigurationObject()

checkCompleted

public boolean checkCompleted()

Description copied from interface: FormComponent

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.

Specified by:

checkCompleted in interface FormComponent

Returns:

whether to allow advancing to the next screen or not.

See Also:

• Context.setVariable(String, Object)

initialize

public void initialize()

Description copied from interface: FormComponent

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.

Specified by:

initialize in interface FormComponent

See Also:

• AbstractBean.replaceVariables(String)

initalize

@Deprecated
protected final void initalize()

Deprecated.

The name of this method has changed to "initialize"

formWillActivate

public void formWillActivate()

Description copied from interface: FormComponent

This method is called by the framework just before the containing screen will be activated.

Specified by:

formWillActivate in interface FormComponent

See Also:

• Screen.willActivate()

formActivated

public void formActivated()

Description copied from interface: FormComponent

This method is called by the framework just after the containing screen has been activated.

Specified by:

formActivated in interface FormComponent

See Also:

• Screen.activated()

formDeactivated

public void formDeactivated()

Description copied from interface: FormComponent

This method is called by the framework just after the containing screen has been deactivated.

Specified by:

formDeactivated in interface FormComponent

See Also:

• Screen.deactivated()

handleConsole

public boolean handleConsole(Console console)
                      throws UserCanceledException

Description copied from interface: FormComponent

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.

Specified by:

handleConsole in interface FormComponent

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:

• Screen.handleConsole(Console)
• FormEnvironment.handleConsole(Console)

handleUnattended

public boolean handleUnattended()

Description copied from interface: FormComponent

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.

Specified by:

handleUnattended in interface FormComponent

Returns:

whether the installer or uninstaller can proceed with the next form component or whether the process should be canceled.

getInitValue

protected Object getInitValue(Object defaultValue,
 String variableName,
 Class<?> valueClass)

Helper method to get an init value. If the variable is defined and of class valueClass, the variable value is used. Otherwise, the default value is used.

Parameters:

defaultValue - the default value. Can be null.

variableName - the installer variable name the value will be assigned to later on

valueClass - the desired class of the variable content

Returns:

the init value to be used

replaceFormVariables

public String replaceFormVariables(String value)
                            throws UndefinedVariableException

Same as AbstractBean.replaceVariables(String), only with the additional replacement of form variables.

Throws:

UndefinedVariableException

See Also:

• FormEnvironment.replaceFormVariables(String, ReplacementMode, VariableErrorHandlingDescriptor)

replaceFormVariables

public String replaceFormVariables(String value,
 ReplacementMode replacementMode)
                            throws UndefinedVariableException

Same as AbstractBean.replaceVariables(String, ReplacementMode), only with the additional replacement of form variables.

Throws:

UndefinedVariableException

See Also:

• FormEnvironment.replaceFormVariables(String, ReplacementMode, VariableErrorHandlingDescriptor)

replaceFormVariables

public String replaceFormVariables(String value,
 VariableErrorHandlingDescriptor errorHandlingDescriptor)
                            throws UndefinedVariableException

Same as AbstractBean.replaceVariables(String, VariableErrorHandlingDescriptor), only with the additional replacement of form variables.

Throws:

UndefinedVariableException

See Also:

• FormEnvironment.replaceFormVariables(String, ReplacementMode, VariableErrorHandlingDescriptor)

replaceFormVariables

public String replaceFormVariables(String value,
 ReplacementMode replacementMode,
 VariableErrorHandlingDescriptor errorHandlingDescriptor)
                            throws UndefinedVariableException

Same as AbstractBean.replaceVariables(String, ReplacementMode, VariableErrorHandlingDescriptor), only with the additional replacement of form variables.

Throws:

UndefinedVariableException

See Also:

• FormEnvironment.replaceFormVariables(String, ReplacementMode, VariableErrorHandlingDescriptor)

replaceFormVariables

public String[] replaceFormVariables(String[] values)
                              throws UndefinedVariableException

Same as AbstractBean.replaceVariables(String[]), only with the additional replacement of form variables.

Throws:

UndefinedVariableException

See Also:

• FormEnvironment.replaceFormVariables(String, ReplacementMode, VariableErrorHandlingDescriptor)

replaceFormVariables

public String[] replaceFormVariables(String[] values,
 VariableErrorHandlingDescriptor errorHandlingDescriptor)
                              throws UndefinedVariableException

Same as AbstractBean.replaceVariables(String[], VariableErrorHandlingDescriptor), only with the additional replacement of form variables.

Throws:

UndefinedVariableException

See Also:

• FormEnvironment.replaceFormVariables(String, ReplacementMode, VariableErrorHandlingDescriptor)