SChartAxis Class Reference

Inherits from NSObject
Declared in SChartAxis.h
Availability Standard
Premium
Related samples Area
BarChart
ColumnChart
FinancialChart
LargeDataSet
LineChart

Overview

The SChartAxis is responsible for managing the coordinate space of the chart. It is the link between the set of real data in a series and the laying down of that series on a chart in a desired manner. Each series on the chart is linked to an axis and this SChartAxis is responsible for managing all of the series linked to it. Here is a sample chart with some key axis features highlighted:

For cartesian series, it is expected that you will provide instances of a subclass of SChartAxis each for the xAxis and yAxis of the chart. If not set, both axes will default to instances of SChartNumberAxis.

The axis range can be set to a desired range or left to calculate its own minimum and maximum. When auto-calculating the range, it will consider all data series associated with it.

The axis is also the home of the tick marks and their labels. These can be auto-calculated or set to specific values.

More information about using SChartAxis can be found in the user guide.

Tasks

Initializing the axis

Positioning the Axis

Styling

Ranges

Tickmarks and labels

Zooming

Panning

Data - Pixel Conversions

Values in Data Terms

Drawing

Properties

allowPanningOutOfDefaultRange

Whether or not the user is permitted to pan outside of the user-set default range.

@property (nonatomic) BOOL allowPanningOutOfDefaultRange

Discussion

