Class ChartTrackballBehavior

Enables the trackball functionality in the SfCartesianChart to provide interactive data point tracking.

Inheritance

System.Object

ChartTrackballBehavior

Namespace: Syncfusion.Maui.Toolkit.Charts

Assembly: Syncfusion.Maui.Toolkit.dll

Syntax

public class ChartTrackballBehavior : ChartBehavior, IMarkerDependent, IThemeElement

Remarks

The ChartTrackballBehavior class allows users to track data points as they move the pointer over the chart. The trackball provides visual feedback by displaying information about the data points at the nearest location to the pointer.

It can be customized to display the exact values of one or more series at a specific point, which is especially useful for comparing data across multiple series or analyzing trends in the chart.

To enable and customize the trackball behavior, add an instance of ChartTrackballBehavior to the TrackballBehavior

 <chart:SfCartesianChart>

  <chart:SfCartesianChart.TrackballBehavior>
    <chart:ChartTrackballBehavior/>
  </chart:SfCartesianChart.TrackballBehavior>

</chart:SfCartesianChart>

SfCartesianChart chart = new SfCartesianChart();
ChartTrackballBehavior trackball = new ChartTrackballBehavior();
chart.TrackballBehavior= trackball;

Constructors

ChartTrackballBehavior()

Initializes a new instance of the ChartTrackballBehavior class.

Declaration

public ChartTrackballBehavior()

Fields

ActivationModeProperty

Identifies the ActivationMode bindable property.

Declaration

public static readonly BindableProperty ActivationModeProperty

Field Value

Type
Microsoft.Maui.Controls.BindableProperty

Remarks

The identifier for the ActivationMode bindable property determines the activation mode of the trackball.

DisplayModeProperty

Identifies the DisplayMode bindable property.

Declaration

public static readonly BindableProperty DisplayModeProperty

Field Value

Type
Microsoft.Maui.Controls.BindableProperty

Remarks

The identifier for the DisplayMode bindable property determines the display mode of the trackball labels.

LabelStyleProperty

Identifies the LabelStyle bindable property.

Declaration

public static readonly BindableProperty LabelStyleProperty

Field Value

Type
Microsoft.Maui.Controls.BindableProperty

Remarks

The identifier for the LabelStyle bindable property determines the style of the trackball labels.

LineStyleProperty

Identifies the LineStyle bindable property.

Declaration

public static readonly BindableProperty LineStyleProperty

Field Value

Type
Microsoft.Maui.Controls.BindableProperty

Remarks

The identifier for the LineStyle bindable property determines the style of the trackball line.

MarkerSettingsProperty

Identifies the MarkerSettings bindable property.

Declaration

public static readonly BindableProperty MarkerSettingsProperty

Field Value

Type
Microsoft.Maui.Controls.BindableProperty

Remarks

The identifier for the MarkerSettings bindable property determines the customization options for the trackball markers.

ShowLabelProperty

Identifies the ShowLabel bindable property.

Declaration

public static readonly BindableProperty ShowLabelProperty

Field Value

Type
Microsoft.Maui.Controls.BindableProperty

Remarks

The identifier for the ShowLabel bindable property determines whether the trackball labels are visible.

ShowLineProperty

Identifies the ShowLine bindable property.

Declaration

public static readonly BindableProperty ShowLineProperty

Field Value

Type
Microsoft.Maui.Controls.BindableProperty

Remarks

The identifier for the ShowLine bindable property determines whether the trackball line is visible.

ShowMarkersProperty

Identifies the ShowMarkers bindable property.

Declaration

public static readonly BindableProperty ShowMarkersProperty

Field Value

Type
Microsoft.Maui.Controls.BindableProperty

Remarks

The identifier for the ShowMarkers bindable property determines whether the trackball markers are visible.

Properties

ActivationMode

Gets or sets the value that indicates whether to activate trackball based on the specified touch mode.

Declaration

public ChartTrackballActivationMode ActivationMode { get; set; }

Property Value

Type	Description
ChartTrackballActivationMode	It accepts ChartTrackballActivationMode values, with the default value being TouchMove for Windows and Mac, and LongPress for Android and iOS.

Remarks

On Windows, LongPress gesture is supported only through touch input, not with a mouse. Consequently, when ActivationMode is set to LongPress, the trackball activates only via touch interaction, not with a mouse interaction.

Examples

