hirondelle.stocks.util.ui
Class UiUtil

Object
  UiUtil

public final class UiUtil
extends Object

Static convenience methods for GUIs which eliminate code duplication.

Nested Class Summary

static class	UiUtil.AlignX Enumeration for horizontal alignment.
static class	UiUtil.AlignY Type-safe enumeration vertical alignment.

Constructor Summary

UiUtil()

Method Summary

static JLabel	addSimpleDisplayField(Container aContainer, String aName, Object aValue, GridBagConstraints aConstraints, boolean aWeightOnDisplay) Create a pair of JLabel components, as is typically needed for display of a name-value pair.
static void	addSimpleDisplayFields(Container aContainer, Map<String,String> aNameValuePairs) Present a number of read-only items to the user as a vertical listing of JLabel name-value pairs.
static JTextField	addSimpleEntryField(Container aContainer, String aName, String aInitialValue, int aMnemonic, GridBagConstraints aConstraints, String aTooltip) Create a pair of components, a JLabel and an associated JTextField, as is typically used for user input.
static void	addVerticalGridGlue(JPanel aPanel, int aLastRowIdx) Adds "glue" (an empty component with desired resizing behavior) to the bottom row of a GridBagLayout of components.
static void	alignAllX(Container aContainer, UiUtil.AlignX aAlignment) Imposes a uniform horizontal alignment on all items in a container.
static void	alignAllY(Container aContainer, UiUtil.AlignY aAlignment) Imposes a uniform vertical alignment on all items in a container.
static void	beep() Make the sytem emit a beep.
static void	centerAndShow(Window aWindow) pack, center, and show a window on the screen.
static void	centerOnParentAndShow(Window aWindow) A window is packed, centered with respect to a parent, and then shown.
static void	equalizeSizes(List<JComponent> aComponents) Sets the items in aComponents to the same size.
static JComponent	getCommandColumn(List<JComponent> aButtons) Make a vertical row of buttons of equal size, whch are equally spaced, and aligned on the right.
static JComponent	getCommandRow(List<JComponent> aButtons) Make a horizontal row of buttons of equal size, whch are equally spaced, and aligned on the right.
static GridBagConstraints	getConstraints(int aY, int aX) Return a set of constraints with convenient default values.
static GridBagConstraints	getConstraints(int aY, int aX, int aWidth, int aHeight) Return getConstraints(int, int), with the addition of setting gridwidth to aWidth, and setting gridheight to aHeight.
static String	getDialogTitle(String aSpecificDialogName) Return text which conforms to the Look and Feel Design Guidelines for the title of a dialog : the application name, a colon, then the name of the specific dialog.
static Dimension	getDimensionFromPercent(int aPercentWidth, int aPercentHeight) Return a Dimension whose size is defined not in terms of pixels, but in terms of a given percent of the screen's width and height.
static Icon	getEmptyIcon() Return a square icon which paints nothing, and whose dimensions correspond to the user preference for icon size.
static ImageIcon	getImageIcon(String aImageId) Return an ImageIcon using its String identifier.
static ImageIcon	getImageIcon(String aImageId, Class<?> aClass) Return an ImageIcon using its String identifier, relative to a given class.
static String	getLocalizedInteger(Number aNumber) Return a String, suitable for presentation to the end user, representing an integral number with no decimal places, using the default locale.
static String	getLocalizedPercent(Number aNumber) Return a String, suitable for presentation to the end user, representing a percentage having two decimal places, using the default locale.
static String	getLocalizedTime(Date aDate) Return a String, suitable for presentation to the end user, representing a date in DateFormat.SHORT and the default locale.
static Border	getStandardBorder() Return a border of dimensions recommended by the Java Look and Feel Design Guidelines, suitable for many common cases.
static JTextArea	getStandardTextArea(String aText) An alternative to multi-line labels, for the presentation of several lines of text, and for which the line breaks are determined solely by the widget.
static JTextArea	getStandardTextAreaHardNewLines(String aText) An alternative to multi-line labels, for the presentation of several lines of text, and for which line breaks are determined solely by aText, and not by the widget.
static void	noDefaultButton(JRootPane aRootPane) Ensure that aRootPane has no default button associated with it.

