FormUtilities (Tentackle Swing 2.1.1 API)

java.lang.Object
- org.tentackle.swing.FormUtilities

@Service(value=FormUtilities.class)
public class FormUtilities
extends Object

Utilities for the UI layer.

Author:: harald

Constructor Summary

Constructors
Constructor and Description

FormUtilities()
C'tor for this class.

Constructors
Constructor and Description
`FormUtilities()` C'tor for this class.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`activate()` Activates the utility features.
`void`	`addWindow(Window w)` Adds window to the set of windows (must be visible or iconified).
`void`	`addWindowActionListener(ActionListener listener)` Adds a listener being notified whenever the state of the current windows-list has changed.
`protected FormEventQueue`	`createEventQueue()` Creates a new event queue.
`void`	`doFireValueChanged(FormComponent c, Object[] listeners)` Notifies all ValueListeners (usually only one!) that the field is going to be displayed and thus needs the data what to display.
`void`	`doFireValueEntered(FormComponent c, Object[] listeners)` Notifies all ValueListeners (usually only one!) that the field contents should be moved to the actual data object.
`void`	`doValidate(FormComponent c)` Runs the validation if there is a binding and there are validation annotations.
`String`	`dumpComponentHierarchy(Component comp, MouseEvent me)` Creates a text-dump of the component hierarchy.
`Point`	`getAlignedLocation(Window window, Point location)` Calculates the location of a window so that it is completely visible on the screen, using a "free" spot.
`long`	`getAutoClose()` Gets the global autoclose feature for all newly created Windows.
`FormComponentBinding`	`getBinding(FormContainer container, FormComponent component)` Gets the binding for a given component in the given container and all its sub-containers.
`FormComponentBinding`	`getBinding(FormContainer container, String bindingPath)` Gets the binding for a given binding path in the given container and all its sub-containers.
`FormBindingFactory`	`getBindingFactory()` Gets the binding factory (singleton).
`Point`	`getCenteredLocation(Window window)` Calculates the location of a window so that it will be centered on the screen.
`FormEventQueue`	`getEventQueue()` Gets the eventqueue. The method installs the FormEventQueue if not yet done.
`void`	`getFormValue(Component c)` Recursively walk down and fireValueEntered().
`String`	`getHelpURL()` Gets the global help url prefix.
`static FormUtilities`	`getInstance()` The singleton.
`Window`	`getParentWindow(Component comp)` Determines the parent-window of a component. Much the same as getTopLevelAncestor in JComponent, this does method not return Applets.
`String`	`getPreferencesName(Class<?> clazz, String compName)` Determines the Preferences-name for a class. The name is built from the classname and a componentname.
`Point`	`getPreferredLocation(Window window, Window owner)` Calculates the position of a window on the screen so that it is being display in an optimal manner.
`Collection<FormContainer>`	`getSubContainer(FormContainer container)` Gets all subcontainers.
`Window`	`getVisibleParentOrRelatedWindow(Component comp)` Gets the parent window of the given component.
`Window[]`	`getWindows()` Gets the current windows which are visible or iconified.
`void`	`hideErrorPopup()` Hides the currently displayed error popup, if any.
`void`	`installPreferredSizeMenu(Component comp, String prefName)` Installs a menu for setting/retrieving the preferred sizes.
`void`	`invalidateParentInfo(Component c)` Recursively walk down and invalidate the parentInfo.
`boolean`	`isModalDialogShowing()` Checks whether a modal dialog is showing.
`boolean`	`isParentWindowModal(Component comp)` Determines whether parent window a modal dialog.
`boolean`	`isValueChanged(Component c, boolean triggerValueChangedEnabledOnly)` Recursively walk down and check for value changed.
`void`	`loadPreferredSizes(Component comp, String prefName, boolean system)` Loads the preferences of a component. Use it whenever there is no table in it (FormTable provide setting too) or some other scrolling regions need to be preset.
`void`	`modalToFront()` Brings the current modal dialogs toFront.
`void`	`openHelpURL(Component comp)` Opens the online help for a given component.
`boolean`	`packParentWindow(Component comp)` Packs the window containing the given component.
`void`	`processWindowEvent(WindowEvent e)` Process a window event (from a FormDialog or FormFrame).
`void`	`removeWindow(Window w)` Removes a window from the set (i.e.
`void`	`removeWindowActionListener(ActionListener listener)` Removes a listener.
`void`	`requestFocusLater(Component c)` Requests focus by EventQueue.invokeLater().
`void`	`savePreferredSizes(Component comp, String prefName, boolean system)` Saves the preferences of a component. Use it whenever there is no table in it (FormTable provide setting too) or some other scrolling regions need to be preset.
`void`	`saveValue(Component c)` Recursively walk down and saveValue().
`void`	`setAutoClose(long ms)` Sets the global autoclose feature for all newly created Windows.
`void`	`setAutoUpdate(Component c, boolean autoUpdate)` Recursively walk down and setAutoUpdate.
`void`	`setBackground(Component c, Color background)` Recursively walk down and setBackground().
`void`	`setChangeable(Component c, boolean changeable)` Recursively walk down and setChangeable().
`void`	`setDefaultCursor(Component comp)` Sets the default-cursor. Determines the parent or related window and applies the cursor.
`void`	`setDefaultFocusTraversalPolicy(Container container)` Sets the focus-policy for a container.
`void`	`setForeground(Component c, Color foreground)` Recursively walk down and setForeground().
`void`	`setFormValue(Component c)` Recursively walk down and fireValueChanged().
`void`	`setFormValueKeepChanged(Component c)` Recursively walk down and fireValueChanged(), but only fields that have NOT been changed by the user. Nice to mask out unchanged fields.
`void`	`setHelpURL(String aHelpURL)` Sets the global help url prefix.
`void`	`setUIVersionOfFormWindow(FormWindow formWindow)` Sets the initial uiversion of a `FormWindow`.
`void`	`setupDefaultBindings(JComponent comp)` Registers some default Keyboard Actions for Components.
`void`	`setWaitCursor(Component comp)` Sets the wait-cursor. Determines the parent or related window and applies the cursor.
`void`	`showErrorPopup(FormComponent formComponent, String message)` Shows an error popup for a given component and message. Any currently displayed error popup will be hidden first.
`void`	`triggerValueChanged(Component c)` Recursively walk up and trigger value changed in FormContainers.
`void`	`updateUIofAllWindows()` Updates the UI of all registered windows
`void`	`updateUIofWindow(Window w)` Updates the UI of a given window.
`void`	`waitForEmptyEventQueue()` Waits for the event queue to become empty. This method must not be invoked from the GUI thread! The method waits until the q is empty.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - FormUtilities
```
public FormUtilities()
```
    C'tor for this class. This class is supposed to have only one single instance.
    
    See Also:
    
    getInstance()
- Method Detail
  - getInstance
```
public static FormUtilities getInstance()
```
    The singleton.
    
    Returns:
    
    the singleton
  - activate
```
public void activate()
```
    Activates the utility features.
  - dumpComponentHierarchy
```
public String dumpComponentHierarchy(Component comp,
                                     MouseEvent me)
```
    Creates a text-dump of the component hierarchy.
    
    Parameters:
    
    comp - the deepest component
    
    me - the optional mouse event (necessary for table headers only)
    
    Returns:
    
    the dumped hierarchy
  - createEventQueue
```
protected FormEventQueue createEventQueue()
```
    Creates a new event queue.
    
    Returns:
    
    the created queue
  - getEventQueue
```
public FormEventQueue getEventQueue()
```
    Gets the eventqueue.
    The method installs the FormEventQueue if not yet done. This is the preferred method to get the event queue in an application.
    
    Returns:
    
    the form event queue
  - getBindingFactory
```
public FormBindingFactory getBindingFactory()
```
    Gets the binding factory (singleton).
    
    Returns:
    
    the binding factory
  - waitForEmptyEventQueue
```
public void waitForEmptyEventQueue()
```
    Waits for the event queue to become empty.
    This method must not be invoked from the GUI thread! The method waits until the q is empty.
  - setAutoClose
```
public void setAutoClose(long ms)
```
    Sets the global autoclose feature for all newly created Windows.
    
    Parameters:
    
    ms - timeout in milliseconds. Default is 0.
  - getAutoClose
```
public long getAutoClose()
```
    Gets the global autoclose feature for all newly created Windows.
    
    Returns:
    
    the timeout in milliseconds. Default is 0.
  - modalToFront
```
public void modalToFront()
```
    Brings the current modal dialogs toFront.
  - addWindow
```
public void addWindow(Window w)
```
    Adds window to the set of windows (must be visible or iconified).
    
    Parameters:
    
    w - the window to add
  - removeWindow
```
public void removeWindow(Window w)
```
    Removes a window from the set (i.e. window is hidden or closed now)
    
    Parameters:
    
    w - the window to remove
  - getWindows
```
public Window[] getWindows()
```
    Gets the current windows which are visible or iconified.
    
    Returns:
    
    the array of windows
  - isModalDialogShowing
```
public boolean isModalDialogShowing()
```
    Checks whether a modal dialog is showing.
    
    Returns:
    
    true if at least one modal dialog is showing
  - setUIVersionOfFormWindow
```
public void setUIVersionOfFormWindow(FormWindow formWindow)
```
    Sets the initial uiversion of a FormWindow.
    
    Parameters:
    
    formWindow - the created window
  - updateUIofWindow
```
public void updateUIofWindow(Window w)
```
    Updates the UI of a given window.
    
    Parameters:
    
    w - the window
  - updateUIofAllWindows
```
public void updateUIofAllWindows()
```
    Updates the UI of all registered windows
  - processWindowEvent
```
public void processWindowEvent(WindowEvent e)
```
    Process a window event (from a FormDialog or FormFrame). Update the list of registered windows.
    
    Parameters:
    
    e - the event to process
  - addWindowActionListener
```
public void addWindowActionListener(ActionListener listener)
```
    Adds a listener being notified whenever the state of the current windows-list has changed.
    
    Parameters:
    
    listener - the action listener
  - removeWindowActionListener
```
public void removeWindowActionListener(ActionListener listener)
```
    Removes a listener.
    
    Parameters:
    
    listener - the listener to be removed
  - setDefaultFocusTraversalPolicy
```
public void setDefaultFocusTraversalPolicy(Container container)
```
    Sets the focus-policy for a container. The method does nothing if the given container is not a FormContainer.
    
    Parameters:
    
    container - the container.
  - setAutoUpdate
```
public void setAutoUpdate(Component c,
                          boolean autoUpdate)
```
    Recursively walk down and setAutoUpdate.
    
    Parameters:
    
    c - the component
    
    autoUpdate - the autoUpdate flag
  - doFireValueChanged
```
public void doFireValueChanged(FormComponent c,
                               Object[] listeners)
```
    Notifies all ValueListeners (usually only one!) that the field is going to be displayed and thus needs the data what to display.
    
    Parameters:
    
    c - the component
    
    listeners - the listener array
  - doFireValueEntered
```
public void doFireValueEntered(FormComponent c,
                               Object[] listeners)
```
    Notifies all ValueListeners (usually only one!) that the field contents should be moved to the actual data object.
    
    Parameters:
    
    c - the component
    
    listeners - the listener array
  - doValidate
```
public void doValidate(FormComponent c)
```
    Runs the validation if there is a binding and there are validation annotations.
    
    Parameters:
    
    c - the component
  - setFormValue
```
public void setFormValue(Component c)
```
    Recursively walk down and fireValueChanged().
    
    Parameters:
    
    c - the component
  - setFormValueKeepChanged
```
public void setFormValueKeepChanged(Component c)
```
    Recursively walk down and fireValueChanged(), but only fields that have *NOT* been changed by the user.
    Nice to mask out unchanged fields.
    
    Parameters:
    
    c - the component
  - getFormValue
```
public void getFormValue(Component c)
```
    Recursively walk down and fireValueEntered().
    
    Parameters:
    
    c - the component
  - saveValue
```
public void saveValue(Component c)
```
    Recursively walk down and saveValue().
    
    Parameters:
    
    c - the component
  - isValueChanged
```
public boolean isValueChanged(Component c,
                              boolean triggerValueChangedEnabledOnly)
```
    Recursively walk down and check for value changed.
    
    Parameters:
    
    c - the component
    
    triggerValueChangedEnabledOnly - true if check only components with triggerValueChangedEnabled
    
    Returns:
    
    true if data has changed in some component
  - triggerValueChanged
```
public void triggerValueChanged(Component c)
```
    Recursively walk up and trigger value changed in FormContainers.
    
    Parameters:
    
    c - the component
  - setChangeable
```
public void setChangeable(Component c,
                          boolean changeable)
```
    Recursively walk down and setChangeable().
    
    Parameters:
    
    c - the component
    
    changeable - true if changeable
  - setBackground
```
public void setBackground(Component c,
                          Color background)
```
    Recursively walk down and setBackground().
    
    Parameters:
    
    c - the component
    
    background - the background color
  - setForeground
```
public void setForeground(Component c,
                          Color foreground)
```
    Recursively walk down and setForeground().
    
    Parameters:
    
    c - the component
    
    foreground - the foreground color
  - getParentWindow
```
public Window getParentWindow(Component comp)
```
    Determines the parent-window of a component.
    Much the same as getTopLevelAncestor in JComponent, this does method not return Applets.
    
    Parameters:
    
    comp - the component
    
    Returns:
    
    the parent window, null if none
  - getVisibleParentOrRelatedWindow
```
public Window getVisibleParentOrRelatedWindow(Component comp)
```
    Gets the parent window of the given component. If the parent is not visible, gets the related window.
    
    Parameters:
    
    comp - the component
    
    Returns:
    
    the parent or related window, null if neither nor
  - isParentWindowModal
```
public boolean isParentWindowModal(Component comp)
```
    Determines whether parent window a modal dialog.
    
    Parameters:
    
    comp - the component
    
    Returns:
    
    true if parent window is a modal dialog, false if no parent, not a dialog or not modal
  - packParentWindow
```
public boolean packParentWindow(Component comp)
```
    Packs the window containing the given component.
    
    Parameters:
    
    comp - the component
    
    Returns:
    
    true if packed, false if no window
  - invalidateParentInfo
```
public void invalidateParentInfo(Component c)
```
    Recursively walk down and invalidate the parentInfo.
    
    Parameters:
    
    c - the component
  - getSubContainer
```
public Collection<FormContainer> getSubContainer(FormContainer container)
```
    Gets all subcontainers.
    
    Parameters:
    
    container - the parent container
    
    Returns:
    
    the sub containers, never null
  - getBinding
```
public FormComponentBinding getBinding(FormContainer container,
                                       FormComponent component)
```
    Gets the binding for a given component in the given container and all its sub-containers.
    The method differs from Binder.getBinding(java.lang.String) because the latter only finds bindings that were explicitly bound to the container. This method, however, also finds bindings bound on sub containers.
    
    Parameters:
    
    container - the parent container
    
    component - the component
    
    Returns:
    
    the binding, null if component is not bound
  - getBinding
```
public FormComponentBinding getBinding(FormContainer container,
                                       String bindingPath)
```
    Gets the binding for a given binding path in the given container and all its sub-containers.
    The method differs from Binder.getBinding(java.lang.String) because the latter only finds bindings that were explicitly bound to the container. This method, however, also finds bindings bound on sub containers.
    
    Parameters:
    
    container - the parent container
    
    bindingPath - the opject's binding path
    
    Returns:
    
    the binding, null if binding path is not bound
  - requestFocusLater
```
public void requestFocusLater(Component c)
```
    Requests focus by EventQueue.invokeLater(). Also sets a flag that such a request is pending.
    
    Parameters:
    
    c - the component
  - setWaitCursor
```
public void setWaitCursor(Component comp)
```
    Sets the wait-cursor.
    Determines the parent or related window and applies the cursor.
    
    Parameters:
    
    comp - the related component
  - setDefaultCursor
```
public void setDefaultCursor(Component comp)
```
    Sets the default-cursor.
    Determines the parent or related window and applies the cursor.
    
    Parameters:
    
    comp - the related component
  - hideErrorPopup
```
public void hideErrorPopup()
```
    Hides the currently displayed error popup, if any.
    
    Throws:
    
    IllegalStateException - if not invoked from within the dispatch thread
  - showErrorPopup
```
public void showErrorPopup(FormComponent formComponent,
                           String message)
```
    Shows an error popup for a given component and message.
    Any currently displayed error popup will be hidden first. There is only one error popup displayed at a time. The method must be invoked from within the event dispatch thread.
    
    Parameters:
    
    formComponent - the component
    
    message - the message, null to hide
    
    Throws:
    
    IllegalStateException - if not invoked from within the dispatch thread
  - getCenteredLocation
```
public Point getCenteredLocation(Window window)
```
    Calculates the location of a window so that it will be centered on the screen.
    
    Parameters:
    
    window - the window
    
    Returns:
    
    the location (top left corner)
  - getPreferredLocation
```
public Point getPreferredLocation(Window window,
                                  Window owner)
```
    Calculates the position of a window on the screen so that it is being display in an optimal manner.
    
    Parameters:
    
    window - the window to be positioned on the screen
    
    owner - the window to which the window will be related to
    
    Returns:
    
    the location
  - getAlignedLocation
```
public Point getAlignedLocation(Window window,
                                Point location)
```
    Calculates the location of a window so that it is completely visible on the screen, using a "free" spot.
    
    Parameters:
    
    window - the current window
    
    location - the desired (not necessarily current!) location
    
    Returns:
    
    the location
  - setupDefaultBindings
```
public void setupDefaultBindings(JComponent comp)
```
    Registers some default Keyboard Actions for Components. Will also replace some standard actions!
    
    Parameters:
    
    comp - the component
  - savePreferredSizes
```
public void savePreferredSizes(Component comp,
                               String prefName,
                               boolean system)
```
    Saves the preferences of a component.
    Use it whenever there is no table in it (FormTable provide setting too) or some other scrolling regions need to be preset. The method scans for all scrolling regions contained in component and stores their sizes.
    
    Parameters:
    
    comp - is the component (usually a panel, srolling area or window)
    
    prefName - is the preferences name
    
    system - is true if store to system-preferences, else store in userprefs
  - loadPreferredSizes
```
public void loadPreferredSizes(Component comp,
                               String prefName,
                               boolean system)
```
    Loads the preferences of a component.
    Use it whenever there is no table in it (FormTable provide setting too) or some other scrolling regions need to be preset. The method scans for all scrolling regions contained in component and sets their preferred-sizes.
    
    Parameters:
    
    comp - is the component (usually a panel, srolling area or window)
    
    prefName - is the preferences name
    
    system - is true if load from system-preferences, else try userprefs first
  - installPreferredSizeMenu
```
public void installPreferredSizeMenu(Component comp,
                                     String prefName)
```
    Installs a menu for setting/retrieving the preferred sizes.
    
    Parameters:
    
    comp - is the component
    
    prefName - is the preferences name
  - getPreferencesName
```
public String getPreferencesName(Class<?> clazz,
                                 String compName)
```
    Determines the Preferences-name for a class.
    The name is built from the classname and a componentname. plus the name of the table. E.g.: "/de/krake/bixworx/common/OpAusziffTableEntry/opAusziffOpTable"
    
    Parameters:
    
    clazz - the class
    
    compName - the name of the component
    
    Returns:
    
    the preferences name
  - setHelpURL
```
public void setHelpURL(String aHelpURL)
```
    Sets the global help url prefix. The prefix will be prepended to all help requests.
    
    Parameters:
    
    aHelpURL - the prefix
  - getHelpURL
```
public String getHelpURL()
```
    Gets the global help url prefix.
    
    Returns:
    
    the prefix
  - openHelpURL
```
public void openHelpURL(Component comp)
```
    Opens the online help for a given component.
    
    Parameters:
    
    comp - the component

Class FormUtilities

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

FormUtilities

Method Detail

getInstance

activate

dumpComponentHierarchy

createEventQueue

getEventQueue

getBindingFactory

waitForEmptyEventQueue

setAutoClose

getAutoClose

modalToFront

addWindow

removeWindow

getWindows

isModalDialogShowing

setUIVersionOfFormWindow

updateUIofWindow

updateUIofAllWindows

processWindowEvent

addWindowActionListener

removeWindowActionListener

setDefaultFocusTraversalPolicy

setAutoUpdate

doFireValueChanged

doFireValueEntered

doValidate

setFormValue

setFormValueKeepChanged

getFormValue

saveValue

isValueChanged

triggerValueChanged

setChangeable

setBackground

setForeground

getParentWindow

getVisibleParentOrRelatedWindow

isParentWindowModal

packParentWindow

invalidateParentInfo

getSubContainer

getBinding

getBinding

requestFocusLater

setWaitCursor

setDefaultCursor

hideErrorPopup

showErrorPopup

getCenteredLocation

getPreferredLocation

getAlignedLocation

setupDefaultBindings

savePreferredSizes

loadPreferredSizes

installPreferredSizeMenu

getPreferencesName

setHelpURL

getHelpURL

openHelpURL