com.ccg.values
Class ValuesConfigList

java.lang.Object
  com.ccg.values.ValuesConfigList

public final class ValuesConfigList
extends Object

A configuration chooser (and optional editor) which lets the end user pick configurations from a named list.

This class is used to allow the user to scroll through the available configurations and optionally edit, add new, or remove existing configurations.

The general usage of this class goes as follows:

• Construct the object.
• Configure the object (indicate what buttons you would like shown and whether or not there is a associated editor). At a minimum, the ValuesConfigModel must be set.
• Get the graphical component and add it to your GUI.
• Optionally register any list selection listeners.

Since:

1.0

Version:

$Revision: 1.1 $

Author:

$Author: pkb $

See Also:

ValuesConfigModel

Field Summary

static int	ADD Bit mask option which can be passed to setButtons to request a "Add" button.
static int	ALL Bit mask option which can be passed to setButtons to request that all possible buttons be added.
static int	EAST Bit mask option which controls where the buttons are placed.
static int	EDIT Bit mask option which can be passed to setButtons to request a "Edit" button.
static int	REMOVE Bit mask option which can be passed to setButtons to request a "Remove" button.
static int	SOUTH Bit mask option which controls where the buttons are placed.

Constructor Summary

ValuesConfigList()
Default construction of the object - will NOT be ready for use.

ValuesConfigList(ValuesConfigModel vcm, ValuesEditor ve, int bmask)
Allows one to fully configure the object at time of construction.

Method Summary

void	addChangeListener(ChangeListener cl) Add a "change listener" to notify if the user modifies any of the values in the model.
void	addListSelectionListener(ListSelectionListener lsl) Add a "list selection listener" to notify if the user selects a different configuration from the list.
int	getButtons() Get the desired buttons to be included at the bottom of the configuration list.
JComponent	getComponent() Get the Swing component the user will interact with.
ValuesEditor	getEditor() Get the optional ValuesEditor to allow the user to add/edit configurations.
int	getMinListRows() Get the minimum number of rows to appear in the configuration list.
ValuesConfigModel	getModel() Get the ValuesConfigModel associated with the list.
void	removeChangeListener(ChangeListener l) Remove a "change listener" that had been previously added.
void	removeListSelectionListener(ListSelectionListener lsl) Remove a "list selection listener" which had previously been added.
void	setButtons(int val) Set the desired buttons to be included at the bottom of the configuration list.
void	setEditor(ValuesEditor val) Set the optional ValuesEditor to allow the user to add/edit configurations.
void	setMinListRows(int val) Set the minimum number of rows to appear in the configuration list.
void	setModel(ValuesConfigModel val) Set the ValuesConfigModel associated with the list.

Methods inherited from class java.lang.Object

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

Field Detail

EDIT

public static final int EDIT

Bit mask option which can be passed to setButtons to request a "Edit" button.

This constant is used to make a request that the "Edit" button appear in addition to the list of configuration choices. This is only a request and will only be honored if a non-null editor has been set.

Since:

1.0

See Also:

setButtons(int), Constant Field Values

ADD

public static final int ADD

Bit mask option which can be passed to setButtons to request a "Add" button.

This constant is used to make a request that the "Add" button appear in addition to the list of configuration choices. This is only a request and will only be honored if a non-null editor has been set.

Since:

1.0

See Also:

setButtons(int), Constant Field Values

REMOVE

public static final int REMOVE

Bit mask option which can be passed to setButtons to request a "Remove" button.

This constant is used to make a request that the "Remove" button appear in addition to the list of configuration choices.

Since:

1.0

See Also:

setButtons(int), Constant Field Values

SOUTH

public static final int SOUTH

Bit mask option which controls where the buttons are placed.

This constant can be bit OR'ed with the other constants when setting the button options. This flag indicates that you want the buttons to appear south of the list instead of the default position (which is east of the list).

Since:

1.0

See Also:

setButtons(int), Constant Field Values

EAST

public static final int EAST

Bit mask option which controls where the buttons are placed.

This constant can be bit OR'ed with the other constants when setting the button options. This flag indicates that you want the buttons to appear east of the list instead of the default position (which is east of the list).

Since:

1.0

See Also:

setButtons(int), Constant Field Values

ALL

public static final int ALL

Bit mask option which can be passed to setButtons to request that all possible buttons be added.

This constant is used to make a request that ALL of the available buttons which can be created, should be added to the list of configuration choices.

Since:

1.0

See Also:

setButtons(int), Constant Field Values

Constructor Detail

ValuesConfigList

public ValuesConfigList()

Default construction of the object - will NOT be ready for use.

This default constructor leaves the object in a unusable state. You must use the setModel method before the object will be able to be used.

Since:

1.0

See Also:

setModel(com.ccg.values.ValuesConfigModel)

ValuesConfigList

public ValuesConfigList(ValuesConfigModel vcm,
                        ValuesEditor ve,
                        int bmask)

