Search this API

y.option
Class OptionItem

java.lang.Object
  extended by 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: 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: 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

© Copyright 2000-2022,
yWorks GmbH.
All rights reserved.