TAChart Tutorial: Chart Tools

Introduction

Charts are powerful to display relationships between data. They get even more powerful if the user can interact with them, for example

• by zooming into a crowded series to display more details,
• by panning the visible viewport to other features,
• by reading values from the series or by measuring characteristic parameters of the plot.

The TAChart package is equipped with a powerful collection of tools to help creating interactive charts. In this tutorial, we want to show how to apply zooming and panning in your own programs, in another tutorial we will focus on data tools to analyze data interactively.

If you are not familiar with TAChart we recommend that you have a look at the Getting started tutorial. Of course, you must have some experience with Lazarus and FPC.

ChartTools have made some progress after the official version 1.0 of Lazarus has been released. Therefore, it may be advantageous to use the current trunk version from svn, otherwise some topics of this tutorial will not be available.

Preparation

We need a chart to play with. You can use any chart that you ever created for our exercises, but I'll be using here the simple chart of the Getting started tutorial.

Zooming and Panning - the easy way

Zooming

Zooming is very easy - you don't have to do anything to implement it since it is built into the heart of the chart component. You just have to drag a rectangle with the left mouse button down around the feature of interest that you want to see in detail. However, you should keep in mind that you have to drag the mouse from the top-left to the right-bottom corner of the rectangle to get the zoom effect. After you release the mouse button, the region is blown up to fill the entire chart. Easy.

You can repeat this procedure to zoom into the chart deeper and deeper.

If you want to restore the original viewport just click into the chart with the left button, or drag a rectangle in any -- except for the top-left to right-bottom -- direction.

Maybe, for some reason, you do not like this behavior. TChart has a property AllowZoom with which you can turn off the zooming capability. Beyond that, there is nothing else to control the default zooming action. But don't give up: A bit further down we will discuss the ChartTools, and they give you almost unlimited access to any interactive feature.

Panning

After you have zoomed into a chart you may want to shift the viewport a bit to find a better view. This operation is called "panning". Unfortunately, the released version of Lazarus (v1.0) does not have built-in panning capabilities. Only recently a default panning operation has been introduced into the trunk version of Lazarus. For this purpose, you hold down the right mouse button, the cursor transforms into a 4-arrow-shape to indicate that you can move the viewport around by dragging.

As with zooming you can restore the original viewport by clicking into the chart, or by dragging a rectangle in any direction, except from top-left to bottom-right. Note that you use the left mouse button for "un-panning" although you had used the right button for panning.

TChart currently does not have a property AllowPan to turn off panning. As we will see shortly, panning can be turned off also with ChartTools, so this is no real disadvantage.

Using chart tools

Basics

As you have seen, to add zooming and panning capabilities to your program can't be easier -- there's nothing to do, they are already there. But on the other hand, usage of the built-in routines is quite limited: zooming is only possible by using the left mouse button, panning by using the right mouse button; no mouse-wheel support; no vertical-only or horizontal-only zooming; no reading of data values, etc.

For more versatile user interaction a set of chart tools has been added to TAChart. All these tools inherit from TChartTool (there is another ancestor down along the hierarchy, TBasicChartTools, but this is not important here). Each tool is specialized to some specific action. There are two types of tools: Extent tools and data tools.

• Extent tools modifiy the extent of the chart -- this is the visible viewport -- i.e. they are responsible for zooming and panning.
  • for zooming:
    • TZoomDragTool allows zooming by dragging the mouse, just as was described above, but now with access to many parameters to adjust the behavior
    • TZoomClickTool zooms by a predefined factor after clicking with the mouse.
    • TZoomMouseWheelTool allows zooming by rotating the mouse wheel.
  • for unzooming:
    • there are no dedicated tools for unzooming, this feature is built into the tools used for zooming. For unzooming, you usually invert the parameter that defines the amount of zooming.
  • for panning:
    • TPanDragTool is specialized for panning the visible viewport by dragging with the mouse, as described above.
    • TPanClickTool allows to pan by clicking the mouse near the edge of the chart. Panning goes into the direction of that edge.
    • TPanMouseWheelTool is for panning by rotating the mouse wheel.
• Data tools give interactive access to data displayed in the series, or even allow to modify the data:
  • TDataPointClickTool identifies the data point and series onto which the mouse is clicked.
  • TDataPointDragTool allows to drag a data point by means of the mouse
  • TDataPointHintTool displays a hovering hint windows when the mouse is close enough to a data point
  • TDataPointCrosshairTool displays a crosshair when the mouse is sufficiently close to a data point:
  • TDataPointDistanceTool allows to measure the distance between data points.
• and, if nothing else fits your needs, TUserDefinedTool allows you to build your own tool according to your specific needs.

Alle these tools have a property called Shift containing a set of shift states that activate the tool. TShiftState is a fundamental LCL property and declared as follows:

  TShiftState = (ssShift, ssAlt, ssCtrl,
    ssLeft, ssRight, ssMiddle, ssDouble,
    // Extra additions
    ssMeta, ssSuper, ssHyper, ssAltGr, ssCaps, ssNum,
    ssScroll,ssTriple,ssQuad,ssExtra1,ssExtra2);

An example: If the tool's Shift contains ssCtrl and ssLeft then the tool becomes active when the user presses the CTRL key and left mouse button. Note that all conditions must be met, the tool does not activate if the left mouse button is pressed alone. Therefore, each tool must have its own set of unique shift values.

There is another condition that must be met for the tool to become active: Its property Enabled must be set to true, but this is the default setting. This property is useful when several tools share the same Shift combinations and are activated by some other code, for example by toolbar buttons.

Finally, all tools have in common a series of events that are fired before or after a key or mouse button has been pressed or released; in case of the mouse, there is also an event that fires before or after the mouse is moved. Usually, these chart tools work "out of the box", and these events are not needed. But they are necessary when some functionality is to be added.

Chart tools are collected by the TChartToolset component. This is the primary interface that you see in the component gallery. The ChartToolset components has to be assigned to the property Tools of the chart -- this step is easily forgotten and an explanation when tools do not work at all.

Here we want to finish that introduction to chart tools. Enough of theory! Let's practice.