Xceed Chart for WinForms v4.4 Documentation
Hit Testing

Welcome to Xceed Chart for WinForms v4.4 > User Guide > Interactivity > Hit Testing

The ability to determine chart objects by given window coordinates is an essential functionality built into Xceed Chart for WinForms. This feature is called "hit testing" and allows the developer to build advanced interactive applications. 

You perform hit testing by calling the HitTest method of the ChartControl class. It accepts two parameters specifying a point in window coordinates. The function returns an object of type HitTestResult. The following code for example intercepts the mouse click event and obtains a HitTestResult object for the chart object under the mouse:

VB.NET  

Private Sub MouseEventsUC_Load(ByVal sender As Object, ByVal e As System.EventArgs) Handles MyBase.Load
AddHandler chartControl1.MouseDown, AddressOf chartControl1_MouseDown
End Sub 'MouseEventsUC_Load
.......
Private Sub chartControl1_MouseDown(ByVal sender As Object, ByVal e As System.EventArgs)
Dim hitTestResult As HitTestResult = chartControl1.HitTest(e.X, e.Y)
 
if hitTestResult.ChartElement = ChartElement.ControlBackground then
' the user clicked on the chart control background.
end if
End Sub
C#  

private void Form_Load(object sender, System.EventArgs e)
{
chartControl1.MouseDown += new System.Windows.Forms.MouseEventHandler(OnMouseDown);
}
.....
public void OnMouseDown(object sender, MouseEventArgs e)
{
HitTestResult hitTestResult = chartControl.HitTest(e.X, e.Y);
 
if (hitTestResult.ChartElement == ChartElement.ControlBackground)
{
// the user clicked on the chart control background.
}
}

The most important property of the HitTestResult object is the ChartElement property. It describes the type of the chart element at the given window coordinates. Depending on the chart element type, some of the properties of the HitTestResult referencing objects may be null (Nothing in VB .NET). Similarly, properties specifying indexes in some of the chart collections may be -1. The following table shows how the properties depend on the ChartElement property: 

Property Description Valid for chart elements
Object A refence to a chart element. Valid for all chart elements except ChartElement.Nothing.
Background The chart background The Object property contains a reference to the Background object of the control.
Chart Returns a reference to the Chart object containing the located object.

Valid when the ChartElement is DataPoint, SurfaceDataPoint, Axis,AxisStripe and ChartWall. 

ChartIndex Returns the index of the Chart object containing the located object in the Charts collection of the ChartControl. Valid when the ChartElement is DataPoint, SurfaceDataPoint, Axis,AxisStripe and ChartWall.
ChartWall Returns a reference to a ChartWall object. Valid only when ChartElement is set to ChartWall.
ChartWallIndex Returns the index of the ChartWall object in the Chart  Walls collection. Valid only when ChartElement is set to ChartWall.
Series Returns a reference to the SeriesBase object containing the located data item. Valid when ChartElement is ChartElement.SurfaceDataPoint or ChartElement.DataPoint.
SeriesIndex Returns the index of the SeriesBase object in the Chart Series collection. Valid when ChartElement is SurfaceDataPoint or DataPoint.
DataPointIndex Returns the index of the data point in the Series  Values collection. Valid only when ChartElement is set to DataPoint.
SurfaceDataPointX Returns the index of the data point in the SurfaceSeriesBase Values collection. Valid only when ChartElement is set to SurfaceDataPoint.
SurfaceDataPointY Returns the index of the data point in the SurfaceSeriesBase Values collection. Valid only when ChartElement is set to SurfaceDataPoint.
Axis Returns a reference to a Axis object. Valid when ChartElement is Axis or AxisStripe.
AxisIndex Returns the index of the Axis object in the Chart  Axes collection. Valid when ChartElement is Axis or AxisStripe.
AxisStripe Returns a reference to a AxisStripe object. Valid only when ChartElement is set to AxisStripe.
AxisStripeIndex Returns the index of the AxisStripe object in the Axis  Stripes collection. Valid only when ChartElement is set to AxisStripe.
Label Returns a reference to a Label object. Valid only when ChartElement is set to Label.
LabelIndex Returns the index of the Label object in the control Labels collection. Valid only when ChartElement is set to Label.
Watermark Returns a reference to a Watermark object. Valid only when ChartElement is set to Watermark.
WatermarkIndex Returns the index of the Watermark object in the control Watermarks collection. Valid only when ChartElement is set to Watermark.

