Skip to main content
Version: 5.3

Cartesian Category Axes

The category axis will draw the labels from one of the label arrays included in the chart data.

Here are some example how to create category axes:

// creates a category axis with default scale id "x" and default kind "x" 
CartesianCategoryAxis axis1 = new CartesianCategoryAxis(chart);

// creates a category axis with scale id "my-axis" and default kind "x"
CartesianCategoryAxis axis2 = new CartesianCategoryAxis(chart, "my-axis");

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

// creates a category axis with default scale id "x" and custom kind "x"
CartesianCategoryAxis axis4 = new CartesianCategoryAxis(chart, AxisKind.X);

// creates a category axis with scale id "my-axis" and custom kind "x"
CartesianCategoryAxis axis5 = new CartesianCategoryAxis(chart, "my-axis", AxisKind.X;

// creates a category axis with scale id "my-axis" and custom kind "x"
ScaleId myAxis = ScaleId.create("my-axis");
CartesianCategoryAxis axis6 = new CartesianCategoryAxis(chart, myAxis, AxisKind.X);

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

Options

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

// creates a category axis 
CartesianCategoryAxis axis = new CartesianCategoryAxis(chart);
// sets and gets the reverse value
axis.setReverse(true);

boolean reverse = axis.isReverse();

The following are the attributes that you can set:

NameTypeScriptableDescription
alignToPixelsbooleanYesAlign pixel values to device pixels.
backgroundColorString - IsColorYesThe background color of scale area.
boundsBoundsYesDetermines the scale bounds on axis.
displayboolean - DisplayYesIf Display.TRUE, the axis is shown.
maxStringYesUser defined maximum string for the scale, overrides maximum value from data.
minStringYesUser defined minimum string for the scale, overrides minimum value from data.
labelsLabels-The labels to display.
offsetbooleanYesIf true, extra space is added to the both edges and the axis is scaled to fit in the chart area.
positionAxisPositionYesPosition of the axis
reversebooleanYesReverses order of tick labels.
singleStackedboolean-If you might want to stack positive and negative values together.
stackStringYesSets the stack group. Axes at the same position with same stack are stacked.
stackedbooleanYesIf the axis are stacked.
stackWeightdoubleYesSets the weight of the scale in stack group. Used to determine the amount of allocated space for the scale within the group.
weightdoubleYesThe weight used to sort the axis. Higher weights are further away from the chart area.

Scriptable

Scriptable options at scale 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 a category axis 
CartesianCategoryAxis axis = new CartesianCategoryAxis(chart);
// sets the option by a callback
axis.setBackgroundColor(new ColorCallback<ScaleContext>(){

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

The following options can be set by a callback:

NameCallbackReturned types
alignToPixelsAlignToPixelsCallbackboolean
backgroundColorColorCallback<ScaleContext>String - IsColor
boundsBoundsCallbackBounds
displayDisplayCallbackboolean - Display
maxMinMaxCallback<String>String
minMinMaxCallback<String>String
offsetScaleOffsetCallbackboolean
positionScalePositionCallbackAxisPosition
reverseReverseCallbackboolean
stackStackCallbackString
stackedStackedCallbackboolean
stackWeightScaleWeightCallbackdouble
weightScaleWeightCallbackdouble

Ticks

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

// creates a category axis 
CartesianCategoryAxis axis = new CartesianCategoryAxis(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.
crossAlignCrossAlign-The tick alignment perpendicular to the axis.
displayboolean-If true, the tick marks are shown.
fontIsFontYesFont of ticks.
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.
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.
paddingint-The padding between the tick label and the axis.
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
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.

For both the min and max properties, the value must be in the labels array.

The further customization of ticks, a callback is provided.

Ticks scriptable options

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 a category axis 
CartesianCategoryAxis axis = new CartesianCategoryAxis(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
fontFontCallback<ScaleContext>FontItem
showLabelBackdropShowLabelBackdropCallbackboolean
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.

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

axis.getTicks().setCallback(new CategoryTickCallback(){

/**
* 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, String value, int index, List<String> values){
// add a label
return value + myLabel;
}

});

The callback can return a string (for single line) or a list of strings (for multiple lines).