com.davisor.graphics.chart
Class ChartAxis

java.lang.Object
  com.davisor.graphics.chart.AxisAttributes
      com.davisor.graphics.chart.ChartAxis

All Implemented Interfaces:

com.davisor.core.Dupable, java.io.Serializable

public class ChartAxis

extends AxisAttributes

ChartAxis represents one chart coordinate axis that is a member of a group of ChartAxes. In particular, each axis knows which axes group it belongs to, and can revert back to the group for example for default attribute values.

A chart axis extends the set of user configurable attributes defined by its superclass with the following attributes:

• angle - chart rotation angle around this axis (degrees)
• dim - the axis dimension (non-negative dimension index)
• value range attributes:
  • min - axis minimum value as string (may be null)
  • max - axis maximum value as string (may be null)
  • step - axis step value as string (may be null)
• titleText - axis title text (may be null)
• unitTitle - axis unit explanation text (may be null)

Axis dimension

Axis dimension controls in what role the axis will be used in it's parent axes group. Any two axes belonging to the same axes group can not have the same dimension index. An axis dimension may be:

• integer string ("0", "1", ...)
• physical dimension ("x", "y", "z")
• conceptual dimension ("category", "value", "series")
• anything else but null

Please note, that the axis dimension names are case sensitive, and therefore for example a dimension name "X" will not be interpreted as a physical dimension. For more information about axis dimension, please see ChartAxes.getAxis(int) method.

Axis angle

Axis angle measures visual orientation of the chart around this axis. Depending on context, the orientation angle may be visualized by isometric, true 3D, or mere logical orientation change, whatever is meaningfull in each context. Angle units are always expressed as degrees. Chart factories should support at least positive small values between 0-90 degrees even if they can not do full 3D visualization.

Orientation around several axes is also possible, with each axis contributing one orientation angle. When meaningfull, axis orientation angles should be applied in their dimension index order, starting from the X -axis (dimension zero).

Use getAngle() and setAngle(float) to access the axis angle attribute.

Axis value range attributes

Axis minimum, maximum and step attributes define axis value range and principal step magnitude. The user configurable range attributes are expressed as strings in order to allow them to be applied to values of any data Type. In particular, actual data may be later laid along this axis by calling the computeValues(com.davisor.data.DataValue[]) method.

If the operation is successfull, the given value range string attributes, if any, are converted to DataValue objects. These objects can then be used to carry out various data value computation operations in data type specific way.

Use getStringValue(int) and setStringValue(int, java.lang.String) to access the generic axis value range attributes, and getDataValue(int) and setDataValue(int, com.davisor.data.DataValue, boolean) to access the data values derived from them.

Axis titles

Axis title defines a title string that somehow describes the values laid along the axis, while axis unit title describes the units of the values. All titles are axis spesific, and they do not have coordinate system wide default values.

Use getTitleText() and setTitleText(java.lang.String) to access the axis title attribute.Use getUnitTitle() and setUnitTitle(java.lang.String) to access the axis unit title attribute.

Value sharing

Any number of axes may be linked together to share their limit and step values together. This linking makes any limit or step value change in any linked axis visible to all other axes linked with it. The linking works by making one of the linked axis a master axis others will then refer to for up-to-date shared axis limit and step value information.

Axes are linked with combine(com.davisor.graphics.chart.ChartAxis) method. Please see the documentation of that method for more information about how to link axes together.

The linking mechanism complicates the processing and access of certain axis attributes that are derived from axis limit and step values. In particular, in order to keep the derived values up-to-date, a notification of any change in shared limit and step values must reach all the axes sharing them. In order to do this, all axes maintain a status indicator that tells when the derived values were last updated. Each time when an axis derived value is then requested, a check is made to see if axis status is up-to-date, and if it is not, the derived values are recomputed before returning their values.

Value computing

During chart processing the computeValues(com.davisor.data.DataValue[]) method will be called once. At the end of that method call, the original minimum, maximum, and step attribute string values will be replaced with string representations of the values the chart axis value resolver finally ended up with. These string values are later used in particular when axis label size requirements are estimated.

Chart axis objects are mutable, stateful objects that are modified in many other ways too during chart construction. In particular, a chart axis object carries the following transient attributes, derived from the chart data:

• minValue - axis minimum value as data value
• maxValue - axis maximum value as data value
• stepValue - axis step value as data value
• steps - the number of major axis value steps
• position - axis proportional position
• wasSet - indicates if axis limit values were computed or explicitly set

Axis minimum and maximum values define the axis value range. The step value defines the value change that represents one major value step along the axis. The number of steps tells into how many major value steps the axis is divided. Finally, the position tells where other axes should cross this axis, relative to current axis value range. Typically this coincides with axis zero value position, but not always.

           min                max
            : axis value range :
 -----------+------------------+----------->  axis values
            : step : step : step :            step values
 ... <0 ... 0  ...   0<1  ...  1 ... >1 ...   axis position
 

The attributes derived from chart data may be accessed only after the axis minimum and maximum data values have been determined and applied to the axis with a call of the computeValues method. Calling that method also resolves any proposed minimum and maximum values that the axis might have been given earlier.

Since:

JDK1.2

See Also:

computeValues(com.davisor.data.DataValue[]), ChartAxes, Serialized Form

Field Summary

