SciChart v3 Migration guide

SciChart v3.0 is the latest major release of SciChart - High Performance Realtime Charts framework for iOS.

This guide is provided to ease the transition of existing applications using SciChart v2.5 to the latest APIs, as well as explain the design and structure of new and updated functionality.

Table of contents

• Benefits of Upgrading
• Breaking Changes
  • Type naming changes
  • Removed SCIGenericType
  • Drawing assets creation
  • Observable collections
  • Animations
  • Annotations API
  • Chart Modifiers API

Benefits of Upgrading

• All the API was improved, became more flexible and more consistent with other platforms
• Supports Metal and OpenGL (fixed Metal - related issues from version 2.5)
• New, more efficient mechanism of Data Resampling
• Improved performance of certain renderable series types (SCIFastBubbleRenderableSeries, SCIFastCandlestickRenderableSeries, SCIFastUniformHeatmapRenderableSeries and some more)
• More rich and much more flexible Animations, Chart Modifiers, Annotations API
• A lot of bug fixes
• Removed SCIGenericType, so no boxing needed anymore.
• Whole SciChart API became more Swift-friendly
• New 3D Chart types were implemented
• Better structured examples suite

Breaking Changes

In version 3.x iOS API was fully updated to improve flexibility, swift compatibility and become consistent with other platforms. Because of this, almost all the API has been modified in some way. There’s no possibility to document every single change, so we’re going to attempt to identify the most commonly used parts of SciChart and describe what have been changed there.

Type naming changes

To keep code cleaner and simpler we’ve got rid of convention to end all the protocol names with a “Protocol” suffix and use “I” prefix instead, e.g.:

• SCIRenderableSeriesProtocol became ISCIRenderableSeries.
• SCIAxisCoreProtocol became ISCIAxisCore.

Also, SCIBubbleRenderableSeries type was renamed to SCIFastBubbleRenderableSeries to match the other platforms.

So in case if, in you SciChart v2 depended code you see the errors like this:

- No type or protocol named 'SCIAxis2DProtocol'
- Cannot find protocol declaration for 'SCIChartSurfaceProtocol'
- No type or protocol named 'SCIRenderableSeriesProtocol'
- Unknown receiver 'SCIBubbleRenderableSeries'; did you mean 'SCIFastBubbleRenderableSeries'?

you’ll need just update a corresponding type name according to a new convention.

Removed SCIGenericType

As Objective-C doesn’t have generics and hence in previous version of SciChart we used to box all the native types into SCIGenericType, which caused code to become inaccurate and dirty. In version 3.x we enriched our API to get rid of SCIGenericType. Some of generic APIs expect object conforming ISCIComparable protocol, others just extended to work with primitive types directly.

NOTE: SciChart API has extensions for NSNumber and NSDate types, adding conformance to ISCIComparable.

Also SCIArrayController class (which was fully based on the SCIGenericType) has been removed and data structures conforming to ISCIValues were introduced instead. These changes heavily affected the DataSeries API, so now the preferred way to modify your chart’s data - is using methods based on ISCIValues under the hood.

So if you see the following errors in your SciChart v2 depended code:

- Unknown type name 'SCIGenericType'
- Unknown type name 'SCIArrayController'
- Expected a type 'SCIArrayController'
- Expected a type 'SCIGenericType'
- No visible @interface for 'SCIXyzDataSeries' declares the selector 'initWithXType:YType:ZType:'
- No visible @interface for 'SCIDoubleRange' declares the selector 'initWithMin:Max:'
- Implicit conversion of 'int' to 'id<ISCIComparable>' is disallowed with ARC

Just use ISCIComparable conforming types instead of SCIGenericType, ISCIValues instead of SCIArrayController and remove SCIGenericWrapper.swift from your Swift project.

Please check Append, Insert, Update, Remove section, to get more details.

Drawing assets creation

In v3.x we introduced ISCIAssetManager2D protocol, which is responsible for creating all the engine-specific drawing assets (pen, brushes, sprites, textures etc.). So in your SciChart v2 depended code, you might see errors like:

- No visible @interface for 'SCISolidPenStyle' declares the selector 'initWithColorCode:withThickness:'
- No visible @interface for 'SCIRadialGradientBrushStyle' declares the selector 'initWithColorCodeStart:finish:'
- No visible @interface for 'SCILinearGradientBrushStyle' declares the selector 'initWithColorCodeStart:finish:direction:'

You can create an asset, using corresponding style object. The styles was refactored as well, so SCISolidPenStyle, SCILinearGradientPenStyle, SCIRadialGradientPenStyle, SCISolidBrushStyle, SCILinearGradientBrushStyle and SCIRadialGradientBrushStyle have been changed. Here is an example, how to create pen and brush in SciChart v3.x.

This will affect your code if you have implemented custom drawing of some SciChart visual primitives. For example, now customization of renderable series drawing you’ll need to override the following method:

- (void)internalDrawWithContext:(id<ISCIRenderContext2D>)renderContext 
                    assetManager:(id<ISCIAssetManager2D>)assetManager 
                    renderPassData:(id<ISCISeriesRenderPassData>)renderPassData;

