Skip to main content
Version: 4.2

Cartesian Linear Axes

The linear axis is use to chart numerical data. It can be placed on either the x or y axis.

Here are some example how to create linear axes:

// creates a linear axis with default scale id "y" and default kind "y" 
CartesianLinearAxis axis1 = new CartesianLinearAxis(chart);

// creates a linear axis with scale id "my-axis" and default kind "y"
CartesianLinearAxis axis2 = new CartesianLinearAxis(chart, "my-axis");

// creates a linear axis with scale id "my-axis" and default kind "y"
CartesianLinearAxis axis3 = new CartesianLinearAxis(chart, ScaleId.create("my-axis"));

// creates a linear axis with default scale id "y" and custom kind "y"
CartesianLinearAxis axis4 = new CartesianLinearAxis(chart, AxisKind.Y);

// creates a linear axis with scale id "my-axis" and custom kind "y"
CartesianLinearAxis axis5 = new CartesianLinearAxis(chart, "my-axis", AxisKind.Y);

// creates a linear axis with scale id "my-axis" and custom kind "y"
ScaleId myAxis = ScaleId.create("my-axis");
CartesianLinearAxis axis6 = new CartesianLinearAxis(chart, myAxis, AxisKind.Y);

// adds axes to chart configuration
chart.getOptions().setAxes(axis1, ...);

Options

The cartesian linear axis allows to define a number of properties, used to display the data.

// creates a linear axis 
CartesianLinearAxis axis = new CartesianLinearAxis(chart);
// sets and gets the max value
axis.setMax(100);

double max = axis.getMax();

The following are the attributes that you can set:

NameTypeDescription
alignToPixelsbooleanAlign pixel values to device pixels.
backgroundColorString - IsColorThe background color of scale area.
beginAtZerobooleanIf true, scale will include 0 if it is not already included.
boundsBoundsDetermines the scale bounds on axis.
displayboolean - DisplayIf Display.TRUE, the axis is shown.
graceintAmount of pixels for added room in the scale range above and below data.
graceAsPercentageStringPercentage (string ending with %) for added room in the scale range above and below data.
maxdoubleUser defined maximum number for the scale, overrides maximum value from data.
mindoubleUser defined minimum number for the scale, overrides minimum value from data.
offsetbooleanIf true, extra space is added to the both edges and the axis is scaled to fit in the chart area.
positionAxisPositionPosition of the axis.
reversebooleanReverses order of tick labels.
singleStackedbooleanIf you might want to stack positive and negative values together.
stackStringSets the stack group. Axes at the same position with same stack are stacked.
stackedbooleanIf the axis are stacked.
stackWeightdoubleSets the weight of the scale in stack group. Used to determine the amount of allocated space for the scale within the group.
suggestedMaxdoubleAdjustment used when calculating the maximum data value.
suggestedMindoubleAdjustment used when calculating the minimum data value.
weightintThe weight used to sort the axis. Higher weights are further away from the chart area.

Ticks

The linear axis provides the following options for configuring tick marks.

// creates a linear axis 
CartesianLinearAxis axis = new CartesianLinearAxis(chart);
// sets and gets the max value
axis.getTicks().setColor(HtmlColor.RED);

IsColor color = axis.gteTicks().getColor();

The following are the attributes that you can set:

NameTypeScriptableDescription
alignElementAlign-The tick alignment along the axis.
autoSkipboolean-If true, automatically calculates how many labels that can be shown and hides labels accordingly. Labels will be rotated up to maxRotation before skipping any. Turn autoSkip off to show all labels no matter what.
autoSkipPaddingint-The padding between the ticks on the horizontal axis when autoSkip is enabled.
backdropColorString - IsColorYesColor of label backdrops.
backdropPaddingPadding-The padding of tick backdrop.
See padding documentation for more details.
colorString - IsColorYesColor of ticks.
countintYesThe number of ticks to generate. If specified, this overrides the automatic generation.
crossAlignCrossAlign-The tick alignment perpendicular to the axis.
displayboolean-If true, the tick marks are shown.
fontIsFontYesFont of ticks.
See Font.
includeBoundsboolean-If true, the defined min and max values should be presented as ticks even if they are not "nice".
labelOffsetint-Distance in pixels to offset the label from the centre point of the tick (in the x-direction for the x-axis, and the y-direction for the y-axis).

Note: This can cause labels at the edges to be cropped by the edge of the canvas.
maxRotationint-The maximum rotation for tick labels when rotating to condense labels.

