com.nwoods.jgo.instruments
Class AbstractIndicator

java.lang.Object
  extended bycom.nwoods.jgo.JGoObject
      extended bycom.nwoods.jgo.JGoDrawable
          extended bycom.nwoods.jgo.instruments.AbstractIndicator
All Implemented Interfaces:
JGoActionObject, JGoXMLSaveRestore, java.io.Serializable
Direct Known Subclasses:
IndicatorBar, IndicatorKnob, IndicatorNeedle, IndicatorSlider

public abstract class AbstractIndicator
extends JGoDrawable
implements JGoActionObject

An abstract class designed to visually represent a specific quantitative value.

AbstractIndicator provides a basis for indicators designed to interact with an implementation of GraduatedScale to indicate values that correspond to specific graphical points, determined by the GraduatedScale. However, it is possible to create an AbstractIndicator that does not rely on an instance of GraduatedScale, and the information needed to indicate specific values would be contained internally. This would be useful when the value system does not correspond to graphical points, such as a color scale system.

See Also:
Serialized Form

Field Summary
static int ChangedActionEnabled
          This is a JGoObject update subhint.
static int ChangedQuantBase
          This is a JGoObject update subhint.
static int ChangedQuantized
          This is a JGoObject update subhint.
static int ChangedQuantUnit
          This is a JGoObject update subhint.
static int ChangedScale
          This is a JGoObject update subhint.
static int ChangedValue
          This is a JGoObject update subhint.
 
Fields inherited from class com.nwoods.jgo.JGoObject
Bottom, BottomCenter, BottomLeft, BottomMiddle, BottomRight, Center, CenterLeft, CenterRight, Changed4ResizeHandles, ChangedAutoRescale, ChangedBrush, ChangedDraggable, ChangedDragsNode, ChangedGeometry, ChangedGrabChildSelection, ChangedInitializing, ChangedPen, ChangedResizable, ChangedSelectable, ChangedUpdatePartner, ChangedVisible, ChangedZOrder, LastChangedHint, Left, LeftCenter, NoHandle, NoSpot, NumReservedHandles, RepaintAll, Right, RightCenter, SideLeft, SideRight, Top, TopCenter, TopLeft, TopMiddle, TopRight
 
Constructor Summary
protected AbstractIndicator()
          The constructor changes the default JGoDrawable brush of Indicators to JGoBrush.red and makes it not Selectable.
 
Method Summary
 void changeValue(JGoDocumentChangedEdit e, boolean undo)
          Handle undo and redo changes.
protected  void computePath(java.awt.geom.GeneralPath path)
          Compute a GeneralPath used to paint this AbstractIndicator
 void copyNewValueForRedo(JGoDocumentChangedEdit e)
          This method is called when a JGoDocumentChangedEdit is created for a JGoDocumentEvent.CHANGED event, when a JGoObject has been changed.
 JGoObject copyObject(JGoCopyEnvironment env)
          Copy the field values and the internal data structures to avoid sharing references
 boolean doUncapturedMouseMove(int flags, java.awt.Point dc, java.awt.Point vc, JGoView view)
          Change the cursor to Cursors.Hand if the user can modify the value of this indicator interactively.
 void expandRectByPenWidth(java.awt.Rectangle rect)
          Take into account the bounds of the GeneralPath.
 void generateSVGOutput(DomDoc svgDoc, DomElement jGoElementGroup)
           
