com.ccg.swing
Class Groupings

java.lang.Object
  com.ccg.swing.Groupings

public class Groupings
extends Object

Allows one to work with various groupings of components.

This class is designed to aid one in working with various groupings of GUI components. It allows one to enable/disable sets of GUI components by simply specifying a name. It also helps one dynamically assign GUI components to various group(s) as they are created.

This is a very handy class. Unfortunately, its simple appearance makes it easy to underestimate to underlying complexities.

Since:

1.0

Version:

$Revision: 1.2 $

Author:

$Author: pkb $

See Also:

Grouping

Constructor Summary

Groupings()
Initializes the object with zero Groupings.

Method Summary

int	addToGroups(String groups, Object o) Do a "smart" add of objects to zero or more different groups.
JComponent	createButtonGrid(TagLookup tl, Object callback, ImageHolder ih) Creates an entire "grid" of buttons AND registers callbacks.
Grouping	createGrouping(String name) Get or create the Grouping associated with a particular name.
Grouping	getGrouping(String name) Get the Grouping associated with a particular name.
boolean	hasGroup(String name) Does the specified group exist?
void	setEnabled(String name, boolean enable) Enable/Disable ALL components in a group.
void	setSelected(String name, boolean enable) Select/Unselect ALL "boolean" components in a group.

Methods inherited from class java.lang.Object

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

Constructor Detail

Groupings

public Groupings()

Initializes the object with zero Groupings.

This method initializes the object such that it will contain no initial groups.

Since:

1.0

See Also:

addToGroups(java.lang.String, java.lang.Object), createGrouping(java.lang.String)

Method Detail

getGrouping

public Grouping getGrouping(String name)

Get the Grouping associated with a particular name.

This method will lookup a group with a particular name. If the group isn't found, null is returned.

Parameters:

name - The name of the group you want. You can pass null - in which case you'll get null back.

Returns:

If a Grouping exists for the specified name, it will be returned, otherwise null will be returned.

See Also:

createGrouping(java.lang.String)

createGrouping

public Grouping createGrouping(String name)

Get or create the Grouping associated with a particular name.

This method will lookup a group with a particular name. If the group isn't found, a new Grouping object will be allocated and associated with the name.

Parameters:

name - The name of the group you want to get or create. If you pass null, you'll get null back.

Returns:

A Grouping for the name will be returned (it will be created if it did not exist). Never returns null unless you pass null.

See Also:

getGrouping(java.lang.String)

hasGroup

public boolean hasGroup(String name)

Does the specified group exist?

Returns:

Current boolean value assigned.

See Also:

getGrouping(java.lang.String)

setEnabled

public void setEnabled(String name,
                       boolean enable)

Enable/Disable ALL components in a group.

This method will invoke the JComponent.setEnabled(boolean) method for each component in the collection (lets you enable/disable the entire group of components).

Parameters:

name - Name of the group you want to enable/disable

enable - Whether the component should be enabled or not.

Since:

1.0

See Also:

setSelected(java.lang.String, boolean)

setSelected

public void setSelected(String name,
                        boolean enable)

Select/Unselect ALL "boolean" components in a group.

This method will invoke the setSelected(boolean) or setState(boolean) method for each JComponent in the specified group that has a "boolean" state associated with it (such as AbstractButton derived objects like the javax.swing.JCheckBoxMenuItem.

Parameters:

name - Name of the group you want to enable/disable

select - Whether the component should be selected (checked) or not.

Since:

1.0

See Also:

setEnabled(java.lang.String, boolean)

addToGroups

public int addToGroups(String groups,
                       Object o)

Do a "smart" add of objects to zero or more different groups.

This method allows one to add a particular item to one or more different groups. Look at the following code fragment:

 JButton b = new JButton("Connect");
 JTextField port = new JTextField("12222");
 JTextField host = new JTextField("server.foo.com");
 
                                // add button just to "start" group
 Groupings g = new Groupings();
 g.addToGroups("start",b);

                                // add config fields to "start" AND "config"
                                // group
 Object[] oa = { port, host };
 g.addToGroups("start,config",oa);

                                // will enabled b, port, and host
 g.setEnabled("start",true);

                                // will disable port and host
 g.setEnabled("config",false);
 

This method is typically used indirectly by components which are dynamically created from resource files (see createButtonGrid(com.ccg.util.TagLookup, java.lang.Object, com.ccg.awt.ImageHolder) for an example.

Parameters:

groups - String specifying the group(s) which the objects are to be added to. The group names can be separated by white space or commas. You can pass null, in which case we don't do anything.

o - The object to "smartly" add to the groups (you can pass null - which means we don't do anything).

Returns:

Total number of components added to various groups

Since:

1.0

See Also:

Grouping.smartAdd(java.lang.Object)

createButtonGrid

public JComponent createButtonGrid(TagLookup tl,
                                   Object callback,
                                   ImageHolder ih)

Creates an entire "grid" of buttons AND registers callbacks.

This method will build an entire grid of buttons from a resource file and install the necessary callbacks so that the buttons will invoke various methods on your object. See the MyClass.java and msgs/MyClass.properties for a working example of how to do this.

Basically, it boils down to:

• Decide on a prefix to "TAG" your button panel with (like "bp" in the example).
• Decide if you want to define the number of rows/columns for the layout using "TAG.rows" and "TAG.cols" values. Typically you will set one of these values to 0 to indicate that the grid grows in that direction. If you omit both values, your buttons will be laid out horizontally.
• Iteratively define the buttons you want to appear (use "TAG.0" for first button, then "TAG.1" and so on for each additional button).
• Specify the "TAG.N.action" that should be called back when the button is pressed for each button that is to appear.
• Optionally specify the attributes for each button (at a minimum, you'll probably want to specify the "TAG.N.text" attribute).
• Optionally, specify a comma separated list of groups which you want the component to belong to.

Parameters:

tl - Where to look for the definitions that define the button grid and the buttons which populate it.

callback - The object which has the methods the buttons are allowed to invoke when pressed (see ActionCallback.create(com.ccg.util.Lookup, javax.swing.AbstractButton, java.lang.Object) for more details - or check out the example mentioned above).

ih - A ImageHolder to retrieve icon images for the buttons (when this becomes supported).

Returns:

A new component which has all of the created buttons installed.

Since:

1.0

See Also:

Resources.setButtonValues(com.ccg.util.TagLookup, javax.swing.AbstractButton, com.ccg.awt.ImageHolder)