org.peace_tools.generic
Class Utilities

java.lang.Object
  org.peace_tools.generic.Utilities

public class Utilities
extends java.lang.Object

This class acts as a helper class and contains STATIC methods (only) that acts as helpers to handle some of the common, often performed tasks in the presentation manager

Field Summary

static int	CHECK_BOX_ITEM Constant that can be supplied to the createMenuItem method
static int	MENU_ITEM Constant that can be supplied to the createMenuItem method
static java.lang.String	PATH_PREFIX The default prefix that is added to the path of the files to be loaded by the various methods in this class.
static int	RADIO_BUTTON_ITEM Constant that can be supplied to the createMenuItem method

Constructor Summary

Utilities()

Method Summary

static void	adjustDimension(java.awt.Component c, int xDelta, int yDelta) Helper method to set the preferred and maximum size of a component.
static void	adjustFont(java.awt.Component c, int sizeChange, int minSize, int bold) Utility method to change the font size set for a given component.
static void	centerPanel(java.awt.Window parent, java.awt.Window child) Helper method to center a given child on a parent.
static javax.swing.JPanel	collapsedMessage(java.lang.String message, java.lang.String details) Helper method to create a collapsed pane with message.
static javax.swing.JButton	createButton(java.lang.String iconFileName, java.lang.String title, java.lang.String command, java.awt.event.ActionListener al, java.lang.String toolTip, boolean enable) This method is a utility method to create generic buttons.
static javax.swing.JPanel	createLabeledComponents(java.lang.String label, java.lang.String subLabel, int textBoxHeightDelta, boolean addEndSpacer, java.awt.Component... components) This method is a helper method to lay out components vertically.
static javax.swing.JMenuItem	createMenuItem(int itemKind, java.lang.String itemTitle, java.lang.String command, java.awt.event.ActionListener al, java.lang.String iconFileName, javax.swing.KeyStroke shortCut, boolean enable, boolean auxFlag) This method is a convenience method that provides a simple mechanism for creating a JMenuItem, given the parameters.
static javax.swing.JMenuItem	createMenuItem(int itemKind, java.lang.String itemTitle, java.lang.String subTitle, java.lang.String command, java.awt.event.ActionListener al, java.lang.String iconFileName, javax.swing.KeyStroke shortCut, boolean enable, boolean auxFlag) This method is a convenience method that provides a simple mechanism for creating a JMenuItem, given the parameters.
static javax.swing.JPanel	createSubPanel(int alignment, java.lang.String label, javax.swing.JComponent... components) This method is a helper method that takes the alignment for a FlowLayout, a label to identify the components, and the actual JComponents themselves and places them in a JPanel with a FlowLayout.
static javax.swing.JButton	createToolButton(java.lang.String iconFileName, java.lang.String title, java.lang.String command, java.awt.event.ActionListener al, java.lang.String toolTip, boolean enable) This method is a utility method to create tool bar buttons.
static void	download(javax.swing.ProgressMonitor pm, java.lang.String address, java.lang.String localFileName) Helper method for download a file from a given URL.
static java.lang.String	enableHTMLText(java.lang.String text, boolean enabled) Utility method to modify HTML text to look enabled or disabled.
static java.lang.String	getDefaultDirectory() Helper method to determine the default working directory for PEACE.
static java.lang.String	getExtension(java.io.File f) A helper method to determine the extension of a file.
static javax.swing.ImageIcon	getIcon(java.lang.String path) This method is a quick little helper method to pull image (icons) using getResource(String).
static java.io.InputStream	getStream(java.lang.String resourceName) This is a helper method that can be used to obtain an input stream for a resource.
static byte[]	integerToByteArray(int integer) Returns a byte array containing the two's-complement representation of the integer. The byte array will be in big-endian byte-order with a fixes length of 4 (the least significant byte is in the 4th element). Example: intToByteArray(258) will return { 0, 0, 1, 2 }, BigInteger.valueOf(258).toByteArray() returns { 1, 2 }.
static void	makeToolBarButton(javax.swing.AbstractButton button, boolean fillContentArea) Method to add mouse adapter to make button like a tool bar button.
static java.lang.String	readFullStream(java.io.InputStream is) This is a helper method to read small text data from a stream into a String.
static java.lang.String	readSmallTextFile(java.lang.String fileName) This is a helper method to read small text files (like license information) into a string.
static void	setEnabled(java.awt.Container parent, boolean status) Helper method to recursively enable/disable a component and its children.
static void	setEnabled(javax.swing.JMenuItem menuItem, boolean enabled) Utility method to update menu item text that uses HTML.
static int	toInteger(byte msb, byte lsb) This is a utility method to convert a pair of bytes into a single integer.
static java.lang.String	toString(java.lang.Throwable e) Helper method to convert the stack trace in an exception to a string.