static double	IMAXSTEPS Inverted maximum number of steps (1/MAXSTEPS).
static int	LIMITS Number of step value indexes.
protected java.lang.Float	M_angle Rotation around axis (degrees).
protected java.lang.String	M_dim Axis dimension.
protected java.util.ArrayList	M_markers Marker lines.
protected java.lang.String[]	M_stringValue Explicitly set string data values, if any (MIN,MAX,STEP).
protected java.lang.String	M_titleText Axis title text string (may be null).
protected java.lang.String	M_unitTitle Axis unit title text.
static int	MAX Maximum value index.
static int	MAXSTEPS Maximum number of steps on an axis (1000).
static int	MIN Minimum value index.
static int	STEP Step value index.

Fields inherited from class com.davisor.graphics.chart.AxisAttributes

AFTER_KEYWORD, AFTER_VALUE, BEFORE_KEYWORD, BEFORE_VALUE, M_gap, M_gridLines, M_labelFormat, M_labelOffset, M_labelRotation, M_level, M_markerOffset, M_opposite, M_positionStringValue, M_render, M_reversed, M_silent, M_tic, M_titleOffset, M_titleRotation, MAX_KEYWORD, MAX_VALUE, MIN_KEYWORD, MIN_VALUE

Constructor Summary

ChartAxis(ChartAxis ca)
Deep copy constructor.

ChartAxis(java.lang.String dim)
Creates a new axis.

ChartAxis(java.lang.String dim, AxisRenderAttributes render, java.lang.String labelFormat, java.lang.Number gap, java.awt.Shape tic, java.lang.Integer level, java.lang.Boolean gridLines, java.lang.String titleText, java.lang.Float titleRotation, java.lang.Float titleOffset, java.lang.Float markerOffset, java.lang.String unitTitle, java.lang.Float labelRotation, java.lang.Float labelOffset, java.lang.Boolean opposite, java.lang.Boolean reversed, java.lang.Boolean silent, java.lang.String position, java.lang.Number angle, java.lang.String min, java.lang.String max, java.lang.String step)
Creates a new fully configured axis.

Method Summary

void	addMarker(AxisMarker marker) Adds a marker to this axis.
int	bumpValue(boolean min, int steps) Bumps axis minimum or maximum values given number of steps away from each other.
float	bumpValue(float length, float before, float after) Bumps axis minimum and maximum values a number of steps away from each other.
protected void	changeStep(DataValue newStep) Changes current step value if not previously explicitly set to a specific value.
void	combine(ChartAxis axis) Combines given axis with this if possible.
protected void	computeDerivedValues() Computes axis derived values, and bring axis state up to date.
protected void	computePosition() Computes axis position relative to current axis minimum and maximum values.
protected void	computeSample() Computes and sets limit value sample.
protected void	computeSteps() Computes the number of steps between current minimum and maximum values, and current step value.
void	computeValues(DataValue[] limitValue) Computes axis minimum, maximum, step, and position values.
com.davisor.core.Dupable	dup() Duplicates this object.
boolean	equals(java.lang.Object object) Tests if this axis equals to given axis.
java.lang.Number	getAngle() Gets the axis angle.
ChartAxes	getAxes() Gets the axes group that this axis belongs to.
Type	getDataType(int valueIndex) Gets the axis value data type.
DataValue	getDataValue(int valueIndex) Gets the axis value.
float	getDefaultPosition() Gets axis default position value.
java.lang.String	getDim() Gets axis dimension identifier.
java.lang.Number	getGap() Gets the axis gap.
java.lang.String	getLabelFormat() Gets axis label type specification.
java.lang.Number	getLabelOffset() Gets the axis label offset.
float	getLabelOffset(float defaultOffset) Gets the axis label offset.
float	getLabelRotation() Gets label rotation in degrees.
java.lang.Float	getMarkerOffset() Gets the axis marker offset.
float	getMarkerOffset(float defaultOffset) Gets the axis marker offset.
java.util.ArrayList	getMarkers() Returns reference to the markers list (may be NULL).
float	getPosition() Gets the axis position value, as computed by computePosition().
java.lang.String	getPositionStringValue() Gets axis position.
AxisRenderAttributes	getRender() Gets the axis render attributes.
float	getSteps() Gets an estimate of the the number of axis steps.
java.lang.String	getStringValue(int valueIndex) Gets the axis value.
java.awt.Shape	getTic() Gets the axis tic mark.
float[]	getTitleBounds(java.awt.Font defaultFont) Compute title bounds from current title font, text, and rotation.
java.lang.Float	getTitleOffset() Gets the axis title offset.
float	getTitleOffset(float defaultOffset) Gets the axis title offset.
float	getTitleRotation() Gets title rotation in degrees.
java.lang.String	getTitleText() Gets axis title text.
java.lang.String	getUnitTitle() Gets the axis unit title text.
java.lang.Boolean	hasGridLines() Tests if grid lines perpendicular to the axis are enabled.
int	hashCode() Gets axis hash code.
boolean	hasStringValue(int valueIndex) Tests if the axis value has been set.
java.lang.Boolean	isOpposite() Gets the axis side.
boolean	isPositionSpecial() Tests if the position returned by getPosition() is special.
java.lang.Boolean	isReversed() Gets the axis direction.
boolean	isShared() Tests if this axis shares it's data value with another axis.
java.lang.Boolean	isSilent() Tests axis silency.
void	reduceSteps(float steps) Reduces the number of axis steps down to given number of steps.
float	reduceSteps(float availableSize, float idealSize) Reduces the number of axis steps if possible and usefull.
protected void	round() Rounds limit values to the current step value.
void	setAngle(float angle) Sets axis angle in degrees.
void	setAngle(java.lang.Number angle) Sets axis angle in degrees.
void	setAxes(ChartAxes axes) Sets the axes group that this axis belongs to.
void	setDataValue(int valueIndex, DataValue dataValue, boolean exact) Sets an axis data value.
void	setDefaultPosition(float defaultPosition) Sets axis default position value.
void	setDim(java.lang.String dim) Sets axis dimension identifier.
void	setRender(AxisRenderAttributes render) Sets the axis render attributes.
void	setStringValue(int valueIndex, java.lang.String stringValue) Sets the axis value.
void	setTitleText(java.lang.String titleText) Sets the axis title text.
void	setUnitTitle(java.lang.String unitTitle) Sets the axis unit title text.
java.lang.String	toString() Gets axis XML representation.
protected boolean	wasSet(int valueIndex) Tests if given axis value has been explicitly set.
protected void	wasSet(int valueIndex, boolean wasSet) Sets if given axis value has been explicitly set.