Methods inherited from class Object

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

Constructor Detail

UiUtil

public UiUtil()

Method Detail

centerAndShow

public static void centerAndShow(Window aWindow)

pack, center, and show a window on the screen.

If the size of aWindow exceeds that of the screen, then the size of aWindow is reset to the size of the screen.

centerOnParentAndShow

public static void centerOnParentAndShow(Window aWindow)

A window is packed, centered with respect to a parent, and then shown.

This method is intended for dialogs only.

If centering with respect to a parent causes any part of the dialog to be off screen, then the centering is overidden, such that all of the dialog will always appear fully on screen, but it will still appear near the parent.

Parameters:

aWindow - must have non-null result for aWindow.getParent.

getStandardBorder

public static Border getStandardBorder()

Return a border of dimensions recommended by the Java Look and Feel Design Guidelines, suitable for many common cases.

Each side of the border has size UiConsts.STANDARD_BORDER.

getDialogTitle

public static String getDialogTitle(String aSpecificDialogName)

Return text which conforms to the Look and Feel Design Guidelines for the title of a dialog : the application name, a colon, then the name of the specific dialog.

Example return value: StocksMonitor: Preferences

Parameters:

aSpecificDialogName - must have visible content

getCommandRow

public static JComponent getCommandRow(List<JComponent> aButtons)

Make a horizontal row of buttons of equal size, whch are equally spaced, and aligned on the right.

The returned component has border spacing only on the top (of the size recommended by the Look and Feel Design Guidelines). All other spacing must be applied elsewhere ; usually, this will only mean that the dialog's top-level panel should use getStandardBorder().

Parameters:

aButtons - contains the buttons to be placed in a row.

getCommandColumn

public static JComponent getCommandColumn(List<JComponent> aButtons)

Make a vertical row of buttons of equal size, whch are equally spaced, and aligned on the right.

The returned component has border spacing only on the left (of the size recommended by the Look and Feel Design Guidelines). All other spacing must be applied elsewhere ; usually, this will only mean that the dialog's top-level panel should use getStandardBorder().

Parameters:

aButtons - contains the buttons to be placed in a column

getImageIcon

public static ImageIcon getImageIcon(String aImageId)

Return an ImageIcon using its String identifier.

Parameters:

aImageId - starts with '/', and refers to an image resource which is accessible through Class.getResource(java.lang.String).

getImageIcon

public static ImageIcon getImageIcon(String aImageId,
                                     Class<?> aClass)

Return an ImageIcon using its String identifier, relative to a given class.

Parameters:

aImageId - does NOT start with '/', and must refer to an image resource which is accessible through Class.getResource(java.lang.String).

aClass - the class relative to which the image is located.

getEmptyIcon

public static Icon getEmptyIcon()

Return a square icon which paints nothing, and whose dimensions correspond to the user preference for icon size.

A common problem occurs with text alignment in menus, where there is a mixture of menu items with and without an icon. Adding an empty icon to menu items which do not have one will adjust its alignment to match that of the others which do have an icon.

getDimensionFromPercent

public static final Dimension getDimensionFromPercent(int aPercentWidth,
                                                      int aPercentHeight)

Return a Dimension whose size is defined not in terms of pixels, but in terms of a given percent of the screen's width and height.

Use to set the preferred size of a component to a certain percentage of the screen.

Parameters:

aPercentWidth - percentage width of the screen, in range 1..100.

aPercentHeight - percentage height of the screen, in range 1..100.

equalizeSizes

public static void equalizeSizes(List<JComponent> aComponents)

Sets the items in aComponents to the same size.

Sets each component's preferred and maximum sizes. The actual size is determined by the layout manager, whcih adjusts for locale-specific strings and customized fonts. (See this Sun doc for more information.)

