VCL for PHP Charting components - Part 7 - Subproperties

By: David Intersimone

Abstract: Creating a VCL for PHP Charting component. This article is a reproduction of the blog post by Jose Leon, developer of Delphi for PHP

VCL for PHP Charting components - Subproperties

Sometimes, our components, need to publish properties that are grouped under a common category. The first example can be the Font property, which allows the user to specify all font attributes in a single property, like name, size, boldness, etc.

You could add all those properties to your component in an ungrouped fashion:

  • FontAlign
  • FontCase
  • FontColor
  • FontFamily
  • FontLineHeight
  • FontSize
  • FontStyle
  • FontVariant
  • FontWeight

But that will clutter the Object Inspector, just let’s imagine a component with several Font properties…

To allow you group such properties and create a better component interface, VCL for PHP provides you a way to create subproperties, keep reading.

Axis

In our chart component, we need to provide a way for the user to specify properties for the chart axis, the horizontal and the vertical one, we are going to do it, by creating a class for each axis.

To create a subproperty, that subproperty must be an object, and that object must be of a class that inherits from Persistent. This is required so the streaming system is able to read and write the properties of that object to an .xml.php file.

So, for the XAxis class, we have some properties to add:

  • Stroke
  • Color
  • TickHeight
  • GridColor
  • Offset
  • Steps
  • 3D
  • Labels
  • Vertical

Let’s write the code:

class XAxis extends Persistent

{

protected $_stroke = 1;

function getStroke() { return $this->_stroke; }

function setStroke($value) { $this->_stroke = $value; }

function defaultStroke() { return 1; }

protected $_color = "";

function getColor() { return $this->_color; }

function setColor($value) { $this->_color = $value; }

function defaultColor() { return ""; }

protected $_tickheight = 1;

function getTickHeight() { return $this->_tickheight; }

function setTickHeight($value) { $this->_tickheight = $value; }

function defaultTickHeight() { return 1; }

protected $_gridcolor = "";

function getGridColor() { return $this->_gridcolor; }

function setGridColor($value) { $this->_gridcolor = $value; }

function defaultGridColor() { return ""; }

protected $_offset = 0;

function getOffset() { return $this->_offset; }

function setOffset($value) { $this->_offset = $value; }

function defaultOffset() { return 0; }

protected $_steps = 1;

function getSteps() { return $this->_steps; }

function setSteps($value) { $this->_steps = $value; }

function defaultSteps() { return 1; }

protected $_3d = 0;

function get3D() { return $this->_3d; }

function set3D($value) { $this->_3d = $value; }

function default3D() { return 0; }

protected $_labels = array();

function getLabels() { return $this->_labels; }

function setLabels($value) { $this->_labels = $value; }

function defaultLabels() { return array(); }

protected $_vertical = 0;

function getVertical() { return $this->_vertical; }

function setVertical($value) { $this->_vertical = $value; }

function defaultVertical() { return 0; }

}

Specify an owner

For the streaming system to work, it also needs to know the owner of such object, in our case, the owner of the XAxis object is going to be the chart itself, but Persistent lacks of a constructor in which we can specify the owner. So simply adding a public field and overriding the readOwner() method of Persistent, will do the trick:

class XAxis extends Persistent

{

public $_control = null;

function readOwner()

{

return($this->_control);

}

}

And we must not forget, when creating this object, to assign the field to the right owner.

Creating the XAxis property

Now is time to add the XAxis property to the OpenChart class, this is done in the same way other properties:

protected $_xaxis = null;

function getXAxis() { return $this->_xaxis; }

function setXAxis($value) { if(is_object($value)) $this->_xaxis = $value; }

But just assign the property if the value we want to set is an object. And now we are going to create the object property in the component constructor:

class OpenChart extends Control

{

function __construct($aowner = null)

{

parent::__construct($aowner);

//Creates the axis properties

$this->_xaxis = new XAxis();

$this->_xaxis->_control = $this;

}

}

And that’s it, now is time to uninstall the package and install again by toggling the check box on Component | Packages dialog, and here is the result:

Hide image

We will need to repeat the process with the YAxis, we decided not to use a base class for the axis, but a different class, because there are several properties that differ from each other, but that would be another option.

Registering property editors for subproperties

We can also specify which property editors are going to be attached to the subproperties, this is done in the same way, but we have to qualify the subproperties with a dot (.):

registerPropertyEditor("OpenChart","XAxis.Color","TSamplePropertyEditor","native");

registerPropertyEditor("OpenChart","XAxis.GridColor","TSamplePropertyEditor","native");

registerPropertyEditor("OpenChart","XAxis.Labels","TStringListPropertyEditor","native");

registerBooleanProperty('OpenChart','XAxis.Offset');

registerBooleanProperty('OpenChart','XAxis.Vertical');

Hope you like it!

Server Response from: ETNASC03