Methods inherited from class com.davisor.graphics.chart.AxisAttributes

getLevel, isOppositeDefault, isReversedDefault, isSilentDefault, setGap, setGap, setGridLines, setGridLines, setLabelFormat, setLabelOffset, setLabelOffset, setLabelRotation, setLabelRotation, setLevel, setMarkerOffset, setMarkerOffset, setOpposite, setOpposite, setPositionStringValue, setReversed, setReversed, setSilent, setSilent, setTic, setTitleOffset, setTitleOffset, setTitleRotation, setTitleRotation

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

MIN

public static final int MIN

Minimum value index.

See Also:

Constant Field Values

MAX

public static final int MAX

Maximum value index.

See Also:

Constant Field Values

STEP

public static final int STEP

Step value index.

See Also:

Constant Field Values

LIMITS

public static final int LIMITS

Number of step value indexes.

See Also:

Constant Field Values

MAXSTEPS

public static final int MAXSTEPS

Maximum number of steps on an axis (1000).

See Also:

Constant Field Values

IMAXSTEPS

public static final double IMAXSTEPS

Inverted maximum number of steps (1/MAXSTEPS).

See Also:

Constant Field Values

M_angle

protected java.lang.Float M_angle

Rotation around axis (degrees).

M_dim

protected java.lang.String M_dim

Axis dimension.

M_markers

protected java.util.ArrayList M_markers

Marker lines.

M_stringValue

protected java.lang.String[] M_stringValue

Explicitly set string data values, if any (MIN,MAX,STEP).

M_titleText

protected java.lang.String M_titleText

Axis title text string (may be null).

M_unitTitle

protected java.lang.String M_unitTitle

Axis unit title text.

Constructor Detail

ChartAxis

public ChartAxis(java.lang.String dim)

Creates a new axis.

Please note, that the dimension identifiers are case sensitive, and therefore for example a dimension name "X" is not the same is dimension name "x".

Parameters:

dim - the dimension this axis represents

See Also:

setDim(java.lang.String), ChartAxes.getAxis(int)

ChartAxis

public ChartAxis(ChartAxis ca)

Deep copy constructor. Parent axes is, however, left undetermined, as it will most propably by of some other axes group than the one that the copied axis belongs to.

See Also:

dup(), setAxes(com.davisor.graphics.chart.ChartAxes)

ChartAxis

public ChartAxis(java.lang.String dim,
                 AxisRenderAttributes render,
                 java.lang.String labelFormat,
                 java.lang.Number gap,
                 java.awt.Shape tic,
                 java.lang.Integer level,
                 java.lang.Boolean gridLines,
                 java.lang.String titleText,
                 java.lang.Float titleRotation,
                 java.lang.Float titleOffset,
                 java.lang.Float markerOffset,
                 java.lang.String unitTitle,
                 java.lang.Float labelRotation,
                 java.lang.Float labelOffset,
                 java.lang.Boolean opposite,
                 java.lang.Boolean reversed,
                 java.lang.Boolean silent,
                 java.lang.String position,
                 java.lang.Number angle,
                 java.lang.String min,
                 java.lang.String max,
                 java.lang.String step)
          throws com.davisor.core.InvalidKeyException

Creates a new fully configured axis.

Please note, that the dimension identifiers are case sensitive, and therefore for example a dimension name "X" is not the same is dimension name "x".

Parameters:

dim - axis dimension

render - render attributes (may be null)

labelFormat - axis label type specification (may be null)

gap - gap (percents, may be null)

tic - tic mark shape (may be null)

level - tic mark recursion level

gridLines - enable or disable grid lines (may be null)

titleText - title text (may be null)

titleRotation - title rotation (degrees,may be null)

titleOffset - axis title offset (may be null)

markerOffset - axis marker offset (may be null)

unitTitle - axis unit text (may be null)

labelRotation - axis label rotation (degrees,may be null)

labelOffset - axis label offset (may be null)

opposite - axis side (may be null)

reversed - axis growth direction (may be null)

silent - suppress axis labels (may be null)

position - axis position (may be null)

angle - rotation around axis (degrees, may be null)

min - axis scale minimum value (may be null)

max - axis scale maximum value (may be null)

step - axis scale step value (may be null)

See Also:

setDim(java.lang.String), ChartAxes.getAxis(int)

Method Detail

getGap

public java.lang.Number getGap()

Gets the axis gap. If the axis has no gap attribute of its own, the axes gap attribute is returned. If axes gap attribute or the axes have not been set, null is returned.

Overrides:

getGap in class AxisAttributes

See Also:

AxisAttributes.getGap(), AxisAttributes.setGap(float)

getLabelOffset

public java.lang.Number getLabelOffset()

Gets the axis label offset. If the axis has no label offset of its own, the axes label offset is returned. If axes label offset or the axes have not been set, null is returned.

If this axis shares label offset with another axis, the offset value is fetched from the other axis instance.

Overrides:

getLabelOffset in class AxisAttributes

See Also:

getLabelOffset(float)

getLabelOffset

public float getLabelOffset(float defaultOffset)

Gets the axis label offset. If the axis has no label offset of its own, the axes label offset is returned. If axes label offset or the axes have not been set, a given default offset value is returned.

If this axis shares label offset with another axis, the offset value is fetched from the other axis instance.

Overrides:

getLabelOffset in class AxisAttributes

Parameters:

defaultOffset - default offset to be used if the offset has not been set

See Also:

getLabelOffset()

getLabelRotation

public float getLabelRotation()

Gets label rotation in degrees. If rotation value is currently unset, rotation defaults to 0, indicating horizontal positive direction. Positive values turn the labels counter-clockwise.

Use Units to convert the angle value to other angle units.

Overrides:

getLabelRotation in class AxisAttributes

See Also:

AxisAttributes.setLabelRotation(float), AxisAttributes.setLabelRotation(Number), Units

getPositionStringValue

public java.lang.String getPositionStringValue()

Gets axis position. If the axis has no position attribute of its own, the axes position attributes is returned. If axes position attribute or the axes have not been set, null is returned.

Overrides:

getPositionStringValue in class AxisAttributes

See Also:

AxisAttributes.setPositionStringValue(java.lang.String)

getRender

public AxisRenderAttributes getRender()

Gets the axis render attributes. If the axis has no render attributes of its own, the axes render attributes are returned. If axes render attributes or the axes have not been set, null is returned.

If this axis and the axis group it belongs to have both a set of render attributes, the attributes in axis attribute set default to axis group attributes.

Overrides:

getRender in class AxisAttributes

See Also:

setRender(com.davisor.graphics.chart.AxisRenderAttributes), AxisAttributes.getRender(), AxisAttributes.setRender(com.davisor.graphics.chart.AxisRenderAttributes), AxisAttributes.getRender(), ChartFactory

getLabelFormat

public java.lang.String getLabelFormat()

Gets axis label type specification. If the axis has no label format attribute of its own, the axes label format attribute is returned. If axes label format attribute or the axes have not been set, null is returned.

Overrides:

getLabelFormat in class AxisAttributes

See Also:

AxisAttributes.getLabelFormat(), AxisAttributes.setLabelFormat(java.lang.String)

getMarkerOffset

public java.lang.Float getMarkerOffset()

Gets the axis marker offset. If the axis has no marker offset of its own, the axes marker offset is returned. If axes marker offset or the axes have not been set, null is returned.

If this axis shares marker offset with another axis, the offset value is fetched from the other axis instance.

Overrides:

getMarkerOffset in class AxisAttributes

See Also:

getMarkerOffset(float)

getMarkerOffset

public float getMarkerOffset(float defaultOffset)

Gets the axis marker offset. If the axis has no marker offset of its own, the axes marker offset is returned. If axes marker offset or the axes have not been set, a given default offset value is returned.

If this axis shares marker offset with another axis, the offset value is fetched from the other axis instance.

Overrides:

getMarkerOffset in class AxisAttributes

Parameters:

defaultOffset - default offset to be used if the offset has not been set

See Also:

getMarkerOffset()

getTic

public java.awt.Shape getTic()

Gets the axis tic mark. If the axis has no tic attribute of its own, the axes tic attribute is returned. If axes tic attribute or the axes have not been set, null is returned.

Overrides:

getTic in class AxisAttributes

See Also:

AxisAttributes.getTic(), AxisAttributes.setTic(java.awt.Shape)

getTitleOffset

public java.lang.Float getTitleOffset()

Gets the axis title offset. If the axis has no title offset of its own, the axes title offset is returned. If axes title offset or the axes have not been set, null is returned.

If this axis shares title offset with another axis, the offset value is fetched from the other axis instance.

Overrides:

getTitleOffset in class AxisAttributes

See Also:

getTitleOffset(float)

getTitleOffset

public float getTitleOffset(float defaultOffset)

Gets the axis title offset. If the axis has no title offset of its own, the axes title offset is returned. If axes title offset or the axes have not been set, a given default offset value is returned.

If this axis shares title offset with another axis, the offset value is fetched from the other axis instance.

Overrides:

getTitleOffset in class AxisAttributes

Parameters:

defaultOffset - default offset to be used if the offset has not been set

See Also:

getTitleOffset()

getTitleRotation

public float getTitleRotation()

Gets title rotation in degrees. If rotation value is currently unset, rotation defaults to 0, indicating horizontal positive direction. Positive values turn the title counter-clockwise.

Use Units to convert the angle value to other angle units.

Overrides:

getTitleRotation in class AxisAttributes

See Also:

AxisAttributes.setTitleRotation(float), AxisAttributes.setTitleRotation(Number), Units

hasGridLines

public java.lang.Boolean hasGridLines()

Tests if grid lines perpendicular to the axis are enabled. If the axis leaves this undetermined, the axes grid lines are tested. If axes grid lines status or the axes have not been set, null is returned.

Overrides:

hasGridLines in class AxisAttributes

See Also:

AxisAttributes.setGridLines(Boolean)

isOpposite

public java.lang.Boolean isOpposite()

