com.sas.visuals
Class UnitsBox

com.sas.visuals.UnitsBox

All Implemented Interfaces:

CompositeInterface, ContainerInterface, com.sas.awt.print.PrintableInterface, VisualInterface, com.sas.beans.PropertyChangeSource, com.sas.beans.VetoableChangeSource, com.sas.collection.ContentsChangedListener, com.sas.ComponentInterface, com.sas.DesignTimeDropTargetInterface, com.sas.lang.DoubleDataInterface, com.sas.lang.StringDataInterface, com.sas.LinkPropertiesInterface, com.sas.measures.MeasureInterface, com.sas.ModelInterface, ValidatorInterface, com.sas.ViewInterface, MultipleValueEventSourceInterface, java.awt.image.ImageObserver, java.awt.MenuContainer, java.beans.PropertyChangeListener, java.io.ObjectInputValidation, java.io.Serializable, java.util.EventListener, javax.accessibility.Accessible

public class UnitsBox
implements com.sas.lang.DoubleDataInterface, com.sas.lang.StringDataInterface, com.sas.measures.MeasureInterface, com.sas.collection.ContentsChangedListener

A UnitsBox object is a visual component for entering a measurement value as a number, in one of a set of units. One of the units is a preferred unit i.e. has a scale of 1.0) and the other units are scaled in relation to that preferred unit. For example, this field may be used to enter a distance; the units may be

 millimeter  centimeter  inch    foot      meter
 0.001       0.01        0.02541 0.304878  1.0
 

In this case, meter is the preferred unit. Or for measuring time, the units may be

 millisecond second  minute hour    day
 0.001       1.0     60.0   3600.0  86400.0
 

and the preferred units is second.

The units and their scaling factors are supplied via a AssociationListInterface; the keys are the unit labels (which are typically strings but may be any object) and the values are java.lang.Number objects containing the units. The toString() value of the keys are used in the combo box drop down list unless a display transform is supplied to convert the keys to strings.

The visual component consists of a text entry field, a spin button for incrementing/decrementing the doubleData, and a combo box which shows the current units. Changing the units will scale the number in the text field, but it does not change the UnitsBox doubleData property.

The UnitsBox presents two main properties.

1. The magnitude property is a double in the preferred units. (i.e. it will always be in meters for the first example above, seconds for the second example above.) If the text field contains "30" and the current units is "minutes", then the magnitude will be 30 * 60 or 1800. To allow the component to implement the com.sas.lang.DoubleDataInterface, the magnitude property can also be accessed by the alias, doubleData.
2. The text property is the combined text field and currently selected unit, such as "30 in". Sorry, for internationalization/portability reasons, no distinction between singular and plural is made; if the doubleData is 1 or 10 the text property will be "1 minute" "10 minute"

See Also:

Serialized Form

Field Summary

protected Choice	choice
static java.lang.String	RB_KEY
protected SpinBox	spinBox

Constructor Summary

UnitsBox()
Default constructor

Method Summary