protected  void geometryChange(java.awt.Rectangle old)
          Whenever the size and/or position is changed, we need to recalculate the GeneralPath.
 JGoObject getPartner()
          Sometimes it is convenient to be able to associate an object with another object, without any predetermined knowledge about the class.
 java.awt.geom.GeneralPath getPath()
           
 double getQuantizeBase()
          Gets the base value which is allowed when AbstractIndicator.Quantized is true.
 double getQuantizeUnit()
          Gets the difference between two consecutive allowed values when AbstractIndicator.Quantized is true.
 GraduatedScale getScale()
          Gets the scale with which the indicator is associated.
 double getValue()
          Gets the value that will be indicated, relative to the associated GraduatedScale.
 double getValueForPoint(java.awt.Point dc)
          This method is called by onActionAdjusted and onAction to get the proposed new value for the given mouse point.
 boolean isActionActivated()
          Gets whether the object's Action is about to be invoked, normally by a mouse button being pressed.
 boolean isActionEnabled()
          Gets whether the user can adjust the indicators value.
 boolean isQuantized()
          Gets whether the indicator is forced to have discrete values.
 java.awt.geom.GeneralPath makePath()
          Make sure that whenever we reconstruct the main GeneralPath for this shape, we call computePath.
 void onAction(JGoView view, int modifiers, java.awt.Point dc, java.awt.Point vc)
          This method is called by JGoView to perform the object's action, normally by a mouse button being released.
 void onActionAdjusted(JGoView view, int modifiers, java.awt.Point dc, java.awt.Point vc, int event)
          This method is called by JGoView as the user is adjusting the object, normally by a mouse drag or move.
 void onActionCancelled(JGoView view)
          Just restore the original value of this indicator, as remembered when this indicator was activated.
 void paint(java.awt.Graphics2D g, JGoView view)
          Paint this object to a view, using a GeneralPath determined by a call to computePath.
 double quantizeValue(double val)
          A function used to ensure valid values within the quantized value system.
protected  void resetPath()
           
 void setActionActivated(boolean value)
          Sets whether the object's Action is about to be invoked, normally by a mouse button being pressed.
 void setActionEnabled(boolean value)
          Sets whether the user can adjust the indicators value.
 void setPartner(JGoObject value)
          Sometimes it is convenient to be able to associate an object with another object, without any predetermined knowledge about the class.
 void setQuantizeBase(double value)
          Sets the base value which is allowed when AbstractIndicator.Quantized is true.
 void setQuantized(boolean value)
          Sets whether the indicator is forced to have discrete values.
 void setQuantizeUnit(double value)
          Sets the difference between two consecutive allowed values when AbstractIndicator.Quantized is true.
 void setScale(GraduatedScale value)
          Sets the scale with which the indicator is associated.
 void setValue(double value)
          Sets the value that will be indicated, relative to the associated GraduatedScale.
 DomNode SVGReadObject(DomDoc svgDoc, JGoDocument jGoDoc, DomElement svgElement, DomElement jGoChildElement)
          Read this object in from a DomDoc representing a Scalable Vector Graphics (SVG) XML document.
 void SVGUpdateReference(java.lang.String attr, java.lang.Object referencedObject)
          This method will be called to fill in object references.
 void SVGWriteObject(DomDoc svgDoc, DomElement jGoElementGroup)
          Write this object out to a DomDoc representing a Scalable Vector Graphics (SVG) XML document.
 double validValue(double val)
          A function used to check the validity of the given value.
 
Methods inherited from class com.nwoods.jgo.JGoDrawable
draw3DRect, draw3DRect, drawEllipse, drawEllipse, drawEllipse, drawLine, drawLine, drawPath, drawPolygon, drawPolygon, drawRect, drawRect, drawRect, drawRoundRect, drawRoundRect, getBrush, getNearestIntersectionPoint, getPen, setBrush, setPen, SVGAddPathArgs, SVGReadAttributes, SVGWriteAttributes
 
