com.ccg.values
Interface ValuesEditor

All Superinterfaces:

ValuesHolder

All Known Implementing Classes:

TimeSpanEditor, ValuesEditorAdapter, ValuesEditorBean

public interface ValuesEditor
extends ValuesHolder

Implemented by Swing editors which are designed for a particular class of objects.

This interface attempts to define the minimal functionality in which a class can provide a graphical editor for the configurable/state values of a particular object. It extends the ValuesHolder class with the following purpose:

• A visual representation of the object is made available as a JComponent.
• The ability to serve as a factory for the objects it is designed to work with.
• The ability to validate the user input without actually risking the transfer of information is provided.
• One may optionally add "change" listeners to tell when the end user has made any modifications to the object.

A ValuesEditor implementation has the following "contractual rules":

• It must first abide by all of the rules of the ValuesHolder interface which it extends.
• It must also serve as a "object" factory - that is the createObjectInstance method must return a new instance of a object which can be used as a parameter to both the toObject and fromObject methods.
• The init method is option. A implementation choose to do nothing in its implementation of the init method. Likewise, a user of the implementation does not need to invoke the init method. However, it provides the opportunity to customize strings (typically by converting a resource bundle into a lookup object). One will need to refer to the documentation for the implementation to see what parameters are available.
• If the validate method is successful (returns true), then the toObject method should not throw a IllegalStateException (you should be able to transfer values from the editor to a object if the user input is valid). This doesn't turn out to be that difficult to implement (typically the first thing your toObject implementation will do is invoke your validate method.
• All method invocations should occur within the Swing event dispatch thread, so the implementation does not need to worry about whether or not it is "Swing safe" when transferring values.

The following UML diagram provides a overview of how this class "fits" in to the scheme of things:

You should be able to use the View utility to verify the behavior of ANY implementation of this interface:

 java com.ccg.values.View -class CLASS [CLASS_SETTINGS]
 

For example, to try out the TimeSpanEditor and adjust the labels, one could use:

 java com.ccg.values.View -class com.ccg.values.stock.TimeSpanEditor \
   -start.label "Search From: " -end.label "Until: "
 

Since:

1.0

Version:

$Revision: 1.2 $

Author:

$Author: pkb $

Field Summary

Fields inherited from interface com.ccg.values.ValuesHolder

HAS_FROM, HAS_TO, HAS_TO_FROM

Method Summary

void	addChangeListener(ChangeListener cl) Add a "change listener" to notify if the user modifies ANY of the values in the Swing component.
Object	createObjectInstance() Creates a new instance of a object (with default values set) which the editor is designed to work with.
JComponent	getComponent() Get the Swing component which the user sees.
void	init(Lookup props) Set the properties to be used when constructing the visual component.
void	removeChangeListener(ChangeListener cl) Add a "change listener" to notify if the user modifies ANY of the values in the Swing component.
void	validate() Verify that all of the user input fields are valid.

Methods inherited from interface com.ccg.values.ValuesHolder

fromObject, getCapabilities, getObjectClass, toObject

Method Detail

createObjectInstance

Object createObjectInstance()

Creates a new instance of a object (with default values set) which the editor is designed to work with.

This is method should ALWAYS be implemented when possible and is a requirement for the ValuesEditor implementation to be used in "factories".

Returns:

Newly allocated and initialized object (should be suitable for either the fromObject or toObject implementation. Never returns null.

Since:

1.0

init

void init(Lookup props)

Set the properties to be used when constructing the visual component.

Implementations may optionally implement this method (it doesn't need to do anything). It allows one to pass a set of properties which the implementation may optionally use when constructing its visual component.

The properties recognized (if any) are implementation dependent. Typically these properties include custom labels, tooltips, format rules, etc.

If this method is invoked (it is not required), it must be invoked prior to the invocation of the getComponent method (otherwise it would be too late now wouldn't it).

Parameters:

props - Set of properties (implementation dependent) to initialize object with (must not be null).

Since:

1.0

getComponent

JComponent getComponent()
                        throws IllegalStateException

Get the Swing component which the user sees.

All classes which implement this interface need to be able to create a GUI editor.

The first invocation triggers the "creation" of the component.

Multiple invocations will return a reference to the same component as returned by the first invocation.

Returns:

A graphical editor for the object - never returns null.

Throws:

IllegalStateException - If the object was not properly initialized.

Since:

1.0

validate

void validate()
              throws IllegalStateException

Verify that all of the user input fields are valid.

After allowing the user to modify the fields, it is often desirable to "validate" what the user has entered. This method checks the data entered by the user. If any of the user information looks bad, it throws an IllegalStateException.

Throws:

IllegalStateException - If any of the user input fields have invalid values contained which the user needs to fix prior to a commit.

Since:

1.0

See Also:

ValuesHolder.toObject(java.lang.Object)

addChangeListener

void addChangeListener(ChangeListener cl)

Add a "change listener" to notify if the user modifies ANY of the values in the Swing component.

This method allows developers to determine when the state of the graphical component becomes "dirty" (modified by the user).

Parameters:

cl - The ChangeListener to notify of modifications.

Since:

1.0

removeChangeListener

void removeChangeListener(ChangeListener cl)

Add a "change listener" to notify if the user modifies ANY of the values in the Swing component.

Parameters:

cl - The ChangeListener to remove from the notification list.

Since:

1.0