Parameters:

aComponents - items whose sizes are to be equalized

addSimpleEntryField

public static JTextField addSimpleEntryField(Container aContainer,
                                             String aName,
                                             String aInitialValue,
                                             int aMnemonic,
                                             GridBagConstraints aConstraints,
                                             String aTooltip)

Create a pair of components, a JLabel and an associated JTextField, as is typically used for user input.

The JLabel appears on the left, and the JTextField appears on the same row, just to the right of the JLabel. The JLabel has a mnemonic which forwards focus to the JTextField when activated.

Parameters:

aContainer - holds the pair of components.

aName - text of the JLabel component.

aInitialValue - possibly-null initial value to appear in the JTextField; if null, then JTextField will be blank.

aMnemonic - KeyEvent field, used as the mnemonic for the JLabel.

aConstraints - applied to the JLabel; the corresponding constraints for the JTextField are the same as aConstraints, except for gridx being incremented by one; in addition, if aConstraints has weightx=0 (the default), then the entry field will receive weightx=1.0 (entry field gets more horizontal space upon resize).

aTooltip - possibly-null text displayed as tool tip for the JTextField ; if null, the tool tip is turned off.

Returns:

the user input JTextField.

getConstraints

public static GridBagConstraints getConstraints(int aY,
                                                int aX)

Return a set of constraints with convenient default values.

Return constraints with these values :

• gridx, gridy - set to aX, aY
• anchor - GridBagConstraints.WEST
• insets - Insets(0,0,0, UiConsts.ONE_SPACE)

All other items simply take their default values :

• fill - GridBagConstraints.NONE
• gridwidth, gridheight - 0, 0
• weightx , weighty - 0, 0
• ipadx, ipady - 0, 0

The caller is free to change the returned constraints, to customize for their particular needs.

Parameters:

aY - in range 0..10.

aX - in range 0..10.

getConstraints

public static GridBagConstraints getConstraints(int aY,
                                                int aX,
                                                int aWidth,
                                                int aHeight)

Return getConstraints(int, int), with the addition of setting gridwidth to aWidth, and setting gridheight to aHeight.

The caller is free to change the returned constraints, to customize for their particular needs.

Parameters:

aY - in range 0..10.

aX - in range 0..10.

aWidth - in range 1..10.

aHeight - in range 1..10.

addSimpleDisplayField

public static JLabel addSimpleDisplayField(Container aContainer,
                                           String aName,
                                           Object aValue,
                                           GridBagConstraints aConstraints,
                                           boolean aWeightOnDisplay)

Create a pair of JLabel components, as is typically needed for display of a name-value pair.

The name appears on the left, and the value appears on the right, all on the same row. A colon and an empty space are appended to the name.

If the the length of "value" label is greater than UiConsts.MAX_LABEL_LENGTH, then the text is truncated, an ellipsis is placed at its end, and the full text is placed in a tooltip.

Parameters:

aContainer - holds the pair of components.

aName - text of the name JLabel.

aValue - possibly-null ; if null, then an empty String is used for the value; otherwise Object.toString is used.

aConstraints - for the name JLabel; the corresponding constraints for the value JLabel are mostly taken from aConstraints, except for gridx being incremented by one (weightx may differ as well - see aWeightOnDisplay.)

aWeightOnDisplay - if true, then set weightx for the value field to 1.0 (to give it more horizontal space upon resize).

Returns:

the JLabel for the value (which is usually variable).

addSimpleDisplayFields

public static void addSimpleDisplayFields(Container aContainer,
                                          Map<String,String> aNameValuePairs)

Present a number of read-only items to the user as a vertical listing of JLabel name-value pairs.

Each pair is added in the style of addSimpleDisplayField(java.awt.Container, java.lang.String, java.lang.Object, java.awt.GridBagConstraints, boolean) (its aConstraints param are those returned by getConstraints(int, int), and its aWeightOnDisplay param is set to true).

The order of presentation is determined by the iteration order of aNameValuePairs.