Xaml
C#

    <chart:SfCartesianChart>

          <!--omitted for brevity-->

          <chart:SfCartesianChart.TrackballBehavior>
              <chart:ChartTrackballBehavior ActivationMode="TouchMove"/>
          </chart:SfCartesianChart.TrackballBehavior>

          <chart:LineSeries ItemsSource="{Binding Data}"
                            XBindingPath="XValue"
                            YBindingPath="YValue"/>

    </chart:SfCartesianChart>

    SfCartesianChart chart = new SfCartesianChart();
    ViewModel viewModel = new ViewModel();

   // omitted for brevity 
   chart.TrackballBehavior = new ChartTrackballBehavior()
   {
       ActivationMode = ChartTrackballActivationMode.TouchMove,
   };

    LineSeries series = new LineSeries();
    series.ItemsSource = viewModel.Data;
    series.XBindingPath = "XValue";
    series.YBindingPath = "YValue";
    chart.Series.Add(series);

DisplayMode

Gets or sets display mode of trackball labels. By default, labels for all the series under the current point index value will be shown.

Declaration

public LabelDisplayMode DisplayMode { get; set; }

Property Value

Type	Description
LabelDisplayMode	It accepts LabelDisplayMode values and its defaults value is FloatAllPoints

Examples

Xaml
C#

    <chart:SfCartesianChart>

          <!--omitted for brevity-->

          <chart:SfCartesianChart.TrackballBehavior>
              <chart:ChartTrackballBehavior DisplayMode="NearestPoint"/>
          </chart:SfCartesianChart.TrackballBehavior>

          <chart:LineSeries ItemsSource="{Binding Data}"
                            XBindingPath="XValue"
                            YBindingPath="YValue"/>

    </chart:SfCartesianChart>

    SfCartesianChart chart = new SfCartesianChart();
    ViewModel viewModel = new ViewModel();

   // omitted for brevity
   chart.TrackballBehavior = new ChartTrackballBehavior()
   {
       DisplayMode = LabelDisplayMode.NearestPoint,
   };

    LineSeries series = new LineSeries();
    series.ItemsSource = viewModel.Data;
    series.XBindingPath = "XValue";
    series.YBindingPath = "YValue";
    chart.Series.Add(series);

LabelStyle

Gets or sets the value to customize the appearance of trackball labels.

Declaration

public ChartLabelStyle LabelStyle { get; set; }

Property Value

Type	Description
ChartLabelStyle	This property takes the ChartLabelStyle as its value.

Remarks

To customize the trackball label appearance, you need to create an instance of the ChartLabelStyle class and set to the LabelStyle property.

Null values are invalid.

Examples

Xaml
C#

    <chart:SfCartesianChart>

          <!--omitted for brevity-->

          <chart:SfCartesianChart.TrackballBehavior>
              <chart:ChartTrackballBehavior>
                  <chart:ChartTrackballBehavior.LabelStyle>
                      <chart:ChartLabelStyle TextColor="Red" FontSize="14"/>
                  </chart:ChartTrackballBehavior.LabelStyle>
       </chart:ChartTrackballBehavior>
          </chart:SfCartesianChart.TrackballBehavior>

          <chart:LineSeries ItemsSource="{Binding Data}"
                            XBindingPath="XValue"
                            YBindingPath="YValue"/>

    </chart:SfCartesianChart>

    SfCartesianChart chart = new SfCartesianChart();
    ViewModel viewModel = new ViewModel();

   // omitted for brevity 
   var labelStyle = new ChartLabelStyle()
   {
       TextColor = Colors.Red, FontSize = 12,
   };
   chart.TrackballBehavior = new ChartTrackballBehavior()
   {
       LabelStyle = labelStyle,
   };

    LineSeries series = new LineSeries();
    series.ItemsSource = viewModel.Data;
    series.XBindingPath = "XValue";
    series.YBindingPath = "YValue";
    chart.Series.Add(series);

LineStyle

Gets or sets the value to customize the appearance of the trackball line.

Declaration

public ChartLineStyle LineStyle { get; set; }

Property Value

Type	Description
ChartLineStyle	This property takes the ChartLineStyle as its value.

Remarks

To customize the trackball line appearance, you need to create an instance of the ChartLineStyle class and set to the LineStyle property.

Null values are invalid.

Examples

