SChartAnimation Class Reference

Inherits from NSObject
Conforms to NSCopying
Declared in SChartAnimation.h
Availability Standard
Premium
Related samples

Overview

An SChartAnimation object determines how some elements of the chart are animated.

For example, to show a series, you should use the chart’s ‘animation tracker’ object to schedule an animation:

[_chart.animationTracker showSeries:_series
animation:[SChartAnimation growAnimation]
progressCalculator:[[SChartTimeProgressCalculator alloc] initWithDuration:5]
completion:nil];

The properties you can set on an animation are:

  • The duration of the animation. See duration for more information.
  • The origin point on the chart from where the series animates to its final position. See absoluteOriginX, absoluteOriginY, normalisedOriginX and normalisedOriginY for more information.
  • How the chart series scales as the animation progresses. See xScaleCurve, yScaleCurve or radiusCurve for more information.
  • How the transparency of the series varies over the period of the animation. See alphaCurve for more information.
  • For pie/donut chart series, you can specify how the series rotates around the origin during the animation. See angleCurve for more information.

The SChartAnimation object is composed of several objects conforming to the SChartAnimationCurve protocol, which each describe the transition of an aspect of the chart series from the start of the animation to the end. We have defined concrete implementations of this protocol to support common animation use cases which you might have. Some of the concrete animation curve classes are:

Other animation curves are also available, see the API documentation for more information.

To save you having to create animation classes from scratch, we’ve provided some pre-defined types for you. Have a look at the factory methods we’ve provided in the “Creating Animations” sections of this page.

Warning: This feature isn’t currently supported on radial charts.

More information about using SChartAnimation can be found in our tutorial ‘Animating ShinobiChart Series’.

Properties

absoluteOriginX

If this property is set, this will be the origin value in x in data terms - a curve returning 0 maps to this value, whereas a curve returning 1 maps to the final true value of the series.

@property (retain, nonatomic) id _Nullable absoluteOriginX

Discussion

Points will scale from this value along the x axis in either direction. If this property is not set, the animation will use a normalized origin on x - see normalisedOriginX.

Declared In

SChartAnimation.h

absoluteOriginY

If this property is set, this will be the origin value in y in data terms - a curve returning 0 maps to this value, whereas a curve returning 1 maps to the final true value.

@property (retain, nonatomic) id _Nullable absoluteOriginY

Discussion

Points will scale from this value along the y axis in either direction. If this property is not set, the animation will use a normalized origin on y - see normalisedOriginY.

Declared In

SChartAnimation.h

alphaCurve

The animation curve describing how the transparency of the series changes during the animation.

@property (retain, nonatomic) NSObject<SChartAnimationCurve> *alphaCurve

Discussion

This curve describes how the alpha value of the colors of the series scale from some initial alpha value at the start of the animation to some destination alpha at the end of the animation. We multiply the value returned by this curve with the colors set to the series, therefore a curve value of 0 results in a completely transparent color and a value of 1 results in the final alpha value of the series color. This curve applies to both cartesian and pie/donut series.

Declared In

SChartAnimation.h

angleCurve

This curve only applies to pie/donut chart series. The animation curve describes the transition of the series around its origin.

@property (retain, nonatomic) NSObject<SChartAnimationCurve> *angleCurve

Discussion

This curve describes how the points of the series rotate around the centre of the series from some initial angle at the start of the animation to a destination angle at the end of the animation. An angle scale value of 0 maps to the original angle whereas a value of 1 maps to the destination angle.

Declared In

SChartAnimation.h

curve

The overall animation curve for the animation.

@property (retain, nonatomic) NSObject<SChartAnimationCurve> *curve

Discussion

Setting this curve will set each of the other curves for the animation to this same curve. By default, this property is set to SChartFlatAnimationCurve.

Declared In

SChartAnimation.h

normalisedOriginX

This property enables you to set a normalized point of origin along the x axis for the animation.

@property (nonatomic) CGFloat normalisedOriginX

Discussion

This value is normalized using the range of the series which the animation is applied to. For example, setting a normalisedOriginX of 0.f would cause the series to animate from its left-most point. Setting a normalisedOriginX of 1.f would cause the series to animate from its right-most point. By default, this property is set to 0.5f. However, if a value is set for absoluteOriginX, this property will be ignored.

Declared In

SChartAnimation.h

