com.internationalnetwork.gui
Class GridBag<Type extends java.awt.Container>

Object
  extended by com.internationalnetwork.gui.GridBag<Type>

public class GridBag<Type extends java.awt.Container>
extends Object

This class provides a series of convenience methods that help to simplify the GridBagLayout classes.  A set of simple keywords are supported so that all the constraints can be provided in a simple one-step method call (and some HTML-table-like aliases are also provided for additional convenience).

Although this may seem like duplication of what is already available with the java.awt.GridBagLayout and its side-kick, java.awt.GridBagConstraints, this class removes much of the tedious aspects of GridBagLayout programming and can result in code that requires less effort to comprehend and is easier to maintain.


Field Summary
static String DESCRIPTION
          Description of this Package (read-only).
static String VERSION
          Version number of this Package (read-only).
 
Constructor Summary
GridBag(Type container)
          This is the main constructor, and is the point where the GridBagLayout is added to the specified container (by way of using the setLayout method).
GridBag(Type container, java.awt.GridBagConstraints constraints)
          This is the main constructor, and is the point where the GridBagLayout is added to the specified container (by way of using the setLayout method).
GridBag(Type container, String... settings)
          This is the main constructor, and is the point where the GridBagLayout is added to the specified container (by way of using the setLayout method).
 