Gets the axis side. If the axis has no opposite side attribute of its own, the axes opposite side attribute is returned. If axes opposite side attribute or the axes have also not been set, null is returned.

Overrides:

isOpposite in class AxisAttributes

Returns:

axis side (may be null)

See Also:

AxisAttributes.isOpposite(), AxisAttributes.setOpposite(boolean), AxisAttributes.setOpposite(Boolean)

isReversed

public java.lang.Boolean isReversed()

Gets the axis direction. If the axis has no reversed direction attribute of its own, the axes reversed direction attribute is returned. If axes reversed direction attribute or the axes have not been set, null is returned.

Overrides:

isReversed in class AxisAttributes

Returns:

axis direction (may be null)

See Also:

AxisAttributes.isReversed(), AxisAttributes.setReversed(boolean), AxisAttributes.setReversed(Boolean)

isSilent

public java.lang.Boolean isSilent()

Tests axis silency. If the axis has no silency attribute of its own, the axes silency attribute is returned. If axes silency attribute or the axes have not been set, null is returned.

Overrides:

isSilent in class AxisAttributes

Returns:

axis silence status (may be null)

See Also:

AxisAttributes.isSilent(), AxisAttributes.setSilent(boolean), AxisAttributes.setSilent(Boolean)

setRender

public void setRender(AxisRenderAttributes render)

Sets the axis render attributes. If the axis belongs to an axes group, the render attribute defaults are set to the axes render attributes.

Overrides:

setRender in class AxisAttributes

See Also:

getRender(), AxisAttributes.setRender(com.davisor.graphics.chart.AxisRenderAttributes)

dup

public com.davisor.core.Dupable dup()

Duplicates this object.

Specified by:

dup in interface com.davisor.core.Dupable

Overrides:

dup in class AxisAttributes

equals

public boolean equals(java.lang.Object object)

Tests if this axis equals to given axis. The axes are equal if their super classes and dimensions are. The rest of the axis attributes do not matter.

Overrides:

equals in class AxisAttributes

hashCode

public int hashCode()

Gets axis hash code. It depends on super class hash code, and the current axis dimension. The rest of the axis attributes do not matter.

Overrides:

hashCode in class AxisAttributes

toString

public java.lang.String toString()

Gets axis XML representation.

Overrides:

toString in class AxisAttributes

See Also:

AxisAttributes.toString(), Strings.toXML(String,Object)

changeStep

protected void changeStep(DataValue newStep)

Changes current step value if not previously explicitly set to a specific value. If the step is changes, the current minimum and maximum limit values are rounded to the new step value, and the current number of steps and axis position are recalculated.

Parameters:

newStep - a new step value to replace the old

See Also:

getDataValue(int), round(), setDataValue(int, com.davisor.data.DataValue, boolean)

computeDerivedValues

protected void computeDerivedValues()

Computes axis derived values, and bring axis state up to date. This method is called automatically once whenever there has been changes to axis limit or step values, and a value depending on them is requested.

Axis derived values are the number of steps, axis position, and format sample. Number of steps is computed with computeSteps(), position with computePosition(). Format sample is computed by multiplying current step value by three.

Axis steps and position are stored in internal variables, from where they can be accessed with getSteps() and getPosition(), respectively. Axis format sample value is stored in axis minimum and maximum value types, assuming they are instances of FormatType that supports the concept of format samples. If they do no, sample value is ignored.

See Also:

computePosition(), computeSample(), computeSteps(), getDataValue(int), getPosition(), getSteps(), FormatType.setSample(java.lang.Object)

computeSample

protected void computeSample()

Computes and sets limit value sample. The sample tells the magnitude of steps between the limit values. This magnitude may affect step label formatting. Please see for example SimpleNumberType.createFormatter().

See Also:

computeDerivedValues(), computeValues(com.davisor.data.DataValue[])

computeSteps

protected void computeSteps()

Computes the number of steps between current minimum and maximum values, and current step value. The result may never be zero, or has absolute value that exceeds system maximum allowed number of steps (ChartAxis.MAXSTEPS). The result may however be negative, indicating that current axis maximum value is smaller than current minimum value.

The number of steps is resolved by deinterpolating the value min+step against the value range axis minimum and maximum value span. This result may become zero for example if axis minimum and maximum values are equal. In this case a warning message is printed to system error channel, and the number of steps is set to 1.0.

The number of steps mat exceed the maximum allowed number of steps for example if axis step value magnitude is too small compared to the value range axis minimum and maximum values span. In this case a warning message is printed to system error channel, and the number of steps is set to equal to MAXSTEPS or -1.0 * MAXSTEPS, depending on steps value sign.

See Also:

computeDerivedValues(), computePosition(), getSteps(), DataValue.deinterpolate(com.davisor.data.DataValue, com.davisor.data.DataValue)

computePosition

protected void computePosition()

Computes axis position relative to current axis minimum and maximum values. This position tells where crossing axis lines should be rendered relative to the minimum and maximum values of this axis. In particular, a normal position value will be within range [0,1]: 0.0 indicates that axis position is before axis minimum value. 1.0 indicates that axis position is after axis maximum value. Other values within the range express axis zero value relative position between axis minimum and maximum values.

Position values outside the range [0,1] indicate special axis position: a value below zero indicates a position as far below axis minimum value as possible in given context. Likewise, a value above one indicates a position as far above axis maximum value as possible. In axis rendering for example, this indicates that an axis should be drawn at the edge of plotting area, even if the axis would fall outside the valid value range.

