com.jidesoft.chart.event
Class ChartCrossHair

java.lang.Object
  com.jidesoft.chart.event.ChartCrossHair

All Implemented Interfaces:

Drawable, ComponentListener, MouseListener, MouseMotionListener, EventListener

public class ChartCrossHair
extends Object
implements MouseListener, MouseMotionListener, ComponentListener, Drawable

This class can be used to track the mouse position as it moves along a trace.

Here is a screenshot, where the ChartCrossHair is shown in red:

When the model property is not set, the class tracks the nearest point from all available models. When the model property is set, the points are limited to points from that model.

Note: This class used to be called ChartValueFocus but was renamed to avoid overloading the term focus

Author:

Simon White (swhite@catalysoft.com)

See Also:

ChartValueReporter

Field Summary

static String	PROPERTY_CHART The propertyName of the PropertyChangeEvent that is fired when the chart property changes
static String	PROPERTY_CIRCLE_DIAMETER The propertyName of the PropertyChangeEvent that is fired when the circleDiameter property changes
static String	PROPERTY_COLOR The propertyName of the PropertyChangeEvent that is fired when the color property changes
static String	PROPERTY_HORIZONTAL_LINE_VISIBLE The propertyName of the PropertyChangeEvent that is fired when the visibility of the horizontal line changes
static String	PROPERTY_MODEL The propertyName of the PropertyChangeEvent that is fired when the model property changes
static String	PROPERTY_OBSERVED_MODEL The propertyName of the PropertyChangeEvent that is fired when the (read-only) observedModel property changes
static String	PROPERTY_POSITION The property name of the PropertyChangeEvent that is fired when the position of the cross hair changes.
static String	PROPERTY_SNAP_TO_POINTS The propertyName of the PropertyChangeEvent that is fired when the snapToPoints property changes.
static String	PROPERTY_STROKE The property name of the PropertyChangeEvent that is fired when the Stroke property changes.
static String	PROPERTY_UPDATE_FROM_MODEL The property name of the PropertyChangeEvent that is fired when the UpdateFromModel property changes.
static String	PROPERTY_VERTICAL_LINE_VISIBLE The propertyName of the PropertyChangeEvent that is fired when the visibility of the vertical line changes
static String	PROPERTY_VISIBLE The propertyName of the PropertyChangeEvent that is fired when the (read-only) visible property changes

Constructor Summary

ChartCrossHair()
Default constructor provided mainly for compatibility with Java bean pattern.

ChartCrossHair(Chart chart)
Create a new ChartCrossHair instance for use with the supplied chart.

ChartCrossHair(Chart chart, boolean autoRegister)
Creates a new ChartCrossHair instance for use with the supplied chart.

Method Summary

