org.tentackle.ui
Interface FormComponent

All Known Subinterfaces:

FormFieldComponent

All Known Implementing Classes:

AcceptDenyCheckBox, AppDbObjectFieldPanel, AppDbObjectLinkPanel, BMoneyFormField, ByteFormField, DateFormField, DoubleFormField, FloatFormField, FormCalendarField, FormCheckBox, FormComboBox, FormComponentPanel, FormField, FormFieldComboBox, FormFieldComponentPanel, FormFileChooser, FormMailField, FormRadioButton, FormSpinField, FormTelnoField, FormTextArea, FormTextAreaTableCellRenderer, FormUrlField, HourSpinField, IntegerFormField, LocaleComboBox, LongFormField, MinSecSpinField, MonthComboBox, NumberFormField, PermissionComboBox, ShortFormField, StringFormField, TimeZoneComboBox, WeekdayComboBox, YearSpinField, YesNoRadioButton

public interface FormComponent

Interface all Tentackle form components must implement.

Tentackle beans derived from Swing components that the user interacts with in order to edit some data are FormComponents. FormComponents are aware of the binding between the data and the GUI and provide a standardized way to update the view and the data, vice versa. This simplifies the development and design of the GUI significantly.

Author:

harald

Method Summary

void	addValueListener(ValueListener listener) Adds a value listener that implements the binding between this component and the data.
void	fireValueChanged() Fires all value listeners registered on this component invoking their valueChanged-handler. This method is invoked whenever the data has been changed and that change should be reflected in the view.
void	fireValueEntered() Fires all listeners registered on this component invoking their valueEntered-handler. This method is invoked whenever the user edited the view and that change should be reflected in the data.
Object	getFormValue() Retrieves the value from this component. The method is used to update the data if the view has changed because the user edited it.
String	getHelpURL() Gets the online-help URL.
Window	getParentWindow() Gets the parent window of this component.
boolean	hasFocus() Returns whether this component has the keyboard focus.
void	invalidateParentInfo() Invalidates all container-relevant (cached) information for the hierarchy of this component's parents. For optimization purposes.
boolean	isCellEditorUsage() Returns whether this component is used as a cell editor.
boolean	isChangeable() Returns if this component is changeable.
boolean	isFireRunning() Checks whether a fire-method is running.
boolean	isFormTraversable() Returns whether this component is form traversable or not.
boolean	isHonourChangeable() Returns whether this component should honour the changeable-attribute or not.
boolean	isValueChanged() Checks whether the contents have been changed since the last savepoint.
void	prepareFocusLost() Prepares for FOCUS_LOST. Gives this component the opportunity to invoke fireValueEntered() earlier than FOCUS_LOST is really received.
void	removeValueListener(ValueListener listener) Remove a value listener.
void	requestFocusLater() Requests the keyboard focus for this component by appending an event to the end of the event queue. Applications should not use requestFocus() or requestFocusInWindow() unless the order in which the events are processed is unimportant.
void	saveValue() Sets a savepoint for the data of this component. Allows to decide whether the user has changed the data associated with this component or not.
void	setCellEditorUsage(boolean cellEditorUsage) Sets a hint that this component is used as a cell editor. Some components behave differently in tables than in forms, for example.
void	setChangeable(boolean changeable) Set the component to be changeable. This is a unified abstraction and will be translated to setEditable or setEnabled, whatever is appropriate to this component.
void	setFireRunning(boolean fireRunning) Sets a component's flag that a fire-method is currently running. Used by the framework to minimize valueChanged/valueEntered processing.
void	setFormTraversable(boolean formTraversable) Sets whether this component is form traversable or not, i.e.
void	setFormValue(Object object) Sets a value in this component. The method is used to update the view if the data has changed.
void	setFormWrapWindow(FormWindow window) Sets the window that will fire a FormWrapEvent when this components loses the keyboard focus.
void	setHelpURL(String helpURL) Sets the online-help URL. If a help url is set for this component, a browser will be launched to show that url.
void	setHonourChangeable(boolean honourChangeable) Sets whether this component should honour the changeable-attribute or not. The default is true.
void	showHelp() Displays online help for this component. Usually triggered by KeyEvent.VK_F1 or VK_HELP or a button.
void	transferFocus() Transfers keyboard focus forward to the logically next component.
void	transferFocusBackward() Transfers keyboard focus forward to the logically previous component.
void	triggerValueChanged() Promotes the fact that value changed to all FormContainers this component is a child of.
boolean	wasFocusGainedFromTransfer() Returns whether the keyboard focus was gained due to transferFocus() in the opposite component.
boolean	wasFocusGainedFromTransferBackward() Returns whether the keyboard focus was gained due to transferFocusBackward() in the opposite component.
boolean	wasTransferFocus() Returns whether this component lost the keyboard focus due to transferFocus().
boolean	wasTransferFocusBackward() Returns whether this component lost the keyboard focus due to transferFocusBackward().
boolean	wasTransferFocusByEnter() Returns whether this component lost the keyboard focus due to KeyEvent.VK_ENTER.