The crossing position can be controlled in several ways. First, if axis position string member variable contains values "min" or "max", the position will be at axis minimum or maximum end, respectively. "before" or "after" will place the position before or after the axis minimum or maximum end. Any other value will be interpreted as a data value that identifies a point along the axis. A null position value (the default) places crossing axes at the axis specific default value, typically zero (see setDefaultPosition(float)).

If after the above evaluation the position value would fall outside the range [0,1], the position becomes special. The actual position value is then cropped back to the range [0,1], but the special status is remembered, and it can later be checked with the isPositionSpecial() method.

If axis value range does not include zero, the crossing axes are placed to the axis end nearer to the zero value. If axis direction is reversed (see AxisAttributes.isReversedDefault()), the zero position is mirrored, too.

See Also:

computeDerivedValues(), computeSteps(), getPosition(), isPositionSpecial(), setDefaultPosition(float)

round

protected void round()
              throws InvalidDataException

Rounds limit values to the current step value. Any limit values previously explicitly set to specific values are not rounded.

Basic limit value rounding is done with limit value data type specific DataValue.ceil(DataValue) and DataValue.floor(DataValue) methods.

Throws:

InvalidDataException - if rounding fails

wasSet

protected boolean wasSet(int valueIndex)

Tests if given axis value has been explicitly set.

If this axis shares a data range with another axis, the status is queried from the other axis instance.

Parameters:

valueIndex - one of MIN, MAX, or STEP

See Also:

wasSet(int,boolean)

wasSet

protected void wasSet(int valueIndex,
                      boolean wasSet)

Sets if given axis value has been explicitly set.

If this axis shares a data range with another axis, the status is set for the other axis instance.

Parameters:

valueIndex - one of MIN, MAX, or STEP

wasSet - indicator that axis value has been explicitly set or not

See Also:

wasSet(int)

addMarker

public void addMarker(AxisMarker marker)

Adds a marker to this axis.

Parameters:

marker - the marker to be added

See Also:

getMarkers()

bumpValue

public int bumpValue(boolean min,
                     int steps)

Bumps axis minimum or maximum values given number of steps away from each other. Explicitly set axis minimum or maximum values are not affected.

Successfull bumping will increase the current number of steps. Axis position will also be recomputed.

Parameters:

min - if true, bump minimum value, otherwise bump maximum value

steps - the number of steps to bump

Returns:

the number of steps really added

See Also:

bumpValue(float,float,float), computePosition()

bumpValue

public float bumpValue(float length,
                       float before,
                       float after)

Bumps axis minimum and maximum values a number of steps away from each other. Explicitly set axis minimum or maximum values are not affected.

The number of steps to bump axis with is computed from a length value that describes an abstract distance between current minimum and maximum values, and the length values that describe how much of the new length is to be allocated for new steps. In particular, if length is chosen to be 100 units, before and after tell how many percents the new steps will take from the total new length after new steps have been added.

For example, if the axis currently has 8 steps, and length and the overflow aguments values are set to 100, 10, and 10, one new step will be added on either end, resulting 10 steps in total. The one new step on either side then represents 10% of all steps, as requested.

After both sides have been bumped, axis unit step is recomputed, if not explicitly set earlier. The number of axis steps is also updated, if neccessary.

Argument values are expecteed to be non-negative values. The value of before and after must be less than length value.

Parameters:

length - length of the area between minimum and maximum values

before - length of the area extending beyond minimum limit value

after - length of the area extending beyond maximum limit value

Returns:

maximum radius for a shape drawn inside the old value boundaries, expressed relative to the width of new boundaries

See Also:

bumpValue(boolean,int), computePosition()

combine

public void combine(ChartAxis axis)
             throws com.davisor.core.MismatchException

Combines given axis with this if possible. Combination is possible if the axes do not contain conflicting opposite or reverse status or explicitly set limit or step values, and if the data types of corresponding computed limit or step values are compatible. In particular, the following outcomes are possible:

• if given argument axis is already sharing limit or step values with any axis, even this one, the combination fails
• if axis limit or step values are explictly set to different values, the combination fails
• if a limit or step value is explictly set in one of the given axes, that value is used for all of them
• if a limit or step value is not explictly set in either one of the given axes, the value is derived as follows:
  • for minimum limit value, the value will be the smaller of the two computed minimum limit values
  • for maximum limit value, the value will be the greater of the two computed minimum limit values
  • for step value, the value will be the unit value computed from the two step values

Combination, if successfull, will replace the current limit and step values of this axis, and make the other axis to refer to this one as the primary source for limit and step value information. Any changes to the new shared limit and step values will thereafter affect both of these axes.

It is also possible to share limit and step values among more than two axes. In particular, if this axis already shares limit and step values with some other axes, all value sharing operations will target those already shared values, and therefore affect all the axes already sharing their limit and step values. An axis may however only belong to only one group of axes sharing ther limit and step values.

Parameters:

axis - axis to combine this axis with (may be null)

Throws:

com.davisor.core.MismatchException - if the two axes can not be combined

computeValues

public void computeValues(DataValue[] limitValue)
                   throws InvalidDataException

Computes axis minimum, maximum, step, and position values. The values are computed from given minimum and maximum data values, and current axis attributes.

The given limit value objects are made private members to this axis object. The limit value objects should therefore not be referenced from the outside after this method returns.

The data types of the given data values are also modified by this method, by applying axis type specifications to them. The resulting types are then used to interpret the axis minimum, maximum and step value strings. The same types may also be used later to compose axis data value labels.

