Difference between revisions of "TAChart Tutorial: Chart Tools"

From Lazarus wiki
(Chapter on chart tools started)
(Add description of Shift and Enabled)
Line 60: Line 60:
 
** [[TAChart_documentation#Data_point_distance_tool|TDataPointDistanceTool]] allows to measure the distance between data points.
 
** [[TAChart_documentation#Data_point_distance_tool|TDataPointDistanceTool]] allows to measure the distance between data points.
 
* and, if nothing else fits your needs, [[TAChart_documentation#User_defined_tool|TUserDefinedTool]] allows you to build your own tool according to your specific needs.
 
* and, if nothing else fits your needs, [[TAChart_documentation#User_defined_tool|TUserDefinedTool]] allows you to build your own tool according to your specific needs.
 +
 +
Alle these tools have a property called <code>Shift</code> containing a set of shift states that activate the tool. <code>TShiftState</code> is a fundamental LCL property and declared as follows:
 +
 +
<source>
 +
  TShiftState = (ssShift, ssAlt, ssCtrl,
 +
    ssLeft, ssRight, ssMiddle, ssDouble,
 +
    // Extra additions
 +
    ssMeta, ssSuper, ssHyper, ssAltGr, ssCaps, ssNum,
 +
    ssScroll,ssTriple,ssQuad,ssExtra1,ssExtra2);
 +
</source>
 +
 +
An example: If the tool's <code>Shift</code> contains <code>ssCtrl</code> and <code>ssLeft</code> then the tool becomes active when 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 <code>shift</code> values.
 +
 +
There is another condition that must be met for the tool to become active: Its property <code>Enabled</code> must be set to <code>true</code>, but this is the default setting. This property is useful when several tools share the same <code>Shift</code> combinations and are activated by some other code, for example by toolbar buttons.
 +
declared in  efines the "shift states" that have to be activeThe tools are activated when
  
 
=== Tools for zooming ===
 
=== Tools for zooming ===

Revision as of 13:51, 6 October 2012

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.

tachart getting started step6.png

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.

ZoomPan01.png ZoomPan02.png

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.

ZoomPan03.png

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:
  • 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 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. declared in efines the "shift states" that have to be activeThe tools are activated when

Tools for zooming

Tools for panning

Using the TChartNavPanel and the TChartNavScrollbar

Some background on Extents

A combined zoom/drag tool