Difference between revisions of "PHPTutorial6"

From Steema Software Reference Wiki
Jump to: navigation, search
(Series events)
 
Line 615: Line 615:
 
</center>
 
</center>
 
----
 
----
© 1998-2013 Steema Software SL. All rights reserved.
+
© 1998-{{CURRENTYEAR}} Steema Software SL. All rights reserved.

Latest revision as of 12:00, 29 April 2016

Tchart php.png

Contents page
Previous | Next


Tutorial 6 - Working with Series


Series Types

The Series component is the common ancestor for all Series types.

Series Class structure

As a little background on the structure of the TeeChart Type Library, here is an explanation of the Series classes and interfaces. The diagram below shows the relationship between TeeChart Series classes. All classes derive from the generic "Series" class and thus share "Series" methods. Several abstract Classes derive from Series (Custom3DSeries, CustomBarSeries and CircledSeries), these are highlighted in grey and their interfaces are not directly accessible for programming, their characteristics are inherited by their descendant Series types. All derived Series (in orange) are accessible in the TeeChart gallery for inclusion in your Chart. TeeChart Series, derived in this way, allow programmable access to the inherited methods via a common index structure (see example code later in this section).


Seriestree.png

TeeChart for PHP's internal Series Class hierarchy

You can create and add new and differing Series types to the same Chart.

//Add a series at runtime 
$area1 = new Area($tChart1->getChart()); $area1->fillSampleValues(4);
//Or
$area1 = new Area(); $tChart1->addSeries($area1); $area1->fillSampleValues(4);

An example of mixing different series classes in the same Chart would be to add a Area (Series(0)), Bar (Series(1)) and Line (Series(2)) Series to a Chart at design time.
All access a common index structure, the Chart's Series list. To work with the Series may look something like the below:

<?php
//Includes
require_once "../sources/TChart.php";

$tChart1 = new TChart(500,300);

$tChart1->getAspect()->setView3D(false);
//$tChart1->getPanel()->getGradient()->setVisible(false);
$tChart1->getPanel()->getGradient()->setEndColor(Color::GRAY());

//You could add the Series at runtime
$area1 = new Area($tChart1->getChart());
$bar1 = new Bar($tChart1->getChart());
$line1 = new Line($tChart1->getChart());
$line2 = new Line($tChart1->getChart());
//Use Series common properties
$tChart1->getSeries(0)->fillSampleValues(10);
$tChart1->getSeries(1)->fillSampleValues(10);
$tChart1->getSeries(2)->fillSampleValues(10);
$tChart1->getSeries(3)->fillSampleValues(10);

$area1->setColor(new Color(230,250,105));
$area1->getLinePen()->setVisible(false);

$bar1->setColor(new Color(100,155,255));
$bar1->getMarks()->setColor(Color::WHITE());
$bar1->getMarks()->getPen()->setVisible(false);
$bar1->getMarks()->getArrow()->setVisible(false);
$bar1->getPen()->setVisible(false);

$line1->setColor(Color::RED());
$line2->setColor(Color::FUCHSIA());

$bar1->setBarStyle(BarStyle::$PYRAMID);
//Modify Line specific properties
$line1->setStairs(true); //Set line to Stairs
$line1->getLinePen()->setColor(Color::BLUE()); //LineSeries bounding lines colour

$tChart1->render("chart1.png");
$rand=rand();
print '<img src="chart1.png?rand='.$rand.'">';
 ?>

Choosing a Series Type

Choosing a Series Type for a Chart will very much depend on your own requirements for the Chart. There are occasions, however, where the choice of Chart depends on which Series types support the number of input variables because of the high number of variables to plot. The following table shows the number of variables allowed by a sample of Series types.

Series Type

No. of variables

Datasource Properties

Basic

Line

2

XValues, YValues, XLabel

Fast Line

2

XValues, YValues, XLabel

Bar

2

XValues, YValues (called Bar), XLabel

HorizBar

2

XValues, YValues (called Bar), XLabel

Area

2

XValues, YValues, XLabel

Point

2

Xvalues, YValues, XLabel

Pie

1

PieValues, XLabel

Arrow

4

StartXValues, StartYValues, XLabel, EndXValues, EndYValues

Bubble

3

Xvalues, YValues, XLabel, RadiusValues

Gantt

3

StartValues, EndValues, AY (Y axis level), AXLabel (Label optionally shown on Y-axis or as mark)

ShapeSeries

4

X0 (Top), Y0 (Bottom), X1 (Left), Y1 (Right)

Extended

Bezier

2

XValues, YValues, XLabel

Candle

5

OpenValues, CloseValues, HighValues, LowValues, DateValues

Point3D

3

XValues, YValues, XLabel, ZValues

Volume

2

XValues, YValues (VolumeValues), XLabel

Labelling can be used to extend the value of a 2 variable Series Type. See the example below that uses 3 instances of the Bar Series type in the same Chart.

Example

Uses Bar Series types

Product code

Month

Quantity produced

10

Jan

300

10

Feb

325

10

Mar

287

12

Jan

175

12

Feb

223

12

Mar

241

14

Jan

461

14

Feb