Method Summary
 GridBag add(java.awt.Component component, String... settings)
          Adds a component to the current cell (any settings that specify the "gridx" and/or "gridy" positions will be processed first).
 GridBag add(javax.swing.JComponent component, String... settings)
          Adds a JComponent to the current cell (any settings that specify the "gridx" and/or "gridy" positions will be processed first).
 java.awt.GridBagConstraints getConstraints()
          Returns the GridBagContraints object (this shouldn't be needed because the point of this class is to handle all of these details conveniently).
 Type getContainer()
          Returns the container that was provided with the constructor.  This might be useful for minimizing the number of objects being passed along to other methods.
 java.awt.GridBagLayout getLayout()
          Returns the GridBagLayout object (which is usually needed for the setLayout method with containers the JFrame or JPanel, but this shouldn't be needed because the point of this class is to handle all of these details conveniently).
 char lookup(java.awt.Component component, char alternative)
          Converts the supplied Component to a char, using the internal Component reference.  The "ref=" setting is used to define the character for one or more Components.  If you have a JButton and a JLabel that should both trigger the same action, then they can both have the same "ref=" setting and your code will only need to test for one primitive "char" to determine if an event occurred (this results in much simpler and cleaner code, which should be easier to maintain in the long-run).
 char lookup(JListenerEvent jListenerEvent, char alternative, int... actions)
          Converts the supplied JListenerEvent's Component to a char, using the internal Component reference.  The "ref=" setting is used to define the character for one or more Components.  If you have a JButton and a JLabel that should both trigger the same action, then they can both have the same "ref=" setting and your code will only need to test for one primitive "char" to determine if an event occurred (this results in much simpler and cleaner code, which should be easier to maintain in the long-run).
 char lookupKey(JListenerEvent jListenerEvent, char alternative, int... actions)
          Similar to the lookup() method, except that if the Component comes from a KeyListener then the keystroke's character will be returned instead of the converted reference character code (see the IMPORTANT NOTE in the lookup() method for more information).
 GridBag nextColumn()
          Proceed to the next column by incrementing the "gridx" constraint.  If the column doesn't exist yet, it will NOT be added automatically by the underlying GridBagLayout object.
 GridBag nextCR()
          Proceed to the next row by incrementing the "gridy" constraint, and reset the column to 0 (the first column).  If the row doesn't exist yet, it will NOT be added automatically by the underlying GridBagLayout object and the row won't be incremented.
 GridBag nextRow()
          Proceed to the next row by incrementing the "gridy" constraint.  If the row doesn't exist yet, it will NOT be added automatically by the underlying GridBagLayout object.
 GridBag set(String... settings)
          Use this to set any of the following keys which are expressed in the form of a String that represents key=value pairs.  Multiple key=value pairs may be specified in a single String by using one or more spaces to separate them:
 GridBag setConstraints(java.awt.GridBagConstraints constraints)
          Replaces the current GridBagConstraints.  This is useful if the same settings from another GridBagLayout need to be duplicated here.
 
Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DESCRIPTION

public static final String DESCRIPTION
Description of this Package (read-only).

See Also:
Constant Field Values

VERSION

public static final String VERSION
Version number of this Package (read-only).

See Also:
Constant Field Values
Constructor Detail

GridBag

public GridBag(Type container)
This is the main constructor, and is the point where the GridBagLayout is added to the specified container (by way of using the setLayout method).

Parameters:
container - The container, such as a JFrame or JPanel, that the underlying GridBagLayout will be applied to.

GridBag

public GridBag(Type container,
               java.awt.GridBagConstraints constraints)
This is the main constructor, and is the point where the GridBagLayout is added to the specified container (by way of using the setLayout method).

The GridBagConstraints object you provide will be used and overrides all Java defaults.

A clone() of the GridBagConstraints is stored by this method to prevent an unexpected external change (e.g., in a separate thread) from causing unpredictable results.

Parameters:
container - The container, such as a JFrame or JPanel, that the underlying GridBagLayout will be applied to.
constraints - - A specific set of GridBagConstraints to use

GridBag

public GridBag(Type container,
               String... settings)
This is the main constructor, and is the point where the GridBagLayout is added to the specified container (by way of using the setLayout method).

See the set() method for documentation on how to specify parameters.

If the "ref=" parameter is specified here, it will be applied to the container then reset back to its default (null), as usual.

Parameters:
container - The container, such as a JFrame or JPanel, that the underlying GridBagLayout will be applied to.
settings - - Settings to parse and implement
Method Detail

add

public GridBag add(java.awt.Component component,
                   String... settings)
Adds a component to the current cell (any settings that specify the "gridx" and/or "gridy" positions will be processed first).

Parameters:
component - - The component to add (may be a JLabel, JPanel, JTextField, JButton, JScreen, JCheckBox, JList, etc.)
settings - - Settings to parse and implement
Returns:
GridBag - This object (as a convenience to developers who wish to stack a group of method calls together)

add

public GridBag add(javax.swing.JComponent component,
                   String... settings)
Adds a JComponent to the current cell (any settings that specify the "gridx" and/or "gridy" positions will be processed first).

Parameters:
component - - The JComponent to add (may be a JLabel, JPanel, JTextField, JButton, JScreen, JCheckBox, JList, etc.)
settings - - Settings to parse and implement
Returns:
GridBag - This object (as a convenience to developers who wish to stack a group of method calls together)

getConstraints

public java.awt.GridBagConstraints getConstraints()
Returns the GridBagContraints object (this shouldn't be needed because the point of this class is to handle all of these details conveniently).

Returns:
GridBagConstraints (self-explanatory)

getContainer

public Type getContainer()
Returns the container that was provided with the constructor.  This might be useful for minimizing the number of objects being passed along to other methods.

Returns:
Type (self-explanatory)

getLayout

public java.awt.GridBagLayout getLayout()
Returns the GridBagLayout object (which is usually needed for the setLayout method with containers the JFrame or JPanel, but this shouldn't be needed because the point of this class is to handle all of these details conveniently).

Returns:
GridBagLayout (self-explanatory)

lookup

public char lookup(java.awt.Component component,
                   char alternative)
Converts the supplied Component to a char, using the internal Component reference.  The "ref=" setting is used to define the character for one or more Components.  If you have a JButton and a JLabel that should both trigger the same action, then they can both have the same "ref=" setting and your code will only need to test for one primitive "char" to determine if an event occurred (this results in much simpler and cleaner code, which should be easier to maintain in the long-run).

This is a convenience method that can be used in conjunction with event processing to reduce the amount of coding required to handle a combination of keyboard and mouse events on multiple Components that co-exist in a single JFrame.  The resulting "char" can then be used in a switch() statement to handle the event appropriately.

If a reference to the Component doesn't exist, then the alternative "char" will be returned instead since primitive types cannot be substituted with a null.  One of the really useful techniques here is that the character from a KEY_TYPED event can be supplied here to further simplify your event handling code since one main switch() statement can then handle all events since they can each now be represented by single characters.

IMPORTANT NOTE:  Due to the way the KeyEvent class was designed, the first JComponent will usually be the source Component (unless it's editable) and you MUST use the KeyEvent.getChar() method to determine which key was actually pressed -- the lookupKey() method resolves this problem.

Parameters:
component - - The component to obtain the referenced character for (may be a JLabel, JPanel, JTextField, JButton, JScreen, JCheckBox, JList, etc.)
alternative - - The default character to return if the lookup fails
Returns:
char - Based on the relevant "ref=" setting

lookup

public char lookup(JListenerEvent jListenerEvent,
                   char alternative,
                   int... actions)
Converts the supplied JListenerEvent's Component to a char, using the internal Component reference.  The "ref=" setting is used to define the character for one or more Components.  If you have a JButton and a JLabel that should both trigger the same action, then they can both have the same "ref=" setting and your code will only need to test for one primitive "char" to determine if an event occurred (this results in much simpler and cleaner code, which should be easier to maintain in the long-run).

This is a convenience method that can be used in conjunction with event processing to reduce the amount of coding required to handle a combination of keyboard and mouse events on multiple Components that co-exist in a single JFrame.  The resulting "char" can then be used in a switch() statement to handle the event appropriately.

If a reference to the JListenerEvent's Component doesn't exist, then the alternative "char" will be returned instead since primitive types cannot be substituted with a null.  One of the really useful techniques here is that the character from a KEY_TYPED event can be supplied here to further simplify your event handling code since one main switch() statement can then handle all events since they can each now be represented by single characters.

IMPORTANT NOTE:  Due to the way the KeyEvent class was designed, the first JComponent will usually be the source Component (unless it's editable) and you MUST use the KeyEvent.getChar() method to determine which key was actually pressed -- the lookupKey() method resolves this problem.

Parameters:
jListenerEvent - - The event to obtain the referenced character for
alternative - - The default character to return if the lookup fails
actions - - If defined, then only the actions listed here will be converted (examples of relevant actions are ActionEvent.ACTION_PERFORMED, KeyEvent.KEY_TYPED, MouseEvent.MOUSE_CLICKED, WindowEvent.WINDOW_CLOSING, etc.)
Returns:
char - Based on the relevant "ref=" setting

lookupKey

public char lookupKey(JListenerEvent jListenerEvent,
                      char alternative,
                      int... actions)
Similar to the lookup() method, except that if the Component comes from a KeyListener then the keystroke's character will be returned instead of the converted reference character code (see the IMPORTANT NOTE in the lookup() method for more information).

Parameters:
jListenerEvent - - The event to obtain the referenced character for
alternative - - The default character to return if the lookup fails
actions - - If defined, then only the actions listed here will be converted (examples of relevant actions are ActionEvent.ACTION_PERFORMED, KeyEvent.KEY_TYPED, MouseEvent.MOUSE_CLICKED, WindowEvent.WINDOW_CLOSING, etc.)
Returns:
char - Based on the relevant "ref=" setting

nextColumn

public GridBag nextColumn()
Proceed to the next column by incrementing the "gridx" constraint.  If the column doesn't exist yet, it will NOT be added automatically by the underlying GridBagLayout object.

Returns:
GridBag - This object (as a convenience to developers who wish to stack a group of method calls together)

nextCR

public GridBag nextCR()
Proceed to the next row by incrementing the "gridy" constraint, and reset the column to 0 (the first column).  If the row doesn't exist yet, it will NOT be added automatically by the underlying GridBagLayout object and the row won't be incremented.

"CR" is an acronym for "Carriage Return," which originated with typewriters where the typist would turn a handle on the right-hand side to advance the carriage by one row and return it to the left side, ready for more typing.

Returns:
GridBag - This object (as a convenience to developers who wish to stack a group of method calls together)

nextRow

public GridBag nextRow()
Proceed to the next row by incrementing the "gridy" constraint.  If the row doesn't exist yet, it will NOT be added automatically by the underlying GridBagLayout object.

The column will not be updated.

Returns:
GridBag - This object (as a convenience to developers who wish to stack a group of method calls together)

set

public GridBag set(String... settings)
Use this to set any of the following keys which are expressed in the form of a String that represents key=value pairs.  Multiple key=value pairs may be specified in a single String by using one or more spaces to separate them:

Parameters:
settings - - Settings to parse and implement
Returns:
GridBag - This object (as a convenience to developers who wish to stack a group of method calls together)

setConstraints

public GridBag setConstraints(java.awt.GridBagConstraints constraints)
Replaces the current GridBagConstraints.  This is useful if the same settings from another GridBagLayout need to be duplicated here.

A clone() of the GridBagConstraints is stored by this method to prevent an unexpected external change (e.g., in a separate thread) from causing unpredictable results.

Parameters:
constraints - - The new GridBagConstraints to use
Returns:
GridBag This object (as a convenience to developers who wish to stack a group of method calls together)