maspack.widgets

Class LabeledControl

java.lang.Object

java.awt.Component

java.awt.Container

javax.swing.JComponent

javax.swing.JPanel

maspack.widgets.LabeledComponentBase

maspack.widgets.LabeledComponent

maspack.widgets.LabeledControl

All Implemented Interfaces:

java.awt.event.ActionListener, java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable, java.util.EventListener, javax.accessibility.Accessible, HasProperties, Disposable, HasAlignableLabels, LabeledWidget

Direct Known Subclasses:

AffineTransformWidget, BooleanSelector, ColorSelector, DoubleSlider, FontField, IntegerSlider, LabeledComboBox, LabeledMultiTextField, LabeledTextField, LabeledToggleButton, MouseClickField, RigidTransformWidget

public abstract class LabeledControl
extends LabeledComponent

A LabeledComponent which is specifically intended to modify values of some primitive, such as numeric or string values, colors, file selections, etc. In support of this purpose, a LabeledControl can accept ValueChangeListeners, which are fired every time the value associated with this control changes. Values can be set externally (outside of the GUI) by calling #setValue.

Values for a LabeledControl can be set either through the GUI or by calling setValue. All controls should be able to support a special ``void'' value identified by Property.VoidValue, which can be used to indicate undefined or unspecified values. Void values are typically not enabled by default but can be enabled by calling setVoidValueEnabled. If enabled, a void value can be set by calling

 setValue (Property.VoidValue);
 

Some individual controls may also allow a void value to be set through the GUI. In this case, getGUIVoidEnabled will return true.

Some controls may accept null as a valid value. In this case, getNullValueEnabled will return true. null is not used to indicate void values because in some situations it may be a proper value in its own right.

The current value of a control can be read back using getValue. If void values are enabled, the user should check that the value is not Property.VoidValue before casting it to a type specific to the control. An application can add value change listeners that are called whenever the value of the control changes. Firing occurs only when there is a change a value, not just when a value is set. An application can also add value check listeners that are called to check any prospective new value. These listeners can declare a value to be invalid, or correct it to an adjusted value.

In general, setting a new value entails:

• checking the new value's validity
• set the new value, and fire the value change listeners if the new value differs from the old
• update the display if the new value differs from the old

Generally speaking, these items are handled by validateValue, updateValue, and updateDisplay.

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class javax.swing.JComponent

javax.swing.JComponent.AccessibleJComponent

Nested classes/interfaces inherited from class java.awt.Component

java.awt.Component.BaselineResizeBehavior

Field Summary

Fields inherited from class maspack.widgets.LabeledComponent

myProps

Fields inherited from class javax.swing.JComponent

TOOL_TIP_TEXT_KEY, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

Constructors

Constructor and Description
LabeledControl(java.lang.String labelText) Creates a control with specified label text.
LabeledControl(java.lang.String labelText, java.awt.Component comp) Creates a control with specified label text and a major component.

Method Summary

Modifier and Type	Method and Description
void	addValueChangeListener(ValueChangeListener l) Adds a ValueChangeListener to this control.
void	addValueCheckListener(ValueCheckListener l) Adds a ValueCheckListener to this control.
void	dispose() Releases all the resources held by this control.
boolean	getGUIVoidEnabled() Returns true if void values can be set from the GUI.
boolean	getNullValueEnabled() Returns true if null values are enabled for this control.
java.lang.Object	getValue()
ValueChangeListener[]	getValueChangeListeners() Returns a list of all the ValueChangeListeners currently held by this control.
ValueCheckListener[]	getValueCheckListeners() Returns a list of all the ValueCheckListeners currently held by this control.
boolean	getVoidValueEnabled() Returns true if void values are enabled for this control.
boolean	isEnabledAll() Returns true if this control, and all its components, are enabled.
void	maskValueChangeListeners(boolean masked) Enables or disables the value change listeners.
void	maskValueChecks(boolean masked) Enables or disables value checking from within setValue.
void	removeValueChangeListener(ValueChangeListener l) Removes a ValueChangeListener from this control.
void	setBackgroundAll(java.awt.Color color) Sets the background of this control and all its sub-components, except for JTextFields, where setting the background would obscure the text field.
void	setEnabledAll(boolean enable) Enables or disables this control by enabling or disabling all its components.
void	setValue(java.lang.Object value) Sets a new value for this control.
void	setVoidValueEnabled(boolean enable) Enables void values to be set for this control.
boolean	valueChangeListenersMasked() Returns true if the value change listeners are masked.
boolean	valueChecksMasked() Returns true if value checking is enabled within setValue.
boolean	valueIsNull() Returns true if the current value for this control is null.
boolean	valueIsVoid() Returns true if the current value for this control is void (i.e., Property.VoidValue).

Methods inherited from class maspack.widgets.LabeledComponent