Methods inherited from class com.nwoods.jgo.JGoObject
canView, computeBoundingRect, computeMove, computeResize, copy, copyObjectDelayed, copyOldValueForUndo, copyRect, doMouseClick, doMouseDblClick, findCommonParent, foredate, gainedSelection, geometryChangeChild, getBoundingRect, getDocument, getDraggingObject, getFlags, getHeight, getLayer, getLeft, getLocation, getLocation, getParent, getParentJGoNode, getParentNode, getRectangleSpotLocation, getSize, getSize, getSpotLocation, getSpotLocation, getToolTipText, getTop, getTopLeft, getTopLeft, getTopLevelObject, getView, getWidth, growRect, handleMove, handleResize, hideSelectionHandles, is4ResizeHandles, isAutoRescale, isBoundingRectInvalid, isChildOf, isDraggable, isDragsNode, isInitializing, isPointInObj, isResizable, isSelectable, isSkipsUndoManager, isSuspendChildUpdates, isSuspendUpdates, isTopLevel, isUpdatePartner, isVisible, lostSelection, ownerChange, partnerUpdate, pick, redirectSelection, remove, set4ResizeHandles, setAutoRescale, setBoundingRect, setBoundingRect, setBoundingRect, setBoundingRectForce, setBoundingRectForce, setBoundingRectInvalid, setBoundsRect, setDraggable, setDragsNode, setFlags, setHeight, setInitializing, setLeft, setLocation, setLocation, setLocationOffset, setLocationOffset, setParent, setRectangleSpotLocation, setResizable, setSelectable, setSize, setSize, setSizeKeepingLocation, setSkipsUndoManager, setSpotLocation, setSpotLocation, setSpotLocation, setSpotLocationOffset, setSuspendChildUpdates, setSuspendUpdates, setTop, setTopLeft, setTopLeft, setUpdatePartner, setVisible, setWidth, showSelectionHandles, spotOpposite, update, update
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ChangedValue

public static final int ChangedValue
This is a JGoObject update subhint.

See Also:
Constant Field Values

ChangedScale

public static final int ChangedScale
This is a JGoObject update subhint.

See Also:
Constant Field Values

ChangedQuantized

public static final int ChangedQuantized
This is a JGoObject update subhint.

See Also:
Constant Field Values

ChangedQuantBase

public static final int ChangedQuantBase
This is a JGoObject update subhint.

See Also:
Constant Field Values

ChangedQuantUnit

public static final int ChangedQuantUnit
This is a JGoObject update subhint.

See Also:
Constant Field Values

ChangedActionEnabled

public static final int ChangedActionEnabled
This is a JGoObject update subhint.

See Also:
Constant Field Values
Constructor Detail

AbstractIndicator

protected AbstractIndicator()
The constructor changes the default JGoDrawable brush of Indicators to JGoBrush.red and makes it not Selectable.

Method Detail

copyObject

public JGoObject copyObject(JGoCopyEnvironment env)
Copy the field values and the internal data structures to avoid sharing references

Overrides:
copyObject in class JGoDrawable
Parameters:
env - the environment for the copy operation - keeps track of copied objects.
Returns:
the new AbstractIndicator

getValue

public double getValue()
Gets the value that will be indicated, relative to the associated GraduatedScale.


setValue

public void setValue(double value)
Sets the value that will be indicated, relative to the associated GraduatedScale.

This calls validValue to make sure the new value is in the permitted range.


getScale

public GraduatedScale getScale()
Gets the scale with which the indicator is associated.


setScale

public void setScale(GraduatedScale value)
Sets the scale with which the indicator is associated.


validValue

public double validValue(double val)
A function used to check the validity of the given value.

Parameters:
val -
Returns:
If the given value is valid, returns that value. Else, returns the valid value that is "closest" to the given value.

isQuantized

public boolean isQuantized()
Gets whether the indicator is forced to have discrete values. If true, AbstractIndicator.Value is restricted to values that follow (value - AbstractIndicator.QuantizeBase) mod AbstractIndicator.QuantizeUnit = 0.


setQuantized

public void setQuantized(boolean value)
Sets whether the indicator is forced to have discrete values. If true, AbstractIndicator.Value is restricted to values that follow (value - AbstractIndicator.QuantizeBase) mod AbstractIndicator.QuantizeUnit = 0.

Setting this property does not actually change the Value. If you want to make sure the Value is "quantized" correctly, you will need to set it explicitly.


getQuantizeBase

public double getQuantizeBase()
Gets the base value which is allowed when AbstractIndicator.Quantized is true.


setQuantizeBase

public void setQuantizeBase(double value)
Sets the base value which is allowed when AbstractIndicator.Quantized is true.

Setting this property does not actually change the Value. If you want to make sure the Value is "quantized" correctly, you will need to set it explicitly.


getQuantizeUnit

