Using TRChart

TRChart provides the following chart elements which can be controlled by their corresponding properties and methods:

• the on-screen chart area
• the data window
• up to 16 labeled axes (x and y)
• captions
• various kinds of grids

TRChart stores all the graphics elements drawn on it in a data container. This ensures that these elements can be automatically redrawn if e.g. the coordinate system or the extents of the chart area are changed. Thus, you should not draw on the chart area using methods other than the built-in methods of TRChart.

These are the elements (also called items in the program code) which are currently available in TRChart :

• point marks
• lines
• short texts (max. 15 characters)
• filled rectangles
• framed rectangles
• text labels
• crosshairs
• labels
• ellipses
• 3D bars
• arrows
• data points with attached error bars

Each of these items has at least three implicit attributes which are either set by some method of TRChart or are derived from some class properties at run-time; the common attributes are the position of an element (in the real coordinate system of the associated chart layer), its color, and the number of the class it belongs to. The class numbers are initially set to the ClassDefault property and can be used to differentiate between groups of drawing entries. Graphic elements of some classes may be selectively hidden by setting the array property ClassVisible accordingly. Class numbers can also be used to restrict some operations to certain items in the drawing.

RChart offers a flexible way to draw differently scaled data in a common diagram: it allows to activate up to 16 independently scaled (both in x and y) layers which are plotted on top of each other. Each layer has two independent axes which may or may not be displayed. The properties of the axes are controlled by the array properties ScalePropsX and ScalePropsY. The first four axes are represented by the published properties Scale1X..Scale4X and Scale1Y..Scale4Y which can be accessed via the object inspector. The drawing always takes place in the active layer which is specified by the property ActiveLayer. You may switch off the visibility of a particular layer by setting the array property LayerVisibility. For scenarios where several layers has a common axis (e.g. several traces of an x-t-chart recording), you can couple the axes of arbitrary layers by setting the property JointLayers accordingly.

TRChart provides an efficient and easy-to-handle algorithm for labeling the axes. The inscription of the axes is automatically generated in a way that the scale ticks always are placed on multiples of the numbers 1, 2, and 5. This avoids an effect often seen in other packages which creates inscriptions like "-0.124 -0.001 0.122 0.245 0.368" instead of "-0.1 0.0 0.1 0.2 0.3". The user only has to specify the intended minimum number of scale ticks (properties ScalePropsX[].MinTicks and ScalePropsY[].MinTicks), and the bounds of the axes (ScalePropsX[].RangeLow, ScalePropsY[].RangeLow, ScalePropsX[].RangeHigh, ScalePropsY[].RangeHigh). As an alternative, the method AutoRange may be used to set the bounds of the chart axes such that all graphic elements are visible. In addition, the user may also create axes based on a TDateTime (see Delphi reference) variable, showing time and date in various user-definable formats. User-defined labels of the axes can be created by using the events OnScaleTickDrawn and OnScalesRendered. RChart offers several predefined layouts of the axes which can be set by setting the property StandardLayout.

TRChart provides a simple but efficient means to suppress flickering when drawing new items. By default, drawing on a chart is done in the off; the results must be explicitly copied to the visible screen window by calling the method ShowGraf. Of course, there are a few exceptions to this general rule: the chart is automatically redrawn when you change any properties which effect the appearance of the drawing (type of scaling, colors, grid, ...). In addition, the property AutoRedraw controls the automatic redrawing of the chart. If you add new data items without changing the set-up of the chart, you may use ShowGrafNewOnly instead of ShowGraf. This method updates only the new graphics elements and is thus much quicker than ShowGraf.

Basically, there are three ways to print the resulting charts: (1) You can use the method Print of the form where the chart is located. This is a quick and dirty method and produces a result which is usually not optimum. (2) The class TRChart provides a method PrintIt which has several advantages over the first approach: the output is scalable and can be forced to handle black and white printouts properly. (3) In order to mix hardcopies and text, or to place hardcopies at some special position on the paper, the user may resort to the method CopyToOpenPrinter. This method is the most flexible way of printing. In addition to printing a chart, the user may also copy the chart into the clipboard or store it as a Windows BMP file.

TRChart also provides a mouse interface in order to display the current position of the mouse cursor (in real-world chart coordinates of the active layer). The event OnMouseMoveInChart returns the mouse coordinates if the mouse moves within the chart area. It can be used to display the mouse position using any label or text component (the component TNumLab is well suited to this task, since it provides a flickerfree update of the position). Alternatively, you may use various events to add any kind of user defined graphics to the chart. The scales may also manipulated interactively by setting the property MouseAction accordingly. The array property MouseAffectsLayer controls which layers are affected by the mouse interaction.

Here is a sample framework for using TRChart :

1. set up the extents of the axes
2. initialize the drawing memory
3. draw the graph (in the off)
4. display the graph

In terms of Delphi source code this might look like this (note that the set-up of the ranges can also be performed within the object inspector):

  MyChart.SuppressPaint := TRUE;{ switch off automatic redrawing }
  MyChart.Scale1X.RangeLow := -1.2;        { range of chart area }
  MyChart.Scale1X.RangeHigh := 1.2;
  MyChart.Scale1Y.RangeLow := -1.5;
  MyChart.Scale1Y.RangeHigh := 1.5;
  MyChart.ClearGraf;                          { initialize chart }
  MyChart.MoveTo (0,0);                { initial cursor position }
  for i:=1 to 200 do                 { draw the chart in the off }
    MyChart.DrawTo (sin(i/9),sin(i/7));
  MyChart.SuppressPaint := FALSE;             { triggers repaint }

If you prefer to use C++ (Borland C++Builder) the corresponding code might look like this:

  MyChart->SuppressPaint = true;{ switch off automatic redrawing }
  MyChart->Scale1X->RangeLow = -1.2;       { range of chart area }
  MyChart->Scale1X->RangeHigh = 1.2;
  MyChart->Scale1Y->RangeLow = -1.5;
  MyChart->Scale1Y->RangeHigh = 1.5;
  MyChart->ClearGraf();                       { initialize chart }
  MyChart->MoveTo (0,0);               { initial cursor position }
  for (i=1; i<=200; i++)             { draw the chart in the off }
    {
    MyChart->DrawTo (sin(i/9),sin(i/7));
    }
  MyChart->SuppressPaint = false;             { triggers repaint }