Using TPolChart

The component TPolChart is an easy to use polar diagram component providing methods to draw various kinds of drawing elements in a polar coordinate system. In order to get a first impression of TPolChart try to run the sample program "poldiag". Please note that TPolChart is similar to TRChart in many respects, so that it should be easy to use it if you are familiar with TRChart.

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

• the on-screen chart area
• two labeled axes (radial and angular)
• various kinds of grids
• several crosshairs (both orthogonal and radial)

TPolChart 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 TPolChart.

The following elements (also called items in the program code) are currently available in TPolChart :

• point marks
• lines
• short texts (max. 15 characters)
• filled rectangles
• framed rectangles
• circles around the pole
• text labels
• crosshairs

The appearance as well as the extents of the chart can be affected by a number of properties, such as RangeLow, RangeHigh, LabelModeAngular, LabelModeRadial, AngleBtwRays, AngleOffset, DecPlaceRad, DecPlacePhi, GridStyleAngular, GridStyleRadial, MagFactor, and ScaleColor. The property UseDegrees determines whether the angular coordinates of the chart are interpreted as degrees or radians. User-defined labels of the axes can be created by using the events OnDataRendered and OnBeforeDrawScaleLabel.

TPolChart 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 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 TPolChart 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 screen copies 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.

TPolChart also provides a mouse interface in order to display the current position of the mouse cursor (in real-world chart coordinates). 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 the event OnDataRendered to add any kind of user defined graphics to the chart.

Here is a sample framework for using TPolChart :

1. set up the range and layout of the coordinate 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.RangeLow := 2;                   { range of chart area }
  MyChart.RangeHigh := 13.2; 

  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.ShowGraf;                   { show the chart on screen }

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

  MyChart->RangeLow = 2;                 { range of  chart area  }
  MyChart->RangeHigh = 13.2;
  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->ShowGraf();                { show the chart on screen }