void	attachModel(com.sas.ModelInterface model) Attaches the specified model to this view.
void	contentsChanged(com.sas.collection.ContentsChangedEvent event) handle a change in the units association list.
protected void	createComponents() Create the components of the composite object.
double	getCurrentScale() Return the amount by which the number is scaled The number in the text field is scaled by this much (determined by the current units) to calculate the doubleData property.
java.lang.Object	getCurrentUnits() Deprecated. use getDisplayedUnit()
static int	getDefaultHeight()
static int	getDefaultWidth()
java.lang.Object	getDisplayedUnit() Return the current units
double	getDoubleData() Return the numeric value of the UnitsBox object.
double	getEquivalent(java.lang.String unit) Deprecated. use getMagnitude (Object unit)
static com.sas.beans.ExtendedBeanInfo	getExtendedBeanInfo()
double	getMagnitude() Return the numeric value of the UnitsBox object.
double	getMagnitude(java.lang.Object unit) Get the magnitude in the given unit.
double	getMaximumMagnitude() Return the value of the maximumMagnitude property.
double	getMinimumMagnitude() Return the value of the minimumMagnitude property.
java.lang.Object	getPreferredUnits() Deprecated. use getUnit()
java.util.Vector	getRequiredInterfaces() Returns the required interfaces Vector for this component.
java.lang.String	getText() Get the text value of the object
boolean	getTextScaled() Deprecated. This property has been removed.
java.lang.Object	getUnit() Return the preferred unit of UnitsBox
java.lang.String	getUnitName() Return the preferred unit of UnitsBox
com.sas.collection.AssociationListInterface	getUnits() return the units association list.
com.sas.util.transforms.TransformInterface	getUnitsDisplayTransform() return the units display transform
protected void	hookupComponents() Hookup the components by establishing event listener lists, etc.
void	initialize() Initialize the component.
protected void	layoutComponents() Lays out the components in a layout manager.
static com.sas.collection.AssociationListInterface	makeTimeUnits() Deprecated. Use com.sas.measures.Time.makeUnitsAssociationList()
protected Choice	newChoice() Factory method for creating the choice Override this in subclasses if you want to use a different choice object
protected SpinBox	newSpinBox()
void	pickBestUnits() Change the units to one whose scale is closest to the value.
void	propertyChange(java.beans.PropertyChangeEvent event) Handle a property change event from one of the components.
void	setColumns(int nCols) Set the number of columns in the textField of the UnitsBox.
void	setCurrentUnits(java.lang.Object unit) Deprecated. use setDisplayedUnit(Object)
static void	setDefaultHeight(int newDefaultHeight)
void	setDefaultValues() Set default values.
static void	setDefaultWidth(int newDefaultWidth)
void	setDisplayedUnit(int i) Set the current units
void	setDisplayedUnit(java.lang.Object unit) Set the current units.
void	setDoubleData(double d) Set the numeric value of the UnitsBox object.
void	setEnabled(boolean e) setEnabled() is the set accessor method for the Enabled attribute.
void	setErrorHandler(ErrorHandlerInterface errorHandler) Set the errorHandler for the validator of the text in the textField of the SpinBox.
void	setForeground(java.awt.Color color) Overrides setForeground in java.awt.Component.
void	setMagnitude(double d) Set the value of the UnitsBox, in perferred units.
void	setMaximumMagnitude(double newMaximumMagnitude) Set the maximumMagnitude property.
void	setMinimumMagnitude(double newMinimumMagnitude) Set the minimumMagnitude property.
void	setText(java.lang.String text) Set the text attribute.
void	setTextScaled(boolean textScaled) Deprecated. This property has been removed. To get unscaled behavior, simply provide an association list with all values equal to 1.0
void	setUnits(com.sas.collection.AssociationListInterface newUnits) Set the units used to control the object.
void	setUnitsDisplayTransform(com.sas.util.transforms.TransformInterface unitsDisplayTransform) Set the units display transform.
void	setValidator(ValidationInterface validator) Set the validator for the text in the textField of the SpinBox.
java.lang.String	toString() Get the text value of the object
protected static java.lang.String	toString(double d) format a double as a string, stripping trailing ".0"
protected void	updateMagnitude() Update the magnitude based on changes in the doubleData on the spinBox.
protected void	updateText() Change the text after the units or double data have changed, while preserving the doubleData.
protected void	updateUnits() update the object after the units collection has changed.
static void	validateUnits(com.sas.collection.AssociationListInterface unitList) Check that the units list is valid and throw an exception if not.

Methods inherited from class com.sas.awt.Panel

remove, remove, removeAll

Methods inherited from class com.sas.awt.PanelContainerComponent

addNotify, clone, dragEnter, dragLeave, dragOver, drop, getContainerInterfaceSupportInfo, getErrorHandler, getInsets, getValidator, isIDEDnDDropBarrier, isIDEDnDDropTarget, isValid, removeNotify, setContainerInterfaceSupportInfo, setIDEDnDDropBarrier, setIDEDnDDropTarget, setInsets, setInsets, superAddNotify, superGetInsets, superRemoveNotify, superSetDefaultValues

Methods inherited from class com.sas.awt.PanelVisualComponent