470

14

Mar

455

In its simplest form, the data produces the following Chart, grouping the information by month:

Series1.gif

or (grouping by product):

Series2.gif

We have added new values to the table above (Stock).

Product code

Month

Quantity produced

Stock level

10

Jan

300

600

10

Feb

325

715

10

Mar

287

676

12

Jan

175

245

12

Feb

223

270

12

Mar

241

315

14

Jan

461

800

14

Feb

470

755

14

Mar

455

835

The values of stock are generally higher than those of monthly production so displaying them gives the following chart (2D this time). The Chart uses Line Series to differentiate Stocks.

Series3.gif

Adding data to a Series

Most Series types (other than Functions [Tutorial7.htm Tutorial 7]) use the Add and ADDXY methods for adding data. There are some exceptions, see the following table:



Series Type

Add Series points

Delete Series points

Standard Series types

Line

Series.Add
Series.AddXY
Series.AddNull
Series.AddNullXY
Series.AddArray
Series.AddText
Series.AddXYColor
Series.AddXYText
Series.AddXYTextColor
Series.AddYColor
Series.AddYText
Series.AddYTextColor

Series.Delete
Series.Clear

Horiz Line

Series.Add
Series.AddXY
Series.AddNull
Series.AddNullXY
Series.AddArray
Series.AddText
Series.AddXYColor
Series.AddXYText
Series.AddXYTextColor
Series.AddYColor
Series.AddYText
Series.AddYTextColor

Series.Delete
Series.Clear

Fast Line

Series.Add
Series.AddXY
Series.AddNull
Series.AddNullXY
Series.AddArray
Series.AddText
Series.AddXYColor
Series.AddXYText
Series.AddXYTextColor
Series.AddYColor
Series.AddYText
Series.AddYTextColor

Series.Delete
Series.Clear

Bar

Series.Add
Series.AddXY
Series.AddNull
Series.AddNullXY
Series.AddArray
Series.AddText
Series.AddXYColor
Series.AddXYText
Series.AddXYTextColor
Series.AddYColor
Series.AddYText
Series.AddYTextColor

Series.Delete
Series.Clear

HorizBar

Series.Add
Series.AddXY
Series.AddNull
Series.AddNullXY
Series.AddArray
Series.AddText
Series.AddXYColor
Series.AddXYText
Series.AddXYTextColor
Series.AddYColor
Series.AddYText
Series.AddYTextColor

Series.Delete
Series.Clear

Area

Series.Add
Series.AddXY
Series.AddNull
Series.AddNullXY
eries.AddArray
Series.AddText
Series.AddXYColor
Series.AddXYText
Series.AddXYTextColor
Series.AddYColor
Series.AddYText
Series.AddYTextColor

Series.Delete
Series.Clear

Point

Series.Add
Series.AddXY
Series.AddNull
Series.AddNullXY
eries.AddArray
Series.AddText
Series.AddXYColor
Series.AddXYText
Series.AddXYTextColor
Series.AddYColor
Series.AddYText
Series.AddYTextColor

Series.Delete
Series.Clear

Pie

Series.Add
Series.AddNull

Series.Delete
Series.Clear

Arrow

ArrowSeries.AddArrow
Series.AddNull
Series.AddNullXY

Series.Delete
Series.Clear

Bubble

BubbleSeries.AddBubble
Series.AddNull
Series.AddNullXY

Series.Delete
Series.Clear

Gantt

GanttSeries.AddGantt

Series.Delete
Series.Clear

Shape

ShapeSeries.X0,
ShapeSeries.Y0,
ShapeSeries.X1,
ShapeSeries.Y1]

RemoveSeries
(Each Shape is a unique Series)


Colour

Colour may be manually added for a point when adding the point.

Example

$tChart1->addSeries(new Bar());
$tChart1->getSeries(0)->addYTextColor(50,"oranges", Color::ORANGE());

Alternatively, you can allow TeeChart to allocate a colour. TeeChart will choose one of up to 19 unique and as yet unused colours for each new Series, or for each new Series point if ColorEach is set to true.
Example