With a user-set default range this can be used to either limit panning and zooming to a subset of the data or to allow panning or zooming outside of the data range but whilst still setting limits. If the default range is not set, it defaults to dataRange and `allowPanningOutOfMaxRange' should be used instead.

By default, this property is set to YES.

Declared In

SChartAxis.h

allowPanningOutOfMaxRange

Whether or not the user is permitted to pan outside of the union of the data range and the default range

@property (nonatomic) BOOL allowPanningOutOfMaxRange

Discussion

If this is enabled but allowPanningOutOfDefaultRange is disabled, panning will still be restricted to the data range.

By default, this property is set to NO.

Declared In

SChartAxis.h

anchorPoint

The start point for the calculation of tick marks.

@property (nonatomic, retain, nullable) id anchorPoint

Discussion

For example, if your range is @1 to @9, your anchorPoint is @0 and the currentMajorTickFrequency is @2, you will get tickmarks and labels at @2, @4, @6 and @8, assuming that the labels' text and the clipping settings permit.

Regardless of whether a tick mark frequency has been set or automatically calculated, it must start somewhere. This value acts as the origin point for tickmarks on the axis.

By default, this property is set to the minimum of the dataRange.

Declared In

SChartAxis.h

animationEdgeBouncing

Whether or not the axis allows the range to temporarily go past the limit specified before bouncing back in

@property (nonatomic) BOOL animationEdgeBouncing

Discussion

If this is enabled, the range will bounce back into the given limit. If there is no range limit, this option does nothing.

By default, this property is set to YES.

Declared In

SChartAxis.h

animationEnabled

Whether or not the axis animates when zooming programmatically, or via double-tap on box gesture.

@property (nonatomic) BOOL animationEnabled

Discussion

If this is enabled, the axis will zoom smoothly from starting to target zoom levels.

By default, this property is set to YES.

Warning: Animation is not currently supported by radial charts.

Declared In

SChartAxis.h

autoCalculateRange

Specifies whether the axis auto-calculates its range when the chart reloads its data.

@property (nonatomic, assign) BOOL autoCalculateRange

Discussion

By default, this property is set to YES.

Declared In

SChartAxis.h

axisFrame

The frame bounding the area where the axis is drawn.

@property (nonatomic) CGRect axisFrame

Discussion

This area in terms of the chart frame within which the axis line, tickmarks and ticklabels are drawn. It can have a fixed width if the width property is set, otherwise it wil be dynamic and affected by the tickmarks and their labels.

Warning: Setting an explicit axis frame is not currently supported by radial charts.

Declared In

SChartAxis.h

axisLabelsAreFixed

This property determines whether the axis labels will move with the axis lines and tick marks when an axis position value has been set.

@property (nonatomic) BOOL axisLabelsAreFixed

Discussion

If this is set to YES, labels will stay fixed at the bottom/left or top/right of the chart depending on the axisPosition parameter.

Declared In

SChartAxis.h

axisOrientation

The orientation of the axis.

@property (nonatomic, readonly) SChartOrientation axisOrientation

Discussion

Axis objects are universal and may be used as an x-axis (horizontal) or as a y-axis (vertical).

  • SChartOrientationHorizontal: Configures the axis to be used as an x-axis (horizontal).
  • SChartOrientationVertical: Configures the axis to be used a y-axis (vertical).

This property is determined when the axis is assigned to the chart.

Warning: With regards to radial charts, horizontal is the outer (radial) axis, and vertical is the inner (polar) axis.

Declared In

SChartAxis.h

axisPosition

The SChartAxisPosition defines whether the axis will be positioned at the normal or reverse location.

@property (nonatomic) SChartAxisPosition axisPosition

Discussion

  • SChartAxisPositionNormal: For x-axes, the ‘normal’ position is below the plot area. For y-axes, the ‘normal’ position is to the left of the plot area.
  • SChartAxisPositionReverse: For x-axes, the ‘reverse’ position is above the plot area. For y-axes, the ‘reverse’ position is to the right of the plot area.

Often, it is a good idea when adding a secondary axis, using addXAxis or addYAxis, to position one axis in each position.

Warning: Radial charts do not respond to SChartAxisPositionReverse.

Declared In

SChartAxis.h

axisPositionValue

The value at which an axis intersects with the opposite axis. For example, if this is set to 0 on a yAxis, it will intersect with the xAxis at the point which corresponds to a value of 0 in data terms.

@property (nonatomic, retain, nullable) NSNumber *axisPositionValue

Discussion

If there is more than one axis of the other orientation on the chart, the primary axis will be used.

Warning: Axes on a radial chart do not support axis position.

Declared In

SChartAxis.h

calculateMajorTickFrequencyFromDiscontinuousRange

This property controls how the auto-tick-frequency calculations are done. Normally, the axis will use the full range of data to calculate how often to place a tick-mark, however if the range has discontinuities, this option allows the axis to exclude the discontinuities in its calculations of the range over which the tick marks are added.

@property (nonatomic) BOOL calculateMajorTickFrequencyFromDiscontinuousRange

Discussion

For example - you have a year range, but are excluding 7 months using discontinuous periods. If this property is NO, the tick labels will be added as if the range is one year. If this property is YES, the tick labels will be added as if the range is 5 months (12 - 7).

If YES, the axis will exclude discontinuities when calculating the range.

By default, this property is NO.

Declared In

SChartAxis.h

chart

A pointer to the parent chart

@property (nonatomic, assign, nullable) ShinobiChart *chart

Discussion

The axis retains a handle on the chart using it so that it can access user-set drawing parameters.

Declared In

SChartAxis.h

dataRange

A readonly property indicating the total data range across all series represented by this axis.

@property (nonatomic, readonly) SChartRange *dataRange

Discussion

These are absolute minimum and absolute maximum values from the data series represented by this axis. This range does not necessarily represent exactly the range of what is drawn on the axis, depending on how the data is visualised - for this see visibleRange.

Declared In

SChartAxis.h

defaultRange

This is the range that will be displayed after the chart initially loads - and if the zoom is reset.

@property (nullable, nonatomic, retain) SChartRange *defaultRange

Discussion

By default, this property is set to dataRange, but can be set to custom values.

Declared In

SChartAxis.h

discontinuousTickLabelClipping

This property comes into effect for discontinuous axes over a discontinuity. When there are labels either side of a discontinuity which overlap, either the higher or lower label will be removed, this property controls which.

@property (nonatomic) SChartDiscontinuousTickLabelClipping discontinuousTickLabelClipping

Discussion

  • SChartDiscontinuousTickLabelClippingLow: Removes the lower tick labels.
  • SChartDiscontinuousTickLabelClippingHigh: Removes the higher tick labels.

By default, this property is set to ‘SChartDiscontinuousTickLabelClippingLow’.

Declared In

SChartAxis.h

enableGesturePanning

Set to YES to allow swipe gestures to pan the chart.

@property (nonatomic) BOOL enableGesturePanning

Discussion

Warning: Panning isn’t currently supported by radial charts.

Declared In

SChartAxis.h

enableGestureZooming

Set to YES to allow pinch gestures to zoom the chart.

@property (nonatomic) BOOL enableGestureZooming

Discussion

Warning: Zooming isn’t currently supported by radial charts.

Declared In

SChartAxis.h

enableMomentumPanning

Enables momentum panning

@property (nonatomic, assign) BOOL enableMomentumPanning

Discussion

When momentum panning is enabled, fast pan gestures will cause the chart to continue to pan during a brief ‘slowing down’ period rather than stopping immediately.

By default, this property is set to NO.

Declared In

SChartAxis.h

enableMomentumZooming

Enables momentum zooming

@property (nonatomic, assign) BOOL enableMomentumZooming

Discussion

When momentum zooming is enabled, fast pinch gestures will cause the chart to continue to zoom during a brief ‘slowing down’ period rather than stopping immediately.

Declared In

SChartAxis.h

isMomentumPanning

Will always be YES when the axis is decelerating from a pan swipe gesture

@property (nonatomic, readonly) BOOL isMomentumPanning

Declared In

SChartAxis.h

isMomentumZooming

Will always be YES when the axis is decelerating from a pinch zoom gesture

@property (nonatomic, readonly) BOOL isMomentumZooming

Declared In

SChartAxis.h

labelFormatString

A string to format each tick mark label - actual format is dependent on axis type. If an axis is auto-calculating tick marks - it will select an appropriate label format (ie: months, days, hours, etc). However, setting this value will override all tick mark labels to use this formatter.

@property (nonatomic, retain, nullable) NSString *labelFormatString

Discussion

  • A number axis will pass the tick value as an NSNumber to NSString’s stringWithFormat: method so set a number format string, ie @"%1.2f mm".
  • A date axis will pass the tick value as an NSDate through an NSDateFormatter so set the string as if you were setting a date formatter’s dateFormat property, i.e @"dd MMM".
  • A category axis will pass the tick value as an NSString to NSString’s stringWithFormat: method so set any suitable format string, i.e @“%@ District”.

Declared In

SChartAxis.h

labelFormatter

A label formatter for tick mark labels.

@property (nonatomic, retain, nullable) SChartTickLabelFormatter *labelFormatter

Discussion

Use this to set formatting options for tick labels on this axis - currencies, (negative) value styles etc.

Declared In

SChartAxis.h

majorTickFrequency

An appropriate object representing the major tick mark frequency.

@property (nonatomic, retain, nullable) id majorTickFrequency

Discussion

If this value is set, the chart will attempt to display major tick marks at this frequency. However, if there is not enough space for labels at this desired frequency, the chart will select a frequency automatically.

The definition of appropriate value is dependent upon the axis type - ie: SChartNumberAxis, SChartDateTimeAxis.

The first major tick mark will be at the absolute minimum data value across all series for this axis - with subsequent major tick marks incrementing by the frequency. To change this initial value see anchorPoint.

By default an appropriate major tick mark value will be selected by the chart and will adapt as the user zooms the chart.

Declared In

SChartAxis.h

minimumFreeAxisSpace

This property allows you to specify the percentage of the axis space that should be empty, available for padding around tick labels. This can be used to control tick-label over-crowding.

@property (nonatomic) double minimumFreeAxisSpace

Discussion

When tick labels are added, if the remaining space on the axis is less than minimumFreeAxisSpace, then the frequency of labels will be decreased until sufficient space remains after adding each label.

By default, this property is set to ‘0.01’, or 1%.

Declared In

SChartAxis.h

minorTickFrequency

An appropriate object representing the minor tick mark frequency.

@property (nonatomic, retain, nullable) id minorTickFrequency

Discussion

If this value is set, the chart will attempt to display minor tick marks at this frequency. However, if there is not enough space for labels at this desired frequency, the chart will select a frequency automatically.

The first minor tick mark will be at the absolute minimum data value across all series for this axis - with subsequent minor tick marks incrementing by the frequency. To change this initial value see anchorPoint.

By default an appropriate minor tick mark value will be selected by the chart and will adapt as the user zooms the chart. In order for the chart to adhere to a non-nil value you have assigned to this property you must also set a majorTickFrequency.

Declared In

SChartAxis.h

panMomentumDelay

The time steps of each deceleration after a pan swipe gesture.

@property (nonatomic) double panMomentumDelay

Discussion

If enableMomentumPanning is set to YES, the velocity of the swipe gesture will decay over a number of increments. These increments are a fixed time period specified here. During this fixed period the velocity will decay by a factor panMomentumFactor

By default, this property is set to 0.0f.

Declared In

SChartAxis.h

panMomentumFactor

The factor by which the velocity of the gesture will decay during one deceleration time period.

@property (nonatomic) double panMomentumFactor

Discussion

If enableMomentumPanning is set to YES, the velocity of the swipe gesture will decay over a number of increments. These increments are a fixed time period specified in panMomentumDelay. During this fixed period the velocity will decay by this factor.

By default, this property is set to 0.98f.

Declared In

SChartAxis.h

range

The current displayed range of the axis.

@property (nonatomic, retain) SChartRange *range

Discussion

This property is the actual range currently displayed on the visible area of the chart- which may not be the range that was explicitly set. The axis may make small adjustments to the range to make sure that whole bars are displayed etc.

Declared In

SChartAxis.h

rangePaddingHigh

In data terms, the amount by which the upper limit of the axis range will be raised past the range of the data.

@property (nonatomic, retain, nullable) id rangePaddingHigh

Discussion

Warning: This is only added when the range is automatically calculated. Setting the range explicitly will result in the rangePaddingHigh being ignored.

By default, this property is set to 0.

Declared In

SChartAxis.h

rangePaddingLow

In data terms, the amount by which the lower limit of the axis range will be lowered past the range of the data.

@property (nonatomic, retain, nullable) id rangePaddingLow

Discussion

Warning: This is only added when the range is automatically calculated. Setting the range explicitly will result in the rangePaddingLow being ignored.

By default, this property is set to 0.

Declared In

SChartAxis.h

secondaryAxisOffset

The offset to the axis object from the edge of the canvas, in points.

@property (nonatomic, assign) CGFloat secondaryAxisOffset

Discussion

For x-axes, this is from the bottom edge of the canvas frame for axes at the ‘normal’ axisPosition and from the top for y-axes at the ‘reverse’ axisPosition. For y-axes, this is from the left edge of the canvas frame for axes at the ‘normal’ axisPosition and from the right for y-axes at the ‘reverse’ axisPosition.

Declared In

SChartAxis.h

style

The SChartAxisStyle object that manages the appearance of the axis.

@property (nonatomic, retain) SChartAxisStyle *style

Discussion

Setting these values will override any values set by the theme. Calling applyTheme on the chart, though, will reapply the theme style.

Declared In

SChartAxis.h

tickLabelClippingModeHigh

This property allows you to alter the tick label clipping mode for the upper end of an axis.

@property (nonatomic) SChartTickLabelClippingMode tickLabelClippingModeHigh

Discussion

  • SChartTickLabelClippingModeTicksAndLabelsPersist: Keeps both the label and tick visible for as long as possible, allowing the label to overlap with adjacent axes.
  • SChartTickLabelClippingModeTicksPersist: Keeps the tick mark visible for as long as possible and clip the label as soon as it reaches the edge of its view.
  • SChartTickLabelClippingModeNeitherPersist: Keeps the tick mark visible as long as the tick label is visible - as soon as the tick label reaches its bounds, and is clipped, clip the tick mark too.

Warning: Tick label clipping isn’t currently supported on radial charts.

Declared In

SChartAxis.h

tickLabelClippingModeLow

This property allows you to alter the tick label clipping mode for the lower end of an axis.

@property (nonatomic) SChartTickLabelClippingMode tickLabelClippingModeLow

Discussion

See tickLabelClippingModeHigh.

Warning: Tick label clipping isn’t currently supported on radial charts.

Declared In

SChartAxis.h

tickLabelRefreshRate

Provides the ability to customize the rate at which the tick labels are refreshed. Decreasing the rate at which they are updated can improve performance, particularly on older devices.

@property (nonatomic, copy) id<SChartTickLabelRefreshRate> tickLabelRefreshRate

Discussion

Default implementation is SChartTickLabelRefreshRateDeviceBased.

Declared In

SChartAxis.h

title

The text to display in the axis title.

@property (nonatomic, retain, nullable) NSString *title

See Also

Declared In

SChartAxis.h

titleLabel

The title for the axis.

@property (nonatomic, retain, nullable) SChartTitle *titleLabel

Declared In

SChartAxis.h

width

Specifies a fixed width (in points) for the axis area that won’t change.

@property (nonatomic, retain, nullable) NSNumber *width

Discussion

This is useful to fix the axis in position to align multiple charts. However, it may restrict the options for labelling the chart.

Warning: A radial chart will not respond to this value.

Declared In

SChartAxis.h

zoomMomentumDelay

The time steps of each deceleration after a pinch zoom gesture.

@property (nonatomic) double zoomMomentumDelay

Discussion

If enableMomentumZooming is set to YES, the velocity of the zoom pinch gesture will decay over a number of increments. These increments are a fixed time period specified here. During this fixed period the velocity will decay by a factor zoomMomentumFactor.

By default, this property is set to 0.0f.

Declared In

SChartAxis.h

zoomMomentumFactor

The factor by which the velocity of the gesture will decay during one deceleration time period.

@property (nonatomic) double zoomMomentumFactor

Discussion

If enableMomentumZooming is set to YES, the velocity of the zoom pinch gesture will decay over a number of increments. These increments are a fixed time period specified in zoomMomentumDelay. During this fixed period the velocity will decay by this factor.

By default, this property is set to 0.75f.

Declared In

SChartAxis.h

Instance Methods

alterTickMark:

This will call sChart:alterTickMark:onAxis: if your delegate implements it. Implement this method in your axis subclass to alter tickmarks on that axis only.

- (void)alterTickMark:(SChartTickMark *)tickMark

Discussion

This method gives you each tickMark just before it is added to its axis. Use this to set colors, borders, or even move the tickmark’s label elsewhere.

Declared In

SChartAxis.h

currentMajorTickFrequency

Returns the current major tick frequency in use by this axis.

- (id)currentMajorTickFrequency

Discussion

Warning: Important majorTickFrequency returns the frequency that you have manually set, whereas currentMajorTickFrequency returns the frequency currently in use - the two are not necessarily the same.

Declared In

SChartAxis.h

currentMinorTickFrequency

Returns the current minor tick frequency in use by this axis.

- (id)currentMinorTickFrequency

Discussion

Warning: Important minorTickFrequency returns the frequency that you have manually set, whereas currentMinorTickFrequency returns the frequency currently in use - the two are not necessarily the same.

Declared In

SChartAxis.h

dataValueForPixelValue:

Returns the data value of the given pixel value along this axis, in the coordinate system of the plot area.

- (id)dataValueForPixelValue:(double)px

Discussion

If the pixel value given is negative, or is larger than the respective height/width of the plot area in pixels, than this method may return a data value that is not currently in range of the axis.

Warning: Currently, this method will not return a data value for radial charts.

Declared In

SChartAxis.h

getNewRangeWithMinimum:withMaximum:

Creates a new range object with the given maximum and minimum

- (SChartRange *)getNewRangeWithMinimum:(NSNumber *)minimum withMaximum:(NSNumber *)maximum

Discussion

The subclass of SChartRange that is returned will correspond to the axis type.

Declared In

SChartAxis.h

initWithRange:

Create an axis for a given chart area with a default range.

- (id)initWithRange:(nullable SChartRange *)range

Discussion

See defaultRange for the implications of setting this type of range.

Declared In

SChartAxis.h

isXAxis

Whether or not its axisOrientation is horizontal

- (BOOL)isXAxis

Return Value

Whether or not its axisOrientation is horizontal.

Declared In

SChartAxis.h

offsetForSeries:

Returns the difference in data terms between where data in a series is drawn to it’s value on this axis.

- (id)offsetForSeries:(SChartMappedSeries *)series

Discussion

This is useful for calculating where the centres of datapoints are, relative to their value. For example, where you have more than one column series along an x-axis they will stand next to each other so as not to overlap: If columns in two series each have an xValue of ‘5’, the column in the first series will be offset left from ‘5’ and the column in the second series will be offset right from ‘5’. You can use this method to find out what that offset is for each series.

Warning: The ‘series’ parameter has been changed from class SChartCartesianSeries to SChartMappedSeries.

Declared In

SChartAxis.h

pixelValueForDataValue:

Returns the pixel value, in the coordinate system of the plot area, of the given data value along this axis.

- (double)pixelValueForDataValue:(id)data

Discussion

If a data value would fall outside of the plot area (is not currently within the range of the axis) then this method may return either a negative value, or a value larger than the respective height/width of the plot area in pixels.

Warning: Currently, this method will not return a pixel value for radial charts.

Declared In

SChartAxis.h

resetZoomLevel

- (BOOL)resetZoomLevel

Declared In

SChartAxis.h

resetZoomLevelWithAnimation:

Sets the axis back to its original zoom

- (BOOL)resetZoomLevelWithAnimation:(BOOL)animate

Parameters

animate
  • whether or not the zoom operation should be animated. If not animated, this reset will be instant.

Return Value

Whether or not the zoom operation was successful.

Declared In

SChartAxis.h

setRange:withAnimation:

Attempts to set the current visible range range to a range with the given minimum and maximum values.

- (void)setRange:(SChartRange *)range withAnimation:(BOOL)animation

Parameters

range

the range to be displayed, in data terms.

animation

whether or not to animate the range change.

Discussion

Given any restrictions on setting the range, such as allowPanningOutOfMaxRange etc, this method will attempt to set the current axis range. This implementation allows you to explicitly set whether to animate the transition to the new range or not.

Declared In

SChartAxis.h

setZoomLevel:

Sets the zoom to a standard level.

- (BOOL)setZoomLevel:(SChartAxisZoomLevel)zoomLevel

Parameters

zoomLevel
  • a predefined SChartAxisZoomLevel for the axis. To set an explicit zoom use setZoom:fromPosition:

Discussion

  • SChartAxisZoomLevelOriginal: Zooms the chart to be at the default range.
  • SChartAxisZoomLevelDouble: Doubles the current zoom level.
  • SChartAxisZoomLevelHalf: Halves the current zoom level.

Declared In

SChartAxis.h

spaceRequiredToDrawWithTitle:

Returns the amount of space in points needed to draw the axis between the plot area and the edge of the chart frame.

- (CGFloat)spaceRequiredToDrawWithTitle:(BOOL)shouldIncludeTitle

Parameters

shouldIncludeTitle
  • Whether or not to include the space required to draw the axis title, if enabled.

Discussion

This includes the space required to draw tickmarks and ticklabels. Note that altering tick labels via the delegate may cause the return value of this method to be incorrect.

Declared In

SChartAxis.h

stringForId:

Returns a string representation of the given object.

- (nullable NSString *)stringForId:(id)obj

Discussion

This will use the ‘labelFormatter’ where possible. This is used for creating ticklabel and crosshair text.

Declared In

SChartAxis.h

visibleRange

Returns a range within which all the visible (non-hidden) series on this axis will be displayed.

- (SChartRange *)visibleRange

Discussion

Setting the default range to this range should frame your data nicely. Note that this will take baselines, bar/column widths etc into consideration and so is not necessarily the same as dataRange.

Declared In

SChartAxis.h

zoom

Returns the current zoom level, relative to the defaultRange of the axis.

- (double)zoom

Declared In

SChartAxis.h