void	addPropertyChangeListener(PropertyChangeListener listener) Add a property change listener to this object.
void	componentHidden(ComponentEvent e)
void	componentMoved(ComponentEvent e)
void	componentResized(ComponentEvent e)
void	componentShown(ComponentEvent e)
void	detach()
void	draw(Graphics g) Draw the object implementing this interface onto the supplied Graphics context
Chart	getChart() Returns the chart object this class operates with
int	getCircleDiameter() The diameter of the circle that is used for locating the position of the cross hair
Color	getColor() The color used for the cross hair
ChartModel	getModel() Returns the model of interest, if any.
ChartModel	getObservedModel() This is a read-only property that allows you to find out which model the cross hair is currently pointing at.
Chartable	getPosition() Returns the position of the cross hair in user coordinates
Stroke	getStroke() Returns the stroke currently used for the horizontal and vertical line of the cross hair
Point	getXAxisPoint() Returns the pixel point for (x, 0).
Point	getYAxisPoint() Returns the pixel point for (y, 0).
boolean	isHorizontalLineVisible() Returns the flag to indicate whether a horizontal line is drawn as part of the cross hair
boolean	isSnapToPoints() Returns a value indicating whether the cross hair is allowed to assume a position between adjacent data points of a model (false) or 'snap' to genuine points (true).
boolean	isUpdateFromModel() Returns the value of the updateFromModel property
boolean	isVerticalLineVisible() Returns the flag to indicate whether a vertical line is drawn as part of the cross hair
void	mouseClicked(MouseEvent e) Not used
void	mouseDragged(MouseEvent e) Recognises a change in the mouse position under dragging
void	mouseEntered(MouseEvent e) Makes the visible property true when the mouse enters the chart
void	mouseExited(MouseEvent e) Makes the visible property false when the mouse exits the chart
void	mouseMoved(MouseEvent e) Recognises a change in the mouse position
void	mousePressed(MouseEvent e) Not used
void	mouseReleased(MouseEvent e) Not used
void	removePropertyChangeListener(PropertyChangeListener listener) Remove a previously-added listener
void	setChart(Chart chart) Specify the chart object on which the cross hair operates
void	setCircleDiameter(int circleDiameter) Sets the diameter of the circle to use for the centre of the cross hair
void	setColor(Color color) Set the color to use for the cross hair
void	setHorizontalLineVisible(boolean horizontalLineVisible) Specify whether a horizontal line should be drawn as part of the cross hair
void	setModel(ChartModel model) If you set the model of the ChartValueReporter, then only points from that model will be reported.
void	setPosition(Chartable chartable) Enables you to set the position of the ChartCrossHair programmatically
void	setSnapToPoints(boolean snapToPoints) Specify whether the cross hair should 'snap' to known data points.
void	setStroke(Stroke stroke) Specify the stroke to use for the horizontal and vertical lines of the cross hair
void	setUpdateFromModel(boolean updateFromModel) Specify whether the position of the cross hair is dependent on one or more models in the chart.
void	setVerticalLineVisible(boolean verticalLineVisible) Specify whether a vertical line should be drawn as part of the cross hair
void	update() Update the cross hair using the latest known cursor position.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PROPERTY_COLOR

public static final String PROPERTY_COLOR

The propertyName of the PropertyChangeEvent that is fired when the color property changes

See Also:

Constant Field Values

PROPERTY_CHART

public static final String PROPERTY_CHART

The propertyName of the PropertyChangeEvent that is fired when the chart property changes

See Also:

Constant Field Values

PROPERTY_CIRCLE_DIAMETER

public static final String PROPERTY_CIRCLE_DIAMETER

The propertyName of the PropertyChangeEvent that is fired when the circleDiameter property changes

See Also:

Constant Field Values

PROPERTY_MODEL

public static final String PROPERTY_MODEL

The propertyName of the PropertyChangeEvent that is fired when the model property changes

See Also:

Constant Field Values

PROPERTY_OBSERVED_MODEL

public static final String PROPERTY_OBSERVED_MODEL

The propertyName of the PropertyChangeEvent that is fired when the (read-only) observedModel property changes

See Also:

Constant Field Values

PROPERTY_POSITION

public static final String PROPERTY_POSITION

The property name of the PropertyChangeEvent that is fired when the position of the cross hair changes. This may be more interesting when the snapToPoints property is true.

See Also:

Constant Field Values

PROPERTY_SNAP_TO_POINTS

public static final String PROPERTY_SNAP_TO_POINTS

The propertyName of the PropertyChangeEvent that is fired when the snapToPoints property changes.

See Also:

Constant Field Values

PROPERTY_STROKE

public static final String PROPERTY_STROKE

The property name of the PropertyChangeEvent that is fired when the Stroke property changes.

See Also:

Constant Field Values

PROPERTY_UPDATE_FROM_MODEL

public static final String PROPERTY_UPDATE_FROM_MODEL

The property name of the PropertyChangeEvent that is fired when the UpdateFromModel property changes.

See Also:

Constant Field Values

PROPERTY_VISIBLE

public static final String PROPERTY_VISIBLE