$tChart1->getSeries(0)->setColorEach(true);
for($i = 0; $i < 19;   $i) {
$higher = $i   65;
$tChart1->getSeries(0)->add(rand(0,100));

Deleting data points from a Series

Use Series.Delete to delete a point from a Series.

Example

$tChart1->getSeries(0)->delete(7);
//(8th point - Points index start at zero)

Series->Clear clears all points from a Series.


Adding Null points to a Series

See the table Adding data to a Series for a list of Series Types that support the AddNull method. As the name suggests, AddNull will add a Null point to the Series allowing you to define a label for the point but leaving a break in the Series at that point. In the case of a Line Series, the last point before the break will not join to the first point after the break. See Series->AddNull.

example

$line = new Line($tChart1->getChart());
$line->addNull();

Mixing Series Types on a Chart

TeeChart Pro offers an empty Chart Canvas as a backdrop to data Series. That means that no Chart types are predefined. You define the Chart type you require as a mix of the Series Types that you wish to display. Due to the specialised nature of some Series types it is impractical to mix a few of the Series types together on a Chart. TeeChart helps you by greying out unsuitable Series types in the Chart Gallery when you arrive to add a new Series. There is no practical limit to the number of Series that you can put in one Chart.

Adding New Series

Add a Series using the Chart Editor (see [Tutorial1.htm Tutorial 1]) or by code.

Example

$bar1 = new Bar($tChart1->getChart());
$bar1->fillSampleValues(10);

Choose Axes for a Series

Series added to the Chart will automatically take the Left and Bottom axes as their reference axes. You may change the reference axes, there are 4 axes available, Top, Left, Bottom and Right. By code, changing the axes will look like this:

$bar1->setHorizontalAxis(HorizontalAxis::$TOP);
$bar1->setVerticalAxis(VerticalAxis::$RIGHT);

More than 1 Series may be associated with each Axis. TeeChart will decide the best scale to fit the Series matched to the Axis but you may change Axis scales yourself (See the Scales Axis Tutorial). Additional axes may be added, they will copy the scales associated with their counterparts from the first 4 axes (see the Tutorial section Additional axes).

Connecting Series

You may use a Series as the datasource for another Series. To do it by code see below:

$bar1 = new Bar($tChart1->getChart());
$bar1->fillSampleValues();
$line1 = new Line($tChart1->getChart());
$average1 = new Average();
$line1->setFunction($average1);
$line1->setDataSource($bar1);
$line1->checkDataSource();

See [Tutorial7.htm tutorial 7 - Working with Functions] for more information about how to use TeeChart functions.


Changing Series order

Changing series order is very easy. Series order will decide the relative display position of the Series in the Chart with respect to other Series. Use the SeriesList property or the ExchangeSeries method.

Example

$tChart1->exchangeSeries(0,1);� //Change Series(0) with Series(1) in the index order

*Note. After exchanging Series, the index for the Series will be changed. Thus the line of code above will perpetually interchange the 2 Series '0' and '1' if the code is rerun, as 0 becomes 1 and 1 becomes 0.

Setting a Series to 'Active=False' will hide the Series from the Chart but maintain its data content intact.

Series Value list

TeeChart Series store their values in a Valuelist accessible and modifiable via the TChartValueList component.

Example using Values

This code modifies the value of a BarSeries Bar according to the user's mouseclick.

Example

upDatePoint($valueIndex,$tChart1->getAxes()->getLeft()->calcPosPoint($e->Y));

Call the UpdatePoint Sub routine to modify the Bar's value:

private function upDatePoint($bar, $Y)
{ 
if($bar < $tChart1->getSeries(0)->getCount())
$tChart1->getSeries(0)->getYValues()->setValue($bar,Y);
}

Series events

The previous section introduces some use of Series events. This section shows some additional uses.

OnGetAxisLabel


In the case we want to change or add extra text to some or all of the axis labels, the OnGetAxisLabel event must be used, it allows to get the LabelText which is going to be displayed and modify it if required.

Here we can see an example of use  :

<?php
//Includes
include "../../../sources/TChart.php";

function handleLoad($sender, $args)
{
// print 'object '.get_class($sender).' loaded with '.count($args).' args!<br />';
$sender->getHeader()->setText("OnLoad Event");
}

function handleUnLoad($sender, $args)
{
 ?><br><br><?php
print 'object '.get_class($sender).' unloaded with '.count($args).' args!<br />';
 ?></br><?php
}

// Args contains axis, index order to be displayed, labelText
function handleGetAxisLabel($sender, $args)
{
// If it's going to display left axis labels
if ($args[0] === $sender->getAxes()->getLeft())
{
// if the left axis label value is bigger than 50 add extra character
if ((int)$args[2] > 50) {
$args[0]->getLabels()->labelText = $args[2].'-e';
}
}
else
{
if ($args[0] === $sender->getAxes()->getBottom())
{
if ((int)$args[2] < 4) {
// if value is less than 5 changes its labeltext
$args[0]->getLabels()->labelText = $args[2].'-u';
}
}
}
}

$handlers = new EventHandlerCollection();
$handlers->add(new EventHandler(new ChartEvent('OnLoad'),'handleLoad'));
$handlers->add(new EventHandler(new ChartEvent('OnUnload'),'handleUnload'));
$handlers->add(new EventHandler(new ChartEvent('OnGetAxisLabel'),'handleGetAxisLabel'));

$chart = new TChart(500,300, $handlers);

$chart->getAspect()->setView3D(false);

$points = new Points($chart->getChart());
$chart->addSeries($points);

$points->fillSampleValues();
$points->getPointer()->setHorizSize(10);
$points->getPointer()->setVertSize(5);
$points->setColorEach(true);

//$chart->getLegend()->getSymbol()->setWidth(10);

$chart->getLegend()->getSymbol()->setSquared(false);


$chart->render('chart.png');
$rand=rand();

print '<font face="Verdana" size="2">This Demo shows how to use the OnLoad, OnUnload and OnGetAxisLabel Events<p>';
print '<img src="chart.png?rand='.$rand.'">';
 ?>



PREVIOUS

NEXT


© 1998-2019 Steema Software SL. All rights reserved.