addLink, addPropertyChangeListener, addVetoableChangeListener, anyPropertyChangeListeners, attachView, computePreferredSize, detachModel, detachView, dumpComponent, firePropertyChange, firePropertyChange, fireVetoableChange, getBackgroundColor, getBorder, getComponentDescription, getComponentSupportInfo, getEventMethod, getEventValues, getFont, getForegroundColor, getHeight, getHorizontalPosition, getLinkInfo, getMinimumSize, getModelInterface, getPageBounds, getPreferredSize, getPrePainter, getPrintOptionsPanel, getVerticalPosition, getViewInterfaceSupportInfo, getVisualInterfaceSupportInfo, getWidth, initializeComponent, isDesignTime, isEnabled, isFocus, isLinked, isTransparent, isVisible, pageExists, paint, print, printFinalize, printInitialize, queryLinks, queryLinks, refresh, removeAllLinks, removeInterfaceTraps, removeLink, removePropertyChangeListener, removeVetoableChangeListener, setBackgroundColor, setBorder, setBounds, setComponentDescription, setComponentSupportInfo, setFocus, setFont, setForegroundColor, setHeight, setHorizontalPosition, setLinkInfo, setModelInterface, setPreferredSize, setPrePainter, setRequiredInterfaces, setTransparent, setVerticalPosition, setViewInterfaceSupportInfo, setVisible, setVisualInterfaceSupportInfo, setWidth, superGetFont, superGetMinimumSize, superGetPreferredSize, superIsEnabled, superIsVisible, superPaint, superSetBounds, superSetEnabled, superSetFont, superSetVisible, superUpdate, supportsListenerInterface, supportsRequiredInterfaces, trapInterfaceEvents, update, validateObject

Methods inherited from interface com.sas.awt.ContainerInterface

getComponents, getLayout, invalidate, setLayout, validate

Methods inherited from interface com.sas.awt.VisualInterface

computePreferredSize, getBackgroundColor, getBorder, getFont, getForegroundColor, getHeight, getHorizontalPosition, getMinimumSize, getPreferredSize, getPrePainter, getVerticalPosition, getVisualInterfaceSupportInfo, getWidth, isEnabled, isFocus, isTransparent, isVisible, setBackgroundColor, setBorder, setBounds, setFocus, setFont, setForegroundColor, setHeight, setHorizontalPosition, setPreferredSize, setPrePainter, setTransparent, setVerticalPosition, setVisible, setVisualInterfaceSupportInfo, setWidth, superGetFont, superGetMinimumSize, superGetPreferredSize, superIsEnabled, superIsVisible, superPaint, superSetBounds, superSetEnabled, superSetFont, superSetVisible, superUpdate

Field Detail

RB_KEY

public static final java.lang.String RB_KEY

See Also:

Constant Field Values

choice

protected Choice choice

spinBox

protected SpinBox spinBox

Constructor Detail

UnitsBox

public UnitsBox()

Default constructor

Method Detail

getDefaultWidth

public static int getDefaultWidth()

setDefaultWidth

public static void setDefaultWidth(int newDefaultWidth)

getDefaultHeight

public static int getDefaultHeight()

setDefaultHeight

public static void setDefaultHeight(int newDefaultHeight)

getExtendedBeanInfo

public static com.sas.beans.ExtendedBeanInfo getExtendedBeanInfo()

getRequiredInterfaces

public java.util.Vector getRequiredInterfaces()

Returns the required interfaces Vector for this component.

Specified by:

getRequiredInterfaces in interface com.sas.ViewInterface

Overrides:

getRequiredInterfaces in class PanelVisualComponent

Returns:

the required interfaces Vector for this component.

See Also:

ViewInterface.getRequiredInterfaces()

setDefaultValues

public void setDefaultValues()

Set default values.

Specified by:

setDefaultValues in interface ContainerInterface

Specified by:

setDefaultValues in interface VisualInterface

Specified by:

setDefaultValues in interface com.sas.ComponentInterface

Overrides:

setDefaultValues in class CompositePanel

See Also:

ContainerInterface.setDefaultValues()

setEnabled

public void setEnabled(boolean e)

Description copied from interface: VisualInterface

setEnabled() is the set accessor method for the Enabled attribute. Pass in true to enable the component. Pass in false to disable the component.