like demonstrated below:

NOTE: To see the full example which uses the code snippet above, please check the SplineLineRenderableSeries class in our Spline Scatter Line Chart example which can be found in the SciChart iOS Examples Suite as well as on GitHub.

Observable collections

SCIObservableCollection API was refactored - some methods of concrete classes have been removed, or partially moved to a base class.

So in your SciChart v2 depended code, you might see errors like:

- No visible @interface for 'SCIChartModifierCollection' declares the selector 'initWithChildModifiers:'

To fix this, please check the example code for setting chart modifiers to a surface:

Animations

To become more flexible, and have better integration into SciChart run loop - Animation API has been completely re-designed and re-written. In SciChart v3.x we introduced SCIAnimations utility, which provides an interface to create basic animations for renderable series.

So in your SciChart v2 depended code, you might see errors like:

- Unknown receiver 'SCISweepRenderableSeriesAnimation'
- Unknown receiver 'SCIWaveRenderableSeriesAnimation'
- Unknown receiver 'SCIScaleRenderableSeriesAnimation'

The example below demonstrates the difference of animation creation in v2x and v3.x, end explains how to fix these errors.

To get more details about existing easing functions and animation types, please check Animation API guide.

Annotations API

All the annotations in SciChart v3.x conforms to the ISCIAnnotation protocol and inherits SCIAnnotationBase class. To get more info about existing annotation types and common functionality of the SCIAnnotationBase please check the documentation for Annotations API. The most prominent changes to the Annotations API are the following:

• As the SCIGenericType was removed, now annotation coordinates became ISCIComparable.
• AnnotationStyle classes (e.g SCILineAnnotationStyle, SCITextAnnotationStyle) were removed, their properties either moved to corresponding annotation class, or to the SCIAnnotationBase.

So in your SciChart v2 depended code, you might see errors like:

- Property 'style' not found on object of type 'SCITextAnnotation *'
- Property 'style' not found on object of type 'SCIHorizontalLineAnnotation *'

Here is how the creation of SCIHorizontalLineAnnotation looks now:

Chart Modifiers API

In SciChart v3.x Chart Modifiers API was deeply refactored, became more flexible, easy to use and have now more clear customization points. To get more information about all available chart modifier types, please visit the Chart Modifier APIs article.

Breaking changes of the Chart Modifiers API, which might impact your code are listed below:

• ModifierStyle’s objects have been removed and their properties moved to corresponding modifier classes (The same way like with annotations).
• All the modifiers in SciChart v3.x now conforms to ISCIChartModifierCore protocol and inherits SCIChartModifierCore base class.
• SCIGestureController class was removed, and now all the chart modifiers are driven by the native UIGestureRecognizer
• Gesture Modifiers are now inherited from the SCIGestureModifierBase or SCIGestureModifierBase3D. Each gesture modifier is responsible for creation its own UIGestureRecognizer while the SCIGestureModifierBase setups target-action relationship between gesture recognizer and modifier instance for you. So, gesture modifier now has more points for customization, including possibility to set your custom UIGestureRecognizerDelegate:

        // Override this method to make modifier work with custom gesture recognizer
        - (UIGestureRecognizer *)createGestureRecognizer;

        // Override this method to handle gesture recognizers action
        - (void)internalHandleGesture:(UIPinchGestureRecognizer *)gestureRecognizer 

In addition to the above - SCIRolloverModifier, SCITooltipModifier, and SCICursorModifier are became much more flexible. You don’t need to subclass renderable series to make custom tooltip view for it. Now you can just inject custom ISCISeriesInfoProvider with all needed customizations instead.

So in your SciChart v2 depended code, you might see errors like:

- Property 'style' not found on object of type 'SCICursorModifier *'
- Cannot find interface declaration for 'SCIGestureModifier', superclass of 'CustomModifier'; did you mean 'SCIGestureModifierBase'?
- Interface type 'SCIHitTestInfo' cannot be passed by value
- Property 'match' not found on object of type 'SCIHitTestInfo *'

Here is an example of SCIRolloverModifier customization (the rest of listed modifiers have quite the same customization logic):

NOTE: The full Customization RolloverModifier example can be found in the SciChart iOS Examples Suite as well as on GitHub:

• Obj-C/Swift Example

Also in SciChart v3 we improved a mechanism of syncing modifiers, of multiple surfaces. As a result,SCIMultiSurfaceModifier, SCIAxisAreaSizeSynchronization and SCIAxisRangeSynchronization classes got removed.

As the result, in your SciChart v2 depended code, you might see errors like:

- Unknown type name 'SCIAxisRangeSynchronization'
- Unknown type name 'SCIMultiSurfaceModifier'

So, now to sync ranges of two axises (from different surfaces) you’ll need just assign both of them the same instance of visibleRange. And to synchronize modifiers - you’ll need just create an SCICharModifierGroup with the same event tag for both surfaces, and put in this group all the modifiers you want to be synchronized:

NOTE: The full Sync Multiple Charts example can be found in the SciChart iOS Examples Suite as well as on GitHub:

• Obj-C/Swift Example