FormComponent (Tentackle Swing 2.1.1 API)

All Superinterfaces:

FormChangeable, FormChangeableComponent

All Known Subinterfaces:

FormFieldComponent

All Known Implementing Classes:

AbstractFormField, AbstractFractionNumberFormField, AbstractNumberFormField, AcceptDenyCheckBox, BMoneyFormField, ByteFormField, DateFormField, DoubleFormField, FloatFormField, FormCalendarField, FormCheckBox, FormComboBox, FormComponentPanel, FormConsole, FormFieldComboBox, FormFieldComponentPanel, FormFileChooser, FormMailField, FormRadioButton, FormSpinField, FormTelnoField, FormTextArea, FormToggleButton, FormUrlField, HourSpinField, IntegerFormField, LocaleComboBox, LongFormField, MinSecSpinField, MonthComboBox, MonthSpinField, ShortFormField, StringFormField, TimeZoneComboBox, WeekdayComboBox, YearSpinField, YesNoRadioButton
```
public interface FormComponent
extends FormChangeableComponent
```
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

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`addValueListener(ValueListener listener)` Adds a value listener that implements the binding between this component and the data.
`void`	`clearValueShownModified()` Clears the value shown status. May be used by components that update the value shown programmatically.
`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.
`int`	`getBaseline(int width, int height)` Returns the baseline of this component.
`FormComponentBinding`	`getBinding()` Gets the binding.
`String`	`getBindingPath()` Gets the binding path.
`String`	`getComponentPath()` Gets the component path.
`FocusTraversalGroup`	`getFocusTraversalGroup()` Gets the focus traversal group for this component.
`Object`	`getFormValue()` Retrieves the value from this component. The method is used to update the data model 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.
`PropertyGroup`	`getPropertyGroup()` Gets the property group for this component.
`Object`	`getValueShown()` Gets the value shown to the user. This is the visual representation, not necessarily the model's value.
`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`	`isAutoUpdate()` Returns whether the auto-update feature is enabled.
`boolean`	`isBindable()` Determines whether this component is bindable.
`boolean`	`isCellEditorUsage()` Returns whether this component is used as a cell editor.
`boolean`	`isFireRunning()` Checks whether a fire-method is running.
`boolean`	`isFormTraversable()` Returns whether this component is form traversable or not.
`boolean`	`isMandatory()` Gets the mandatory option.
`boolean`	`isSmartValueEntered()` Returns whether the model should only be updated if the component's value really changed. The default is true.
`boolean`	`isTriggerValueChangedEnabled()` Determines whether triggering value changes is enabled.
`boolean`	`isValueChanged()` Checks whether the contents have been changed since the last savepoint.
`boolean`	`isValueShownModified()` Checks whether the currently shown value differs from the initially shown. Used to implement smartValueEntered.
`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`	`setAutoUpdate(boolean autoUpdate)` Sets the auto-update feature. By default, all components update the data model if the view changes (due to certain events, for example focus lost).
`void`	`setBindable(boolean bindable)` Sets whether this component is bindable.
`void`	`setBinding(FormComponentBinding binding)` Sets the binding.
`void`	`setBindingPath(String bindingPath)` Sets the path to bind this component to.
`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`	`setComponentPath(String componentPath)` Sets the component path.
`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`	`setFocusTraversalGroup(FocusTraversalGroup group)` Sets the focus traversal group for this component.
`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`	`setMandatory(boolean mandatory)` Sets the mandatory option. Mandatory fields are differently visualized.
`void`	`setPropertyGroup(PropertyGroup group)` Sets the property group for this component.
`void`	`setSmartValueEntered(boolean smartValueEntered)` Sets whether the model should only be updated if the component's value really changed. The default is true.
`void`	`setTriggerValueChangedEnabled(boolean enabled)` Enables triggering value changes. Disabling this feature may be necessary for model-agnostic components.
`void`	`showErrorPopup(String message)` Shows the error popup for a given message. The popup component used is an `ErrorToolTip`.
`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 `FormContainer`s 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`.

Methods inherited from interface org.tentackle.swing.FormChangeableComponent
updateAllChangeable

Methods inherited from interface org.tentackle.swing.FormChangeable
isChangeable, isHonourChangeable, setChangeable, setHonourChangeable

- 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 model if the view has changed because the user edited it.
    
    Returns:
    
    the object from the form
  - getValueShown
```
Object getValueShown()
```
    Gets the value shown to the user.
    This is the visual representation, not necessarily the model's value. Used to implemement smartValueEntered.
    
    Returns:
    
    the value visible to the user
  - isValueShownModified
```
boolean isValueShownModified()
```
    Checks whether the currently shown value differs from the initially shown.
    Used to implement smartValueEntered.
    
    Returns:
    
    true if user changed the visual representation
  - clearValueShownModified
```
void clearValueShownModified()
```
    Clears the value shown status.
    May be used by components that update the value shown programmatically.
  - setSmartValueEntered
```
void setSmartValueEntered(boolean smartValueEntered)
```
    Sets whether the model should only be updated if the component's value really changed.
    The default is true.
    
    Parameters:
    
    smartValueEntered - true if optimize, false if always update the model
  - isSmartValueEntered
```
boolean isSmartValueEntered()
```
    Returns whether the model should only be updated if the component's value really changed.
    The default is true.
    
    Returns:
    
    true if optimize, false if always update the model
  - 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.
  - setTriggerValueChangedEnabled
```
void setTriggerValueChangedEnabled(boolean enabled)
```
    Enables triggering value changes.
    Disabling this feature may be necessary for model-agnostic components.
    
    Parameters:
    
    enabled - true if invoke triggerValueChanged() on each change (default), false if not.
  - isTriggerValueChangedEnabled
```
boolean isTriggerValueChangedEnabled()
```
    Determines whether triggering value changes is enabled.
    
    Returns:
    
    true if invoke triggerValueChanged() on each change (default), false if not.
  - setAutoUpdate
```
void setAutoUpdate(boolean autoUpdate)
```
    Sets the auto-update feature.
    By default, all components update the data model if the view changes (due to certain events, for example focus lost).
    
    Parameters:
    
    autoUpdate - true if auto update the data (default), false if not
  - isAutoUpdate
```
boolean isAutoUpdate()
```
    Returns whether the auto-update feature is enabled.
    
    Returns:
    
    true if auto update the data (default), false if not
  - 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.
  - setMandatory
```
void setMandatory(boolean mandatory)
```
    Sets the mandatory option.
    Mandatory fields are differently visualized. There is no further functional difference.
    
    Parameters:
    
    mandatory - true if mandatory
  - isMandatory
```
boolean isMandatory()
```
    Gets the mandatory option.
    
    Returns:
    
    true if mandatory
  - 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:
    
    FormUtilities.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.
  - showErrorPopup
```
void showErrorPopup(String message)
```
    Shows the error popup for a given message.
    The popup component used is an ErrorToolTip.
    
    Parameters:
    
    message - the message to be displayed, null to remove
  - 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
  - setFocusTraversalGroup
```
void setFocusTraversalGroup(FocusTraversalGroup group)
```
    Sets the focus traversal group for this component.
    
    Parameters:
    
    group - the focus traversal group
  - getFocusTraversalGroup
```
FocusTraversalGroup getFocusTraversalGroup()
```
    Gets the focus traversal group for this component.
    
    Returns:
    
    the focus traversal group
  - setPropertyGroup
```
void setPropertyGroup(PropertyGroup group)
```
    Sets the property group for this component.
    
    Parameters:
    
    group - the property group
  - getPropertyGroup
```
PropertyGroup getPropertyGroup()
```
    Gets the property group for this component.
    
    Returns:
    
    the property group
  - setBindingPath
```
void setBindingPath(String bindingPath)
```
    Sets the path to bind this component to.
    Usually the binding path will be determined from the components declared name. However, it can be set programatically as well.
    
    Parameters:
    
    bindingPath - the binding path, for ex. "invoiceNumber", null if autobinding
    
    See Also:
    
    Binder
  - getBindingPath
```
String getBindingPath()
```
    Gets the binding path.
    
    Returns:
    
    the field path, null if autobinding (default)
  - setComponentPath
```
void setComponentPath(String componentPath)
```
    Sets the component path.
    The path is <declaring-class-name>.<field-name>. Example "de.krake.invoicer.InvoicePanel.customerNumberField".
    Notice: the component path is set during binding.
    
    Parameters:
    
    componentPath - the component path
  - getComponentPath
```
String getComponentPath()
```
    Gets the component path.
    
    Returns:
    
    the component path, null if not bound
  - setBinding
```
void setBinding(FormComponentBinding binding)
```
    Sets the binding.
    
    Parameters:
    
    binding - the binding, null if none.
  - getBinding
```
FormComponentBinding getBinding()
```
    Gets the binding.
    
    Returns:
    
    the binding, null if none
  - setBindable
```
void setBindable(boolean bindable)
```
    Sets whether this component is bindable.
    FormComponents are bindable by default.
    
    Parameters:
    
    bindable - true if bindable, else not eligible for the binding process
  - isBindable
```
boolean isBindable()
```
    Determines whether this component is bindable.
    
    Returns:
    
    true if bindable, else not eligible for the binding process
  - 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
  - getBaseline
```
int getBaseline(int width,
                int height)
