How to Add Mouse Interactions to SciChart

How does Mouse Interaction work in SciChart?

Mouse Interaction is provided by the ChartModifiers. These are a collection of classes which derive from ChartModifierBase, which handle mouse input, listen to events on the parent SciChartSurface, and are able to manipulate the zoom or scale of the chart.

What can ChartModifiers do?

Please see our documentation article What is the ChartModifier API for a full list of available Chart Modifiers.

Chart Modifiers in SciChart provide the ability to:

• Zoom or Pan a chart via the mouse
• Draw over the chart (e.g. zoom rectangles, axis markers, annotations)
• Select Series
• Provide DataSources to bind to e.g. Legend data sources
• Link multiple charts together

It is also possible to create Custom ChartModifiers via our rich API.

How to add ChartModifiers to SciChart

Many of the examples utilize one or more modifiers, which can be added to a SciChartSurface as simply as this:

<s:SciChartSurface>
    <s:SciChartSurface.ChartModifier>
        <!—Provides zoom on mouse-drag -->
        <s:RubberBandXyZoomModifier/>
    </s:SciChartSurface.ChartModifier>
</s:SciChartSurface>

How to add Multiple ChartModifiers to a single SciChartSurface

Or, you can add multiple modifiers to a chart by using a ModifierGroup:

<s:SciChartSurface>
    <s:SciChartSurface.ChartModifier>
        <!—Groups many ChartModifiers on a single chart with mouse-event
precedence -->
        <s:ModifierGroup>
             <!—Provides zoom on mouse-drag -->
             <s:RubberBandXyZoomModifier/>
             <!—Selects Series on mouse-click -->
             <s:SeriesSelectionModifier/>
             <!—Zoom Extents on Double-Click -->
             <s:ZoomExtentsModifier/>
             <!—Provides zoom or pan on dragging a YAxis -->
             <s:YAxisDragModifier/>
             <!—Provides zoom or pan on dragging an XAxis -->
             <s:XAxisDragModifier/>
        </s:ModifierGroup>
    </s:SciChartSurface.ChartModifier>
</s:SciChartSurface>

ChartModifier Precedence (Handled Events)

ChartModifiers obey a precedence, rather like WPF RoutedEvents. If you have a number of modifiers in a SciChartSurface, then the first modifier that handles an event marks it as e.Handled. Subsequent modifiers will not receive the event.

For instance, consider the following code:

<s:SciChartSurface>
    <s:SciChartSurface.ChartModifier>
        <!—Groups many ChartModifiers on a single chart with mouse-event
precedence -->
        <s:ModifierGroup>
             <!—Provides zoom on mouse-drag, handles MouseUp on successful
zoom-->
             <s:RubberBandXyZoomModifier/>
             <!—Selects Series on mouse-up -->
             <s:SeriesSelectionModifier/>
        </s:ModifierGroup>
    </s:SciChartSurface.ChartModifier>
</s:SciChartSurface>

If you drag the chart, then the series will not be selected too, because the RubberBandXyZoomModiifer marks MouseUp as Handled. The SeriesSelectionModifier relies on MouseUp to select. If the event is handled then it will not select.

So far this is all intuitive and good. But what about this case?

<s:SciChartSurface>
    <s:SciChartSurface.ChartModifier>
        <!—Groups many ChartModifiers on a single chart with mouse-event
precedence -->
        <s:ModifierGroup>
             <!—Provides pan on mouse-drag, handles MouseDown, MouseMove on
pan-->
             <s:ZoomPanModifier/>
             <!—Provides a cursor on mouse-move, requires MouseMove event
-->
             <s:CursorModifier/>
        </s:ModifierGroup>
    </s:SciChartSurface.ChartModifier>
</s:SciChartSurface>

Oh dear … Now if you mouse-drag the chart the cursor will not move with the mouse. Why is this occurring? Because the ZoomPanModifer marks the MouseMove event as handled, the CursorModifier never receives it. This functionality is intended to prevent bad interactions between modifiers such as selection and zoom on click, but in this case it is hindering us.

Working around event handling with ReceiveHandledEvents

The solution to the above problem is to set ReceiveHandledEvents=True on a modifier. This way the modifier will receive *all* events, even those marked as handled. Try the following code for instance:

<s:SciChartSurface>
    <s:SciChartSurface.ChartModifier>
        <!—Groups many ChartModifiers on a single chart with mouse-event
precedence -->
        <s:ModifierGroup>
             <!—Provides pan on mouse-drag, handles MouseDown, MouseMove on
pan-->
             <s:ZoomPanModifier/>
             <!—Provides a cursor on mouse-move, requires MouseMove event
-->
             <s:CursorModifier ReceiveHandledEvents=”True”/>
        </s:ModifierGroup>
    </s:SciChartSurface.ChartModifier>
</s:SciChartSurface>

Be careful with this flag though as it could enable event handling where it should not occur.

Further Reading

More detailed information can be found in our documentation:

• ChartModifiers API
• Custom Modifiers API