Methods inherited from class java.lang.Object

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

Field Detail

PATH_PREFIX

public static final java.lang.String PATH_PREFIX

The default prefix that is added to the path of the files to be loaded by the various methods in this class. This prefix path enables organizing and collating files appropriately.

See Also:

Constant Field Values

MENU_ITEM

public static final int MENU_ITEM

Constant that can be supplied to the createMenuItem method

See Also:

Constant Field Values

CHECK_BOX_ITEM

public static final int CHECK_BOX_ITEM

Constant that can be supplied to the createMenuItem method

See Also:

Constant Field Values

RADIO_BUTTON_ITEM

public static final int RADIO_BUTTON_ITEM

Constant that can be supplied to the createMenuItem method

See Also:

Constant Field Values

Constructor Detail

Utilities

public Utilities()

Method Detail

createMenuItem

public static javax.swing.JMenuItem createMenuItem(int itemKind,
                                                   java.lang.String itemTitle,
                                                   java.lang.String command,
                                                   java.awt.event.ActionListener al,
                                                   java.lang.String iconFileName,
                                                   javax.swing.KeyStroke shortCut,
                                                   boolean enable,
                                                   boolean auxFlag)

This method is a convenience method that provides a simple mechanism for creating a JMenuItem, given the parameters.

Parameters:

itemKind - This is a enumeration value which can be MENU_ITEM, CHECK_BOX_ITEM, or RADIO_BUTTON_ITEM

itemTitle - String representing the menu option. Note: The string may contain a "_" (underscore) character preceeding the letter that is suppoed to be used as an accelerator for this item. However, if an explicit key stroke is specified (parameter 3 to this method call) then this underscore will be ignored. In either case the "_" will be stripped out of the option! The string cannot be "null"

command - The string representing the action command that will be generated when this menu option is slected!

al - The ActionListener to register with the Menu Item.

iconFileName - String representing the file name of the icon (*.jpg or *.gif) to be assiocated with this menu option. If the name is "null" then no icon is associates with this menu.

shortCut - Keystroke representing the shortcut for this menu item

enable - Boolean value that indicates if this menu item should be enabled by default. "true" implies menu item is enabled and "false" implies the menu item is disabled.

auxFlag - A boolean value that is used to select or unselect a CHECK_BOX_ITEM. Refer to the documentation of CheckBoxMenuItem in Java SDK API for further information

Returns:

The newly created JMenuItem or NULL on error!

createMenuItem

public static javax.swing.JMenuItem createMenuItem(int itemKind,
                                                   java.lang.String itemTitle,
                                                   java.lang.String subTitle,
                                                   java.lang.String command,
                                                   java.awt.event.ActionListener al,
                                                   java.lang.String iconFileName,
                                                   javax.swing.KeyStroke shortCut,
                                                   boolean enable,
                                                   boolean auxFlag)

This method is a convenience method that provides a simple mechanism for creating a JMenuItem, given the parameters.

Parameters:

itemKind - This is a enumeration value which can be MENU_ITEM, CHECK_BOX_ITEM, or RADIO_BUTTON_ITEM

itemTitle - String representing the menu option. Note: The string may contain a "_" (underscore) character preceding the letter that is supposed to be used as an accelerator for this item. However, if an explicit key stroke is specified (parameter 3 to this method call) then this underscore will be ignored. In either case the "_" will be stripped out of the option! The string cannot be "null"

subTitle - A sub title string to be used for this menu item. If this string is null then this method calls the overloaded method that does not take a subTitle as parameter.

command - The string representing the action command that will be generated when this menu option is slected!

al - The ActionListener to register with the Menu Item.