normalisedOriginY

This property enables you to set a normalized point of origin along the y axis for the animation.

@property (nonatomic) CGFloat normalisedOriginY

Discussion

This value is normalized using the range of the series which the animation is applied to. For example, setting a normalisedOriginY of 0.f would cause the series to animate from its lowest point. Setting a normalisedOriginY of 1.f would cause the series to animate from its highest point. By default, this property is set to 0.5f. However, if a value is set for absoluteOriginY, this property will be ignored.

Declared In

SChartAnimation.h

radiusCurve

The animation curve describing how the radius/radii of the series change during the animation.

@property (retain, nonatomic) NSObject<SChartAnimationCurve> *radiusCurve

Discussion

This curve describes how both the x values and the y values of a series scale from some origin to their true values. It is mostly used for pie/donut series, often in conjunction with an origin at the centre of the pie/donut series. Setting this curve will override any previously set values for xScaleCurve and yScaleCurve.

Declared In

SChartAnimation.h

xScaleCurve

The animation curve describing the transition of the series parallel to the x axis.

@property (retain, nonatomic) NSObject<SChartAnimationCurve> *xScaleCurve

Discussion

This curve describes how the x values of the series scale from some origin along the x axis at the start of the animation to their destination at the end of the animation. An xScale value of 0 maps a point at the animation origin whereas a value of 1 maps the point at it’s true value perpendicular to the x axis.

Declared In

SChartAnimation.h

yScaleCurve

The animation curve describing the transition of the series parallel to the y axis.

@property (retain, nonatomic) NSObject<SChartAnimationCurve> *yScaleCurve

Discussion

This curve describes how the y values of the series scale from some origin along the y axis at the start of the animation to their destination at the end of the animation. An yScale value of 0 maps a point at the animation origin whereas a value of 1 maps the point at it’s true value perpendicular to the yAxis.

Declared In

SChartAnimation.h

Class Methods

fadeAnimation

Returns an animation where the series fades.

+ (SChartAnimation *)fadeAnimation

Discussion

By default, the normalized X and Y are both set to 0.5f, and the animation duration is set to 2.4 seconds.

Declared In

SChartAnimation.h

growAnimation

Returns an animation where the series scales from its centre.

+ (SChartAnimation *)growAnimation

Discussion

This is the default entry & exit animation for SChartScatterSeries, SChartDonutSeries, and SChartPieSeries.

By default, the normalized X and Y are both set to 0.5f, and the animation duration is set to 2.4 seconds.

Declared In

SChartAnimation.h

growHorizontalAnimation

Returns an animation where the series scales from its leftmost point.

+ (SChartAnimation *)growHorizontalAnimation

Discussion

This is the default entry & exit animation for SChartBarSeries.

By default, the normalized X is set to 0.f, normalized Y is set to 0.5f, and the animation duration is set to 2.4 seconds. If a baseline is set on a bar series, and a custom origin has not been set for the animation, the baseline will be used as the origin instead.

Declared In

SChartAnimation.h

growVerticalAnimation

Returns an animation where the series scales from its lowest point.

+ (SChartAnimation *)growVerticalAnimation

Discussion

This is the default entry & exit animation for SChartColumnSeries, SChartOHLCSeries, and SChartCandlestickSeries.

By default, the normalized X is set to 0.5f, normalized Y is set to 0.f, and the animation duration is set to 2.4 seconds. If a baseline is set on a column, OHLC, or candlestick series, and a custom origin has not been set on the animation, the baseline will be used as the origin instead.

Declared In

SChartAnimation.h

radialSelection

Returns an animation where the series rotates with a bounce and changes its protrusion with a bounce.

+ (SChartAnimation *)radialSelection

Discussion

This is the default selection animation for SChartDonutSeries and SChartPieSeries.

By default, the normalized X and Y are both set to 0.5f, and the animation duration is set to 2.4 seconds.

Declared In

SChartAnimation.h

televisionAnimation

Returns an animation where the series mimics the entrance/exit of the picture in an old television.

+ (SChartAnimation *)televisionAnimation

Discussion

This is the default entry & exit animation for SChartLineSeries, SChartStepLineSeries, and SChartBandSeries.

By default, the normalized X and Y are both set to 0.5f, and the animation duration is set to 2.4 seconds.

Declared In

SChartAnimation.h