Skip to main content

Crosshair Cursor

  • 16 minutes to read

Overview

The Crosshair Cursor allows users to track series or indicator data point coordinates on the Chart Control with the Cartesian (XY-) or (Swift Plot) diagram. It consists of argument and value lines, their labels, and data point labels:

crosshair__title-image

Important

The Crosshair Cursor is enabled by default when the Chart’s diagram type is Cartesian (XY-) or SwiftPlot.

A Tooltip also allows users to track values. The Tooltip and Crosshair Cursor guide describes the differences between the Tooltip and Crosshair Cursor.

Enable the Crosshair Cursor

The following code demonstrates how to enable or disable the Crosshair Cursor for a Chart Control and individual series:

// The property below sets whether the Chart displays the Crosshair Cursor:
chartControl.CrosshairEnabled = DefaultBoolean.True;
// The following property manages whether the Crosshair Cursor displays specific series values:
chartControl.Series["DevAV North"].CrosshairEnabled = DefaultBoolean.False;
Property Description
ChartControl.CrosshairEnabled Gets or sets a value that specifies whether a crosshair cursor is enabled for a chart.
SeriesBase.CrosshairEnabled Gets or sets a value that specifies whether or not a crosshair cursor is enabled for this series.

Important

If the Chart’s CrosshairEnabled property is set to DefaultBoolean.False, a series’ CrosshairEnabled property is not taken into account.

Display the Crosshair Cursor at Runtime

You can call the XYDiagram2D.ShowCrosshair method to show and hide the Crosshair Cursor at runtime.

The code snippet below shows the crosshair cursor on a mouse click. Call the XYDiagram2D.ShowCrosshair method and specify mouse position coordinates as this method’s parameters.

using System.Windows.Forms;
using DevExpress.XtraCharts;

namespace ShowCrosshair {
    public partial class Form1 : Form {
        public Form1() {
            InitializeComponent();
        }

        #region #ShowCrosshair
        private void OnChartMouseUp(object sender, MouseEventArgs e) {
            XYDiagram xyDiagram = chartControl.Diagram as XYDiagram;
            if(xyDiagram == null) return;

            xyDiagram.ShowCrosshair(e.Location);
        }
        #endregion #ShowCrosshair
    }
}

Hide the Crosshair Cursor at Runtime

Pass the Point.Empty value to the XYDiagram2D.ShowCrosshair(Point) method to hide the crosshair cursor.

private void simpleButton_Click(object sender, EventArgs e) {
    (chartControl1.Diagram as XYDiagram2D).ShowCrosshair(Point.Empty);
}

Manage Crosshair Cursor Options

The Crosshair Cursor contains a set of settings that allows you to specify the Crosshair Cursor’s position, appearance, and behavior. In code, you can use the ChartControl.CrosshairOptions property to access the Crosshair Cursor settings.

Note

Review the following help topic for information on how to use the Crosshair Cursor’s advanced customization API: Customize the Crosshair Cursor at Runtime.

This section contains the following scenarios you can implement:

Note that all customizations are done in code in this guide. However, options that configure the Crosshair Cursor are also available at design time:

crosshair__properties-window

Specify Crosshair Cursor Elements Visibility

The Crosshair Cursor can show or hide its elements. For example, the Crosshair Cursor’s axis labels are hidden and lines are shown in the image below:

crosshair__elements-visibility

This code example demonstrates how to use this functionality:

chartControl.CrosshairOptions.ShowArgumentLine = true;
chartControl.CrosshairOptions.ShowArgumentLabels = false;
chartControl.CrosshairOptions.ShowValueLine = true;
chartControl.CrosshairOptions.ShowValueLabels = true;
chartControl.CrosshairOptions.ShowCrosshairLabels = true;
chartControl.CrosshairOptions.ShowGroupHeaders = false;
// An axis can hide the Crosshair Cursor's Axis Label that is displayed on this axis:
((XYDiagram)chartControl.Diagram).AxisY.CrosshairAxisLabelOptions.Visibility = DefaultBoolean.False;
Property Description
ChartControl.CrosshairOptions Returns options that allow you to specify the Crosshair Cursor’s position, appearance and behavior.
CrosshairOptions.ShowArgumentLabels Specifies whether to show an argument line of a series point indicated by a crosshair cursor on a diagram.
CrosshairOptions.ShowArgumentLine Specifies whether to show an argument line of a series point indicated by a crosshair cursor on a diagram.
CrosshairOptions.ShowValueLabels Gets or sets a value that specifies whether to show a value label of a series point indicated by a crosshair cursor on a diagram.
CrosshairOptions.ShowValueLine Specifies whether to show a value line of a series point indicated by a crosshair cursor on a diagram.
CrosshairOptions.ShowCrosshairLabels Specifies whether to show a crosshair label of a series point indicated by a crosshair cursor on a diagram.
CrosshairOptions.ShowGroupHeaders Specifies whether to show a header for each series group in crosshair cursor labels.
Axis2D.CrosshairAxisLabelOptions Gets the crosshair axis label settings allowing you to specify its appearance on a diagram.
CrosshairAxisLabelOptions.Visibility Specifies whether to show crosshair axis labels for a diagram.

Specify the Crosshair Cursor’s Content

The Crosshair Cursor uses text patterns to prepare text it displays for series, axis labels, etc.

crosshair__patterns

The following code demonstrates how to format values that the Crosshair Cursor displays:

// The Crosshair Options contains a pattern specifying Crosshair Label Group Headers' texts:
chartControl.CrosshairOptions.GroupHeaderPattern = "{A:F0}";
// The Series' property formats the Crosshair element's text:
chartControl.SeriesTemplate.CrosshairLabelPattern = "{S}: {V:F2}";
// The axis provides a property formatting the Crosshair Axis Label's text:
((XYDiagram)chartControl.Diagram).AxisY.CrosshairAxisLabelOptions.Pattern = "{V:F1}";
Property Description
ChartControl.CrosshairOptions Returns options that allow you to specify the Crosshair Cursor’s position, appearance and behavior.
CrosshairOptions.GroupHeaderPattern Gets or sets a pattern that specifies the group header text to be displayed within the crosshair label.
SeriesBase.CrosshairLabelPattern Gets or sets a string which represents the pattern specifying the text to be displayed within a crosshair label for the current Series type.
Axis2D.CrosshairAxisLabelOptions Gets the crosshair axis label settings allowing you to specify its appearance on a diagram.
CrosshairAxisLabelOptions.Pattern Gets or sets a string which represents the pattern specifying the text to be displayed within the crosshair axis label that appears for a series point.

Note

The Crosshair Cursor’s Axis Label uses axis’ label text patterns by default.

A full list of available placeholders is detailed below.

Pattern Description
{S} Displays the name of the series.
{A} Displays a series point argument.
{V} Displays series point values.

Pie (Donut) series specific placeholders.

Placeholder Description
{VP} Displays series point values as percentages.
{TV} Displays a total group value.
Stacked series specific placeholders
{VP} Displays series point values as percentages.
{G} Displays the name of a stacked group.
{TV} Displays a total group value.

Bubble series specific placeholders.

Placeholder Description
{W} Displays the weight.

Range series specific placeholders.