Specified by:

setEnabled in interface VisualInterface

Overrides:

setEnabled in class PanelVisualComponent

Parameters:

e - Whether the component should be enabled.

See Also:

VisualInterface.setEnabled(boolean)

setForeground

public void setForeground(java.awt.Color color)

Overrides setForeground in java.awt.Component. This is overridden to get notification of a color change and to filter it to the contained components.

Overrides:

setForeground in class java.awt.Component

Parameters:

color - the new color for the foreground

setUnits

public void setUnits(com.sas.collection.AssociationListInterface newUnits)

Set the units used to control the object.

Parameters:

newUnits - an association list that maps a unit value (the keys in the association list; keys may be any object) to a scale factor for each unit. The values in the association list must be java.lang.Number objects; at least one of them must have the value 1.0; it is referred to as the preferred unit and all other units are scaled from the preferred unit.

hookupComponents

protected void hookupComponents()

Hookup the components by establishing event listener lists, etc.

setTextScaled

public void setTextScaled(boolean textScaled)

Deprecated. This property has been removed. To get unscaled behavior, simply provide an association list with all values equal to 1.0

If textScaled is true (the default), then changing the units will convert the visible text value but not change the underlying numeric value. For example, changing from "inches" to "millimeters" will change the text field from 1 to 25.4, for example. If false, then the visible text does not change, but the doubleData changes.

Parameters:

textScaled - true to scale the text, not the numeric value; false to preserve the visible text and scale the number.

getTextScaled

public boolean getTextScaled()

Deprecated. This property has been removed.

return the value of the textScaled property

Returns:

the value of the textScaled property

attachModel

public void attachModel(com.sas.ModelInterface model)

Description copied from interface: ViewInterface

Attaches the specified model to this view. Calls attachView on the model to notify it of the attach request. Throws a run time ComponentException if the model denies the attach request. Calls trapInterfaceEvents on the view to set up the appropriate event handlers in the view for attribute changed events from the model. attachModel will be called once for the model specified in the setModel method. It is the responsibility of the views to maintain interface handles to multiple models; one interface handle will be set in the attachModel call and cleared in detachModel. Therefore, the interface handle will always point to the last model attached to. Throws a run time ComponentException if the specified model does not support the required interface on the view. Calls refresh, passing the model interface, on the view after successful completion to allow the view to update itself.

Specified by:

attachModel in interface com.sas.ViewInterface

Overrides:

attachModel in class PanelVisualComponent

Parameters:

model - Model to attach to

See Also:

ViewInterface.attachModel(com.sas.ModelInterface)

updateUnits

protected void updateUnits()

update the object after the units collection has changed.

getUnits

public com.sas.collection.AssociationListInterface getUnits()

return the units association list.

Returns:

the association list that maps units to scales.

contentsChanged

public void contentsChanged(com.sas.collection.ContentsChangedEvent event)

handle a change in the units association list.

Specified by:

contentsChanged in interface com.sas.collection.ContentsChangedListener

Parameters:

event - a contents change event from the units association list.

validateUnits

public static void validateUnits(com.sas.collection.AssociationListInterface unitList)

Check that the units list is valid and throw an exception if not.

Throws:

java.lang.IllegalArgumentException - if the units contains values but one or more values is not a java.lang.Number, or if none == 1.0

getText

public java.lang.String getText()

Get the text value of the object

Specified by:

getText in interface com.sas.lang.StringDataInterface

Returns:

the numeric value in the text field followed by the string value of the current units.

toString

public java.lang.String toString()

Get the text value of the object

Overrides:

toString in class java.awt.Component

Returns:

the numeric value in the text field followed by the string value of the current units.

toString

protected static java.lang.String toString(double d)

format a double as a string, stripping trailing ".0"

Parameters:

d - a double

Returns:

the string representation of d, with the trailing ".0" stripped.

setText

public void setText(java.lang.String text)

Set the text attribute.

Specified by:

setText in interface com.sas.lang.StringDataInterface

Parameters:

text - must consist of a number, one or more spaces, and a string which matches one of the units toString values, Examples of valid input are "1.5 hours" or "0.001 meters" or "3e8 m/s"