When axis steps is resolved, the resulting step data value is normalized by substracting data type specific zero value from it. This allows step value to be entered like any other data value, using the same format than axis minimum and maximum values.

It is worth noting that badly chosen limit and step values may result in a very large number of steps. To avoid such mistakes, the axis has an inbuilt maximum number of steps that is given with MAXSTEPS. See the class description for the value of the maximum number of steps.

After calling this method, axis steps and position values can be retrieved by the getSteps() and getPosition() methods, respectively.

Parameters:

limitValue - axis minimum and maximum data values, with [ChartAxis.MIN,ChartAxis.MAX] as index

Throws:

InvalidDataException - if value computation fails

See Also:

computeSample(), getPosition(), getSteps(), AxisFactory.resolveLimits(com.davisor.graphics.chart.ChartDataSummary)

getAngle

public java.lang.Number getAngle()

Gets the axis angle.

Returns:

axis angle in degrees (may be null)

See Also:

setAngle(float), setAngle(Number)

getAxes

public ChartAxes getAxes()

Gets the axes group that this axis belongs to.

See Also:

setAxes(com.davisor.graphics.chart.ChartAxes)

getDataType

public Type getDataType(int valueIndex)
                 throws InvalidDataException

Gets the axis value data type. null value indicates that the value has not been set.

If axis current state does not match current target state, the current state is brough up-to-date before returning the (updated) value.

Parameters:

valueIndex - one of MIN, MAX, or STEP

Returns:

axis value data type (may be null)

Throws:

InvalidDataException - if type retrieval fails

See Also:

getStringValue(int), hasStringValue(int), setDataValue(int, com.davisor.data.DataValue, boolean), setStringValue(int, java.lang.String)

getDataValue

public DataValue getDataValue(int valueIndex)

Gets the axis value. null value indicates that the value has not been set.

If this axis shares a data range with another axis, the data value is fetched from the other axis instance.

Parameters:

valueIndex - one of MIN, MAX, or STEP

See Also:

getStringValue(int), hasStringValue(int), setDataValue(int, com.davisor.data.DataValue, boolean), setStringValue(int, java.lang.String)

getDefaultPosition

public float getDefaultPosition()

Gets axis default position value.

Returns:

axis position default value

See Also:

computeValues(com.davisor.data.DataValue[]), getPosition(), setDefaultPosition(float)

getDim

public java.lang.String getDim()

Gets axis dimension identifier.

See Also:

setDim(java.lang.String)

getMarkers

public java.util.ArrayList getMarkers()

Returns reference to the markers list (may be NULL).

See Also:

addMarker(com.davisor.graphics.chart.AxisMarker)

getPosition

public float getPosition()

Gets the axis position value, as computed by computePosition().

Axis position is always returned without taking axis current reverse status into account. Instead, it is the responsibility of the caller to take appropriate actions if the axis is reversed (for example, use '1 - position').

If axis current state does not match current target state, the current state is brough up-to-date before returning the (updated) value.

Returns:

axis position (always within range [0,1])

See Also:

computeDerivedValues(), getSteps(), isPositionSpecial()

getSteps

public float getSteps()

Gets an estimate of the the number of axis steps. The returned value tells how many uniformly spaced unit steps can be expected to fit between axis current minimum and maximum values. The returned value may contain a fraction part if the steps do not fit evenly between the minimum and maximum values.

If axis current state does not match current target state, the current state is brough up-to-date before returning the (updated) value.

See Also:

computeDerivedValues(), getPosition()

getStringValue

public java.lang.String getStringValue(int valueIndex)

Gets the axis value. null value indicates that the value has not been set.

If this axis shares a data range with another axis, the string value is fetched from the other axis instance.

Parameters:

valueIndex - one of MIN, MAX, or STEP

See Also:

getDataValue(int), hasStringValue(int), setDataValue(int, com.davisor.data.DataValue, boolean), setStringValue(int, java.lang.String)

getTitleBounds

public float[] getTitleBounds(java.awt.Font defaultFont)

Compute title bounds from current title font, text, and rotation.

Parameters:

defaultFont - title default font

Returns:

title bounds, in [AxisFactory.WIDTH,AxisFactory.HEIGHT] array

getTitleText

public java.lang.String getTitleText()

Gets axis title text.

See Also:

setTitleText(java.lang.String)

getUnitTitle

public java.lang.String getUnitTitle()

Gets the axis unit title text.

See Also:

setUnitTitle(java.lang.String)

hasStringValue

public boolean hasStringValue(int valueIndex)

Tests if the axis value has been set.

Parameters:

valueIndex - one of MIN, MAX, or STEP

See Also:

getStringValue(int), setStringValue(int, java.lang.String)

isPositionSpecial

public boolean isPositionSpecial()

Tests if the position returned by getPosition() is special. If it is, a position value 'zero' indicates that the position should actually extend as far before the minimum value as possible in given context. Likewise, a position value 'one' indicates that the position should axterd as far after the maximum value as possible.

See Also:

getPosition(), computePosition()

isShared

public boolean isShared()

Tests if this axis shares it's data value with another axis.

See Also:

ChartAxes.isShared(int)

reduceSteps

public void reduceSteps(float steps)

Reduces the number of axis steps down to given number of steps. If the new given number of steps is greater or equal to current number of steps, nothing happens. Otherwise current minimum, maximum, and step values are changed to comply with the given new constrain. The new value range will be equal or greated than the old one.

If any of the old limit or step values are have been set to exact values, none of them are changed. Instead, axis grid lines are turned off.

