y.option
Class OptionItem

java.lang.Object
  y.option.OptionItem

All Implemented Interfaces:

AttributeOwner, PropertyChangeReporter, VetoableChangeReporter

Direct Known Subclasses:

ComponentOptionItem, ObjectOptionItem

public abstract class OptionItem
extends java.lang.Object
implements AttributeOwner, PropertyChangeReporter, VetoableChangeReporter

Abstract class that serves as base class for all items that can be added to an OptionHandler.
Past versions of this class were responsible for providing an editor component for a specific kind of parameter or option type. This task falls now to an ItemEditor created either through an ItemEditorFactory or in the context of another Editor.

It is the responsibility of an OptionItem to update the value, enabled, and valueUndefined properties of registered editors that are in autoAdopt state. The various publishXXX methods can be used to this end.

An OptionItem must also provide means to reset the value of the parameter to its original value.
It is recommended that subclasses implement the BackupValueOwner interface to allow editors to access that original value (or backup value).

See Also:

publishEnabled(boolean), publishValue(Object), publishValueUndefined(boolean)

Field Summary

static java.lang.String	ATTRIBUTE_CONTEXT Attribute key used to store the item context handlername.sectionname.
static java.lang.String	ATTRIBUTE_GROUPS Attribute key used to store the Collection of OptionGroup instance that the item belongs to.
static java.lang.String	ATTRIBUTE_LONG_DESCRIPTION Attribute key used to store a detailed description.
static java.awt.Color	COLOR_UNDEFINED A Color that is used in the editor to signal that the value is not defined (yet).
protected java.lang.String	name This field stores the name of the OptionItem.
static java.lang.String	PROPERTY_CLASS_TYPE Name of property classType.
static java.lang.String	PROPERTY_ENABLED Name of property enabled.
static java.lang.String	PROPERTY_TIP_TEXT Name of property tipText.
static java.lang.String	PROPERTY_VALUE Name of property value.
static java.lang.String	PROPERTY_VALUE_UNDEFINED Name of property valueUndefined.
static java.lang.Object	UNDEFINED A value item that can be used to signal that there is no defined value yet.

Constructor Summary

protected	OptionItem() Creates a new instance of OptionItem.
protected	OptionItem(java.lang.Class classType) Creates a new instance of OptionItem.
protected	OptionItem(java.lang.Class classType, java.lang.String name) Creates a new instance of OptionItem that has the given identifying name.
protected	OptionItem(java.lang.String name) Creates a new instance of OptionItem that has the given identifying name.

Method Summary