The propertyName of the PropertyChangeEvent that is fired when the (read-only) visible property changes

See Also:

Constant Field Values

PROPERTY_HORIZONTAL_LINE_VISIBLE

public static final String PROPERTY_HORIZONTAL_LINE_VISIBLE

The propertyName of the PropertyChangeEvent that is fired when the visibility of the horizontal line changes

See Also:

Constant Field Values

PROPERTY_VERTICAL_LINE_VISIBLE

public static final String PROPERTY_VERTICAL_LINE_VISIBLE

The propertyName of the PropertyChangeEvent that is fired when the visibility of the vertical line changes

See Also:

Constant Field Values

Constructor Detail

ChartCrossHair

public ChartCrossHair()

Default constructor provided mainly for compatibility with Java bean pattern. It is expected that you would usually pass in a chart object to the constructor since you cannot use this class without telling the instance which chart object it should be applied to.

ChartCrossHair

public ChartCrossHair(Chart chart)

Create a new ChartCrossHair instance for use with the supplied chart.

Parameters:

chart - the Chart instance for which we wish to create a cross hair

ChartCrossHair

public ChartCrossHair(Chart chart,
                      boolean autoRegister)

Creates a new ChartCrossHair instance for use with the supplied chart. If autoRegister is true, it also registers itself as a MouseListener and a MouseMotionListener on the chart, as well as adding itself as a Drawable. It is very common to perform these operations immediately after creating the ChartCrossHair so the ChartCrossHair class offers this as a convenience.

Parameters:

chart - the chart instance for which we wish to create a CrossHair

autoRegister - whether we wish to auto-register the CrossHair as a listener on the chart.

Method Detail

detach

public void detach()

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener listener)

Add a property change listener to this object. You might do this for instance to discover when the ChartModel that is under the cross hair changes.

Parameters:

listener - the PropertyChangeListener

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener listener)

Remove a previously-added listener

Parameters:

listener - the PropertyChangeListener to remove

getChart

public Chart getChart()

Returns the chart object this class operates with

Returns:

a chart object

setChart

public void setChart(Chart chart)

Specify the chart object on which the cross hair operates

Parameters:

chart - the chart object

isVerticalLineVisible

public boolean isVerticalLineVisible()

Returns the flag to indicate whether a vertical line is drawn as part of the cross hair

Returns:

whether a vertical line is drawn as part of the cross hair

setVerticalLineVisible

public void setVerticalLineVisible(boolean verticalLineVisible)

Specify whether a vertical line should be drawn as part of the cross hair

Parameters:

verticalLineVisible - whether the line is visible

isHorizontalLineVisible

public boolean isHorizontalLineVisible()

Returns the flag to indicate whether a horizontal line is drawn as part of the cross hair

Returns:

whether a horizontal line is drawn as part of the cross hair

setHorizontalLineVisible

public void setHorizontalLineVisible(boolean horizontalLineVisible)

Specify whether a horizontal line should be drawn as part of the cross hair

Parameters:

horizontalLineVisible - whether the line is visible

isSnapToPoints

public boolean isSnapToPoints()

Returns a value indicating whether the cross hair is allowed to assume a position between adjacent data points of a model (false) or 'snap' to genuine points (true).

Returns:

a boolean to indicate whether the snapToPoints property is set.

setSnapToPoints

public void setSnapToPoints(boolean snapToPoints)

Specify whether the cross hair should 'snap' to known data points. If this is not set the cross hair is allowed to assume a position on the straight line path between adjacent points of a model.

Parameters:

snapToPoints - the new value of the snapToPoints property

isUpdateFromModel

public boolean isUpdateFromModel()

Returns the value of the updateFromModel property

Returns:

the value of the updateFromModel property

setUpdateFromModel

public void setUpdateFromModel(boolean updateFromModel)

Specify whether the position of the cross hair is dependent on one or more models in the chart. If set to false you can set the position of the cross hair independently.

Parameters:

updateFromModel - the new value of the updateFromModel property

getStroke

public Stroke getStroke()

Returns the stroke currently used for the horizontal and vertical line of the cross hair

Returns:

the Stroke currently used for the horizontal and vertical line of the cross hair

setStroke

public void setStroke(Stroke stroke)

Specify the stroke to use for the horizontal and vertical lines of the cross hair

Parameters:

stroke - the stroke to use for the horizontal and vertical line of the cross hair

getXAxisPoint

public Point getXAxisPoint()

Returns the pixel point for (x, 0). This is useful when working out where to draw the cross hair.

Returns:

the pixel point for (x, 0)

getYAxisPoint

public Point getYAxisPoint()

Returns the pixel point for (y, 0). This is useful when working out where to draw the cross hair.

Returns:

the pixel point for (y, 0)

mouseClicked

public void mouseClicked(MouseEvent e)

Not used

Specified by:

mouseClicked in interface MouseListener

mousePressed

public void mousePressed(MouseEvent e)

Not used

Specified by:

mousePressed in interface MouseListener

mouseReleased

public void mouseReleased(MouseEvent e)

Not used

Specified by:

mouseReleased in interface MouseListener

mouseDragged

public void mouseDragged(MouseEvent e)

Recognises a change in the mouse position under dragging

Specified by:

mouseDragged in interface MouseMotionListener

mouseEntered

public void mouseEntered(MouseEvent e)

Makes the visible property true when the mouse enters the chart

Specified by:

mouseEntered in interface MouseListener

mouseExited

public void mouseExited(MouseEvent e)

Makes the visible property false when the mouse exits the chart

Specified by:

mouseExited in interface MouseListener

mouseMoved

public void mouseMoved(MouseEvent e)

Recognises a change in the mouse position

Specified by:

mouseMoved in interface MouseMotionListener

componentResized

public void componentResized(ComponentEvent e)

Specified by:

componentResized in interface ComponentListener

componentMoved

public void componentMoved(ComponentEvent e)

Specified by:

componentMoved in interface ComponentListener

componentShown

public void componentShown(ComponentEvent e)

Specified by:

componentShown in interface ComponentListener

componentHidden

public void componentHidden(ComponentEvent e)

Specified by:

componentHidden in interface ComponentListener

getModel

public ChartModel getModel()

Returns the model of interest, if any. Note that this may be different from the observed model.

Returns:

the model of interest, if any

setModel

public void setModel(ChartModel model)

If you set the model of the ChartValueReporter, then only points from that model will be reported. Otherwise points from the nearest model will be reported.

Parameters:

model - the model from which points should be reported

getColor

public Color getColor()

The color used for the cross hair

Returns:

the color used for the cross hair

setColor

public void setColor(Color color)

Set the color to use for the cross hair

Parameters:

color - the new color to use

getObservedModel

public ChartModel getObservedModel()

This is a read-only property that allows you to find out which model the cross hair is currently pointing at.

Returns:

the ChartModel under the cross hair

update

public void update()

Update the cross hair using the latest known cursor position. You should not need to call this method directly.

setPosition

public void setPosition(Chartable chartable)

Enables you to set the position of the ChartCrossHair programmatically

Parameters:

chartable - the position of the cross hair in user coordinates

getPosition

public Chartable getPosition()

Returns the position of the cross hair in user coordinates

Returns:

the position of the cross hair in user coordinates

draw

public void draw(Graphics g)

Draw the object implementing this interface onto the supplied Graphics context

Specified by:

draw in interface Drawable

Parameters:

g - the Graphics context

getCircleDiameter

public int getCircleDiameter()

The diameter of the circle that is used for locating the position of the cross hair

Returns:

the diameter of the circle used for the centre of the cross hair

setCircleDiameter

public void setCircleDiameter(int circleDiameter)

Sets the diameter of the circle to use for the centre of the cross hair

Parameters:

circleDiameter - given in pixels