public double getQuantizeUnit()
Gets the difference between two consecutive allowed values when AbstractIndicator.Quantized is true.


setQuantizeUnit

public void setQuantizeUnit(double value)
Sets the difference between two consecutive allowed values when AbstractIndicator.Quantized is true.

Setting this property does not actually change the Value. If you want to make sure the Value is "quantized" correctly, you will need to set it explicitly.


quantizeValue

public double quantizeValue(double val)
A function used to ensure valid values within the quantized value system.

Parameters:
val -
Returns:
If AbstractIndicator.Quantized is true, returns an acceptable quantized value that is closest to the given value. Otherwise it just returns the given value.

isActionEnabled

public boolean isActionEnabled()
Gets whether the user can adjust the indicators value.

The default value is false.

Specified by:
isActionEnabled in interface JGoActionObject

setActionEnabled

public void setActionEnabled(boolean value)
Sets whether the user can adjust the indicators value.

Specified by:
setActionEnabled in interface JGoActionObject
Parameters:
value -

isActionActivated

public boolean isActionActivated()
Gets whether the object's Action is about to be invoked, normally by a mouse button being pressed.

This defaults to false.

Specified by:
isActionActivated in interface JGoActionObject

setActionActivated

public void setActionActivated(boolean value)
Sets whether the object's Action is about to be invoked, normally by a mouse button being pressed.

A change to this state is considered transient, and does not invoke JGoObject.update.

Specified by:
setActionActivated in interface JGoActionObject
Parameters:
value -

onActionAdjusted

public void onActionAdjusted(JGoView view,
                             int modifiers,
                             java.awt.Point dc,
                             java.awt.Point vc,
                             int event)
This method is called by JGoView as the user is adjusting the object, normally by a mouse drag or move.

By default this just sets the Value according to the current input point. This will get called repeatedly as the user drags the mouse around. When calling setValue, this method temporarily sets SkipsUndoManager to true.

Specified by:
onActionAdjusted in interface JGoActionObject
Parameters:
view - the JGoView that the input event occurred in
modifiers - which keys are pressed
vc - the current position of the mouse in view coords
dc - the current position of the mouse in doc coords
event - one of JGoView.EventMouseDown, EventMouseMove, or EventMouseUp.

onAction

public void onAction(JGoView view,
                     int modifiers,
                     java.awt.Point dc,
                     java.awt.Point vc)
This method is called by JGoView to perform the object's action, normally by a mouse button being released.

By default this starts a transaction, sets the Value according to the current input point, and then ends the transaction.

Specified by:
onAction in interface JGoActionObject
Parameters:
view - the JGoView that the input event occurred in
modifiers - which keys are pressed
vc - the current position of the mouse in view coords
dc - the current position of the mouse in doc coords

onActionCancelled

public void onActionCancelled(JGoView view)
Just restore the original value of this indicator, as remembered when this indicator was activated.

Specified by:
onActionCancelled in interface JGoActionObject
Parameters:
view - the JGoView where the user is cancelling an action

getValueForPoint

public double getValueForPoint(java.awt.Point dc)
This method is called by onActionAdjusted and onAction to get the proposed new value for the given mouse point.

Parameters:
dc - a Point in document coordinates
Returns:
the new value, a double

doUncapturedMouseMove

public boolean doUncapturedMouseMove(int flags,
                                     java.awt.Point dc,
                                     java.awt.Point vc,
                                     JGoView view)
Change the cursor to Cursors.Hand if the user can modify the value of this indicator interactively.

Overrides:
doUncapturedMouseMove in class JGoObject
Parameters:
flags - the modifiers for this event
dc - the current mouse point in document coordinates
vc - the current mouse point in view coordinates
view - the JGoView
Returns:
true if the view's Cursor is changed to Cursors.Hand
See Also:
JGoView.doUncapturedMouseMove(int, java.awt.Point, java.awt.Point)

getPartner

public JGoObject getPartner()
Description copied from class: JGoObject
Sometimes it is convenient to be able to associate an object with another object, without any predetermined knowledge about the class. Although JGoObject does not provide any storage for this "property", subclasses may decide to do so.

By default this returns null.