ItemEditor	addEditor(ItemEditor editor) Adds the specified editor to this item.
void	addEditorListener(Editor.Listener el) Register el so that it will receive notifications when an editor is added or removed.
void	addPropertyChangeListener(java.beans.PropertyChangeListener pcl) Adds a PropertyChangeListener to the listener list.
void	addPropertyChangeListener(java.lang.String propertyname, java.beans.PropertyChangeListener pcl) Adds a PropertyChangeListener to the listener list for a specific property.
void	addVetoableChangeListener(java.lang.String propertyname, java.beans.VetoableChangeListener vcl) Adds a VetoableChangeListener to the listener list for a specific property.
void	addVetoableChangeListener(java.beans.VetoableChangeListener vcl) Adds a VetoableChangeListener to the listener list.
boolean	adoptEditorValue() Deprecated. Use Editor.commitValue() instead.
boolean	checkEditorValue() Deprecated. Register a VetoableChangeListener instead.
protected void	firePropertyChange(java.beans.PropertyChangeEvent pce) Fires a PropertyChangeEvent in response to a change in a bound property.
protected void	firePropertyChange(java.lang.String pn, java.lang.Object oldValue, java.lang.Object newValue) Fires a PropertyChangeEvent in response to a change in a bound property.
protected void	fireVetoableChange(java.beans.PropertyChangeEvent pce) Fires a PropertyChangeEvent in response to a change in a vetoable property.
protected void	fireVetoableChange(java.lang.String pn, java.lang.Object oldValue, java.lang.Object newValue) Fires a PropertyChangeEvent in response to a change in a vetoable property.
java.lang.Object	getAttribute(java.lang.String name) Returns the value of the attribute with the specified name.
java.lang.Class	getClassType() Getter for property classType.
javax.swing.JComponent	getEditor() Deprecated. Use ItemEditorFactory.createEditor(y.option.OptionItem) instead.
javax.swing.JComponent	getEditor(GuiFactory factory, java.lang.String parentName) Deprecated. Use ItemEditorFactory.createEditor(y.option.OptionItem) instead.
java.util.List	getEditors() Returns a list of all the editors that were added to the OptionItem with addEditor(y.option.ItemEditor).
java.lang.String	getName() Returns the name of this OptionItem.
java.lang.String	getStringValue() Returns the stringified value of this option item if the classType property is set, it uses the y.util.ObjectStringConversion class to perform its task, otherwise it will return null.
java.lang.String	getTipText() Returns the tool tip text for the item editor.
abstract java.lang.String	getType() Returns a unique identifier for the type of this OptionItem.
abstract java.lang.Object	getValue() Returns the value of this option item.
boolean	isEnabled() Returns the enabled state of this item.
boolean	isValueUndefined() Returns whether or not the editor should start up displaying an undefined value.
protected void	publishEnabled(boolean enabled) Sets the enabled property to the specified value for all registered editors that are in autoAdopt state.
protected void	publishValue(java.lang.Object value) Sets the specified value for all registered editors that are in autoAdopt state.
protected void	publishValueUndefined(boolean valueUndefined) Sets the valueUndefined property to the specified value for all registered editors that are in autoAdopt state.
void	removeAttribute(java.lang.String name) Removes the attribute with the specified name.
void	removeEditor(ItemEditor editor) Removes the specified editor from this item.
void	removeEditorListener(Editor.Listener el) Unregister el so that it will no longer receive notifications when an editor is added or removed.
void	removePropertyChangeListener(java.beans.PropertyChangeListener pcl) Removes a PropertyChangeListener from the listener list.
void	removePropertyChangeListener(java.lang.String propertyname, java.beans.PropertyChangeListener pcl) Removes a PropertyChangeListener from the listener list for a specific property.
void	removeVetoableChangeListener(java.lang.String propertyname, java.beans.VetoableChangeListener vcl) Removes a VetoableChangeListener from the listener list for a specific property.
void	removeVetoableChangeListener(java.beans.VetoableChangeListener vcl) Removes a VetoableChangeListener from the listener list.
abstract void	resetValue() Resets the value of this item to its initial value.
void	setAttribute(java.lang.String name, java.lang.Object value) Sets an arbitrary attribute with the specified name and value.
protected void	setClassType(java.lang.Class classType) Sets the value of property classType.
void	setEnabled(boolean enabled) Specifies the enabled state of this item.
void	setStringValue(java.lang.String value) Sets the stringified value of this option item if the classType property is set, it uses the y.util.ObjectStringConversion class to perform its task, otherwise it will return null.
void	setTipText(java.lang.String tipText) Sets the tool tip text for the item editor.
abstract void	setValue(java.lang.Object value) Sets the value of this option item.
void	setValueUndefined(boolean valueUndefined) Whether or not the editor should start up displaying an undefined value.
boolean	wantsVisibleName() Whether or not the identifying name should be displayed along with this item.

Methods inherited from class java.lang.Object

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

Field Detail

COLOR_UNDEFINED

public static final java.awt.Color COLOR_UNDEFINED

A Color that is used in the editor to signal that the value is not defined (yet).

UNDEFINED

public static final java.lang.Object UNDEFINED

A value item that can be used to signal that there is no defined value yet.

ATTRIBUTE_CONTEXT

public static final java.lang.String ATTRIBUTE_CONTEXT

Attribute key used to store the item context handlername.sectionname.

ATTRIBUTE_GROUPS

public static final java.lang.String ATTRIBUTE_GROUPS

Attribute key used to store the Collection of OptionGroup instance that the item belongs to.

Note:
Since the attribute value is of type Collection, an option group can be added without triggering a PropertyChangeEvent.

ATTRIBUTE_LONG_DESCRIPTION

public static final java.lang.String ATTRIBUTE_LONG_DESCRIPTION

Attribute key used to store a detailed description.

PROPERTY_ENABLED

public static final java.lang.String PROPERTY_ENABLED

Name of property enabled.

PROPERTY_VALUE

public static final java.lang.String PROPERTY_VALUE

Name of property value.

PROPERTY_VALUE_UNDEFINED

public static final java.lang.String PROPERTY_VALUE_UNDEFINED

Name of property valueUndefined.