Allows one to fully configure the object at time of construction.

This method should fully construct and initialize the object such that one can immediately use the getComponent method.

Parameters:

vcm - New ValuesConfigModel value to assign (must not be null).

ve - The ValuesEditor to be used when allowing the user to edit/add configurations (may be null).

val - Bit mask of desired buttons (see setButtons.

Throws:

NullPointerException - If you pass null.

See Also:

setModel(com.ccg.values.ValuesConfigModel), setEditor(com.ccg.values.ValuesEditor), setButtons(int)

Method Detail

setModel

public void setModel(ValuesConfigModel val)

Set the ValuesConfigModel associated with the list.

This method allows one to configure the ValuesConfigModel associated with the list. It is illegal to use this method if the component has already been realized.

Parameters:

val - New ValuesConfigModel value to assign (must not be null).

Throws:

NullPointerException - If you pass null.

IllegalStateException - If the graphical component has already been realized via getComponent.

See Also:

getModel()

getModel

public ValuesConfigModel getModel()

Get the ValuesConfigModel associated with the list.

Returns:

Current ValuesConfigModel value assigned (will never return null if the graphical component has been realized).

See Also:

setModel(com.ccg.values.ValuesConfigModel)

setEditor

public void setEditor(ValuesEditor val)

Set the optional ValuesEditor to allow the user to add/edit configurations.

If you would like to allow the user the ability to edit and/or add configurations, you need to set a non-null editor (which is compatible with your ValuesConfig model). If you pass null (or do not specify one), then the ADD and EDIT options will be ignored.

Parameters:

val - The ValuesEditor to be used when allowing the user to edit/add configurations (may be null).

Throws:

IllegalStateException - If the graphical component has already been realized via getComponent.

See Also:

getEditor()

getEditor

public ValuesEditor getEditor()

Get the optional ValuesEditor to allow the user to add/edit configurations.

Returns:

Current ValuesEditor value assigned (possibly null).

See Also:

setEditor(com.ccg.values.ValuesEditor)

setButtons

public void setButtons(int val)

Set the desired buttons to be included at the bottom of the configuration list.

This method may only be used prior to getComponentMethod to indicate what (if any) actions should be presented to the user. You can use the ALL to indicate that you want all of the possible buttons, or use a bit or combination of ADD, REMOVE and/or EDIT.

Please note, that this is only a request. It is possible that fewer buttons will appear (for example, if you request the EDIT button, but don't provied a editor, then the edit button will NOT be displayed).

Parameters:

val - New int value to assign.

Throws:

IllegalStateException - If the graphical component has already been realized via getComponent.

See Also:

getButtons()

getButtons

public int getButtons()

Get the desired buttons to be included at the bottom of the configuration list.

Returns:

Current int value assigned.

See Also:

setButtons(int)

setMinListRows

public void setMinListRows(int val)

Set the minimum number of rows to appear in the configuration list.

This parameter allows one to control how many rows (at a minimum) will appear in the scrollable configuration list area.

Parameters:

val - New int value to assign (must be in the range of [1,100].

Throws:

IllegalArgumentException - If you pass a value which is out of range.

See Also:

getMinListRows()

getMinListRows

public int getMinListRows()

Get the minimum number of rows to appear in the configuration list.

Returns:

Current int value assigned.

See Also:

setMinListRows(int)

getComponent

public JComponent getComponent()

Get the Swing component the user will interact with.

You should only use this method once you have specified all of the desirable settings (you can't change settings once the component has been realized). In particular, you MUST set the values config model.

Returns:

A Swing component which the user can interact with to choose and possibly create/edit/delete configurations from.

Throws:

IllegalStateException - If the model wasn't set.

Since:

1.0

addChangeListener

public final void addChangeListener(ChangeListener cl)

Add a "change listener" to notify if the user modifies any of the values in the model.

This method allows developers to determine if the user has modified (removed, edited or added) a configuration. Currently, this doesn't tell you what happened - just that something changed.

NOTE: This does not include the selection of a choice from the list - you can use the model to monitor selection events.

Parameters:

cl - The ChangeListener to notify of modifications.

Since:

1.0

removeChangeListener

public final void removeChangeListener(ChangeListener l)

Remove a "change listener" that had been previously added.

Parameters:

cl - The ChangeListener to remove from the notification list.

Since:

1.0

addListSelectionListener

public final void addListSelectionListener(ListSelectionListener lsl)

Add a "list selection listener" to notify if the user selects a different configuration from the list.

This method allows developers to determine if the user has chosen a different configuration from the list of available choices. It does not indicate that the configuration has been modified in any way, just that a configuration has been chosen.

Parameters:

cl - The ListSelectionListener to notify of modifications.

Since:

1.0

removeListSelectionListener

public final void removeListSelectionListener(ListSelectionListener lsl)

Remove a "list selection listener" which had previously been added.

Parameters:

cl - The ListSelectionListener to stop notifying of modifications.

Since:

1.0