actionPerformed, addMajorComponent, addMajorComponent, getActions, getAllPropertyInfo, getLabel, getLabelSpacing, getMainComponent, getMajorComponent, getMaximumSize, getMinimumSize, getPreferredLabelSpacing, getSpacing, indexOfMajor, isLabelStretchable, isStretchable, numMajorComponents, removeMajorComponent, setLabelSpacing, setLabelStretchable, setLabelText, setSpacing, setStretchable

Methods inherited from class maspack.widgets.LabeledComponentBase

getBackgroundColor, getLabelFontColor, getLabelText, getLeftInset, getProperty, isSelected, setBackgroundColor, setLabelFontColor, setLabelFontColor, setSelected

Methods inherited from class javax.swing.JPanel

getAccessibleContext, getUI, getUIClassID, setUI, updateUI

Methods inherited from class javax.swing.JComponent

addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, hide, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintImmediately, paintImmediately, print, printAll, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusDownCycle, validate

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, contains, createImage, createImage, createVolatileImage, createVolatileImage, dispatchEvent, enable, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface maspack.widgets.LabeledWidget

getToolTipText, setToolTipText

Constructor Detail

LabeledControl

public LabeledControl(java.lang.String labelText)

Creates a control with specified label text.

Parameters:

labelText - text value for the control label

LabeledControl

public LabeledControl(java.lang.String labelText,
                      java.awt.Component comp)

Creates a control with specified label text and a major component.

Parameters:

labelText - text value for the control label

comp - major component to add to this control

Method Detail

maskValueChangeListeners

public void maskValueChangeListeners(boolean masked)

Enables or disables the value change listeners. If disabled, then fireValueChangeListeners will do nothing.

Parameters:

masked - if true, masks the value change listeners.

valueChangeListenersMasked

public boolean valueChangeListenersMasked()

Returns true if the value change listeners are masked.

Returns:

true if change listeners are masked.

maskValueChecks

public void maskValueChecks(boolean masked)

Enables or disables value checking from within setValue.

Parameters:

masked - if true, masks value checking.

valueChecksMasked

public boolean valueChecksMasked()

Returns true if value checking is enabled within setValue.

Returns:

true if value checking is enabled.

addValueChangeListener

public void addValueChangeListener(ValueChangeListener l)

Adds a ValueChangeListener to this control.

Parameters:

l - listener to add

removeValueChangeListener

public void removeValueChangeListener(ValueChangeListener l)

Removes a ValueChangeListener from this control.

Parameters:

l - listener to remove

getValueChangeListeners

public ValueChangeListener[] getValueChangeListeners()

Returns a list of all the ValueChangeListeners currently held by this control.

Returns:

list of ValueChangeListeners

addValueCheckListener

public void addValueCheckListener(ValueCheckListener l)

Adds a ValueCheckListener to this control.

Parameters:

l - listener to add

getValueCheckListeners

public ValueCheckListener[] getValueCheckListeners()

Returns a list of all the ValueCheckListeners currently held by this control.

Returns:

list of ValueCheckListeners

dispose

public void dispose()

Releases all the resources held by this control.

Specified by:

dispose in interface Disposable

Overrides:

dispose in class LabeledComponent

setEnabledAll

public void setEnabledAll(boolean enable)

Enables or disables this control by enabling or disabling all its components.

Parameters:

enable - enables or disables all components

setBackgroundAll

public void setBackgroundAll(java.awt.Color color)

Sets the background of this control and all its sub-components, except for JTextFields, where setting the background would obscure the text field.

Parameters:

color - new background color

isEnabledAll

public boolean isEnabledAll()

Returns true if this control, and all its components, are enabled.

Returns:

true if this control is enabled

getGUIVoidEnabled

public boolean getGUIVoidEnabled()

Returns true if void values can be set from the GUI.

Returns:

true if the GUI can set void values

setVoidValueEnabled

public void setVoidValueEnabled(boolean enable)

Enables void values to be set for this control. The default setting is false.

Parameters:

enable - enables or disables void values for this control

getVoidValueEnabled

public boolean getVoidValueEnabled()

Returns true if void values are enabled for this control.

Returns:

true if void values are enabled

getNullValueEnabled

public boolean getNullValueEnabled()

Returns true if null values are enabled for this control.

Returns:

true if null values are enabled

getValue

public java.lang.Object getValue()

Returns:

current value for this control

valueIsVoid

public boolean valueIsVoid()

Returns true if the current value for this control is void (i.e., Property.VoidValue).

Returns:

true if the current value is void

valueIsNull

public boolean valueIsNull()

Returns true if the current value for this control is null.

Returns:

true if the current value is null

setValue

public void setValue(java.lang.Object value)

Sets a new value for this control. This may include null or void if those values are enabled.

Parameters:

value - new value for this control