Note: Rotation doesn't occur until necessary and only applicable to horizontal scales.
maxTicksLimitintYesMaximum number of ticks and gridlines to show.
minRotationint-The minimum rotation for tick labels.
mirrorboolean-The flips tick labels around axis, displaying the labels inside the chart instead of outside.

Note: Only applicable to vertical scales.
numberFormatNumberFormatOptionsYesThe number format options used by the default label formatter.
See INTL number format documentation.
paddingint-The padding between the tick label and the axis.
precisionintYesIf defined and stepSize is not specified, the step size will be rounded to this many decimal places.
sampleSizeint-The number of ticks to examine when deciding how many labels will fit. Setting a smaller value will be faster, but may be less accurate when there is large variability in label length.
showLabelBackdropbooleanYesIf true, draw a background behind the tick labels
stepSizedoubleYesUser defined fixed step size for the scale.
textStrokeColorString - IsColorYesThe color of the stroke around the text.
textStrokeWidthintYesStroke width around the text.
zint-z-index of tick layer. Useful when ticks are drawn on chart area. Values less than or equals to 0 are drawn under data sets, greater than 0 on top.

Given the number of axis range settings, it is important to understand how they all interact with each other.

The suggestedMax and suggestedMin settings only change the data values that are used to scale the axis. These are useful for extending the range of the axis while maintaining the auto fit behavior.

In contrast to the suggested* settings, the min and max settings set explicit ends to the axes. When these are set, some data points may not be visible.

If stepSize set, the scale ticks will be enumerated by multiple of stepSize, having one tick per increment. If not set, the ticks are labeled automatically using the nice numbers algorithm.

The further customization of ticks, a callback is provided.

Scriptable

Scriptable options at ticks level accept a callback which is called for each of the underlying data values. See more details in Configuring charts section.

All scriptable options callbacks will get a ScaleContext instance.

// creates the axis for chart
CartesianLinearAxis axis = new CartesianLinearAxis(chart);
// sets the option by a callback
axis.getTicks().setColor(new ColorCallback<ScaleContext>(){

@Override
public IsColor invoke(ScaleContext context){
// logic
return color;
}
});

The following options can be set by a callback:

NameCallbackReturned types
backdropColorColorCallback<ScaleContext>String - IsColor
colorColorCallback<ScaleContext>String - IsColor
countCountCallbackint
fontFontCallback<ScaleContext>FontItem
maxTicksLimitMaxTicksLimitCallbackint
numberFormatNumberFormatCallbackNumberFormatItem
precisionPrecisionCallbackint
showLabelBackdropShowLabelBackdropCallbackboolean
stepSizeStepSizeCallbackdouble
textStrokeColorColorCallback<ScaleContext>String - IsColor
textStrokeWidthWidthCallback<ScaleContext>int

Callback

It is also common to want to change the tick marks to include information about the data type. For example, adding a dollar sign ('$'). To do this, you need to implement a ticks callback in the axis configuration.

To apply a custom callback, you can set a TickCallback instance to the axis options, as following:

// creates the axis for chart
CartesianLinearAxis axis = new CartesianLinearAxis(chart);
// sets the option by a callback
axis.getTicks().setCallback(new TickCallback(){

/**
* Changes the tick marks to include information about the data type.
*
* @param axis axis instance where this callback as been defined
* @param value value of tick
* @param index index of tick
* @param values list of all tick values
* @return the tick to apply or if the callback returns null the associated grid line will be hidden.
*/
public String onCallback(Axis axis, double value, int index, List<Double> values){
// add $
return "$" + value;
}

});

See INTL number format documentation if you want to use a number formatter, provided out-of-the-box.

NoSelectedDatasetTicksCallback callback

Charba provides a common implementation for tick callback to set the decimal digits of ticks in case of all data sets are hidden, to avoid the annoying standard format of doubles.

To apply the callback, you can set an instance to the axis options, as following:

// creates the axis for chart
CartesianLinearAxis axis = new CartesianLinearAxis(chart);
// sets the option by a callback
axis.getTicks().setCallback(new NoSelectedDatasetTicksCallback());

The default decimal precision is 2. A custom precision can be set by the constructor of callback, as following:

// creates the axis for chart
CartesianLinearAxis axis = new CartesianLinearAxis(chart);
// sets the option by a callback
// 3 decimal digits
axis.getTicks().setCallback(new NoSelectedDatasetTicksCallback(3));