Working with Axes

Topics in this section:

Setting Axis scales

DateTime Axis

Logarithmic Axis

Inverted Axis

Axis Styles & Increment

Setting Axis scales

Chart components have five standard axes: LeftAxis, RightAxis, TopAxis, BottomAxis and DepthAxis. Each axis is an instance of TChartAxis component class. Unlimited Custom Axes may be added.

Axes are responsible of calculating pixel co-ordinates for Series points and to allow any valid range so scroll and zoom can be always performed. As new Series are inserted, or new points are added to the Series, Axes recalculate, by default, their Minimum and Maximum values.

You can turn off automatic recalculation of Axis scales by setting the Automatic property to false:

Chart1.LeftAxis.Automatic := False ;

Also, both the Axis Minimum and Axis Maximum values can optionally be independently automatic or not.

Chart1.LeftAxis.AutomaticMaximum := False ;
Chart1.LeftAxis.AutomaticMinimum := True ;

You can change Axis scales using the Minimum and Maximum properties:

With Chart1.LeftAxis do

    begin
        Automatic := False ;
        Minimum:=         0 ;
        Maximum:= 10000 ;
    end;

or using the Axis SetMinMax method:

Chart1.LeftAxis.SetMinMax( 0, 10000 );

DateTime Axis

Note:

An Axis contains DateTime scales when the associated Series components have XValues.DateTime or YValues.DateTime properties True. There is no DateTime property for Axis.

Changing scales in DateTime Axis is the same as for non-datetime values:

With Chart1.LeftAxis do    
    begin
         Automatic := False ;
        Minimum:=  EncodeDate( 1990, 3,16 ) ;
        Maximum:= EncodeDate( 2000, 5, 24 );
    end;

Logarithmic Axis

An Axis can be set to Logarithmic only if Axis Minimum and Maximum are greater than or equal to zero. This is the only difference between setting linear and logarithmic scales.

Note:

Axis Labels are not displayed in logarithmic increments. You can generate custom Axis Labels (see OnGetNextAxisLabel and OnGetAxisLabel events and the Axis Labels section in this Topic).

Inverted Axis

An Axis can be Inverted so Axis Minimum and Maximum are swapped. We suggest you use Inverted:=True as little as possible as it can give misleading results due to its (normally) rarity of use.

Axis Styles & Increment

Axis can be displayed in several ways, with tick lines or without,

with grids or without, with Labels or without, and you can customise all formatting properties such as colours, fonts and pen styles. The Axis Increment property controls the number of grid lines and labels and the distance between them.

By default it’s zero, meaning Axis will automatically calculate the Labels increment. Setting the Axis Increment property is independent of setting Axis scales. You can have automatic Axis Maximum and Minimum and a fixed Increment.

The Increment property grows automatically until all Axis Labels can be displayed. If you don’t want this automatic feature, set the Axis LabelsSeparation to zero:

Chart1.LeftAxis.LabelsSeparation :=  0 ;

Warning:

When LabelsSeparation is zero, no checking is performed against

labels size, so you must take care labels will not overlap each other.

The following code sets the vertical Axis Increment to 30:

Series1.Clear;
Series1.AddArray( [ 20, 50, 120 ] );
Chart1.LeftAxis.Increment:= 30;

By default, the first Axis label starts at nearest Increment. Setting RoundFirstLabel to False makes labels to start at Axis Maximum:

Chart1.LeftAxis.RoundFirstLabel := False ;

DateTime Increment

Use the predefined DateTimeStep array of constants to determine the Axis Increment on DateTime axis:

Chart1.BottomAxis.Increment := DateTimeStep[ dtOneMonth ] ;

And set the ExactDateTime property to True if you want Axis Labels to be at exact datetime boundaries, for example at 1^st day of month.

Chart1.BottomAxis.ExactDateTime := True;

Note:

Logarithmic axis use the Increment property as linear.

Grid lines

Axis Grid lines are displayed at each Increment position, or at each Axis Label position. The Axis TickOnLabelsOnly property controls this feature:

Chart1.BottomAxis.TickOnLabelsOnly := False ;

Axis Labels

There are several Axis labelling styles. The Axis LabelStyle property control axis labelling modes:

Chart1.BottomAxis.LabelStyle := talValue ;

Possible values are:

Width1Width3Width1041Width3Width5418talValue	Labels display Axis scalesWidth1Width3Width1041Width3Width5418
Width1Width3Width1041Width3Width5418talMark	Labels display Series Point MarksWidth1Width3Width1041Width3Width5418
talText	Labels display Series XLabelsWidth1Width3Width1041Width3Width5418
talNone	No labels displayedWidth1Width3Width1041Width3Width5418
Width1Width3Width1041Width3Width5418talAuto	Style is automatically calculatedWidth1Width3Width1041Width3Width5418

When LabelStyle is talText, TeeChart will set it automatically to talValue if Series have no XLabels.

For talMark and talText styles, axis labels are displayed exactly at Series point positions, thus not using the axis Increment property.