iconFileName - String representing the file name of the icon (*.jpg or *.gif) to be associated with this menu option. If the name is "null" then no icon is associates with this menu.

shortCut - Keystroke representing the shortcut for this menu item

enable - Boolean value that indicates if this menu item should be enabled by default. "true" implies menu item is enabled and "false" implies the menu item is disabled.

auxFlag - A boolean value that is used to select or unselect a CHECK_BOX_ITEM. Refer to the documentation of CheckBoxMenuItem in Java SDK API for further information

Returns:

The newly created JMenuItem or NULL on error!

setEnabled

public static void setEnabled(javax.swing.JMenuItem menuItem,
                              boolean enabled)

Utility method to update menu item text that uses HTML. For some reason when menu items use HTML for formatting the enabling/disabling of the text does not operate correctly because HTML ignores default color settings. This method introduces colors into the menu items to make them appear enabled/disabled.

Note:Calling this method with menu items whose text is not HTML causes no side effects. So it is safe to call this method with any menu item.

Parameters:

menuItem - The menu item that must be enabled or disabled.

enabled - If this parameter is true, then the menu item is enabled. Otherwise it is disabled.

enableHTMLText

public static java.lang.String enableHTMLText(java.lang.String text,
                                              boolean enabled)

Utility method to modify HTML text to look enabled or disabled. For some reason when labels or menu items use HTML for formatting the enabling/disabling of the text does not operate correctly because HTML ignores default color settings. This method introduces colors into the HTML text to make them appear enabled/disabled.

Note:Calling this method with text that is not HTML causes no side effects. So it is safe to call this method with any text.

Parameters:

text - The message whose text is to be modified to make it appear enabled to disabled.

enabled - If this parameter is true, then the text is updated to appear enabled. Otherwise it is set to appear disabled.

Returns:

The modified string. If the original message wasn't HTML then this method simply returns the original text.

createButton

public static javax.swing.JButton createButton(java.lang.String iconFileName,
                                               java.lang.String title,
                                               java.lang.String command,
                                               java.awt.event.ActionListener al,
                                               java.lang.String toolTip,
                                               boolean enable)

This method is a utility method to create generic buttons.

Parameters:

iconFileName - A string representing the icon file (gif/jpeg) that is to be associated with this button

title - A string representing the title for this button

command - The command string to be generated when this button is clicked

al - The action listener for this button. When the button is clicked the action listener gets triggered by the java system where the processing for the button click is performed

toolTip - The string to be associated with the tool tip associated with this button

enable - A boolean that indicates if the button must be enabled by default ("true" => button enabled. "false" => button disabled)

Returns:

A button that meets the specifications

createToolButton

public static javax.swing.JButton createToolButton(java.lang.String iconFileName,
                                                   java.lang.String title,
                                                   java.lang.String command,
                                                   java.awt.event.ActionListener al,
                                                   java.lang.String toolTip,
                                                   boolean enable)

This method is a utility method to create tool bar buttons. This method is synonymous to calling createButton followed by makeToolBarButton.

Parameters:

iconFileName - A string representing the icon file (gif/jpeg) that is to be associated with this button

title - A string representing the title for this button

command - The command string to be generated when this button is clicked

al - The action listener for this button. When the button is clicked the action listener gets triggered by the java system where the processing for the button click is performed

toolTip - The string to be associated with the tool tip associated with this button

enable - A boolean that indicates if the button must be enabled by default ("true" => button enabled. "false" => button disabled)

Returns:

A button that meets the specifications

makeToolBarButton

public static void makeToolBarButton(javax.swing.AbstractButton button,
                                     boolean fillContentArea)

Method to add mouse adapter to make button like a tool bar button. This method can be used to add a custom mouse adapter to a given button to make it behave like a tool bar button. The mouse adapter displays the background and border when a mouse enters the button. Similarly the mouse adapter clears out the background color and border when the mouse exits.

Parameters:

button - The button whose properties have to be modified.

fillContentArea - If this parameter is true, then filling of the content area is enabled when the mouse rolls over a button.

createSubPanel

public static javax.swing.JPanel createSubPanel(int alignment,
                                                java.lang.String label,
                                                javax.swing.JComponent... components)