Overrides:
getPartner in class JGoObject

setPartner

public void setPartner(JGoObject value)
Description copied from class: JGoObject
Sometimes it is convenient to be able to associate an object with another object, without any predetermined knowledge about the class. Although JGoObject does not provide any storage for this "property", subclasses may decide to do so.

By default this is a no-op.

Overrides:
setPartner in class JGoObject

geometryChange

protected void geometryChange(java.awt.Rectangle old)
Whenever the size and/or position is changed, we need to recalculate the GeneralPath.

Overrides:
geometryChange in class JGoObject

computePath

protected void computePath(java.awt.geom.GeneralPath path)
Compute a GeneralPath used to paint this AbstractIndicator

Parameters:
path - a GeneralPath that should be modified

getPath

public java.awt.geom.GeneralPath getPath()

resetPath

protected void resetPath()

makePath

public java.awt.geom.GeneralPath makePath()
Make sure that whenever we reconstruct the main GeneralPath for this shape, we call computePath.

Returns:
a newly allocated and initialized GeneralPath

paint

public void paint(java.awt.Graphics2D g,
                  JGoView view)
Paint this object to a view, using a GeneralPath determined by a call to computePath.

Overrides:
paint in class JGoObject
Parameters:
g - the graphics context on which to draw
view - the view we're drawing in

expandRectByPenWidth

public void expandRectByPenWidth(java.awt.Rectangle rect)
Take into account the bounds of the GeneralPath.

Overrides:
expandRectByPenWidth in class JGoDrawable
Parameters:
rect - the rectangle to be enlarged

copyNewValueForRedo

public void copyNewValueForRedo(JGoDocumentChangedEdit e)
Description copied from class: JGoObject
This method is called when a JGoDocumentChangedEdit is created for a JGoDocumentEvent.CHANGED event, when a JGoObject has been changed. In order for the JGoDocumentChangedEdit to be able to perform a redo, it needs to remember the new property value or state. However, the JGoObject.update method does not provide such a new value. The value must be taken from this object and copied into the JGoDocumentChangedEdit by calling setNewValue and/or setNewValueInt.

Just as the previous/old value/state information is stored as one or both of an integer and an Object, the new value/state information may be stored as either or both of an integer or an Object.

The responsibility for copying rests with the document event listener rather than the code calling JGoObject.update for efficiency when there is no undo/redo manager.

Overrides:
copyNewValueForRedo in class JGoDrawable

changeValue

public void changeValue(JGoDocumentChangedEdit e,
                        boolean undo)
Handle undo and redo changes.

Overrides:
changeValue in class JGoDrawable
Parameters:
e -
undo -

SVGWriteObject

public void SVGWriteObject(DomDoc svgDoc,
                           DomElement jGoElementGroup)
Description copied from interface: JGoXMLSaveRestore
Write this object out to a DomDoc representing a Scalable Vector Graphics (SVG) XML document.

This method will be called by com.nwoods.jgo.svg.DefaultDocument.SVGWriteDoc() for every JGoObject contained within a JGoDocument. The following example uses a JGoRectangle to illustrate the format of a generated SVG JGoObject:

<g>
<JGoClass class="com.nwoods.jgo.JGoRectangle"\>
<rect height="75" style="stroke:black;stroke-width:1;fill:rgb(255,0,0);" width="75" x="65" y="71"/>
<JGoClass class="com.nwoods.jgo.JGoDrawable" drawablebrush="jgoid1" drawablepen="jgoid2" embeddedpenbrush="false"/>
<JGoClass class="com.nwoods.jgo.JGoObject" obj_flags="1054"/>
</g>

Note that the entire JGoObject is enclosed in a group (<g>). Each subclass of the JGoObject is described by a <JGoClass> element, starting with the most specific class and moving to the more general. Each <JGoClass> element has a "class" attribute which defines the class name. Each <JGoClass> element may also have several other attributes which uniquely describe that state of that class. Following the <JGoClass> element, each class may also genereate any other elements that are required, including representations of contained objects and standard SVG elements such as the <rect> element shown in the above example. The generation of SVG elements in the output makes it possible for the output to be read by SVG viewers and other SVG aware applications. The information contained in the <JGoClass> elements allows us to accurately save and restore all the information in a particular JGoObject subclass.