Placeholder Description
{V1} Displays the first value.
{V2} Displays the second value.
{VD} Displays the duration between the first and second data points in a common time format (for example, HH:MM:SS for date time values and #.## for numeric values).
{VDTD} Displays the duration between the first and second date-time data point values in days.
{VDTH} Displays the duration between the first and second date-time data point values in hours.
{VDTM} Displays the duration between the first and second date-time data point values in minutes.
{VDTS} Displays the duration between the first and second date-time data point values in seconds.
{VDTMS} Displays the duration between the first and second date-time data point values in milliseconds.

Financial series specific placeholders.

Placeholder Description
{OV} Displays the open value.
{HV} Displays the high value.
{LV} Displays the low value.
{CV} Displays the close value.

Box Plot series specific placeholders.

Placeholder Description
{BP_MIN} Displays the Box Plot point’s Minimum value.
{BP_Q1} Displays the Box Plot point’s First Quartile value.
{BP_MDN} Displays the Box Plot point’s Median value.
{BP_AVG} Displays the Box Plot point’s Mean value.
{BP_Q3} Displays the Box Plot point’s Third Quartile value.
{BP_MAX} Displays the Box Plot point’s Maximum value.

Note

Make sure before using the {S} placeholder that the Series.Name property is specified.

You can also use standard and custom format specifiers, together with the placeholders and data field values (e.g., {V:F1}). To learn more, see the Format Specifiers topic.

When the chart control or a series is bound to data, the text pattern may contain data field values in addition to default placeholders. For example, the data source contains the Discount field and the text pattern may looks like: {S}: {V:F2} (Discount: {Discount:P0}).

A crosshair group header is not displayed on the crosshair label when the CrosshairOptions.CrosshairLabelMode property is set either to CrosshairLabelMode.ShowForEachSeries or CrosshairLabelMode.ShowForNearestSeries modes, and when the crosshair is only allowed for a single series. Specify CrosshairOptions.GroupHeaderPattern to make the Crosshair Cursor always show group headers.

Example: How to Format Values in a Crosshair Cursor with Label Patterns

This example demonstrates how to change the text displayed in crosshair labels with crosshair format patterns.

The following strings specify the patterns displayed within a crosshair label:

CrosshairAxisLabelOptions.Pattern
“Year: {A:F0}”
SeriesBase.CrosshairLabelPattern

“{S} population: {V}”

“{S} population: {V}”

CrosshairOptions.GroupHeaderPattern
“Year: {A}”

Specified Label patterns

View Example: How to Format Values in a Crosshair Cursor with Label Patterns

//Show crosshair axis lines and crosshair axis labels to see format values of crosshair labels 
chartControl1.CrosshairOptions.ShowArgumentLabels = true;
chartControl1.CrosshairOptions.ShowValueLabels = true;
chartControl1.CrosshairOptions.ShowValueLine = true;
chartControl1.CrosshairOptions.ShowArgumentLine = true;

// Specify the crosshair label pattern for both series.
series1.CrosshairLabelPattern = "{S} population: {V}";
series2.CrosshairLabelPattern = "{S} population: {V}";

// Specify the crosshair group header pattern.
chartControl1.CrosshairOptions.GroupHeaderPattern = "Year: {A}";

// Cast the chart's diagram to the XYDiagram type, to access its axes.
XYDiagram diagram = (XYDiagram)chartControl1.Diagram;

// Specify the crosshair axis labels pattern for X-axis.
diagram.AxisX.CrosshairAxisLabelOptions.Pattern = "Year: {A:F0}";

Customize Crosshair Cursor Elements’ Appearance

All Crosshair Cursor elements’ appearance can be customized. For example, Crosshair Cursor Lines can use a custom color and line style, and the Crosshair Cursor Label - a custom font, text color, and background color:

crosshair__appearance

The code below demonstrates how to configure the Crosshair Cursor appearance to match the sample image above:

Color orangeColor = Color.FromArgb(247, 129, 25);
// Note that Argument Line Labels use this color by default.
chartControl.CrosshairOptions.ArgumentLineColor = orangeColor;
chartControl.CrosshairOptions.ShowValueLine = true;
chartControl.CrosshairOptions.ShowValueLabels = true;
// Note that Value Line Labels use this color by default.
chartControl.CrosshairOptions.ValueLineColor = orangeColor;
chartControl.CrosshairOptions.ValueLineStyle.DashStyle = DashStyle.Dash;
// The axis can customize the Crosshair label that is displayed on it.
((XYDiagram)chartControl.Diagram).AxisY.CrosshairAxisLabelOptions.BackColor = Color.Red;

chartControl.CrosshairOptions.CrosshairLabelBackColor = Color.FromArgb(63, 63, 63);
chartControl.CrosshairOptions.GroupHeaderTextOptions.TextColor = orangeColor;
chartControl.CrosshairOptions.CrosshairLabelTextOptions.TextColor = Color.White;
// The series can customize how its Crosshair element looks:
chartControl.Series["DevAV North"].CrosshairTextOptions.TextColor = orangeColor;
Property Description
ChartControl.CrosshairOptions Returns options that allow you to specify the Crosshair Cursor’s position, appearance and behavior.
CrosshairOptions.ArgumentLineColor Gets or sets the color of crosshair argument lines.
CrosshairOptions.ValueLineColor Gets or sets the color of crosshair value lines.
CrosshairOptions.ArgumentLineStyle Gets the argument line style settings of the crosshair cursor.
CrosshairOptions.ValueLineStyle Gets the value line style settings of the crosshair cursor.
Axis2D.CrosshairAxisLabelOptions Gets the crosshair axis label settings allowing you to specify its appearance on a diagram.
CrosshairAxisLabelOptions.Visibility Specifies whether to show crosshair axis labels for a diagram.
CrosshairAxisLabelOptions.BackColor Gets or sets the background color of crosshair axis labels.
CrosshairOptions.CrosshairLabelBackColor Gets or sets the background color of the Crosshair series label.
CrosshairOptions.GroupHeaderTextOptions Returns text options of the Crosshair series label group header.
CrosshairOptions.CrosshairLabelTextOptions Returns text options of the Crosshair series label item.
SeriesBase.CrosshairTextOptions Returns the text options of the Crosshair label item of the series.

Important

Crosshair Options specify the appearance of all argument/value lines and labels simultaneously. Use the Axis2D.CrosshairAxisLabelOptions property to manage an individual label color and the visibility and the ChartControl.CustomDrawCrosshair event to customize a specific line. Refer to the Customize the Crosshair Cursor at Runtime topic for more information about the Custom Draw event.

Show the Crosshair Cursor on All Panes

The Chart displays the Crosshair Cursor only on the focused pane by default. Use the Crosshair options to display the Crosshair Cursor on all panes.

crosshair__show-only-in-focused-pane

The following code demonstrates how to manage the Crosshair Cursor’s visibility on panes:

chartControl.CrosshairOptions.ShowOnlyInFocusedPane = false;
Property Description
ChartControl.CrosshairOptions Returns options that allow you to specify the Crosshair Cursor’s position, appearance and behavior.
CrosshairOptions.ShowOnlyInFocusedPane Gets or sets a value that specifies whether to show a crosshair cursor in a focused pane only.

Disable Series Point Markers’ Highlighting

The Crosshair Cursor highlights series points that are currently hovered by default. You can specify whether to highlight series points for each series individually.

crosshair__highlight-points-image

The following code produces the image above:

chartControl.CrosshairOptions.HighlightPoints = false;
// Use the following series property to manage an individual series' point highlighting:
chartControl.Series["DevAV North"].CrosshairHighlightPoints = DefaultBoolean.True;
Property Description
ChartControl.CrosshairOptions Returns options that allow you to specify the Crosshair Cursor’s position, appearance and behavior.
CrosshairOptions.HighlightPoints Gets or sets a value that specifies whether the series points are highlighted when the crosshair cursor hovers over them.
SeriesBase.CrosshairHighlightPoints Gets or sets a value that specifies whether the series points are highlighted when the crosshair cursor hovers over them.

Change the Point Snapping Mode (How the Cursor Selects Points to Display)

The Crosshair Cursor allows you to specify what points it displays: points with the nearest argument to the mouse cursor or the nearest value. It shows points with the nearest argument by default. The following image demonstrates the Crosshair Cursor highlighting points with similar values:

crosshair__snap-mode

The following code demonstrates how to change the mode:

chartControl.CrosshairOptions.SnapMode = CrosshairSnapMode.NearestValue;
Property Description
ChartControl.CrosshairOptions Returns options that allow you to specify the Crosshair Cursor’s position, appearance and behavior.
CrosshairOptions.SnapMode Specifies the current snap mode of a crosshair cursor.
CrosshairSnapMode Lists the values used to specify how a crosshair cursor should detect a series point to which to snap.

Include Values That Are Out Of the Visual Range

The Crosshair Cursor shows only values that are in the visual range by default. The chart’s Crosshair Options can enable showing data points that are out of the range in the Crosshair Cursor label:

crosshair__show-out-of-range-points

The following code demonstrates how to enable this feature:

chartControl.CrosshairOptions.ShowOutOfRangePoints = true;
Property Description
ChartControl.CrosshairOptions Returns options that allow you to specify the Crosshair Cursor’s position, appearance and behavior.
CrosshairOptions.ShowOutOfRangePoints Gets or sets the value that specifies whether the Crosshair cursor should show points that are out of a y-axis’s visual range.

Lines: Change the Lines Snapping Mode

The Chart Control draws the Crosshair Cursor’s argument or value lines (depending on the current point selection mode through data points while the second line follows the mouse cursor by default. Both of the Cursor’s lines can follow the mouse position as shown in the image below:

crosshair__free-mode

The following code sample demonstrates how to make the Crosshair Cursor’s lines follow the mouse pointer:

chartControl.CrosshairOptions.LinesMode = CrosshairLinesMode.Free;
Symbol Description
ChartControl.CrosshairOptions Returns options that allow you to specify the Crosshair Cursor’s position, appearance and behavior.
CrosshairOptions.LinesMode Gets or sets the value specifying how the Crosshair Cursor’s lines snap to points when hovering on them.
CrosshairLinesMode Lists values specifying how the Crosshair Cursor’s lines behave.

Label: Display Values in a Legend Instead of a Label

The Crosshair Cursor displays selected points’ elements in a Label (by default) or Legend.

crosshair__content-mode-legend

The code below demonstrates how to make the series display its Crosshair elements in the required Chart Element:

chartControl.CrosshairOptions.ContentShowMode = CrosshairContentShowMode.Legend;
// Each series can configure where the Crosshair Cursor displays its element:
chartControl.Series["DevAV North"].CrosshairContentShowMode = CrosshairContentShowMode.Label;
Symbol Description
ChartControl.CrosshairOptions Returns options that allow you to specify the Crosshair Cursor’s position, appearance and behavior.
CrosshairOptions.ContentShowMode Gets or sets the element that displays the Crosshair’s content.
CrosshairContentShowMode Lists all the chart elements that can display the Crosshair’s content.

Label: Display Individual Labels for Each Series

The Crosshair Cursor can display individual labels for each series instead of a common label for all series:

crosshair__separate-labels

The following code demonstrates how to show individual labels:

chartControl.CrosshairOptions.CrosshairLabelMode = CrosshairLabelMode.ShowForEachSeries;
Symbol Description
ChartControl.CrosshairOptions Returns options that allow you to specify the Crosshair Cursor’s position, appearance and behavior.
CrosshairOptions.CrosshairLabelMode Specifies the way in which the crosshair label is shown for a series on a diagram.
CrosshairLabelMode Lists the values used to specify how many crosshair labels should be displayed when a chart contains several series.

Label: Change the Position

When the Crosshair Cursor displays the common label for all series, the Crosshair Options can specify the Label’s position:

crosshair__label-position

The following code demonstrates how to specify the Crosshair Cursor’s Common Label position:

chartControl.CrosshairOptions.CommonLabelPosition = new CrosshairFreePosition {
    DockTarget = ((XYDiagram)chartControl.Diagram).DefaultPane,
    DockCorner = DockCorner.RightTop,
    OffsetX = 16,
    OffsetY = 16
};
Symbol Description
CrosshairOptions.CommonLabelPosition Gets or sets the position of a crosshair label when a common crosshair label is shown for all series on a diagram.
CrosshairFreePosition Specifies a free position of a crosshair label within a chart (defined by the dock target, dock corner and offset from this corner).
CrosshairMousePosition Specifies a crosshair label position near the mouse pointer.
See Also