You can customise labels text by using the OnGetAxisLabel event:

procedure TForm1.Chart1GetAxisLabel(Sender: TChartAxis;
  Series: TChartSeries; ValueIndex: Integer; var LabelText: String);
begin
      if Sender=Chart1.LeftAxis then
          if ValueIndex < 2 then LabelText :=’’ ;
end;

The OnGetNextAxisLabelEvent allows you to define where you want the Labels to appear. In this example, we want the Vertical Left Axis to show labels only for positive values, starting at zero and with 250 label increment.

procedure TAxisLabelsForm.Chart1GetNextAxisLabel(Sender: TChartAxis;
    LabelIndex: Integer; var LabelValue: Double; var Stop: Boolean);
  begin
    if Sender=Chart1.LeftAxis then
    Begin
      if LabelValue>=250 then LabelValue:=LabelValue+250
                         else LabelValue:=250;
    End;

    { we want more labels !! }
    Stop:=False;
  end;

The following example plots only the specified 3 Labels on the Left Axis then stops plotting Labels for that Axis:

procedure TForm1.Chart1GetNextAxisLabel(Sender: TChartAxis;
  LabelIndex: Integer; var LabelValue: Double; var Stop: Boolean);
begin
    if Sender=Chart1.LeftAxis then
    Begin
      Stop:=False;
      Case LabelIndex of
         0:  LabelValue:=50;
         1:  LabelValue:=80;
         2:  LabelValue:=110;
         else Stop:=True;
      end;

    End;
end;

CustomDraw (Axis)

CustomDraw adds more axes to your Chart - As many as you wish. CustomDraw adds an axis as a ‘copy’ of an existing axis at a new location. CustomDraw axes are not Custom Axes, they are copies of the original Standard Axes at a (normally) different location.

The following example populates a line Series with random data. And creates 2 additional axis. There are 3 configurable locations PosLabels, PosTitle and PosAxis to place, respectively, the labels, title and the axis. The last parameter, GridVisible , which is boolean, defines whether to extend the axis grid to the new axis.

procedure TForm1.FormCreate(Sender: TObject);
var
   t:integer;
begin
     Series1.XValues.DateTime := False;
     Chart1.BottomAxis.Increment:=0;
     For t:= -10 to 10 do
         Series1.addXY(t,Random(100),'', clTeeColor);
end;

procedure TForm1.Series1AfterDrawValues(Sender: TObject);
var posaxis,percent: Integer;
begin
  percent:=50;
  With DBChart1 do
  begin
    
    PosAxis:=ChartRect.Left+Trunc(ChartWidth*Percent/100.0);
   LeftAxis.CustomDraw(posaxis-10,posaxis-40,posaxis,True);
        PosAxis:=ChartRect.Top+Trunc(ChartHeight*Percent/100.0);
       BottomAxis.CustomDraw(posaxis+10,posaxis+40,posaxis,True);

  end;
end;

Custom Axes

With Chart Editor

Custom Axes may be added and configured at design time using the Chart Editor. Basic steps to bear in mind:

On Chart Editor Axis page use the “+” button to add an Axis
The new Axis is vertical with Left sided Labels by default. Go to the Position tab to optionally set it to Horizontal and to set the Labels to the other side (Right or Top depending on whether Vertical or Horizontal axis)
Configure all Axis characteristics as per any Standard Axis. Important feature, as with Standard Axes is the Position tab that allows you to move and redimension the Axis to anywhere on the Chart
The Custom Axis must be associated with one or more Series. Go to the Series General tab and select the Axis for the Series

By Code

The following code adds 2 Axes, vertical and horizontal and associates them to a Series. The axes will scale by default to best fit the data to the Chart, so after adding the Series then adding the custom axes you will note that the Custom Axes scale is (most likely, depending on data) different to the Standard Axis scale. To test the following code, start a new project, add a TChart to a Form and a Bitmap Button, add 2 Series to the Chart with the Chart Editor, then paste in the following code:

procedure TForm1.FormCreate(Sender: TObject);
begin
  Series1.FillSampleValues(10);
  Series2.FillSampleValues(10);
end;

procedure TForm1.BitBtn1Click(Sender: TObject);
var
 tmpVertAxis: TChartAxis;
 tmpHorizAxis: TChartAxis;
begin
  {Add vertical Axis}
  Chart1.CustomAxes.Add;
  tmpVertAxis:=Chart1.CustomAxes[0];
  tmpVertAxis.PositionPercent:=50;
  Series1.CustomVertAxis:=tmpVertAxis;

  {Add horizontal Axis}
  Chart1.CustomAxes.Add;
  tmpHorizAxis:=Chart1.CustomAxes[1];
  tmpHorizAxis.Horizontal:=True;
  tmpHorizAxis.Axis.Color:=clGreen;
  tmpHorizAxis.PositionPercent:=50;
  Series1.CustomHorizAxis:=tmpHorizAxis;
end;

The Custom Axes may be accessed via the Chart.CustomAxes list.