maspack.widgets
Class LabeledControl

java.lang.Object
  extended by java.awt.Component
      extended by java.awt.Container
          extended by javax.swing.JComponent
              extended by javax.swing.JPanel
                  extended by maspack.widgets.LabeledComponentBase
                      extended by maspack.widgets.LabeledComponent
                          extended by 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, 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
    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
     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, 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, 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, transferFocusBackward, 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, hide, 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, 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