PROPERTY_CLASS_TYPE

public static final java.lang.String PROPERTY_CLASS_TYPE

Name of property classType.

PROPERTY_TIP_TEXT

public static final java.lang.String PROPERTY_TIP_TEXT

Name of property tipText.

name

protected java.lang.String name

This field stores the name of the OptionItem.

Constructor Detail

OptionItem

protected OptionItem()

Creates a new instance of OptionItem.

OptionItem

protected OptionItem(java.lang.Class classType)

Creates a new instance of OptionItem.

OptionItem

protected OptionItem(java.lang.String name)

Creates a new instance of OptionItem that has the given identifying name.

OptionItem

protected OptionItem(java.lang.Class classType,
                     java.lang.String name)

Creates a new instance of OptionItem that has the given identifying name.

Method Detail

setClassType

protected void setClassType(java.lang.Class classType)

Sets the value of property classType.

getClassType

public java.lang.Class getClassType()

Getter for property classType.

Returns:

Value of property classType.

getName

public java.lang.String getName()

Returns the name of this OptionItem.

setTipText

public void setTipText(java.lang.String tipText)

Sets the tool tip text for the item editor.

getTipText

public java.lang.String getTipText()

Returns the tool tip text for the item editor.

isEnabled

public boolean isEnabled()

Returns the enabled state of this item.

Returns:

the enabled state of this item

setEnabled

public void setEnabled(boolean enabled)

Specifies the enabled state of this item.

Parameters:

enabled - the new enabled state of this item

wantsVisibleName

public boolean wantsVisibleName()

Whether or not the identifying name should be displayed along with this item. By default this method returns true

getStringValue

public java.lang.String getStringValue()

Returns the stringified value of this option item if the classType property is set, it uses the y.util.ObjectStringConversion class to perform its task, otherwise it will return null.

setStringValue

public void setStringValue(java.lang.String value)

Sets the stringified value of this option item if the classType property is set, it uses the y.util.ObjectStringConversion class to perform its task, otherwise it will return null.

getEditor

public javax.swing.JComponent getEditor()

Deprecated. Use ItemEditorFactory.createEditor(y.option.OptionItem) instead.

Returns the editor component for the this option item.

Note:
Use the getEditor(GuiFactory,String) variant instead.

getEditor

public javax.swing.JComponent getEditor(GuiFactory factory,
                                        java.lang.String parentName)

Deprecated. Use ItemEditorFactory.createEditor(y.option.OptionItem) instead.

Returns the editor component for the this option item. Uses the given GuiFactory the create its content. The default implementation calls the no-arg getEditor() method to preserve backward compatibility. However it is suggested to override this method in order to make use of the GuiFactory.

adoptEditorValue

public boolean adoptEditorValue()

Deprecated. Use Editor.commitValue() instead.

This implementation is a no-op for backwards compatibility.

Returns:

true

resetValue

public abstract void resetValue()

Resets the value of this item to its initial value.

Note:
It is the responsibility of the OptionItem to update registered editors that are in autoAdopt state.

See Also:

publishValue(Object)

checkEditorValue

public boolean checkEditorValue()

Deprecated. Register a VetoableChangeListener instead.

This implementation is a no-op for backwards compatibility.

Returns:

true

isValueUndefined

public boolean isValueUndefined()

Returns whether or not the editor should start up displaying an undefined value.

setValueUndefined

public void setValueUndefined(boolean valueUndefined)

Whether or not the editor should start up displaying an undefined value.

getAttribute

public java.lang.Object getAttribute(java.lang.String name)

Returns the value of the attribute with the specified name.

Specified by:

getAttribute in interface AttributeOwner

Parameters:

name - the name of the attribute being queried

Returns:

the value of the attribute with the specified name

removeAttribute

public void removeAttribute(java.lang.String name)

Removes the attribute with the specified name.
Removing an attribute is reported with PropertyChange events.

Specified by:

removeAttribute in interface AttributeOwner

Parameters:

name - the name of the attribute being removed

setAttribute

public void setAttribute(java.lang.String name,
                         java.lang.Object value)

Sets an arbitrary attribute with the specified name and value.

If value is null, this method will remove the attribute.
Setting an attribute is reported with PropertyChange events.

Specified by:

setAttribute in interface AttributeOwner

Parameters:

name - the name of the attribute being added

value - the value of the attribute being added

getType