setCurrentUnits

public void setCurrentUnits(java.lang.Object unit)

Deprecated. use setDisplayedUnit(Object)

Set the currently selected unit.

Parameters:

unit - must be one of the keys in the units association list

See Also:

setDisplayedUnit(Object)

getCurrentUnits

public final java.lang.Object getCurrentUnits()

Deprecated. use getDisplayedUnit()

Return the currently selected unit.

Returns:

the currently select unit of UnitsBox.

See Also:

getDisplayedUnit()

setDisplayedUnit

public void setDisplayedUnit(java.lang.Object unit)

Set the current units.

Parameters:

unit - must be one of the keys in the units association list

getDisplayedUnit

public java.lang.Object getDisplayedUnit()

Return the current units

Returns:

the currently select unit of UnitsBox.

getPreferredUnits

public final java.lang.Object getPreferredUnits()

Deprecated. use getUnit()

Return the preferred unit of UnitsBox

Returns:

the preferred unit - the first unit in the units association list whose scale is 1.0

getUnit

public java.lang.Object getUnit()

Return the preferred unit of UnitsBox

Specified by:

getUnit in interface com.sas.measures.MeasureInterface

Returns:

the preferred unit - the first unit in the units association list whose scale is 1.0

getUnitName

public java.lang.String getUnitName()

Return the preferred unit of UnitsBox

Specified by:

getUnitName in interface com.sas.measures.MeasureInterface

Returns:

the preferred unit - the first unit in the units association list whose scale is 1.0

getEquivalent

public final double getEquivalent(java.lang.String unit)

Deprecated. use getMagnitude (Object unit)

getMagnitude

public double getMagnitude(java.lang.Object unit)

Get the magnitude in the given unit.

Specified by:

getMagnitude in interface com.sas.measures.MeasureInterface

Parameters:

unit - the unit to scale the magnitude to return the scaled magnitude

getCurrentScale

public double getCurrentScale()

Return the amount by which the number is scaled The number in the text field is scaled by this much (determined by the current units) to calculate the doubleData property. For example, if the current scale is 1000.0 and the current text in the field is "3.5", then getDoubleData() will return 3500.0

Returns:

the current scale

setDisplayedUnit

public void setDisplayedUnit(int i)

Set the current units

Parameters:

i - is an index in the units association list.

Throws:

java.lang.IndexOutOfBoundsException - if i is less than 0 or >= units.count()

pickBestUnits

public void pickBestUnits()

Change the units to one whose scale is closest to the value. For example, if the doubleData property is 16,200,000.0 and the units/scales are 1/milliseconds, 1000/seconds, 60,000/minutes, 3,600,000/hours and 86,400,000/days, pickBestUnits will choose the units "hours" and the text property will change to "4.5 hours"

setColumns

public void setColumns(int nCols)

Set the number of columns in the textField of the UnitsBox.

setMaximumMagnitude

public void setMaximumMagnitude(double newMaximumMagnitude)

Set the maximumMagnitude property. Attempts to set the magnitude higher will be truncated to this value.

Parameters:

newMaximumMagnitude - the new value for the maximumMagnitude property.

getMaximumMagnitude

public double getMaximumMagnitude()

Return the value of the maximumMagnitude property.

Returns:

the value of the maximumMagnitude property.

setMinimumMagnitude

public void setMinimumMagnitude(double newMinimumMagnitude)

Set the minimumMagnitude property. Attempts to set the magnitude lower will be truncated to this value.

Parameters:

newMinimumMagnitude - the new value for the minimumMagnitude property.

getMinimumMagnitude

public double getMinimumMagnitude()

Return the value of the minimumMagnitude property.

Returns:

the value of the minimumMagnitude property.

updateMagnitude

protected void updateMagnitude()

Update the magnitude based on changes in the doubleData on the spinBox.

getDoubleData

public final double getDoubleData()

Return the numeric value of the UnitsBox object. This method is final; subclasses should override getMagnitude(). This method exists to implement DoubleDataInterface().

Specified by:

getDoubleData in interface com.sas.lang.DoubleDataInterface

Returns:

the value of getMagnitude()

See Also:

getMagnitude(java.lang.Object)