Method Detail

setFormValue

void setFormValue(Object object)

Sets a value in this component.
The method is used to update the view if the data has changed.

Parameters:

object - is the object to set

getFormValue

Object getFormValue()

Retrieves the value from this component.
The method is used to update the data if the view has changed because the user edited it.

Returns:

the object from the form

saveValue

void saveValue()

Sets a savepoint for the data of this component.
Allows to decide whether the user has changed the data associated with this component or not.

See Also:

isValueChanged()

isValueChanged

boolean isValueChanged()

Checks whether the contents have been changed since the last savepoint.

Returns:

true if changed

See Also:

saveValue()

triggerValueChanged

void triggerValueChanged()

Promotes the fact that value changed to all FormContainers this component is a child of.

addValueListener

void addValueListener(ValueListener listener)

Adds a value listener that implements the binding between this component and the data.

Parameters:

listener - the value listener to add

removeValueListener

void removeValueListener(ValueListener listener)

Remove a value listener.

Parameters:

listener - the value listener to remove

fireValueChanged

void fireValueChanged()

Fires all value listeners registered on this component invoking their valueChanged-handler.
This method is invoked whenever the data has been changed and that change should be reflected in the view.

fireValueEntered

void fireValueEntered()

Fires all listeners registered on this component invoking their valueEntered-handler.
This method is invoked whenever the user edited the view and that change should be reflected in the data.

setChangeable

void setChangeable(boolean changeable)

Set the component to be changeable.
This is a unified abstraction and will be translated to setEditable or setEnabled, whatever is appropriate to this component.

Parameters:

changeable - true the user can edit the data, false if show only

isChangeable

boolean isChangeable()

Returns if this component is changeable.

Returns:

true the user can edit the data, false if show only

setHonourChangeable

void setHonourChangeable(boolean honourChangeable)

Sets whether this component should honour the changeable-attribute or not.
The default is true. Notice: if this component does not honour the changeable flag, isValueChanged() always returns false and it will not perform any saveValue().

Parameters:

honourChangeable - true if honour the changeable attribute, false if not

isHonourChangeable

boolean isHonourChangeable()

Returns whether this component should honour the changeable-attribute or not.

Returns:

true if honour the changeable attribute, false if not

setFireRunning

void setFireRunning(boolean fireRunning)

Sets a component's flag that a fire-method is currently running.
Used by the framework to minimize valueChanged/valueEntered processing.

Parameters:

fireRunning - true if some fire-method is running

isFireRunning

boolean isFireRunning()

Checks whether a fire-method is running.

Returns:

true if some fire-method is running

wasTransferFocus

boolean wasTransferFocus()

Returns whether this component lost the keyboard focus due to transferFocus().