public abstract java.lang.String getType()

Returns a unique identifier for the type of this OptionItem.

getValue

public abstract java.lang.Object getValue()

Returns the value of this option item.

setValue

public abstract void setValue(java.lang.Object value)

Sets the value of this option item.

Note:
It is the responsibility of the OptionItem to update registered editors that are in autoAdopt state.

See Also:

publishValue(Object)

publishValue

protected void publishValue(java.lang.Object value)

Sets the specified value for all registered editors that are in autoAdopt state.

publishValueUndefined

protected void publishValueUndefined(boolean valueUndefined)

Sets the valueUndefined property to the specified value for all registered editors that are in autoAdopt state.

publishEnabled

protected void publishEnabled(boolean enabled)

Sets the enabled property to the specified value for all registered editors that are in autoAdopt state.

addEditor

public ItemEditor addEditor(ItemEditor editor)

Adds the specified editor to this item.
Note: Editors are referenced using WeakReferences.

Parameters:

editor - the editor to be added

Returns:

the editor argument

See Also:

WeakReference

removeEditor

public void removeEditor(ItemEditor editor)

Removes the specified editor from this item.

Parameters:

editor - the editor to be removed

getEditors

public java.util.List getEditors()

Returns a list of all the editors that were added to the OptionItem with addEditor(y.option.ItemEditor).

Returns:

a list of all the editors that were added to the OptionItem with addEditor(y.option.ItemEditor).

addEditorListener

public void addEditorListener(Editor.Listener el)

Register el so that it will receive notifications when an editor is added or removed.

removeEditorListener

public void removeEditorListener(Editor.Listener el)

Unregister el so that it will no longer receive notifications when an editor is added or removed.

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener pcl)

Adds a PropertyChangeListener to the listener list. The listener is registered for all bound properties of this class, including the following:

• the option class ("classType")
• the tool tip text ("tipText")
• the enabled state ("enabled")
• the value ("value")
• the undefined state ("valueUndefined")

If listener is null, no exception is thrown and no action is performed.

Specified by:

addPropertyChangeListener in interface PropertyChangeReporter

Parameters:

pcl - the PropertyChangeListener to be added

See Also:

removePropertyChangeListener(java.beans.PropertyChangeListener), addPropertyChangeListener(String,java.beans.PropertyChangeListener)

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener pcl)

Removes a PropertyChangeListener from the listener list. This method should be used to remove the PropertyChangeListeners that were registered for all bound properties of this class.

If listener is null, no exception is thrown and no action is performed.

Specified by:

removePropertyChangeListener in interface PropertyChangeReporter

Parameters:

pcl - the PropertyChangeListener to be removed

See Also:

addPropertyChangeListener(java.beans.PropertyChangeListener), removePropertyChangeListener(String,java.beans.PropertyChangeListener)

addPropertyChangeListener

public void addPropertyChangeListener(java.lang.String propertyname,
                                      java.beans.PropertyChangeListener pcl)

Adds a PropertyChangeListener to the listener list for a specific property. The specified property may be user-defined, or one of the following:

• the option class ("classType")
• the option tool tip text ("tipText")
• the option enabled state ("enabled")
• the option value ("value")
• "valueUndefined"

If listener is null, no exception is thrown and no action is performed.

Specified by:

addPropertyChangeListener in interface PropertyChangeReporter

Parameters:

propertyname - one of the property names listed above

pcl - the PropertyChangeListener to be added

See Also:

addPropertyChangeListener(java.beans.PropertyChangeListener), removePropertyChangeListener(String,java.beans.PropertyChangeListener)

removePropertyChangeListener

public void removePropertyChangeListener(java.lang.String propertyname,
                                         java.beans.PropertyChangeListener pcl)

Removes a PropertyChangeListener from the listener list for a specific property. This method should be used to remove PropertyChangeListeners that were registered for a specific bound property.

If listener is null, no exception is thrown and no action is performed.

Specified by:

removePropertyChangeListener in interface PropertyChangeReporter

Parameters:

propertyname - a valid property name

pcl - the PropertyChangeListener to be removed

See Also:

addPropertyChangeListener(String,java.beans.PropertyChangeListener), removePropertyChangeListener(java.beans.PropertyChangeListener)

firePropertyChange

protected void firePropertyChange(java.lang.String pn,
                                  java.lang.Object oldValue,
                                  java.lang.Object newValue)