```
    Returns the baseline of this component.
    
    Parameters:
    
    width - the width to get the baseline for
    
    height - the height to get the baseline for
    
    Returns:
    
    the baseline
    
    Since:
    
    1.6

Interface FormComponent

Method Summary

Methods inherited from interface org.tentackle.swing.FormChangeableComponent

Methods inherited from interface org.tentackle.swing.FormChangeable

Method Detail

setFormValue

getFormValue

getValueShown

isValueShownModified

clearValueShownModified

setSmartValueEntered

isSmartValueEntered

saveValue

isValueChanged

triggerValueChanged

setTriggerValueChangedEnabled

isTriggerValueChangedEnabled

setAutoUpdate

isAutoUpdate

addValueListener

removeValueListener

fireValueChanged

fireValueEntered

setMandatory

isMandatory

setFireRunning

isFireRunning

wasTransferFocus

wasTransferFocusBackward

wasTransferFocusByEnter

wasFocusGainedFromTransfer

wasFocusGainedFromTransferBackward

requestFocusLater

setFormWrapWindow

getParentWindow

invalidateParentInfo

setHelpURL

getHelpURL

showHelp

showErrorPopup

setCellEditorUsage

isCellEditorUsage

prepareFocusLost

setFormTraversable

isFormTraversable

setFocusTraversalGroup

getFocusTraversalGroup

setPropertyGroup

getPropertyGroup

setBindingPath

getBindingPath

setComponentPath

getComponentPath

setBinding

getBinding

setBindable

isBindable

hasFocus

transferFocus

transferFocusBackward

getBaseline