getMagnitude

public double getMagnitude()

Return the numeric value of the UnitsBox object.

Specified by:

getMagnitude in interface com.sas.measures.MeasureInterface

Returns:

the numeric value of the UnitsBox object. This is the value, expressed in the preferred units. For example, if the preferred units is "meters" but the current units is "kilometers" and the text field contains "57.5", then the doubleData property will be 57500.0 since the scale associated with the current units ("kilometers") is 1000.0

setDoubleData

public final void setDoubleData(double d)

Set the numeric value of the UnitsBox object. This method is final; subclasses should override setMagnitude(). This method exists to implement DoubleDataInterface().

Specified by:

setDoubleData in interface com.sas.lang.DoubleDataInterface

Parameters:

d - the new numeric value.

See Also:

setMagnitude(double)

setMagnitude

public void setMagnitude(double d)

Set the value of the UnitsBox, in perferred units.

Parameters:

d - the new value of the UnitsBox. This is the number of preferred units. For example, if the preferred units is "meters" then calling setDoubleData will change the number of meters. For example, setDoubleData(10300.0) will set the UnitsBox at 10,300 meters. If the current (display) units is "kilometers", then the text field will be set to "10.3" and the text property will become "10.3 kilometers".

If d < getMinimumMagnitude() or d > getMaximumMagnitude() it is adjusted to be in the valid range defined by those bounds.

updateText

protected void updateText()

Change the text after the units or double data have changed, while preserving the doubleData.

initialize

public void initialize()

Initialize the component.

Specified by:

initialize in interface com.sas.ComponentInterface

Overrides:

initialize in class PanelVisualComponent

See Also:

ComponentInterface.initialize()

newChoice

protected Choice newChoice()

Factory method for creating the choice Override this in subclasses if you want to use a different choice object

Returns:

a Choice

newSpinBox

protected SpinBox newSpinBox()

createComponents

protected void createComponents()

Create the components of the composite object. This calls the factory methods to create the text field, spin button, and choice object.

layoutComponents

protected void layoutComponents()

Lays out the components in a layout manager.

propertyChange

public void propertyChange(java.beans.PropertyChangeEvent event)

Handle a property change event from one of the components.

1. if integerRange.value changes, increment/decrement the text number (i.e. add/subtract on scale value)
2. if textField.text changes, update the doubleData and text properties accordingly
3. if the choice.text property changes, change the current units and scale

Specified by:

propertyChange in interface java.beans.PropertyChangeListener

Overrides:

propertyChange in class PanelVisualComponent

See Also:

PropertyChangeListener.propertyChange(java.beans.PropertyChangeEvent)

getUnitsDisplayTransform

public com.sas.util.transforms.TransformInterface getUnitsDisplayTransform()

return the units display transform

Returns:

the transform object which this UnitsBox object uses to to convert the unit values (the keys in the units association list) into displayable strings in the combo box.

setUnitsDisplayTransform

public void setUnitsDisplayTransform(com.sas.util.transforms.TransformInterface unitsDisplayTransform)

Set the units display transform.

Parameters:

unitsDisplayTransform - the transform object which this UnitsBox object uses to to convert the unit values (the keys in the units association list) into displayable strings in the combo box. If null, then unit.toString() is used.

setValidator

public void setValidator(ValidationInterface validator)

Set the validator for the text in the textField of the SpinBox. If a model is set the implements the ValidationInterface, this property will be set with the model. This property must be set after the model if a different validator is wanted. If this is set before the model is set, it will be overridden if the model implements the ValidationInterface.

Specified by:

setValidator in interface ValidatorInterface

Overrides:

setValidator in class PanelContainerComponent

setErrorHandler

public void setErrorHandler(ErrorHandlerInterface errorHandler)

Set the errorHandler for the validator of the text in the textField of the SpinBox.

Specified by:

setErrorHandler in interface ValidatorInterface

Overrides:

setErrorHandler in class PanelContainerComponent

makeTimeUnits

public static com.sas.collection.AssociationListInterface makeTimeUnits()

Deprecated. Use com.sas.measures.Time.makeUnitsAssociationList()

Create an associationlist for time units.