Xaml
C#

    <chart:SfCartesianChart>

          <!--omitted for brevity-->

          <chart:SfCartesianChart.TrackballBehavior>
              <chart:ChartTrackballBehavior>
                  <chart:ChartTrackballBehavior.LineStyle>
                      <chart:ChartLineStyle Stroke = "Red" StrokeWidth="2"/>
                  </chart:ChartTrackballBehavior.LineStyle>
       </chart:ChartTrackballBehavior>
          </chart:SfCartesianChart.TrackballBehavior>

          <chart:LineSeries ItemsSource="{Binding Data}"
                            XBindingPath="XValue"
                            YBindingPath="YValue"/>

    </chart:SfCartesianChart>

    SfCartesianChart chart = new SfCartesianChart();
    ViewModel viewModel = new ViewModel();

   // omitted for brevity 
   var lineStyle = new ChartLineStyle()
   {
       Stroke = new SolidColorBrush(Colors.Red), StrokeWidth = 2,
   };
   chart.TrackballBehavior = new ChartTrackballBehavior()
   {
       LineStyle = lineStyle,
   };

    LineSeries series = new LineSeries();
    series.ItemsSource = viewModel.Data;
    series.XBindingPath = "XValue";
    series.YBindingPath = "YValue";
    chart.Series.Add(series);

MarkerSettings

Gets or sets the option for customize the trackball markers.

Declaration

public ChartMarkerSettings MarkerSettings { get; set; }

Property Value

Type	Description
ChartMarkerSettings	This property takes the ChartMarkerSettings as its value.

Examples

Xaml
C#

    <chart:SfCartesianChart>

          <!--omitted for brevity-->

          <chart:SfCartesianChart.TrackballBehavior>
              <chart:ChartTrackballBehavior>
                  <chart:ChartTrackballBehavior.MarkerSettings>
                      <chart:ChartMarkerSettings Height = "10" Width="10" Fill="Red"/>
                  </chart:ChartTrackballBehavior.MarkerSettings>
       </chart:ChartTrackballBehavior>
          </chart:SfCartesianChart.TrackballBehavior>

          <chart:LineSeries ItemsSource="{Binding Data}"
                            XBindingPath="XValue"
                            YBindingPath="YValue"/>

    </chart:SfCartesianChart>

    SfCartesianChart chart = new SfCartesianChart();
    ViewModel viewModel = new ViewModel();

   // omitted for brevity 
   var markerSettings = new ChartMarkerSettings()
   {
       Height = 10, Width = 10,
       Fill = new SolidColorBrush(Colors.Red),
   };
   chart.TrackballBehavior = new ChartTrackballBehavior()
   {
       MarkerSettings = markerSettings,
   };

    LineSeries series = new LineSeries();
    series.ItemsSource = viewModel.Data;
    series.XBindingPath = "XValue";
    series.YBindingPath = "YValue";
    chart.Series.Add(series);

ShowLabel

Gets or sets the value that indicates whether to show label for the trackball.

Declaration

public bool ShowLabel { get; set; }

Property Value

Type	Description
System.Boolean	It accepts `bool` values and its default value is `True`.

Examples

Xaml
C#

    <chart:SfCartesianChart>

          <!--omitted for brevity-->

          <chart:SfCartesianChart.TrackballBehavior>
              <chart:ChartTrackballBehavior ShowLabel="False"/>
          </chart:SfCartesianChart.TrackballBehavior>

          <chart:LineSeries ItemsSource="{Binding Data}"
                            XBindingPath="XValue"
                            YBindingPath="YValue"/>

    </chart:SfCartesianChart>

    SfCartesianChart chart = new SfCartesianChart();
    ViewModel viewModel = new ViewModel();

   // omitted for brevity 
   chart.TrackballBehavior = new ChartTrackballBehavior()
   {
       ShowLabel = false,
   };

    LineSeries series = new LineSeries();
    series.ItemsSource = viewModel.Data;
    series.XBindingPath = "XValue";
    series.YBindingPath = "YValue";
    chart.Series.Add(series);

ShowLine

Gets or sets the value that indicates whether to show the trackball line.

Declaration

public bool ShowLine { get; set; }

Property Value

Type	Description
System.Boolean	It accepts `bool` values and its default value is `True`.

Examples

Xaml
C#

    <chart:SfCartesianChart>

          <!--omitted for brevity-->

          <chart:SfCartesianChart.TrackballBehavior>
              <chart:ChartTrackballBehavior ShowLine="False"/>
          </chart:SfCartesianChart.TrackballBehavior>

          <chart:LineSeries ItemsSource="{Binding Data}"
                            XBindingPath="XValue"
                            YBindingPath="YValue"/>

    </chart:SfCartesianChart>

    SfCartesianChart chart = new SfCartesianChart();
    ViewModel viewModel = new ViewModel();

   // omitted for brevity 
   chart.TrackballBehavior = new ChartTrackballBehavior()
   {
       ShowLine = false,
   };

    LineSeries series = new LineSeries();
    series.ItemsSource = viewModel.Data;
    series.XBindingPath = "XValue";
    series.YBindingPath = "YValue";
    chart.Series.Add(series);