If this class contains a reference to another object, call DomDoc.registerReferencingNode() to register that reference. This will cause the element representing the referenced object to be identified with a unique id attribute, and cause the element representing the referring object to have a user defined attribute containing a reference to that id. See DomDoc.registerReferencingNode() for more information.

Typically, an implementation of this method will generate a <JGoClass> element using the DomDoc.createJGoClassElement() method, adding whatever attributes are necessary to describe the class. It will then call its superclass so that the superclass can add its own <JGoClass> element and other information to jGoElementGroup within the DomDoc.

Refer to com.nwoods.jgo.examples.flower.ActivityNode.SVGWriteObject() and com.nwoods.jgo.examples.SimpleNode.SVGWriteObject() for examples using this method.

Refer to the file com.nwoods.jgo.svg\xsvg.dtd for a formal description of JGo extensions to the SVG document type.

Specified by:
SVGWriteObject in interface JGoXMLSaveRestore
Overrides:
SVGWriteObject in class JGoDrawable

generateSVGOutput

public void generateSVGOutput(DomDoc svgDoc,
                              DomElement jGoElementGroup)

SVGReadObject

public DomNode SVGReadObject(DomDoc svgDoc,
                             JGoDocument jGoDoc,
                             DomElement svgElement,
                             DomElement jGoChildElement)
Description copied from interface: JGoXMLSaveRestore
Read this object in from a DomDoc representing a Scalable Vector Graphics (SVG) XML document.

This method will be called by com.nwoods.jgo.svg.DefaultDocument.SVGReadDoc() for every <JGoClass> element encountered in a DomDoc. First, an object of the type specified by the class attribute will be created and then the SVGReadObject() method will be called on that newly created object. Refer to SVGWriteObject() for a description of the expected format of the SVG document.

This method may also be called by com.nwoods.jgo.svg.DefaultDocument.SVGReadDoc() when reading any SVG document, including those not generated by JGo and therefore not containing any <JGoClass> elements. In such cases, the DefaultDocument.SVGReadElement() method may be subclassed to examine the SVG element and cause the appropriate JGoObject to be created to represent that element and call SVGReadObject() on that newly created object. By default, standard JGoObjects such as JGoRectangles, JGoStrokes, etc will be created to represent these objects.

If this class contains a reference to another object, call DomDoc.registerReferencingObject() to register that reference. This will cause the JGoObject.SVGUpdateReference() to be called on the referencing object after all the objects have been created, passing in the object befing referenced. See DomDoc.registerReferencingObject() for more information.

Typically, an implementation of this method starts by verifying that the element being read is a <JGoClass> element (which will be true if jGoChildElement is not null). This will always be true unless you have subclassed the DefaultDocument.SVGReadElement() method as described above. It will then read the expected attributes of the <JGoClass> element (as written by SVGReadObject()), call SVGReadObject() on its superclass, and finally return the next element by calling svgElement.getNextSibling().

Refer to com.nwoods.jgo.examples.flower.ActivityNode.SVGReadObject() and com.nwoods.jgo.examples.SimpleNode.SVGReadObject() for examples using this method.

Specified by:
SVGReadObject in interface JGoXMLSaveRestore
Overrides:
SVGReadObject in class JGoDrawable

SVGUpdateReference

public void SVGUpdateReference(java.lang.String attr,
                               java.lang.Object referencedObject)
Description copied from class: JGoObject
This method will be called to fill in object references.

This is called by com.nwoods.jgo.svg.DefaultDocument.SVGReadDoc() after all the objects have been created and if DomDoc.registerReferencingObject() has been previously called by SVGReadObject().

Typically, an implementation of this method will first call the superclass and then fill in the appropriate object reference based on the attr argument.

Refer to com.nwoods.jgo.examples.SimpleNode.SVGWriteObject() for an example using this method.

Overrides:
SVGUpdateReference in class JGoDrawable