Parameters:

steps - number of steps to constrain axis value range to

See Also:

setDataValue(int, com.davisor.data.DataValue, boolean), DataValue.unit(com.davisor.data.DataValue, double)

reduceSteps

public float reduceSteps(float availableSize,
                         float idealSize)

Reduces the number of axis steps if possible and usefull. The need for reduction is estimated from the ratio of given available and ideal sizes. The method then decides if it is possible to reduce the number of steps by that abount. If so, a new, larger axis step is computed with DataValue.unit(com.davisor.data.DataValue, double) method, and installed with changeStep(com.davisor.data.DataValue) method. An estimate of the new ideal size assumed to be proportional with the number of steps reduced is returned.

Parameters:

availableSize - available size

idealSize - ideal size

Returns:

new ideal size after step reduction, if any (equal to idealSize if not, less otherwise)

See Also:

changeStep(com.davisor.data.DataValue), DataValue.unit(com.davisor.data.DataValue, double)

setAngle

public void setAngle(float angle)

Sets axis angle in degrees. The axis angle defines the amount of chart rotation around this axis, expressed in degrees. Positive values turn the chart counter-clockwise. Y-axis angle is typically a negative value.

The axis angle is typically used to define a sheare three-dimensional look for the charts. Other chart type specific uses are also possible, like with pie charts where the axis angle can be used to turn the pie around its center axis.

Use Units to convert the angle value to other angle units.

See Also:

getAngle(), setAngle(Number), Units

setAngle

public void setAngle(java.lang.Number angle)

Sets axis angle in degrees. The axis angle defines the amount of chart rotation around this axis, expressed in degrees. Positive values turn the chart counter-clockwise. Y-axis angle is typically a negative value.

The axis angle is typically used to define a sheare three-dimensional look for the charts. Other chart type specific uses are also possible, like with pie charts where the axis angle can be used to turn the pie around its center axis.

Use Units to convert the angle value to other angle units.

Parameters:

angle - new angle value (may be null)

See Also:

getAngle(), setAngle(float), Units

setAxes

public void setAxes(ChartAxes axes)

Sets the axes group that this axis belongs to. This setting controls which axes group, if any, the axis attribute values default to. In particular, it is possible for an axis object to belong to several axes groups simultaneously, but axis attribute defaults values are always taken from only one axes group.

An axis that has been attached to an axes group takes it's default attribute values from that group. Furthermore, axis render attributes default to corresponding axis group render attributes.

Parameters:

axes - axes group that provides default values for this axis

See Also:

getAxes(), RenderAttributes.setDefaults(com.davisor.graphics.RenderAttributes)

setDataValue

public void setDataValue(int valueIndex,
                         DataValue dataValue,
                         boolean exact)

Sets an axis data value. null value indicates that the value has not been set.

The new value may be treated as an exact or an approximate value. If the value is exact, later computations and optimizations may not alter the value even at the risk of unresolvable constrain conflicts. If the value is only approximate, automatic constrain resolvers are permitted to adjust it later.

If this axis shares a data range with another axis, the data value is assigned to the shared axis instance.

Changing an axis data value affects a number of axis internal values that are derived from it. And if axis data values are shared among other axes, a change in data values will affect them all, too. This may potentially require a great number of derived value updates.

To balance and reduce a number of updates requires, derived value recomputing does not place immediately. Instead, axis current target state is changed to mark the need for derived value update operations. Actual recomputing is then deferred until a derived value is really needed.

Parameters:

valueIndex - one of MIN, MAX, or STEP

dataValue - value to be set

exact - tells if value must not be computationally changed

See Also:

getDataValue(int), getStringValue(int), hasStringValue(int), setStringValue(int, java.lang.String)

setDefaultPosition

public void setDefaultPosition(float defaultPosition)

Sets axis default position value. This value will control the axis position value in case the position is not explicitly set.

This parameter is not typically controlled directly by users, but by different chart factories that may want to apply different default axis value policies. For example, bar factory element axis default position is BEFORE_VALUE, as the typical default value MIN_VALUE would place the value axis at the middle of the first bar.

Parameters:

defaultPosition - new axis position default value

See Also:

computeValues(com.davisor.data.DataValue[]), getDefaultPosition(), getPosition(), BarFactory.createContext(com.davisor.graphics.chart.ChartData, com.davisor.graphics.chart.ChartAttributes, com.davisor.graphics.chart.ChartAxes, short)

setDim

public void setDim(java.lang.String dim)

Sets axis dimension identifier.

Please note that if this axis is a member of an axis group, setting axis dimension may create an inconsistency between the dimensions the axis group and the axis itself have for the axis.

Please note also, that the dimension identifiers are case sensitive, and therefore for example a dimension name "X" is not the same is dimension name "x".

Parameters:

dim - axis new dimension identifier (may be null)

See Also:

getDim(), ChartAxes.getAxis(int)

setStringValue

public void setStringValue(int valueIndex,
                           java.lang.String stringValue)

Sets the axis value. The value string interpretation as a data value depends on the axis value type and specification. The axis value type is defined by the data that will be displayed along this axis. The type specification is set by the corresponding axis attribute. A null value indicates that the value has not been set. An value invalid for the type of data dislayed along the axis will be ignored.

If this axis shares a data range with another axis, the string value is assigned to the shared axis instance.

Parameters:

valueIndex - one of MIN, MAX, or STEP

stringValue - value to be set

See Also:

getDataValue(int), getStringValue(int),