The number of items which should be presented using this method is limited, since no scrolling mechanism is given to the user.

Parameters:

aContainer - holds the display fields.

aNameValuePairs - has String keys for the names, and values are possibly null Objects; if null, then an empty String is displayed, otherwise Object.toString is called on the value and displayed.

addVerticalGridGlue

public static void addVerticalGridGlue(JPanel aPanel,
                                       int aLastRowIdx)

Adds "glue" (an empty component with desired resizing behavior) to the bottom row of a GridBagLayout of components. When resized, this glue will take up extra vertical space.

This method is especially useful for text data presented in a listing or tabular form. Such components naturally resize horizontally, while their vertical resizing should often be absent. If such a listing is resized vertically, then this glue can take up the remaining vertical space, keeping the text at the top.

Parameters:

aPanel - uses GridBagLayout, and contains components whose weighty values are all 0.0 (the default).

aLastRowIdx - index of the last row of components, in which the glue will be placed.

getLocalizedPercent

public static String getLocalizedPercent(Number aNumber)

Return a String, suitable for presentation to the end user, representing a percentage having two decimal places, using the default locale.

An example return value is "5.15%". The intent of this method is to provide a standard representation and number of decimals for the entire application. If a different number of decimal places is required, then the caller should use NumberFormat instead.

getLocalizedInteger

public static String getLocalizedInteger(Number aNumber)

Return a String, suitable for presentation to the end user, representing an integral number with no decimal places, using the default locale.

An example return value is "8,000". The intent of this method is to provide a standard representation of integers for the entire application.

getLocalizedTime

public static String getLocalizedTime(Date aDate)

Return a String, suitable for presentation to the end user, representing a date in DateFormat.SHORT and the default locale.

beep

public static void beep()

Make the sytem emit a beep.

May not beep unless the speakers are turned on, so this cannot be guaranteed to work.

getStandardTextArea

public static JTextArea getStandardTextArea(String aText)

An alternative to multi-line labels, for the presentation of several lines of text, and for which the line breaks are determined solely by the widget.

Parameters:

aText - must have visible content, doesn't contain newline characters or html.

Returns:

JTextArea which is not editable, has improved spacing over the supplied default (placing UiConsts.ONE_SPACE on the left and right), which wraps lines on word boundaries, and whose background color is the same as MetalLookAndFeel.getMenuBackground().

getStandardTextAreaHardNewLines

public static JTextArea getStandardTextAreaHardNewLines(String aText)

An alternative to multi-line labels, for the presentation of several lines of text, and for which line breaks are determined solely by aText, and not by the widget.

Parameters:

aText - has visible content

Returns:

JTextArea which is not editable, has improved spacing over the supplied default (placing UiConsts.ONE_SPACE on the left and right), and whose background color is the same as MetalLookAndFeel.getMenuBackground().

alignAllX

public static void alignAllX(Container aContainer,
                             UiUtil.AlignX aAlignment)

Imposes a uniform horizontal alignment on all items in a container.

Intended especially for BoxLayout, where all components need to share the same alignment in order for display to be reasonable. (Indeed, this method may only work for BoxLayout, since apparently it is the only layout to use setAlignmentX, setAlignmentY.)

Parameters:

aContainer - contains only JComponent objects.

alignAllY

public static void alignAllY(Container aContainer,
                             UiUtil.AlignY aAlignment)

Imposes a uniform vertical alignment on all items in a container.

Intended especially for BoxLayout, where all components need to share the same alignment in order for display to be reasonable. (Indeed, this method may only work for BoxLayout, since apparently it is the only layout to use setAlignmentX, setAlignmentY.)

Parameters:

aContainer - contains only JComponent objects.

noDefaultButton

public static void noDefaultButton(JRootPane aRootPane)

Ensure that aRootPane has no default button associated with it.

Intended mainly for dialogs where the user is confirming a delete action. In this case, an explicit Yes or No is preferred, with no default action being taken when the user hits the Enter key.