This method is a helper method that takes the alignment for a FlowLayout, a label to identify the components, and the actual JComponents themselves and places them in a JPanel with a FlowLayout. The panel is useful for situations that require multiple panels to create a vertical layout of many components. (Note: FlowLayout performs only a horizontal layout)

Parameters:

alignment - The Alignment, one of FlowLayout.LEFT, FlowLayout.RIGHT, FlowLayout.CENTER, FlowLayout.LEADING or FlowLayout.TRAILING

label - The label to put before the components (gets converted into a JLabel, set to null for none)

components - One or more comma seperated components to place in the JPanel.

Returns:

A new JPanel containing all of the specified components

createLabeledComponents

public static javax.swing.JPanel createLabeledComponents(java.lang.String label,
                                                         java.lang.String subLabel,
                                                         int textBoxHeightDelta,
                                                         boolean addEndSpacer,
                                                         java.awt.Component... components)

This method is a helper method to lay out components vertically. This is a helper method that is used to layout components in a vertical manner. In addition, this method also creates a label at the top of the components (if a non-null string is specified).

Parameters:

label - The label to put before the components (gets converted into a JLabel, set to null for none)

subLabel - A sub-label to be placed below the main label. This label is displayed with a smaller font if it is not null.

textBoxHeightDelta - If this parameter is non-zero then it adds this value to the preferred height of any JTextField components in the component list. This feature is useful to ensure that text fields are not too small (they happen to be in GTK)

addEndSpacer - If this flag is true, then this method adds a trailing empty component that will stretch to take up any available vertical space.

components - One or more comma separated components to place in the JPanel.

Returns:

A new JPanel containing all of the specified components

getIcon

public static javax.swing.ImageIcon getIcon(java.lang.String path)

This method is a quick little helper method to pull image (icons) using getResource(String).

Parameters:

path - The path of the image (relative)

Returns:

An image icon built from that path

getExtension

public static java.lang.String getExtension(java.io.File f)

A helper method to determine the extension of a file.

Parameters:

f - The file whose extension needs to be determined

Returns:

A string containing the extension

toInteger

public static int toInteger(byte msb,
                            byte lsb)

This is a utility method to convert a pair of bytes into a single integer.

Parameters:

msb - The most significant byte of the number.

lsb - The least significant byte of the number.

Returns:

The integer value generated by combining the msb and lsb values.

integerToByteArray

public static byte[] integerToByteArray(int integer)

Returns a byte array containing the two's-complement representation of the integer.
The byte array will be in big-endian byte-order with a fixes length of 4 (the least significant byte is in the 4th element).

Example:
intToByteArray(258) will return { 0, 0, 1, 2 },
BigInteger.valueOf(258).toByteArray() returns { 1, 2 }.

Parameters:

integer - The integer to be converted.

Returns:

The byte array of length 4.

adjustFont

public static void adjustFont(java.awt.Component c,
                              int sizeChange,
                              int minSize,
                              int bold)

Utility method to change the font size set for a given component.

Parameters:

c - The component whose current font size is to be changed.

sizeChange - The change in font size. This value gets added to the component's current font size to determine the new font size. Therefore, positive values will increase the font size while negative values will decrease the font size.

minSize - The minimum font size below which the font value must never drop.

bold - If this value is 1, then the font is made bold. If this value is -1, the font is made normal. If this value is 0 then the weight of the font is unchanged.

download

public static void download(javax.swing.ProgressMonitor pm,
                            java.lang.String address,
                            java.lang.String localFileName)
                     throws java.lang.Exception

Helper method for download a file from a given URL. This method is a helper method that can be used to download a file from a given URL and save it under a given local file. This method provides an optional feature of updating progress via a progress monitor dialog.

Parameters:

pm - The progress monitor to be updated as data is downloaded.

address - The URL from where the data is to be downloaded/copied.

localFileName - The name of the local file (with optional path) where the data is to be saved.

Throws:

java.lang.Exception - This method throws various exception on errors.

getStream

public static java.io.InputStream getStream(java.lang.String resourceName)
                                     throws java.lang.Exception

This is a helper method that can be used to obtain an input stream for a resource. This method is a convenience method that performs best effort to obtain a valid input stream. Specifically it handles the following two cases:

• First it attempts to load the file from the root path by prepending a "/" to the resourceName (which is typically a file name). This handles the case where the resource is to be loaded from a Jar file.
• If the above step fails, it attempts to obtain the resource by prepending the PATH_PREFIX constant defined in this class to the resource name.

Parameters:

resourceName - The relative path/name of the resource to which an input stream is desired.

Returns:

A valid input stream to the requested resource.

Throws:

java.lang.Exception - This method throws an exception if a valid input stream could not be created to the specified resource.

readSmallTextFile

public static java.lang.String readSmallTextFile(java.lang.String fileName)
                                          throws java.lang.Exception

This is a helper method to read small text files (like license information) into a string. This is a helper method that can read a text file into a string. This method is meant to read and work with small text files, particularly for display purposes in the GUI. This method should not be used to load large files as it does use a lot of memory to hold the text data. This method read files either from a Jar file or from the file system.

Parameters:

fileName - The name of the file to be loaded. Prefer to use relative path names so that the file can be loaded immaterial of whether it is from a jar or from the local file system.

Returns:

A string containing the entire contents of the given text file. All new lines and other special characters (if any) are preserved.

Throws:

java.lang.Exception - This method throws an exception if errors occur during reading the file.

readFullStream

public static java.lang.String readFullStream(java.io.InputStream is)
                                       throws java.lang.Exception

This is a helper method to read small text data from a stream into a String. This is a helper method that can read textual data into a string. This method is meant to read and work with small files, particularly for display purposes in the GUI. This method should not be used to load large files as it does use a lot of memory to hold the text data. This method read files either from a given stream.

Parameters:

is - The input stream from where the data is to be read.

Returns:

A string containing the entire contents of the given text file. All new lines and other special characters (if any) are preserved. If the stream did not have any characters then this method returns an empty string.

Throws:

java.lang.Exception - This method throws an exception if errors occur during reading the stream.

adjustDimension

public static void adjustDimension(java.awt.Component c,
                                   int xDelta,
                                   int yDelta)

Helper method to set the preferred and maximum size of a component. This is a helper method that can be used to adjust the preferred and maximum sizes of a component.

Parameters:

c - The component whose sizes are to be adjusted.

xDelta - The change in width with respect to current width.

yDelta - The change in height with respect to current height.

setEnabled

public static void setEnabled(java.awt.Container parent,
                              boolean status)

Helper method to recursively enable/disable a component and its children. This is a helper method that can be used to recursively enable or disable a component and its children. This is a feature that is not provided by swing.

Parameters:

parent - The parent component whose status is to be changed.

status - If true, the components are enabled otherwise the component is disabled.

toString

public static java.lang.String toString(java.lang.Throwable e)

Helper method to convert the stack trace in an exception to a string.

Parameters:

e - The exception to whose stack trace and information is desired.

Returns:

A string containing the exception's stack trace.

collapsedMessage

public static javax.swing.JPanel collapsedMessage(java.lang.String message,
                                                  java.lang.String details)

Helper method to create a collapsed pane with message. This is a convenience utility method that creates a panel that contains two pieces of information. The first one is a "message" that is placed within a JLabel to be displayed to the user. This information is constantly visible. The second parameter "details", is placed within a JTextArea (inside a scroll pane) that is initially not visible. The text area is made visible only when the user clicks on a "Details" button that is created by this method. The complete JPanel can then be placed within other dialogs (such as JOptionPane.showMessageDialog()) to provide additional information to the user in a form that does not overwhelm the user with information.

Parameters:

message - The message that is to be constantly displayed to the user via a JLabel.

details - The extra information that will be placed within a JTextArea that is hidden (or shown) depending on the user's choice (indicated by clicking on the details button)

Returns:

This method returns the JPanel containing a collapsed details box with the details.

getDefaultDirectory

public static java.lang.String getDefaultDirectory()

Helper method to determine the default working directory for PEACE. This method returns a suitable working directory PATH depending on the operating system.

Returns:

The default working directory for PEACE.

centerPanel

public static void centerPanel(java.awt.Window parent,
                               java.awt.Window child)

Helper method to center a given child on a parent. This method is a helper method that can be used to center a given child component on a parent component.

Parameters:

parent - The parent component on which the child component is to be centered.

child - The child component to be centered.