Tutorial 4 - Axis Control

  Contents page 
  Previous | Next 


TeeChart Pro will automatically define all Axis labelling for you and offers plenty of flexibility to tailor any specific requirements you may have. New for version 4 are true Multiple Axes. These are available at runtime and offer countless possibilities and flexibility for Axis definition. See the section in this tutorial for more information.

Contents

Axes control - Key areas

Scales
Increment
Titles
Labels
Legend
Ticks
Axis position

Additional Axes

Copying axes
Multiple axes

Axis events

OnClickAxis
OnGetAxisLabel
OnGetNextAxisLabel


Axes control - Key areas

Scales

Axis scales are set automatically when you add Series data to your Chart. You may change from the defaults at design time or at runtime by using Axis properties.

Non date-time data
When adding a new Series, the Scales section of the Axis Page of the Chart Editor will show Automatic selected and other options greyed out. All values shown are numeric.
Date-time data
When a Series has datetime set to true (for that axis) on the Series, General page, the Scales section of the Axis Page of the Chart Editor will show Automatic selected and other options greyed out. Values are shown with Date-time values.

Automatic selects the best axis scale range to fit your data. If you turn Automatic off the Scales section will activate options and you can change Axis values. Important, remember to select the Axis that you wish to configure from the Axis radio buttons on the left of the page.

Add a Line Series to a Chart add a Command Button with the following code:

procedure TForm1.BitBtn1Click(Sender: TObject);
var t: Integer;
begin
 For t := 0 To 40 do
   With Series1 do
   begin
     Add(Int(Random(t)), '', clRed);
   end;
end;

Running the code in the button will draw a Line Series with 40 random values. Go to the Chart Editor at design time. Turn Automatic 'off' in the Bottom Axis scales section of the Axis page. You may now configure Maximum and minimum values for the Axis scale. Running the code again will show values depending on the values you configured for the Axis. Using the right button of of the mouse you may scroll to see the remaining values.

Setting axis scales by code
You can change the Maximum and Minimum at runtime using this code:

With Chart1.BottomAxis do
begin
  Automatic := False;
  Maximum := 36;
  Minimum ;= 5;
end;

You may set Axis scale Maximum and Minimum to automatic individually. eg:

With Chart1.BottomAxis do
begin
  AutomaticMaximum := True;
  Minimum := 5;
end;

Increment

You may tailor the intervals for the Axis. Select the Desired Increment combobox from the Scales section of the Axis page and add the increment you require. You may change this by code at runtime:

With Chart1.BottomAxis do
begin
  Increment := 20;
end;

Datetime data
If your data is datetime (You may set the data to datetime for your Series by going to the Series, General page), the Chart, Axis page, scales section will show datetime range. Select the from the range shown in the Desired Increment combobox.
add some sample data

For t := 1 To 25 do
  Series1.AddXY(EncodeDate(1998, 4, t), Random(t), '', clRed);

Change the Increment at runtime:

 Chart1.BottomAxis.Increment := DateTimeStep[dtOneWeek];
End With

See the Axis.ExactDateTime property for more information about date axis labelling.

Note

When changing axis label frequency, bear in mind that TeeChart will avoid label overlap according to the setting of the LabelsSeparation property. This means that if the label frequency is too high for the labels to fit, then TeeChart will allocate 'best fit'. Changing the label angle and label separation are 2 options that may help you fit the labels you require. See the Labels section and LabelsAngle property.

Titles

Titles are set in the Titles section of the Axis page. You may change the Title text for the Axis and its font. The angle may be selected from values 0, 90, 180, 270 degrees. For runtime see TChartAxisTitle Component.

Labels

Note

When changing axis label frequency, bear in mind that TeeChart will avoid label overlap according to the setting of the LabelsSeparation property. This means that if the label frequency is too high for the labels to fit, then TeeChart will allocate 'best fit'. Changing the label angle and label separation are 2 options that may help you fit the labels you require. See the LabelsAngle property.

Label formats
You may apply all standard number and date formats to Axis labels. The Axis page, Labels section contains the field "Values format". If your data is datetime the field name changes to "Date time format". In the Editor drag the help "?" icon onto the field to get a full listing of options. at runtime use:

Chart1.BottomAxis.AxisValuesFormat := '#,##0.00;(#,##0.00)';

//or for Datetime data

Chart1.BottomAxis.DateTimeFormat := 'dd/mmm/yy hh:mm:ss';