Now let's see how this works in practice. The following example creates an interactive pie chart that allows the user to click on the pie slices. When a pie is clicked, it will be detached from the pie center:

VB.NET  

.......
Imports Xceed.Chart.GraphicsCore
Imports Xceed.Chart.Standard
Imports Xceed.Chart
.......
Private Sub MouseEventsUC_Load(ByVal sender As Object, ByVal e As System.EventArgs) Handles MyBase.Load
Dim chart As Chart = chartControl1.Charts(0)
chart.Depth = 25
Dim pie As PieSeries = CType(chart.Series.Add(SeriesType.Pie), PieSeries)
pie.AddPie(12, 0, "Cars", new FillEffect(Color.Red), new LineProperties())
pie.AddPie(42, 0, "Trains", new FillEffect(Color.Gold), new LineProperties())
pie.AddPie(56, 0, "Airplanes", new FillEffect(Color.Chocolate), new LineProperties())
pie.AddPie(23, 0, "Buses", new FillEffect(Color.Cyan), new LineProperties())
pie.LabelMode = PieLabelMode.Spider
pie.Appearance.FillMode = AppearanceFillMode.DataPoints
AddHandler chartControl1.MouseDown, AddressOf nChartControl1_MouseDown
End Sub 'MouseEventsUC_Load
.......
Private Sub chartControl1_MouseDown(ByVal sender As Object, ByVal e As System.EventArgs)
Dim hitTestResult As HitTestResult = nChartControl1.HitTest(e.X, e.Y)
if hitTestResult.ChartElement = ChartElement.DataPoint then
Dim chart As Chart = hitTestResult.Chart
Dim pie As PieSeries = CType(hitTestResult.Series, PieSeries)
for i As Integer = 0 to pie.Detachments.Count - 1
pie.Detachments(i) = 0
next
pie.Detachments(hitTestResult.DataPointIndex) = 10
chartControl1.Refresh()
end if
End Sub
.....
C#  

...
using Xceed.Chart.GraphicsCore;
using Xceed.Chart.Standard;
using Xceed.Chart;
.......
private void Form1_Load(object sender, System.EventArgs e)
{
Chart chart = (Chart)chartControl1.Charts[0];
chart.Depth = 25;
PieSeries pie = (PieSeries)chart.Series.Add(SeriesType.Pie);
pie.AddPie(12, 0, "Cars", new FillEffect(Color.Red), new LineProperties());
pie.AddPie(42, 0, "Trains", new FillEffect(Color.Gold), new LineProperties());
pie.AddPie(56, 0, "Airplanes", new FillEffect(Color.Chocolate), new LineProperties());
pie.AddPie(23, 0, "Buses", new FillEffect(Color.Cyan), new LineProperties());
pie.LabelMode = PieLabelMode.Spider;
pie.Appearance.FillMode = AppearanceFillMode.DataPoints;
chartControl1.MouseDown += new System.Windows.Forms.MouseEventHandler(this.chartControl1_MouseDown);
}
.......
private void chartControl1_MouseDown(object sender, System.Windows.Forms.MouseEventArgs e)
{
HitTestResult hitTestResult = chartControl1.HitTest(e.X, e.Y);
if (hitTestResult.ChartElement == ChartElement.DataPoint)
{
Chart chart = (Chart)(hitTestResult.Chart);
PieSeries pie = (PieSeries)(hitTestResult.Series);
for (int i = 0; i < pie.Detachments.Count; i++)
{
pie.Detachments[i] = 0;
}
pie.Detachments[hitTestResult.DataPointIndex] = 10;
chartControl1.Refresh();
}
}

Now let's take a closer look at the chartControl1_MouseDown function. The code first checks whether the user clicked on a data point object. If not, it does nothing. If yes, it obtains a reference to the PieSeries collection by using the properties in the HitTestResult object:

VB.NET  

Dim chart As Chart = hitTestResult.Chart
Dim pie As PieSeries = CType(hitTestResult.Series, PieSeries)
C#  

Chart chart = (Chart)(hitTestResult.Chart);
PieSeries pie = (PieSeries)(hitTestResult.Series);

This ensures that we'll access the proper chart in case the control displays multiple charts. Finally, it uses the DataPointIndex property to modify the detachment for the clicked pie.

 

 

Copyright Xceed Software Inc

Send Feedback