diff options
author | Kore Nordmann <github@kore-nordmann.de> | 2008-08-27 13:00:21 +0000 |
---|---|---|
committer | Kore Nordmann <github@kore-nordmann.de> | 2008-08-27 13:00:21 +0000 |
commit | 4a04cda9277e5cd089007ee3340d571e3217f20a (patch) | |
tree | 4d2db7d76ca0aa6eda2d4200383609cbddc2981f | |
parent | cc24ba1a3e2bb75ce751a7ec72d140a6582ecf2c (diff) | |
download | zetacomponents-graph-4a04cda9277e5cd089007ee3340d571e3217f20a.zip zetacomponents-graph-4a04cda9277e5cd089007ee3340d571e3217f20a.tar.gz |
- Enhanced chart element documentation
-rw-r--r-- | src/datasets/property/axis.php | 6 | ||||
-rw-r--r-- | src/datasets/property/boolean.php | 8 | ||||
-rw-r--r-- | src/datasets/property/color.php | 6 | ||||
-rw-r--r-- | src/datasets/property/integer.php | 6 | ||||
-rw-r--r-- | src/datasets/property/string.php | 6 | ||||
-rw-r--r-- | src/element/axis.php | 69 | ||||
-rw-r--r-- | src/element/background.php | 35 | ||||
-rw-r--r-- | src/element/legend.php | 41 | ||||
-rw-r--r-- | src/element/text.php | 28 | ||||
-rw-r--r-- | src/exceptions/flash_bitmap_type.php | 4 | ||||
-rw-r--r-- | src/interfaces/axis_label_renderer.php | 3 | ||||
-rw-r--r-- | src/interfaces/dataset_property.php | 30 | ||||
-rw-r--r-- | src/interfaces/element.php | 64 |
13 files changed, 293 insertions, 13 deletions
diff --git a/src/datasets/property/axis.php b/src/datasets/property/axis.php index f813dd0..d5c0768 100644 --- a/src/datasets/property/axis.php +++ b/src/datasets/property/axis.php @@ -10,6 +10,12 @@ /** * Class for axis properties of datasets * + * This class is used to store properties for datasets, which should be + * validated as objects extending the ezcGraphChartElementAxis class. + * + * For a basic usage example of those dataset properties take a look at the API + * documentation of the ezcGraphDataSetProperty class. + * * @version //autogentag// * @package Graph */ diff --git a/src/datasets/property/boolean.php b/src/datasets/property/boolean.php index 6a046e9..24c92f6 100644 --- a/src/datasets/property/boolean.php +++ b/src/datasets/property/boolean.php @@ -8,7 +8,13 @@ * @license http://ez.no/licenses/new_bsd New BSD License */ /** - * Class for integer properties of datasets + * Class for boolean properties of datasets + * + * This class is used to store properties for datasets, which should be + * validated as boolean values. + * + * For a basic usage example of those dataset properties take a look at the API + * documentation of the ezcGraphDataSetProperty class. * * @version //autogentag// * @package Graph diff --git a/src/datasets/property/color.php b/src/datasets/property/color.php index 07a74d2..f20d5cb 100644 --- a/src/datasets/property/color.php +++ b/src/datasets/property/color.php @@ -10,6 +10,12 @@ /** * Class for color properties of datasets * + * This class is used to store properties for datasets, which should be + * validated as objects extending the ezcGraphColor class. + * + * For a basic usage example of those dataset properties take a look at the API + * documentation of the ezcGraphDataSetProperty class. + * * @version //autogentag// * @package Graph */ diff --git a/src/datasets/property/integer.php b/src/datasets/property/integer.php index 3652efd..27c5ba5 100644 --- a/src/datasets/property/integer.php +++ b/src/datasets/property/integer.php @@ -10,6 +10,12 @@ /** * Class for integer properties of datasets * + * This class is used to store properties for datasets, which should be + * validated as integer values. + * + * For a basic usage example of those dataset properties take a look at the API + * documentation of the ezcGraphDataSetProperty class. + * * @version //autogentag// * @package Graph */ diff --git a/src/datasets/property/string.php b/src/datasets/property/string.php index 2f21656..423b6aa 100644 --- a/src/datasets/property/string.php +++ b/src/datasets/property/string.php @@ -10,6 +10,12 @@ /** * Class for string properties of datasets * + * This class is used to store properties for datasets, which should be + * validated as string values. + * + * For a basic usage example of those dataset properties take a look at the API + * documentation of the ezcGraphDataSetProperty class. + * * @version //autogentag// * @package Graph */ diff --git a/src/element/axis.php b/src/element/axis.php index 4eace35..d9b615e 100644 --- a/src/element/axis.php +++ b/src/element/axis.php @@ -8,7 +8,74 @@ * @license http://ez.no/licenses/new_bsd New BSD License */ /** - * Basic axis class + * Class to represent an axis as a chart element + * + * Chart elements can be understood as widgets or layout container inside the + * chart. The actual transformation to images happens inside the renderers. + * They represent all elements inside the chart and contain mostly general + * formatting options, while the renderer itself might define additional + * formatting options for some chart elments. You can find more about the + * general formatting options for chart elements in the base class + * ezcGraphChartElement. + * + * The axis elements are special elements, as the border and background + * settings do not apply directly as axis axis are not put inside any boxes. + * The border value is reused for the color of the axis itself. + * + * Generally you should select the axis which matches your data best. By + * default a labeled x axis and a numeric y axis are used. If you are using + * date or time values on either axis, you should for example use a + * ezcGraphChartElementDateAxis. The currently available axis types are: + * + * - ezcGraphChartElementDateAxis + * - ezcGraphChartElementLabeledAxis + * - ezcGraphChartElementLogarithmicalAxis + * - ezcGraphChartElementNumericAxis + * + * Beside this there are several option to define the general layout of the + * axis labels. The $formatString option may be used to add additional text to + * each label on the axis, like a percent sign on the y axis: + * + * <code> + * $chart->xAxis->formatString = '%s %%'; + * </code> + * + * For more complex formatting operations for the label you may assign a custom + * formatter function to the property $labelCallback. + * + * The orientation of labels and their position relatively to the axis ticks is + * calcualted and rendered by the ezcGraphAxisLabelRenderer classes. You can + * choose between different axis label renderer, or create you own, and assign + * an instance of one to the property $axisLabelRenderer. Currently the + * available axis label renderers are: + * + * - ezcGraphAxisBoxedLabelRenderer + * + * Renders grid and labels like commonly used in bar charts, with the label + * between two grid lines. + * + * - ezcGraphAxisCenteredLabelRenderer + * + * Centers the label right next to a tick. Commonly used for labeled axis. + * + * - ezcGraphAxisExactLabelRenderer + * + * Put the label next to each tick. Commonly used for numeric axis. + * + * - ezcGraphAxisNoLabelRenderer + * + * Renders no labels. + * + * - ezcGraphAxisRadarLabelRenderer + * + * Special label renderer for radar charts. + * + * - ezcGraphAxisRotatedLabelRenderer + * + * Accepts a rotation angle for the texts put at some axis, which might be + * useful for longer textual labels on the axis. + * + * The label renderer used by default is different depending on the axis type. * * @property float $nullPosition * The position of the null value. diff --git a/src/element/background.php b/src/element/background.php index 9238215..f0772c5 100644 --- a/src/element/background.php +++ b/src/element/background.php @@ -8,25 +8,44 @@ * @license http://ez.no/licenses/new_bsd New BSD License */ /** - * Chart element representing the background. In addition to the standard - * background and border for chart elements it can draw an image on the chart - * background, and optionally repeat it. The position will be used for the - * repetition offset. + * Chart element representing the background. + * + * Chart elements can be understood as widgets or layout container inside the + * chart. The actual transformation to images happens inside the renderers. + * They represent all elements inside the chart and contain mostly general + * formatting options, while the renderer itself might define additional + * formatting options for some chart elments. You can find more about the + * general formatting options for chart elements in the base class + * ezcGraphChartElement. + * + * Additionally to common background and border for chart elements it can draw + * an image on the chart background, and optionally repeat it. The position + * will be used to define the start of the repetition. + * + * The repetition effects are modelled similar to the background settings in + * CSS. The example shows some common settings: * * <code> + * $chart = new ezcGraphPieChart(); + * $chart->data['example'] = new ezcGraphArrayDataSet( array( + * 'Foo' => 23, + * 'Bar' => 42, + * ) ); + * * $chart->background->image = 'background.png'; * - * // Image will be repeated horizontal at the top of the background + * // Image would be repeated horizontal at the top of the background * $chart->background->repeat = ezcGraph::HORIZONTAL; * $chart->background->postion = ezcGraph::TOP; * - * // Image will be placed once in the center + * // Image would be placed once in the center * $chart->background->repeat = ezcGraph::NO_REPEAT; // default; * $chart->background->position = ezcGraph::CENTER | ezcGraph::MIDDLE; * - * // Image will be repeated all over + * // Image would be repeated all over the chart, the position is irrelevant * $chart->background->repeat = ezcGraph::HORIZONTAL | ezcGraph::VERTICAL; - * // The position is not relevant here. + * + * $graph->render( 400, 250, 'legend.svg' ); * </code> * * @property string $image diff --git a/src/element/legend.php b/src/element/legend.php index 7063fda..17e2f53 100644 --- a/src/element/legend.php +++ b/src/element/legend.php @@ -10,6 +10,47 @@ /** * Class to represent a legend as a chart element * + * Chart elements can be understood as widgets or layout container inside the + * chart. The actual transformation to images happens inside the renderers. + * They represent all elements inside the chart and contain mostly general + * formatting options, while the renderer itself might define additional + * formatting options for some chart elments. You can find more about the + * general formatting options for chart elements in the base class + * ezcGraphChartElement. + * + * The legend chart element is used to display the legend of a chart. It can be + * deactivated by setting the legend to false, like: + * + * <code> + * $chart->legend = false; + * </code> + * + * The position of the legend in the chart can be influenced by the postion + * property, set to one of the position constants from the ezcGraph base class, + * like ezcGraph::BOTTOM, ezcGraph::LEFT, ezcGraph::RIGHT, ezcGraph::TOP. + * + * Depending on the position of the legend, either the $portraitSize (RIGHT, + * LEFT) or the $landscapeSize (TOP, BOTTOM) defines how much space will be + * aqquired for the legend. + * + * <code> + * $graph = new ezcGraphPieChart(); + * $graph->data['example'] = new ezcGraphArrayDataSet( array( + * 'Foo' => 23, + * 'Bar' => 42, + * ) ); + * + * // Format the legend element + * $graph->legend->background = '#FFFFFF80'; + * + * // Place at the bottom of the chart, with a height of 5% of the remaining + * // chart space. + * $graph->legend->position = ezcGraph::BOTTOM; + * $graph->legend->landscapeSize = .05; + * + * $graph->render( 400, 250, 'legend.svg' ); + * </code> + * * @property float $portraitSize * Size of a portrait style legend in percent of the size of the * complete chart. diff --git a/src/element/text.php b/src/element/text.php index 2fc219a..96cf80b 100644 --- a/src/element/text.php +++ b/src/element/text.php @@ -10,6 +10,34 @@ /** * Chart element to display texts in a chart * + * Chart elements can be understood as widgets or layout container inside the + * chart. The actual transformation to images happens inside the renderers. + * They represent all elements inside the chart and contain mostly general + * formatting options, while the renderer itself might define additional + * formatting options for some chart elments. You can find more about the + * general formatting options for chart elements in the base class + * ezcGraphChartElement. + * + * The text element can only be placed at the top or the bottom of the chart. + * Beside the common options it has only one additional option defining the + * maximum height used for the text box. The actaully required height is + * calculated based on the assigned text size. + * + * <code> + * $chart = new ezcGraphPieChart(); + * $chart->data['example'] = new ezcGraphArrayDataSet( array( + * 'Foo' => 23, + * 'Bar' => 42, + * ) ); + * + * $chart->title = 'Some pie chart'; + * + * // Use at maximum 5% of the chart height for the title. + * $chart->title->maxHeight = .05; + * + * $graph->render( 400, 250, 'title.svg' ); + * </code> + * * @property float $maxHeight * Maximum percent of bounding used to display the text. * diff --git a/src/exceptions/flash_bitmap_type.php b/src/exceptions/flash_bitmap_type.php index ed07baa..9aa30b3 100644 --- a/src/exceptions/flash_bitmap_type.php +++ b/src/exceptions/flash_bitmap_type.php @@ -8,8 +8,8 @@ * @license http://ez.no/licenses/new_bsd New BSD License */ /** - * Flash can only read non interlaced bitmaps. This exception is thrown for - * all other image types. + * Flash can only embed JPEGs and PNGs. This exception is thrown for * all + * other image types. * * @package Graph * @version //autogentag// diff --git a/src/interfaces/axis_label_renderer.php b/src/interfaces/axis_label_renderer.php index 4f925ee..9a5f064 100644 --- a/src/interfaces/axis_label_renderer.php +++ b/src/interfaces/axis_label_renderer.php @@ -11,6 +11,8 @@ * Abstract class to render labels and grids on axis. Will be extended to * make it possible using different algorithms for rendering axis labels. * + * Implements basic methods to render the grid and steps on a axis. + * * @property bool $majorStepCount * Count of major steps. * @property bool $minorStepCount @@ -435,4 +437,5 @@ abstract class ezcGraphAxisLabelRenderer extends ezcBaseOptions ezcGraphChartElementAxis $axis ); } + ?> diff --git a/src/interfaces/dataset_property.php b/src/interfaces/dataset_property.php index 3d427ff..ebc9a4c 100644 --- a/src/interfaces/dataset_property.php +++ b/src/interfaces/dataset_property.php @@ -10,6 +10,36 @@ /** * Abstract class for properties of datasets * + * This class is used to extends datasets with additional properties, and + * stores only non default values for each data point in a data set. + * + * The class is extended by property implementations including simple value + * validators, like: + * + * - ezcGraphDataSetAxisProperty + * - ezcGraphDataSetBooleanProperty + * - ezcGraphDataSetColorProperty + * - ezcGraphDataSetIntProperty + * - ezcGraphDataSetStringProperty + * + * The color property can for example be accessed in a chart like: + * + * <code> + * $graph = new ezcGraphLineChart(); + * $graph->data['example'] = new ezcGraphArrayDataSet( array( + * 'Foo' => 23, + * 'Bar' => 42, + * ) ); + * + * // Set color for all data points in this data set + * $graph->data['example']->color = '#a40000'; + * + * // Set different color for one special datapoint + * $graph->data['example']->color['Foo'] = '#2e3436'; + * + * $graph->render( 400, 200, 'test.svg' ); + * </code> + * * @version //autogentag// * @package Graph */ diff --git a/src/interfaces/element.php b/src/interfaces/element.php index 6c6c93e..21bc576 100644 --- a/src/interfaces/element.php +++ b/src/interfaces/element.php @@ -7,9 +7,71 @@ * @copyright Copyright (C) 2005-2008 eZ systems as. All rights reserved. * @license http://ez.no/licenses/new_bsd New BSD License */ + /** - * Class for basic chart elements + * Base class for chart elements + * + * The base class for chart elements. Chart elements can be understood as + * widgets or layout container inside the chart. The actual transformation to + * images happens inside the renderers. They represent all elements inside the + * chart and contain mostly general formatting options, while the renderer + * itself might define additional formatting options for some chart elments. + * + * Important chart elements for example are: + * + * - Chart title (ezcGraphChartElementText) + * - Chart legend (ezcGraphChartElementLegend) + * - The axis (ezcGraphChartElementNumericAxis, + * ezcGraphChartElementLogarithmicalAxis, ezcGraphChartElementLabeledAxis, + * ezcGraphChartElementDateAxis) + * - ... * + * The position of chart elements is defined in the $position property. The + * effect this has on the visual representation depends on the actual type of + * the chart element. + * + * Each chart element may be configured with options similar to CSS, used with + * HTML to define the general style of the repsective element: + * + * - $padding & $margin defne the distance of the border from inner elements / + * other chart elements. + * - $borderWidth & $border define the style of the border used around the + * chart element + * - $background defines the background color of the chart element. As always + * this may be a (semi-) transparent color. + * + * A typical example with some layout for the chart title element could look + * like: + * + * <code> + * $graph = new ezcGraphPieChart(); + * $graph->data['example'] = new ezcGraphArrayDataSet( array( + * 'Foo' => 23, + * 'Bar' => 42, + * ) ); + * + * // Set a title and format the title element + * $graph->title = 'Example formatted pie chart'; + * $graph->title->margin = 2; + * $graph->title->background = '#FFFFFF80'; + * $graph->title->border = '#FFFFFF'; + * $graph->title->borderWidth = 1; + * $graph->title->margin = 1; + * $graph->title->padding = 1; + * + * // Format the legend element + * $graph->legend->margin = 2; + * $graph->legend->background = '#FFFFFF80'; + * $graph->legend->border = '#FFFFFF'; + * $graph->legend->borderWidth = 1; + * $graph->legend->margin = 1; + * $graph->legend->padding = 1; + * + * $graph->background->background = '#888a85'; + * + * $graph->render( 400, 250, 'element.svg' ); + * </code> + * * @property string $title * Title of chart element. * @property ezcGraphColor $background |