org.tentackle.ui
Class FormHelper

java.lang.Object
  org.tentackle.ui.FormHelper

public class FormHelper
extends Object

Utilities for the UI layer.

Author:

harald

Nested Class Summary

static class

FormHelper.PreferredSizeMouseListener A mouse listener to open a popup menu for setting/getting the preferred sizes.

Field Summary

static boolean	preferencesAreReadOnly true if user should not be allowed to write preferences
static boolean	useSystemPreferencesOnly true if retrieving and storing preferences refers to the systemRoot only.

Constructor Summary

FormHelper()

Method Summary

static void	addWindow(Window w) Adds window to the set of windows (must be visible or iconified).
static void	addWindowActionListener(ActionListener listener) Adds a listener being notified whenever the state of the current windows-list has changed.
static 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.
static void	doFireValueEntered(FormComponent c, Object[] listeners) Notifies all ValueListeners (usually only one!) that the field contents should be moved to the actual data object.
static 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.
static long	getAutoClose() Gets the global autoclose feature for all newly created Windows.
static Point	getCenteredLocation(Window window) Calculates the location of a window so that it will be centered on the screen.
static FormEventQueue	getEventQueue() Gets the eventqueue. The method installs the FormEventQueue if not yet done.
static void	getFormValue(Component c) Recursively walk down and fireValueEntered().
static String	getHelpURL() Gets the global help url prefix.
static Window	getParentWindow(Component comp) Determines the parent-window of a component. Much the same as getTopLevelAncestor in JComponent, this does method not return Applets.
static String	getPreferencesName(Class clazz, String compName) Determines the Preferences-name for a class. The name is built from the classname and a componentname.
static 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.
static Window	getVisibleParentOrRelatedWindow(Component comp) Gets the parent window of the given component.
static Object[]	getWindows() Gets the current windows which are visible or iconified.
static void	installPreferredSizeMenu(Component comp, String prefName) Installs a menu for setting/retrieving the preferred sizes.
static void	invalidateParentInfo(Component c) Recursively walk down and invalidate the parentInfo.
static boolean	isParentWindowModal(Component comp) Determines whether parent window a modal dialog.
static boolean	isValueChanged(Component c) Recursively walk down and check for value changed.
static 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.
static void	modalToFront() Brings the current modal dialogs toFront.
static void	openHelpURL(Component comp) Opens the online help for a given component.
static boolean	packParentWindow(Component comp) Packs the window containing the given component.
static void	processWindowEvent(WindowEvent e) Process a window event (from a FormDialog or FormFrame).
static void	registerLocaleRunnable(Runnable runnable) Registers a runnable which will be invoked for each Locale change.
static void	removeWindow(Window w) Removes a window from the set (i.e.
static void	removeWindowActionListener(ActionListener listener) Removes a listener.
static void	requestFocusLater(Component c) Requests focus by EventQueue.invokeLater().
static 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.
static void	saveValue(Component c) Recursively walk down and saveValue().
static void	setAutoClose(long ms) Sets the global autoclose feature for all newly created Windows.
static void	setBackground(Component c, Color background) Recursively walk down and setBackground().
static void	setChangeable(Component c, boolean changeable) Recursively walk down and setChangeable().
static void	setDefaultCursor(Component comp) Sets the default-cursor. Determines the parent or related window and applies the cursor.
static void	setDefaultFocusTraversalPolicy(Container container) Sets the focus-policy for a container.
static void	setForeground(Component c, Color foreground) Recursively walk down and setForeground().
static void	setFormValue(Component c) Recursively walk down and fireValueChanged().
static 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.
static void	setHelpURL(String aHelpURL) Sets the global help url prefix.
static void	setScale(DecimalFormat format, int scale) Changes the format according to the given scale.
static void	setupDefaultBindings(JComponent comp) Registers some default Keyboard Actions for Components.
static void	setWaitCursor(Component comp) Sets the wait-cursor. Determines the parent or related window and applies the cursor.
static void	triggerLocaleChanged() Invokes all locale runnables.
static void	triggerValueChanged(Component c) Recursively walk up and trigger value changed in FormContainers.
static void	updateUIofAllWindows() Updates the UI of all registered windows
static void	updateUIofWindow(Window w) Updates the UI of a given window.
static 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

Field Detail

useSystemPreferencesOnly

public static boolean useSystemPreferencesOnly

true if retrieving and storing preferences refers to the systemRoot only. This feature is nice to configure a system for all users.

preferencesAreReadOnly

public static boolean preferencesAreReadOnly

true if user should not be allowed to write preferences

Constructor Detail

FormHelper

public FormHelper()

Method Detail

registerLocaleRunnable

public static void registerLocaleRunnable(Runnable runnable)

Registers a runnable which will be invoked for each Locale change. There is no unregister because locales are always static.

Parameters:

runnable - the runnable

triggerLocaleChanged

public static void triggerLocaleChanged()

Invokes all locale runnables.

See Also:

registerLocaleRunnable(java.lang.Runnable)

getEventQueue

public static 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

waitForEmptyEventQueue

public static 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 static void setAutoClose(long ms)

Sets the global autoclose feature for all newly created Windows.

Parameters:

ms - timeout in milliseconds. Default is 0.

getAutoClose

public static long getAutoClose()

Gets the global autoclose feature for all newly created Windows.

Returns:

the timeout in milliseconds. Default is 0.

modalToFront

public static void modalToFront()

Brings the current modal dialogs toFront.

addWindow

public static void addWindow(Window w)

Adds window to the set of windows (must be visible or iconified).

Parameters:

w - the window to add

removeWindow

public static 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 static Object[] getWindows()

Gets the current windows which are visible or iconified.

Returns:

the array of windows

updateUIofAllWindows

public static void updateUIofAllWindows()

Updates the UI of all registered windows

updateUIofWindow

public static void updateUIofWindow(Window w)

Updates the UI of a given window.

Parameters:

w - the window

processWindowEvent

public static 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 static 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 static void removeWindowActionListener(ActionListener listener)

Removes a listener.

Parameters:

listener - the listener to be removed

setDefaultFocusTraversalPolicy

public static 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.

doFireValueChanged

public static 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 static 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

setFormValue

public static void setFormValue(Component c)

Recursively walk down and fireValueChanged().

Parameters:

c - the component

setFormValueKeepChanged

public static 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 static void getFormValue(Component c)

Recursively walk down and fireValueEntered().

Parameters:

c - the component

saveValue

public static void saveValue(Component c)

Recursively walk down and saveValue().

Parameters:

c - the component

isValueChanged

public static boolean isValueChanged(Component c)

Recursively walk down and check for value changed.

Parameters:

c - the component

Returns:

true if data has changed in some component

triggerValueChanged

public static void triggerValueChanged(Component c)

Recursively walk up and trigger value changed in FormContainers.

Parameters:

c - the component

setChangeable

public static void setChangeable(Component c,
                                 boolean changeable)

Recursively walk down and setChangeable().

Parameters:

c - the component

changeable - true if changeable

setBackground

public static void setBackground(Component c,
                                 Color background)

Recursively walk down and setBackground().

Parameters:

c - the component

background - the background color

setForeground

public static void setForeground(Component c,
                                 Color foreground)

Recursively walk down and setForeground().

Parameters:

c - the component

foreground - the foreground color

getParentWindow

public static 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 static 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 static 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 static 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 static void invalidateParentInfo(Component c)

Recursively walk down and invalidate the parentInfo.

Parameters:

c - the component

requestFocusLater

public static 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 static 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 static void setDefaultCursor(Component comp)

Sets the default-cursor.
Determines the parent or related window and applies the cursor.

Parameters:

comp - the related component

getCenteredLocation

public static 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 static 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 static 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 static void setupDefaultBindings(JComponent comp)

Registers some default Keyboard Actions for Components. Will also replace some standard actions!

Parameters:

comp - the component

setScale

public static void setScale(DecimalFormat format,
                            int scale)

Changes the format according to the given scale. (leaves the part before the comma unchanged!)

Parameters:

format - the decimal format

scale - the scale

savePreferredSizes

public static 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 static 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 static 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 static 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 static 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 static String getHelpURL()

Gets the global help url prefix.

Returns:

the prefix

openHelpURL

public static void openHelpURL(Component comp)

Opens the online help for a given component.

Parameters:

comp - the component