ShowMarkers

Gets or sets the value that indicates whether to show markers for the trackball.

Declaration

public bool ShowMarkers { get; set; }

Property Value

Type	Description
System.Boolean	It accepts `bool` values and its default value is `True`.

Examples

Xaml
C#

    <chart:SfCartesianChart>

          <!--omitted for brevity-->

          <chart:SfCartesianChart.TrackballBehavior>
              <chart:ChartTrackballBehavior ShowMarkers="False"/>
          </chart:SfCartesianChart.TrackballBehavior>

          <chart:LineSeries ItemsSource="{Binding Data}"
                            XBindingPath="XValue"
                            YBindingPath="YValue"/>

    </chart:SfCartesianChart>

    SfCartesianChart chart = new SfCartesianChart();
    ViewModel viewModel = new ViewModel();

   // omitted for brevity 
   chart.TrackballBehavior = new ChartTrackballBehavior()
   {
       ShowMarkers = false,
   };

    LineSeries series = new LineSeries();
    series.ItemsSource = viewModel.Data;
    series.XBindingPath = "XValue";
    series.YBindingPath = "YValue";
    chart.Series.Add(series);

Methods

Hide()

Hides the trackball that is visible in the chart.

Declaration

public void Hide()

LabelsGenerated(List<TrackballPointInfo>)

Invokes when the trackball is moved from one data point to another. This helps to customize the trackball label and marker based on the condition.

Declaration

protected virtual void LabelsGenerated(List<TrackballPointInfo> pointInfos)

Parameters

Type	Name	Description
System.Collections.Generic.List<TrackballPointInfo>	pointInfos

OnParentSet()

Declaration

protected override void OnParentSet()

OnTouchDown(ChartBase, Single, Single)

This method is triggered when a touch event is detected on the chart.

Declaration

protected override void OnTouchDown(ChartBase chart, float pointX, float pointY)

Parameters

Type	Name	Description
ChartBase	chart
System.Single	pointX
System.Single	pointY

Overrides

ChartBehavior.OnTouchDown(ChartBase, Single, Single)

Remarks

Use the provided points X and Y to determine the exact location of the touch.

You can use these coordinates to interact with the chart, such as highlighting data points, showing tooltips, or performing other actions.

Example code:

Convert the touch coordinates to value coordinates if needed.

 
chart.ChartPointToValue(xAxis, pointY);

Show a tooltip with information about the data point.

tooltipBehavior.Show(pointX, pointY);

OnTouchMove(ChartBase, Single, Single)

This method is triggered when a touch point is moved along the touch surface.

Declaration

protected override void OnTouchMove(ChartBase chart, float pointX, float pointY)

Parameters

Type	Name	Description
ChartBase	chart
System.Single	pointX
System.Single	pointY

Overrides

ChartBehavior.OnTouchMove(ChartBase, Single, Single)

Remarks

Use the provided points X and Y to determine the exact location of the touch.

You can use these coordinates to define the desired actions to be executed when navigating the touch point across the chart area.

Example code:

Convert the touch coordinates to value coordinates if needed.

 
chart.ChartPointToValue(xAxis, pointY);

Show a tooltip with information about the data point.

tooltipBehavior.Show(pointX, pointY);

OnTouchUp(ChartBase, Single, Single)

This method is triggered when a touch event comes to an end. It is used to finalize the action initiated by the OnTouchDown(ChartBase, Single, Single).

Declaration

protected override void OnTouchUp(ChartBase chart, float pointX, float pointY)

Parameters

Type	Name	Description
ChartBase	chart
System.Single	pointX
System.Single	pointY

Overrides

ChartBehavior.OnTouchUp(ChartBase, Single, Single)

Remarks

Use the provided points X and Y to determine the exact location of the touch.

You can use these coordinates to interact with the chart, such as highlighting data points, hiding tooltips, or performing other actions when the touch is released.

Example code:

Convert the touch coordinates to value coordinates if needed.

 
chart.ChartPointToValue(xAxis, pointY);

Hide a tooltip with information about the data point.

tooltipBehavior.Hide(pointX, pointY);

Show(Single, Single)

Activate the trackball at the nearest point to the specified location.

Declaration

public void Show(float pointX, float pointY)

Parameters

Type	Name	Description
System.Single	pointX
System.Single	pointY