Fires a PropertyChangeEvent in response to a change in a bound property. The event will be delivered to all registered PropertyChangeListeners. No event will be delivered if oldValue and newValue are the same.

Parameters:

pn - the name of the property that has changed

oldValue - the property's previous value

newValue - the property's new value

firePropertyChange

protected void firePropertyChange(java.beans.PropertyChangeEvent pce)

Fires a PropertyChangeEvent in response to a change in a bound property. The event will be delivered to all registered PropertyChangeListeners. No event will be delivered if oldValue and newValue are the same.

Parameters:

pce - the PropertyChangeEvent to be fired

addVetoableChangeListener

public void addVetoableChangeListener(java.beans.VetoableChangeListener vcl)

Adds a VetoableChangeListener to the listener list. The listener is registered for all vetoable properties of this class.

If listener is null, no exception is thrown and no action is performed.

Specified by:

addVetoableChangeListener in interface VetoableChangeReporter

Parameters:

vcl - the VetoableChangeListener to be added

See Also:

removeVetoableChangeListener(java.beans.VetoableChangeListener), addVetoableChangeListener(String,java.beans.VetoableChangeListener)

removeVetoableChangeListener

public void removeVetoableChangeListener(java.beans.VetoableChangeListener vcl)

Removes a VetoableChangeListener from the listener list. This method should be used to remove the VetoableChangeListeners that were registered for all vetoable properties of this class.

If listener is null, no exception is thrown and no action is performed.

Specified by:

removeVetoableChangeListener in interface VetoableChangeReporter

Parameters:

vcl - the VetoableChangeListener to be removed

See Also:

addVetoableChangeListener(java.beans.VetoableChangeListener), removeVetoableChangeListener(String,java.beans.VetoableChangeListener)

addVetoableChangeListener

public void addVetoableChangeListener(java.lang.String propertyname,
                                      java.beans.VetoableChangeListener vcl)

Adds a VetoableChangeListener to the listener list for a specific property.

If listener is null, no exception is thrown and no action is performed.

Specified by:

addVetoableChangeListener in interface VetoableChangeReporter

Parameters:

propertyname - one of the property names listed above

vcl - the VetoableChangeListener to be added

See Also:

addVetoableChangeListener(java.beans.VetoableChangeListener), removeVetoableChangeListener(java.beans.VetoableChangeListener)

removeVetoableChangeListener

public void removeVetoableChangeListener(java.lang.String propertyname,
                                         java.beans.VetoableChangeListener vcl)

Removes a VetoableChangeListener from the listener list for a specific property. This method should be used to remove VetoableChangeListeners that were registered for a specific bound property.

If listener is null, no exception is thrown and no action is performed.

Specified by:

removeVetoableChangeListener in interface VetoableChangeReporter

Parameters:

propertyname - a valid property name

vcl - the VetoableChangeListener to be removed

See Also:

addVetoableChangeListener(java.beans.VetoableChangeListener), removeVetoableChangeListener(java.beans.VetoableChangeListener)

fireVetoableChange

protected void fireVetoableChange(java.lang.String pn,
                                  java.lang.Object oldValue,
                                  java.lang.Object newValue)
                           throws java.beans.PropertyVetoException

Fires a PropertyChangeEvent in response to a change in a vetoable property. The event will be delivered to all registered VetoableChangeListeners. If a VetoableChangeListener throws a PropertyVetoException, a new event is fired reverting all VetoableChangeListeners to the old value and the exception is then rethrown. No event will be delivered if oldValue and newValue are the same.

Parameters:

pn - the name of the property that has changed

oldValue - the property's previous value

newValue - the property's new value

Throws:

java.beans.PropertyVetoException - if a VetoableChangeListener threw PropertyVetoException

fireVetoableChange

protected void fireVetoableChange(java.beans.PropertyChangeEvent pce)
                           throws java.beans.PropertyVetoException

Fires a PropertyChangeEvent in response to a change in a vetoable property. The event will be delivered to all registered VetoableChangeListeners. If a VetoableChangeListener throws a PropertyVetoException, a new event is fired reverting all VetoableChangeListeners to the old value and the exception is then rethrown. No event will be delivered if oldValue and newValue are the same.

Parameters:

pce - the PropertyChangeEvent to be fired

Throws:

java.beans.PropertyVetoException - if a VetoableChangeListener threw PropertyVetoException