Crosshair Cursor Customization
- 5 minutes to read
This topic describes different ways to customize crosshair cursor elements and format crosshair label content.
Interaction Customization
Show Crosshair Axis Lines and Labels
Crosshair argument lines and crosshair common labels are visible by default.
To show value lines, argument labels, and value labels of the crosshair cursor on a chart, set the CrosshairOptions.ShowValueLine, CrosshairOptions.ShowArgumentLabels, and CrosshairOptions.ShowValueLabels properties to true.
A CrosshairOptions object (containing all settings necessary to customize the crosshair cursor appearance and position on the chart) is accessed from the WebChartControl.CrosshairOptions property.
After the crosshair axis lines and labels are enabled, the chart appears as follows:
Specify the Crosshair Label Mode
+In addition, you can also use the CrosshairOptions.CrosshairLabelMode property to specify how a crosshair cursor label is displayed in a multiple series chart.
A common crosshair label can be shown for all series (the default mode in which the group header is displayed on a crosshair label), for each series separately, or for the nearest series only.
The image below demonstrates the second approach.
Note
A crosshair label is automatically displayed with a beak in CrosshairLabelMode.ShowForEachSeries and CrosshairLabelMode.ShowForNearestSeries modes.
Format Crosshair Cursor Content
Use a Pattern of Crosshair Axis and Crosshair Cursor Labels
You can change the default format of text displayed within the crosshair labels by specifying a pattern (e.g., only show point values). To accomplish this, use the CrosshairAxisLabelOptions.Pattern, SeriesBase.CrosshairLabelPattern and CrosshairOptions.GroupHeaderPattern properties.
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 (e.g., 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.
The Format Specifiers topic explains which standard and custom formats can be used with placeholders to format numeric and date-time values within a crosshair cursor label.
The image below shows the SeriesBase.CrosshairLabelPattern property set to “{S}: {A} - {V}”.
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, if the data source contains the Discount field, then the text pattern may appear as follows: {S}: {V:F2} (Discount: {Discount:P0}).
Examples
Appearance Customization
Manage the Crosshair Cursor Appearance Options
The DevExpress.XtraCharts.CrosshairOptions class contains settings that allow you to customize the appearance of the crosshair cursor elements.
The following image highlights settings that configure the crosshair cursor appearance.
The properties in the table below allow you to customize the common appearance options of the crosshair cursor.
| Member | Description |
|---|---|
| CrosshairOptions.ValueLineColor | Gets or sets the color of crosshair value lines. |
| CrosshairOptions.ValueLineStyle | Gets the value line style settings of the crosshair cursor. |
| CrosshairOptions.ArgumentLineColor | Gets or sets the color of crosshair argument lines. |
| CrosshairOptions.ArgumentLineStyle | Gets the argument line style settings of the crosshair cursor. |
| CrosshairOptions.CrosshairLabelBackColor | Gets or sets the background color of the Crosshair series label. |
| CrosshairOptions.CrosshairLabelTextOptions | Returns text options of the Crosshair series label item. |
| CrosshairOptions.GroupHeaderTextOptions | Returns text options of the Crosshair series label group header. |
Handle the CustomDrawCrosshair event
Use the CustomDrawCrosshair event to customize the crosshair cursor elements at runtime.
Display the “Total” Point Value in the Crosshair Panel
This example illustrates how to display the “Total” point value in the crosshair cursor panel.
To accomplish this task, handle the client-side ASPxClientWebChartControl.CustomDrawCrosshair event and use the last crosshair panel element’s LabelElement.footerText property to display the Total value.
<clientsideevents customdrawcrosshair="function(s, e) {
var summary = 0;
for (var i = 0; i < e.crosshairElements.length; i++) {
summary += e.crosshairElements[i].Point.point.values[0];
}
e.crosshairElements[e.crosshairElements.length - 1].LabelElement.footerText = 'Total :' + summary;
}" />
Change the Crosshair Label Font Size
The example below shows how to handle CustomDrawCrosshair to change the label’s font size.
<dxchartsui:WebChartControl ID="WebChartControl1" runat="server" ClientInstanceName="chartControl" CrosshairEnabled="True" Height="368px" Width="607px">
<CrosshairOptions ShowGroupHeaders="False"/>
<!--...-->
<clientsideevents customdrawcrosshair="function(s, e) {
for (var i = 0; i < e.crosshairElements.length; i++) {
e.crosshairElements[i].LabelElement.font.fontSize = 20;
}
}"
/>
</dxchartsui:WebChartControl>