Returns:

true if focus lost due to transferFocus

wasTransferFocusBackward

boolean wasTransferFocusBackward()

Returns whether this component lost the keyboard focus due to transferFocusBackward().

Returns:

true if focus lost due to transferFocusBackward

wasTransferFocusByEnter

boolean wasTransferFocusByEnter()

Returns whether this component lost the keyboard focus due to KeyEvent.VK_ENTER.

Returns:

true if pressing the Enter/Return key caused a focus lost

wasFocusGainedFromTransfer

boolean wasFocusGainedFromTransfer()

Returns whether the keyboard focus was gained due to transferFocus() in the opposite component.

Returns:

true if this component gained the focus from the logically previous component

See Also:

FormFocusTraversalPolicy

wasFocusGainedFromTransferBackward

boolean wasFocusGainedFromTransferBackward()

Returns whether the keyboard focus was gained due to transferFocusBackward() in the opposite component.

Returns:

true if this component gained the focus from the logically next component

See Also:

FormFocusTraversalPolicy

requestFocusLater

void requestFocusLater()

Requests the keyboard focus for this component by appending an event to the end of the event queue.
Applications should not use requestFocus() or requestFocusInWindow() unless the order in which the events are processed is unimportant. This method guarantees that this component gets the focus when all events queued so far have been processed.

setFormWrapWindow

void setFormWrapWindow(FormWindow window)

Sets the window that will fire a FormWrapEvent when this components loses the keyboard focus. When fired the reference to the window is cleared.

Parameters:

window - the window (usually the parent window of this component).

getParentWindow

Window getParentWindow()

Gets the parent window of this component.

Returns:

the parent window, null if none

invalidateParentInfo

void invalidateParentInfo()

Invalidates all container-relevant (cached) information for the hierarchy of this component's parents.
For optimization purposes.

setHelpURL

void setHelpURL(String helpURL)

Sets the online-help URL.
If a help url is set for this component, a browser will be launched to show that url. If there is no url the next higher level container will determine the url, and so forth.

Parameters:

helpURL - the help url

See Also:

FormHelper.openHelpURL(Component)

getHelpURL

String getHelpURL()

Gets the online-help URL.

Returns:

the help url, default is null

showHelp

void showHelp()

Displays online help for this component.
Usually triggered by KeyEvent.VK_F1 or VK_HELP or a button. If help is not configured for this component, the parent's help is used.

setCellEditorUsage

void setCellEditorUsage(boolean cellEditorUsage)

Sets a hint that this component is used as a cell editor.
Some components behave differently in tables than in forms, for example.

Parameters:

cellEditorUsage - true if component is a cell editor, false if not.

isCellEditorUsage

boolean isCellEditorUsage()

Returns whether this component is used as a cell editor.

Returns:

true true if component is a cell editor, false if not.

prepareFocusLost

void prepareFocusLost()

Prepares for FOCUS_LOST.
Gives this component the opportunity to invoke fireValueEntered() earlier than FOCUS_LOST is really received. Useful because the next focused component is determined before FOCUS_LOST is sent to this component. Thus, if this component changes the focusability of the next component, the focus policy would probably pick the wrong component otherwise.

setFormTraversable

void setFormTraversable(boolean formTraversable)

Sets whether this component is form traversable or not, i.e. gets the focus or is skipped.

Parameters:

formTraversable - true if traversable, false if not

isFormTraversable

boolean isFormTraversable()

Returns whether this component is form traversable or not.

Returns:

the focus traversable flag

hasFocus

boolean hasFocus()

Returns whether this component has the keyboard focus.

Returns:

true if has focus

transferFocus

void transferFocus()

Transfers keyboard focus forward to the logically next component.

See Also:

FormFocusTraversalPolicy

transferFocusBackward

void transferFocusBackward()

Transfers keyboard focus forward to the logically previous component.

See Also:

FormFocusTraversalPolicy