MultiLine labels
Axis labels can be displayed as multi-line text instead of a single line of text. Lines are separated using the TeeLineSeparator global constant, which by default is the carriage-return ascii character ( #13 ).

Example
//Add the Series labels in this way and apply 'Marks' as Axis labelling style
  Series1.Add( 1234, 'New'+TeeLineSeparator+'cars' , clRed );
  Series1.Add( 2000, 'Old'+TeeLineSeparator+'bicycles' , clBlue );
Example for DateTime labels:

The following will show the Bottom Axis labels in two lines of text, one showing the month and day, and the second line showing the year:
Feb-28 Mar-1 .. 1998 1998 ..

Series1.AddXY( EncodeDate( 1998,2,28 ), 100, '', clTeeColor );
Series1.AddXY( EncodeDate( 1998,3,1 ), 200, '', clTeeColor );
Series1.AddXY( EncodeDate( 1998,3,2 ), 150, '', clTeeColor );
Series1.XValues.DateTime := True;
Chart1.BottomAxis.DateTimeFormat := 'mm/dd hh:mm';   { <-- space }

If you set the LabelsMultiLine property to True, the axis will automatically split labels in lines where it finds a space.

Chart1.BottomAxis.LabelsMultiLine:=True;

Dividing the Label into two:

'mm/dd' for the first line
'hh:mm' for the second line


At run-time you can always split the label into lines programatically, using the OnGetAxisLabel event:

procedure TForm1.Chart1GetAxisLabel(Sender: TChartAxis;
  Series: TChartSeries; ValueIndex: Integer; var LabelText: String);
begin
  TeeSplitInLines(LabelText,' ');  
end;

The global "TeeSplitInLines" procedure converts all spaces in "LabelText" to line separators (returns).

The axis LabelsAngle property ( label rotation in degree angles 0, 90, 180 or 270 ), can also be used with multi-line axis labels.

Customising Axis labels
Further Label control may be obtained by using Axis events. The events permit you to activate/deactivate/change any individual Axis label. The following example modifies each Label, putting a textual phrase in front of the point index value.

//set LabelStyle to 'Mark' with the TChart editor or use:-
Chart1.BottomAxis.LabelsStyle := talMark;

//OnGetaxisLabel event
procedure TForm1.Chart1GetAxisLabel(Sender: TChartAxis;
  Series: TChartSeries; ValueIndex: Integer; var LabelText: String);
begin
 If Sender = Chart1.BottomAxis Then
   LabelText := 'Period ' + IntToStr(ValueIndex);
end;

See the section entitled Axis events for more information about customising labels with Axis events.

Ticks

   

There are 3 tick types. You may change the length, width and colour of each tick type. If the tick width is set to 1 (default) then you may change the style to one of several line types (dot, dash, etc.). Style will be ignored if width is greater than 1.

With Chart1.BottomAxis do
Begin
  TickLength := 7;
  Ticks.Color := clGreen;
  MinorTickCount := 10; //change number of minorticks between (major) Ticks
end;

Axis position

Axes have a property to modify where each axis is to be located. In this example, the axis is moved 50% of the total Chart width, so it is shown at the chart center:

Chart1.LeftAxis.PositionPercent := 50 ;


Additional Axes

Copying axes

TeeChart offers 5 axes to be associated with data Series, Left,Top,Bottom,Right and Depth. When you add a new series to a Chart you may define to which of the axes the Series should be related (Go to the Series tab, General page). You may repeat anyone (or all) of the 4 front axes at any place on the Chart by using the Axis Customdraw method.

You will find this example, called "CustAxisProject1", with the TeeChart sample code:

//fill the Series for this example with random data
procedure TForm1.BitBtn1Click(Sender: TObject);
Var t:integer;
begin
  For t := 0 To 20 do
    Series1.AddXY(t, Random(100) - Random(70), '', clRed);
end;

//Put this code in the OnBeforeDrawValues() event:
procedure TForm1.Series1BeforeDrawValues(Sender: TObject);
var posaxis :Integer;
begin
  With Chart1 do
  begin
    If LeftAxis.Maximum > 0 Then
    begin
      //When scrolling or on zoom always keep the gridlines enclosed in the Chart rectangle
      Canvas.ClipRectangle(ChartRect);
      //Always draw the 2nd vertical Axis at the middle point of the Chart
      posaxis := (ChartRect.Left) + (ChartRect.Right - ChartRect.Left) div 2;
      LeftAxis.CustomDraw(posaxis - 10, posaxis - 20, posaxis, True);
      //Draw the 2nd Horizontal axis at the level of "10" on the vertical axis
      posaxis := (LeftAxis.CalcYPosValue(10));
      BottomAxis.CustomDraw(posaxis + 10, posaxis + 40, posaxis, True);
      Canvas.UnClipRectangle;
    end;
  end;
end;
   Custom axes

In this example, TeeChart will plot the New axes, one horizontal and one vertical in the centre of your Chart. When you scroll the Chart (dragging with right mouse button), the new vertical axis will always remain central to the Chart, the new horizontal axis will move up and down with vertical scrolling. The new axes are exact copies of the default axes.


Multiple axes

Together with the PositionPercent and stretching properties, it’s possible to have unlimited axes floating anywhere on the chart. Scroll , zoom , and axis hit-detection also apply to custom-created axes. Creating extra axes is only allowed at run-time, as some few lines of code are necessary:

Example

procedure TForm1.BitBtn2Click(Sender: TObject);
Var MyAxis : TChartAxis ;
begin
  MyAxis := TChartAxis.Create(  Chart1 );
  Series2.CustomVertAxis := MyAxis;
  //You can modify any property of the new created axes, such as the axis color or axis title
  With MyAxis do
  begin
    Axis.Color:=clGreen ;
    Title.Caption := 'Extra axis' ;
    Title.Font.Style:=[fsBold];
    Title.Angle := 90;
    PositionPercent := 20; //percentage of Chart rectangle
  end;
end;

You are able to then position the new Axis in overall relation to the Chart by using the StartPosition and EndPosition properties.

StartPosition:=50;
EndPosition:=100;

These figures are expressed as percentages of the Chart Rectangle with 0 (zero) (in the case of a vertical Axis) being Top. These properties can be applied to the Standard Axes to create completely partitioned 'SubCharts' within the Chart.

Example
  With Chart1.LeftAxis do
  begin
    StartPosition:=0;
    EndPosition:=50;
    Title.Caption:='1st Left Axis';
    Title.Font.Style:=[fsBold];
  end;

The above 2 coded examples when combined with the following data:

var t: integer;
begin
  for t := 0 to 10 do
  begin
    Series1.AddXY(t,10+t,'',clTeeColor);
    if t > 1 then
      Series2.AddXY(t,t/2,'',clTeeColor);
  end;

...will show the following Chart:

   Multiple axes

Options are limitless! We advise caution when using Custom Axes as it is easy to start filling the screen with new axes and to lose track of which one you wish to manage !


Axis events

Axis events offer runtime flexibility to modify Axis Labels and offer interaction to the user on Axis Clicks.

OnClickAxis

See the OnClickAxis event.

Example

procedure TForm1.Chart1ClickAxis(Sender: TCustomChart; Axis: TChartAxis;
  Button: TMouseButton; Shift: TShiftState; X, Y: Integer);
begin
//Shows Axis point clicked when click on Bottom Axis.
If Axis = Chart1.BottomAxis Then
  ShowMessage('Clicked Bottom Axis at '  + FloatToStr(Chart1.BottomAxis.CalcPosPoint(X)));
end;

OnGetAxisLabel

Can be used to modify Axis Labels. See the OnGetAxisLabel event.

Example

procedure TForm1.Chart1GetAxisLabel(Sender: TChartAxis;
  Series: TChartSeries; ValueIndex: Integer; var LabelText: String);
begin
 If Sender = Chart1.BottomAxis Then
   Case StrToInt(FormatDateTime('mm', StrToDate(LabelText))) of
     1,2,3 : LabelText := '1st Qtr';
     4,5,6 : LabelText := '2nd Qtr';
   end;
end;

OnGetNextAxisLabel

Can be used to decide which Axis Labels should be displayed. See the OnGetNextAxisLabel event. You should use the Stop Boolean property to include/exclude Axis Labels.

Example

procedure TForm1.Chart1GetNextAxisLabel(Sender: TChartAxis;
  LabelIndex: Integer; var LabelValue: Double; var Stop: Boolean);
begin
 Stop:=False;
 If Sender = Chart1.BottomAxis Then
 begin
   if LabelValue>=5 then LabelValue:=LabelValue+5
                         else LabelValue:=5;
 end
 else
  Stop:=True;
end;

The above example will start labelling at '5' on the Bottom Axis labelling every 5 points. Other Axes' Labelling are unaffected.




© 1998 teeMach SL. All rights reserved.