net.sourceforge.webcompmath.draw
Class CoordinateRect

java.lang.Object
  extended by net.sourceforge.webcompmath.draw.CoordinateRect
All Implemented Interfaces:
java.io.Serializable, Computable, InputObject, Limits, Tieable

public class CoordinateRect
extends java.lang.Object
implements Tieable, Limits, Computable, InputObject

A CoordinateRect represents a rectagular region in the xy-plane, specified by values xmin,xmax,ymin,ymax. The conditions ymin < ymax and xmin < xmax are enforced. (Values are swapped if necessary, and if min==max, they are reset to -1 and +1. If any of the values are set to an infinite or NaN value, then the coordinate rect won't display anything except the message "Error: undefined limits".)

When the Rect is mapped onto the screen, there can be a gap of a specified number of pixels between the min,max values and the edges of the rectangle on the screen. If the gap is non-zero, then the actual range of coordinates on the rect is larger than the range from the specifed min to max. (This is done mainly so I could have axes that don't quite reach the edges of the rect.)

A CoordinateRect maintains a list of Drawable items. When the Rect's draw() method is called, it calls the draw() method of each of the Drawable items it contains. When its compute() method is called, it calls the compute() method of any Drawable that is a Computable. When its checkInput() method is called, it calls the checkInput() method of any Drawable that is an InputObject.

A CoordinateRect represents a rectangular region in a DisplayCanvas. It has a reference to that Canvas, which is set automatically when it is added to the canvas. If the size, range, or gap on the CoordinateRect change, it will ask the Canvas to redraw the area it occupies.

The values of xmin, xmax, ymin, ymax are exported as Value objects, which can be used elsewhere in your program. The Value objects can be obtained by calling getValueObject(). If you do this, you should add the objects that depend on those values to a Controller and register the Controller to listen for changes from this CoordinateRect by calling the CoordinateRect.setOnChange(Controller) method.

See Also:
Serialized Form

Field Summary
protected  boolean changed
          Set to true when one of the limits or the gap has changed.
protected  java.util.Vector drawItems
          Drawable items contained in this CoordinateRect
protected  Controller onChange
          If non-null, this is the Controller that is notified when the limits change.
protected  Tie syncWith
          This contains other Limit objects with which the CoordinateRect is synchronizing.
static int XMAX
          A constant for use with the getValueObject() method to specify which Value is to be returned.
static int XMIN
          A constant for use with the getValueObject() method to specify which Value is to be returned.
static int YMAX
          A constant for use with the getValueObject() method to specify which Value is to be returned.
static int YMIN
          A constant for use with the getValueObject() method to specify which Value is to be returned.
 
Constructor Summary
CoordinateRect()
          Create a CoordinateRect with default limits: -5, 5, -5, 5.
CoordinateRect(double xmin, double xmax, double ymin, double ymax)
          Create a CoordinateRect with specified limits.
 
Method Summary
 void add(Drawable d)
          Add a drawable item to the CoordinateRect.
 void checkInput()
          When this is called, the CoordinateRect will call the checkInput method of any Drawable it contains that is also an InputObject.
 void clearRestoreBuffer()
          A CoordinateRect can store its current limits in a buffer.
 void compute()
          When this is called, the CoordinateRect will call the compute method of any Drawable it contains that is also a Computable.
protected  void doDraw(java.awt.Graphics g)
          Draw all the Drawable items.
 void draw(java.awt.Graphics g, int width, int height)
          Draw in rect with upperleft corner (0,0) and specified width,height.
 void draw(java.awt.Graphics g, int left, int top, int width, int height)
          Draw in specified rect.
 double[] equalizeAxes()
          Reset limits, if necessary, so scales on the axes are the same.
 Drawable getDrawable(int i)
          Get the i-th Drawable in this Rect, or null if i is less than zero or greater than or equal to the number of items.
 int getDrawableCount()
          Returns the number of Drawable items that are in this CoordinateRect.
 int getGap()
          Get the gap, in pixels, between the edges of the CoordinateRect and the limits specified by xmin, xmax, ymin, and ymax.
 int getHeight()
          Get the height in pixels of this CoordinateRect in the DisplayCanvas that contains it.
 int getLeft()
          Get the left edge of this CoordinateRect in the DisplayCanvas that contains it.
 double[] getLimits()
          Get an array containing the limits on the CoordinateRect in the order xmin, xmax, ymin, ymax.
 Controller getOnChange()
          Get the controller that is notified when the limits on this CoordinateRect change.
 double getPixelHeight()
          Return the height of one pixel in this coordinate system.
 double getPixelWidth()
          Return the width of one pixel in this coordinate system.
 double[] getRestoreBuffer()
          Get an array containing the limits for the restore buffer in the order xmin, xmax, ymin, ymax.
 long getSerialNumber()
          Return the serial number of the CoordinateRect, which is incremented each time the limits change.
 int getTop()
          Get the top edge of this CoordinateRect in the DisplayCanvas that contains it.
 Value getValueObject(int which)
          Get a Value object representing one of the limits on this CoordinateRect.
 int getWidth()
          Get the width in pixels of this CoordinateRect in the DisplayCanvas that contains it.
 double getXmax()
          Get the maximum x-coordinate.
 double getXmin()
          Get the mimimum x-coordinate.
 double getYmax()
          Get the maximum x-coordinate.
 double getYmin()
          Get the mimimum y-coordinate.
 boolean isSyncX()
          Get whether to sync xmin and xmax with limits
 boolean isSyncY()
          Get whether to sync ymin and ymax with limits
 void notifyControllerOnChange(Controller c)
          Method required by InputObject interface; in this class, it calls the same method recursively on any input objects containted in this CoordinateRect.
 double pixelToX(float h)
          Convert a horizontal pixel coordinate into an x-coordinate.
 double pixelToX(int h)
          Convert a horizontal pixel coordinate into an x-coordinate.
 double pixelToY(float y)
          Convert a vertical pixel coordinate into a y-coordinate.
 double pixelToY(int y)
          Convert a vertical pixel coordinate into a y-coordinate.
 void remove(Drawable d)
          Remove the given Drawable item, if present in this CoordinateRect.
 double[] restore()
          A CoordinateRect can store its current limits in a buffer.
 void setGap(int g)
          Set the gap.
 void setLimits(double[] d)
          Set the coordinate limits from array; extra elements in array are ignored.
 void setLimits(double xmin, double xmax, double ymin, double ymax)
          Set the limits on the CoordinteRect
 void setLimitsAndRestoreBuffer(double[] d)
          Set the coordinate limits, and also set the restore buffer.
 void setLimitsLazy(double xmin, double xmax, double ymin, double ymax)
          Set the limits on the CoordinteRect, but don't call compute.
 void setOnChange(Controller c)
          Specify a controller to be notified when the limits on this CoordinateRect change.
 void setRestoreBuffer()
          Save current limits in buffer.
 void setRestoreBuffer(double[] limits)
          Save specific limits in buffer.
 void setSyncWith(Tie tie)
          Set the Tie object that is used to synchronize this CoordinareRect with other objects.
 void setSyncX(boolean syncX)
          Set whether to sync xmin and xmax with limits
 void setSyncY(boolean syncY)
          Get whether to sync ymin and ymax with limits
 void sync(Tie tie, Tieable newest)
          Part of the Tieable interface.
 int xToPixel(double x)
          Convert an x-coodinate into a horizontal pixel coordinate.
 float xToPixelF(double x)
          Convert an x-coodinate into a horizontal pixel coordinate.
 int yToPixel(double y)
          Convert a y-coodinate into a vertical pixel coordinate.
 float yToPixelF(double y)
          Convert a y-coodinate into a vertical pixel coordinate.
 double[] zoomIn()
          Change limits to zoom in by a factor of 2.
 double[] zoomInOnPixel(int x, int y)
          Change limits to zoom in by a factor of 2, centered on a specified point.
 double[] zoomOut()
          Change limits to zoom out by a factor of 2.
 double[] zoomOutFromPixel(int x, int y)
          Change limits to zoom out by a factor of 2, centered on a specified point.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

drawItems

protected java.util.Vector drawItems
Drawable items contained in this CoordinateRect


changed

protected boolean changed
Set to true when one of the limits or the gap has changed.


syncWith

protected Tie syncWith
This contains other Limit objects with which the CoordinateRect is synchronizing. This is ordinarily managed by a LimitControlPanel, so you don't have to worry about it. (However, you can also sync several CoordinateRects even in the absense of a LimitControlPanel. To do so, create the Tie that ties the CoordinateRect and pass it to the setSyncWith() method of each CoordinateRect. It is NOT necessary to add the Tie to a Controller. Synchronization is handled by the CoordinateRects themselves.


XMIN

public static final int XMIN
A constant for use with the getValueObject() method to specify which Value is to be returned. XMIN specifies that the Value is the minimum x-coordinate on the CoordinateRect.

See Also:
Constant Field Values

XMAX

public static final int XMAX
A constant for use with the getValueObject() method to specify which Value is to be returned. XMAX specifies that the Value is the maximum x-coordinate on the CoordinateRect.

See Also:
Constant Field Values

YMIN

public static final int YMIN
A constant for use with the getValueObject() method to specify which Value is to be returned. YMIN specifies that the Value is the minimum y-coordinate on the CoordinateRect.

See Also:
Constant Field Values

YMAX

public static final int YMAX
A constant for use with the getValueObject() method to specify which Value is to be returned. YMAX specifies that the Value is the maximum y-coordinate on the CoordinateRect.

See Also:
Constant Field Values

onChange

protected Controller onChange
If non-null, this is the Controller that is notified when the limits change.

Constructor Detail

CoordinateRect

public CoordinateRect()
Create a CoordinateRect with default limits: -5, 5, -5, 5.


CoordinateRect

public CoordinateRect(double xmin,
                      double xmax,
                      double ymin,
                      double ymax)
Create a CoordinateRect with specified limits.

Parameters:
xmin - minimum x coord
xmax - mzximum x coord
ymin - minimum y coord
ymax - maximum y coord
Method Detail

getXmin

public double getXmin()
Get the mimimum x-coordinate.

Returns:
min x coord

getXmax

public double getXmax()
Get the maximum x-coordinate.

Returns:
max x coord

getYmin

public double getYmin()
Get the mimimum y-coordinate.

Returns:
min y coord

getYmax

public double getYmax()
Get the maximum x-coordinate.

Returns:
max y coord

getGap

public int getGap()
Get the gap, in pixels, between the edges of the CoordinateRect and the limits specified by xmin, xmax, ymin, and ymax.

Returns:
gap in pixels

setGap

public void setGap(int g)
Set the gap. This is ignored if g is less than zero. This gap is the number of pixels between the edges of the CoordinateRect and the limits specified by xmin, xmax, ymin, and ymax. The default value is 5.

Parameters:
g - gap in pixels

getLimits

public double[] getLimits()
Get an array containing the limits on the CoordinateRect in the order xmin, xmax, ymin, ymax.

Specified by:
getLimits in interface Limits
Returns:
limits of CoordinateRect

setLimits

public void setLimits(double xmin,
                      double xmax,
                      double ymin,
                      double ymax)
Set the limits on the CoordinteRect

Parameters:
xmin - the minimum x-coordinate on the CoordinateRect
xmax - the maximum x-coordinate on the CoordinateRect
ymin - the minimum y-coordinate on the CoordinateRect
ymax - the maximum y-coordinate on the CoordinateRect

setLimitsLazy

public void setLimitsLazy(double xmin,
                          double xmax,
                          double ymin,
                          double ymax)
Set the limits on the CoordinteRect, but don't call compute. Intended for use when initializing a javabean displaycanvas in a gui builder.

Parameters:
xmin - the minimum x-coordinate on the CoordinateRect
xmax - the maximum x-coordinate on the CoordinateRect
ymin - the minimum y-coordinate on the CoordinateRect
ymax - the maximum y-coordinate on the CoordinateRect

setLimits

public void setLimits(double[] d)
Set the coordinate limits from array; extra elements in array are ignored. This is ignored if the array is null or has fewer than 4 members. The order of values in the array is xmin, xmax, ymin, ymax.

Specified by:
setLimits in interface Limits
Parameters:
d - limits of CoordinateRect

setLimitsAndRestoreBuffer

public void setLimitsAndRestoreBuffer(double[] d)
Set the coordinate limits, and also set the restore buffer.

Parameters:
d - the limits to set

setOnChange

public void setOnChange(Controller c)
Specify a controller to be notified when the limits on this CoordinateRect change.

Parameters:
c - controller to use

getOnChange

public Controller getOnChange()
Get the controller that is notified when the limits on this CoordinateRect change. This can be null.

Returns:
controller

getValueObject

public Value getValueObject(int which)
Get a Value object representing one of the limits on this CoordinateRect. The parameter should be one of the constants CoordinateRect.XMIN, CoordinateRect.XMAX, CoordinateRect.YMIN, or CoordinateRect.YMAX. (If not, it is treated the same as YMAX).

Parameters:
which - specifies one of XMIN, XMAX, YMIN, YMAX
Returns:
value of the limit

getSerialNumber

public long getSerialNumber()
Return the serial number of the CoordinateRect, which is incremented each time the limits change. Part of the Tieable interface. Not meant to be called directly.

Specified by:
getSerialNumber in interface Tieable
Returns:
serial number

setSyncWith

public void setSyncWith(Tie tie)
Set the Tie object that is used to synchronize this CoordinareRect with other objects. This is ordinarily called by a LimitControlPanel, so you don't have to worry about it.

Parameters:
tie - the tie for synchronization

sync

public void sync(Tie tie,
                 Tieable newest)
Part of the Tieable interface. Not meant to be called directly.

Specified by:
sync in interface Tieable
Parameters:
tie - the tie to use
newest - the object to synch with

getLeft

public int getLeft()
Get the left edge of this CoordinateRect in the DisplayCanvas that contains it. (This is only valid when the CoordinateRect has actually been displayed. It is meant mainly to be used by Drawables in this CoordinateRect.)

Returns:
left edge

getWidth

public int getWidth()
Get the width in pixels of this CoordinateRect in the DisplayCanvas that contains it. (This is only valid when the CoordinateRect has actually been displayed. It is meant mainly to be used by Drawables in this CoordinateRect.)

Returns:
width in pixels

getTop

public int getTop()
Get the top edge of this CoordinateRect in the DisplayCanvas that contains it. (This is only valid when the CoordinateRect has actually been displayed. It is meant mainly to be used by Drawables in this CoordinateRect.)

Returns:
top edge

getHeight

public int getHeight()
Get the height in pixels of this CoordinateRect in the DisplayCanvas that contains it. (This is only valid when the CoordinateRect has actually been displayed. It is meant mainly to be used by Drawables in this CoordinateRect.)

Returns:
height in pixels

getPixelWidth

public double getPixelWidth()
Return the width of one pixel in this coordinate system. (This is only valid when the CoordinateRect has actually been displayed. It is meant mainly to be used by Drawables in this CoordinateRect.)

Returns:
width of one pixel

getPixelHeight

public double getPixelHeight()
Return the height of one pixel in this coordinate system. (This is only valid when the CoordinateRect has actually been displayed. It is meant mainly to be used by Drawables in this CoordinateRect.)

Returns:
height of one pixel

xToPixel

public int xToPixel(double x)
Convert an x-coodinate into a horizontal pixel coordinate. (This is only valid when the CoordinateRect has actually been displayed. It is meant mainly to be used by Drawables in this CoordinateRect.)

Parameters:
x - x coord to convert
Returns:
pixel coord

xToPixelF

public float xToPixelF(double x)
Convert an x-coodinate into a horizontal pixel coordinate. This version returns a float, for use with the newer Java 2D graphics. (This is only valid when the CoordinateRect has actually been displayed. It is meant mainly to be used by Drawables in this CoordinateRect.)

Parameters:
x - x coord to convert
Returns:
pixel coord

yToPixel

public int yToPixel(double y)
Convert a y-coodinate into a vertical pixel coordinate. (This is only valid when the CoordinateRect has actually been displayed. It is meant mainly to be used by Drawables in this CoordinateRect.)

Parameters:
y - y coord to conver
Returns:
pixel coord

yToPixelF

public float yToPixelF(double y)
Convert a y-coodinate into a vertical pixel coordinate. This version returns a float, for use with the newer Java 2D graphics. (This is only valid when the CoordinateRect has actually been displayed. It is meant mainly to be used by Drawables in this CoordinateRect.)

Parameters:
y - y coord to conver
Returns:
pixel coord

pixelToX

public double pixelToX(int h)
Convert a horizontal pixel coordinate into an x-coordinate. (This is only valid when the CoordinateRect has actually been displayed. It is meant mainly to be used by Drawables in this CoordinateRect.)

Parameters:
h - pixel coord to convert
Returns:
x coord

pixelToX

public double pixelToX(float h)
Convert a horizontal pixel coordinate into an x-coordinate. (This is only valid when the CoordinateRect has actually been displayed. It is meant mainly to be used by Drawables in this CoordinateRect.)

Parameters:
h - pixel coord to convert
Returns:
x coord

pixelToY

public double pixelToY(int y)
Convert a vertical pixel coordinate into a y-coordinate. (This is only valid when the CoordinateRect has actually been displayed. It is meant mainly to be used by Drawables in this CoordinateRect.)

Parameters:
y - pixel coord to convert
Returns:
y coord

pixelToY

public double pixelToY(float y)
Convert a vertical pixel coordinate into a y-coordinate. (This is only valid when the CoordinateRect has actually been displayed. It is meant mainly to be used by Drawables in this CoordinateRect.)

Parameters:
y - pixel coord to convert
Returns:
y coord

restore

public double[] restore()
A CoordinateRect can store its current limits in a buffer. These limits can be restored by a call to this method. Only one level of save/restore is provided. If limits have not been saved, then nothing happens. The original limits on the CoordinateRect are saves automatically when the CoordinateRect is first created.

Returns:
an array containing new limits.

clearRestoreBuffer

public void clearRestoreBuffer()
A CoordinateRect can store its current limits in a buffer. This method clears that buffer.


setRestoreBuffer

public void setRestoreBuffer()
Save current limits in buffer. They can be restored later by a call to the restore() method. Only one level of save/restore is provided.


setRestoreBuffer

public void setRestoreBuffer(double[] limits)
Save specific limits in buffer. They can be restored later by a call to the restore() method. Only one level of save/restore is provided.

Parameters:
limits - the limits to set

getRestoreBuffer

public double[] getRestoreBuffer()
Get an array containing the limits for the restore buffer in the order xmin, xmax, ymin, ymax.

Returns:
limits of restore buffer

zoomIn

public double[] zoomIn()
Change limits to zoom in by a factor of 2. A maximal zoom is enforced. The center of the rectangle does not move.

Returns:
an array of the new limits, or null if limits don't change.

zoomOut

public double[] zoomOut()
Change limits to zoom out by a factor of 2. A maximal zoom is enforced. The center of the rectangle does not move.

Returns:
an array of the new limits, or null if limits don't change.

zoomInOnPixel

public double[] zoomInOnPixel(int x,
                              int y)
Change limits to zoom in by a factor of 2, centered on a specified point. A maximal zoom is enforced. The point does not move. Only valid when CoordinateRect is displayed in a rectangle on the screen.

Parameters:
x - the horizontal pixel coordinate of the center point of the zoom
y - the vertical pixel coordinate of the center point of the zoom
Returns:
an array of the new limits, or null if limits don't change.

zoomOutFromPixel

public double[] zoomOutFromPixel(int x,
                                 int y)
Change limits to zoom out by a factor of 2, centered on a specified point. A maximal zoom is enforced. The point (x,y) does not move. Valid only if CoordinateRect has been drawn.

Parameters:
x - the horizontal pixel coordinate of the center point of the zoom
y - the vertical pixel coordinate of the center point of the zoom
Returns:
an array of the new limits, or null if limits don't change.

equalizeAxes

public double[] equalizeAxes()
Reset limits, if necessary, so scales on the axes are the same. Only valid of the CoordinateRect has been drawn.

Returns:
an array with the new limits, or null if limits don't change.

checkInput

public void checkInput()
When this is called, the CoordinateRect will call the checkInput method of any Drawable it contains that is also an InputObject. This is ordinarly only called by a DisplayCanvas.

Specified by:
checkInput in interface InputObject

compute

public void compute()
When this is called, the CoordinateRect will call the compute method of any Drawable it contains that is also a Computable. This is ordinarly only called by a DisplayCanvas.

Specified by:
compute in interface Computable

notifyControllerOnChange

public void notifyControllerOnChange(Controller c)
Method required by InputObject interface; in this class, it calls the same method recursively on any input objects containted in this CoordinateRect. This is meant to be called by JCMPanel.gatherInputs().

Specified by:
notifyControllerOnChange in interface InputObject
Parameters:
c - the controller

add

public void add(Drawable d)
Add a drawable item to the CoordinateRect.

Parameters:
d - item to add

remove

public void remove(Drawable d)
Remove the given Drawable item, if present in this CoordinateRect.

Parameters:
d - item to remove

getDrawableCount

public int getDrawableCount()
Returns the number of Drawable items that are in this CoordinateRect.

Returns:
number of items

getDrawable

public Drawable getDrawable(int i)
Get the i-th Drawable in this Rect, or null if i is less than zero or greater than or equal to the number of items.

Parameters:
i - The number of the item to be returned, where the first item is number zero.
Returns:
desired item

draw

public void draw(java.awt.Graphics g,
                 int width,
                 int height)
Draw in rect with upperleft corner (0,0) and specified width,height. This is not ordinarily called directly.

Parameters:
g - graphics context
width - width to draw in
height - height to draw in

draw

public void draw(java.awt.Graphics g,
                 int left,
                 int top,
                 int width,
                 int height)
Draw in specified rect. This is not ordinarily called directly.

Parameters:
g - graphics context
left - left edge
top - top edge
width - width of rect
height - height of rect

doDraw

protected void doDraw(java.awt.Graphics g)
Draw all the Drawable items. This is called by the draw() method and is not meant to be called directly. However, it might be overridden in a subclass.

Parameters:
g - graphics context

isSyncX

public boolean isSyncX()
Get whether to sync xmin and xmax with limits

Returns:
the syncX

setSyncX

public void setSyncX(boolean syncX)
Set whether to sync xmin and xmax with limits

Parameters:
syncX - the syncX to set

isSyncY

public boolean isSyncY()
Get whether to sync ymin and ymax with limits

Returns:
the syncY

setSyncY

public void setSyncY(boolean syncY)
Get whether to sync ymin and ymax with limits

Parameters:
syncY - the syncY to set