The ChartModifierBase API is by far the most powerful API in the SciChart library. Using this API you can create behaviours which you can attach to a chart to perform custom Zooming, Panning, Annotation & Markers, Legend output and much much more. Any time you want to do something to alter the behaviour of a SciChartSurface you should be thinking about creating a custom modifier to do it.
The ChartModifierBase Type
The ChartModifierBase provides an abstract base class for all of the ChartModifiers within SciChart. All of our built-in modifiers inherit ChartModifierBase. For custom ChartModifiers, we recommend that you do the same. For example, you can declare a modifier like this:
|
Copy Code | |
|---|---|
public final class CustomRotateChartModifier extends ChartModifierBase { public void rotateChart() { if (isAttached()) { final ISciChartSurface parentSurface = getParentSurface(); IUpdateSuspender updateSuspender = parentSurface.suspendUpdates(); try { rotateAxes(parentSurface.getXAxes()); rotateAxes(parentSurface.getYAxes()); } finally { updateSuspender.dispose(); } } } private void rotateAxes(AxisCollection axes) { for (int i = 0, size = axes.size(); i < size; i++) { final IAxis axis = axes.get(i); final AxisAlignment axisAlignment = axis.getAxisAlignment(); switch (axisAlignment) { case Right: axis.setAxisAlignment(AxisAlignment.Bottom); break; case Left: axis.setAxisAlignment(AxisAlignment.Top); break; case Top: axis.setAxisAlignment(AxisAlignment.Right); break; case Bottom: axis.setAxisAlignment(AxisAlignment.Left); break; case Auto: if (axis.isXAxis()) { // Bottom axis.setAxisAlignment(AxisAlignment.Left); } else { // Right axis.setAxisAlignment(AxisAlignment.Bottom); } } } } } | |
The modifier above allows to rotate a chart when added to its ChartModifierCollection.
Most Important Methods
The common methods that are currently implemented and are not likely to be replaced can be found in the Common ChartModifiers Features article. In the table below are listed methods which can be overridden to provide a custom behavior:
| Method | Description |
| getRenderableSeries() | Returns the RenderableSeries on the ParentSurface (SciChartSurface). |
| getXAxes() | Returns the XAxes on the ParentSurface (SciChartSurface). |
| getXAxis(String axisId) | Looks for the axis with the Id among all the XAxes. |
| getXAxis() | Returns the Primary Axis among all the XAxes. |
| getYAxes() | Returns the YAxes on the ParentSurface (SciChartSurface). |
| getYAxis(String axisId) | Looks for the axis with the Id among all the YAxes. |
| getYAxis() | Returns the Primary Axis among all the YAxes. |
| getModifierSurface() | Returns the ModifierSurface on the ParentSurface. All Views produced by a modifier should be placed onto it. Also can be used to translate points relative to its boundaries. |
| getRenderableSeriesArea() | Returns the RenderableSeriesArea on the ParentSurface. All RenderableSeries are drawn on it. It is intended to be used to translate points relative to its boundaries. |
| getPointRelativeTo(PointF point, IHitTestable relativeTo) | Transforms a point relative to the specified IHitTestable instance within the ParentSurface. The IHitTestable to pass in can be obtained from the getModifierSurface() or getRenderableSeriesArea() methods. |
| onTouch(ModifierTouchEventArgs args) |
Occurs in response to a touch event. See Android Documentation. Can be used with a GestureDetector to handle gestures. In this case a modifier should implement OnGestureListener. Alternatively, inherit the GestureModifierBase class. |
| onGenericMotion(ModifierTouchEventArgs args) | Occurs in response to any device event. See Android Documentation. |
| attachTo() / detach() | Is called when a modifier gets attached to / detached from the ParentSurface. Current state can be checked with the isAttached() method. |
| applyThemeProvider(IThemeProvider themeProvider) | Is called when a new ThemeProvider is applied to the ParentSurface . |
| onIsEnabledChanged(boolean isEnabled) | Occurs when the modifier's state gets changed. |
| onParentSurfaceResized(ResizedMessage message) | Occurs in response to resizing of the ParentSurface. |
| onRenderSurfaceRendered(RenderedMessage message) | Is called after every render pass of the ParentSurface. |
| onXAxesDrasticallyChanged(ISciChartSurface surface) | Occurs in responce to replacement of the XAxes collection on the ParentSurface via the setXAxes() method. |
| onXAxesCollectionChanged(CollectionChangedEventArgs args) | Occurs when a new axis is added to the XAxes collection or any of the present is removed. |
| onYAxesDrasticallyChanged(ISciChartSurface surface) | Occurs in responce to replacement of the YAxes collection on the ParentSurface via the setYAxes() method. |
| onYAxesCollectionChanged(CollectionChangedEventArgs args) | Occurs when a new axis is added to the YAxes collection or any of the present is removed. |
| onRenderableSeriesDrasticallyChanged(ISciChartSurface surface) | Occurs in responce to replacement of the RenderableSeriesCollection on the ParentSurface via the setRenderableSeries() method. |
| onRenderableSeriesCollectionChanged(CollectionChangedEventArgs args) | Occurs when a new RenderableSeries is added to the RenderableSeriesCollection or any of the present is removed. |
| onAnnotationsDrasticallyChanged(ISciChartSurface surface) | Occurs in responce to replacement of the AnnotationCollection on the ParentSurface via the setAnnotations() method. |
| onAnnotationsCollectionChanged(CollectionChangedEventArgs args) | Occurs when a new Annotation is added to the AnnotationCollection or any of the present is removed. |
| onSelectedSeriesCollectionChanged(CollectionChangedEventArgs args) | Occurs when any RenderableSeries is added to or removed from the SelectedRenderableSeriesCollection. |
Note:
If you want to handle gestures in your custom ChartModifier, you could derive it from the GestureModifierBase class, which already implements the OnGestureListener interface and uses a GestureDetector internally.
The ModifierTouchEventArgs Type
If your custom ChartModifier requires to handle touch events or gestures, you will need to override either the onTouch() or onGenericMotion() method. Both receive the only parameter of the ModifierTouchEventArgs type. This type exposes the following information about an event that occured:
| Field | Description |
| Source | Provides the source of the event, of the IReceiveMotionEvents type. |
| IsMaster | Gets whether the event occured on the ParentSurface or was propagated through MotionEventGroup. |
| IsInSourceBounds | Reports whether the event occured within the Source. |
| IsHandled | Reports whether the event has been already passed to any other modifier and handled by it. |
| E | Returns the original MotionEvent instance. See Android Documentation. |
Note:
To receive handled events, call the setReceiveMotionEvents() on a modifier, passing in True.