From cc24ba1a3e2bb75ce751a7ec72d140a6582ecf2c Mon Sep 17 00:00:00 2001 From: Kore Nordmann Date: Wed, 20 Aug 2008 11:10:02 +0000 Subject: - More documentation improvements # There is still some way to go... --- docs/img/tutorial_chart_font_configuration.svg.png | Bin 0 -> 22368 bytes docs/tutorial.txt | 14 +++- .../tutorial/tutorial_chart_font_configuration.php | 29 +++++++ src/math/boundings.php | 4 + src/math/rotation.php | 9 +++ src/math/transformation.php | 15 +++- src/math/translation.php | 9 +++ src/math/vector.php | 7 ++ src/options/driver.php | 17 ++++- src/options/flash_driver.php | 4 + src/options/font.php | 84 ++++++++++++--------- src/options/line_chart.php | 11 +++ src/options/pie_chart.php | 8 ++ src/options/renderer.php | 25 ++++++ src/options/renderer_3d.php | 4 + src/structs/context.php | 16 ++++ src/structs/coordinate.php | 6 ++ src/structs/step.php | 7 ++ 18 files changed, 229 insertions(+), 40 deletions(-) create mode 100644 docs/img/tutorial_chart_font_configuration.svg.png create mode 100644 docs/tutorial/tutorial_chart_font_configuration.php diff --git a/docs/img/tutorial_chart_font_configuration.svg.png b/docs/img/tutorial_chart_font_configuration.svg.png new file mode 100644 index 0000000..704557d Binary files /dev/null and b/docs/img/tutorial_chart_font_configuration.svg.png differ diff --git a/docs/tutorial.txt b/docs/tutorial.txt index fc862f1..e6d5126 100644 --- a/docs/tutorial.txt +++ b/docs/tutorial.txt @@ -449,8 +449,7 @@ Chart elements ============== The chart elements all extend ezcGraphChartElement. Each of the elements can be -configured independently. A default chart consists of -the following elements: +configured independently. A default chart consists of the following elements: - title - background @@ -474,7 +473,16 @@ for each chart element. The solution is that you can modify the global font configuration by accessing $graph->options->font. This takes effect on all chart elements unless you intentionally access the font configuration of an individual chart -element. The following section shows an example of this. +element. The following example shows how this works. + +.. include:: tutorial/tutorial_chart_font_configuration.php + :literal: + +The output of the example shows, that all texts are using a serif font, while +the title still stays with the default sans-serif font. + +.. image:: img/tutorial_chart_font_configuration.svg.png + :alt: Font configuration in pie chart The chart title --------------- diff --git a/docs/tutorial/tutorial_chart_font_configuration.php b/docs/tutorial/tutorial_chart_font_configuration.php new file mode 100644 index 0000000..a564f62 --- /dev/null +++ b/docs/tutorial/tutorial_chart_font_configuration.php @@ -0,0 +1,29 @@ +palette = new ezcGraphPaletteEzBlue(); +$graph->title = 'Access statistics'; + +// Set the maximum font size to 8 for all chart elements +$graph->options->font->maxFontSize = 8; + +// Set the font size for the title independently to 14 +$graph->title->font->maxFontSize = 14; + +// The following only affects all elements except the // title element, +// which now has its own font configuration. +$graph->options->font->name = 'serif'; + +$graph->data['Access statistics'] = new ezcGraphArrayDataSet( array( + 'Mozilla' => 19113, + 'Explorer' => 10917, + 'Opera' => 1464, + 'Safari' => 652, + 'Konqueror' => 474, +) ); + +$graph->render( 400, 150, 'tutorial_chart_font_configuration.svg' ); + +?> diff --git a/src/math/boundings.php b/src/math/boundings.php index 825700f..f88f4b2 100644 --- a/src/math/boundings.php +++ b/src/math/boundings.php @@ -14,6 +14,10 @@ * Currently only works with plane rectangular boundings, should be enhanced by * rotated rectangular boundings. * + * This class is only used internally to represent space which is used by + * certain obejcts on the drawing plane, or which free space is still + * available. + * * @version //autogentag// * @package Graph * @access private diff --git a/src/math/rotation.php b/src/math/rotation.php index bbc4f1e..12ddd44 100644 --- a/src/math/rotation.php +++ b/src/math/rotation.php @@ -11,6 +11,15 @@ /** * Class to create rotation matrices from given rotation and center point * + * Three dimensional matrices (3x3) may be used to specify transformation of + * points, vectors and complexer structures in a two dimensional cartesian + * coordinate system. For more details have a look here: + * http://en.wikipedia.org/wiki/Transformation_matrix + * + * This class implements a convenient interface to create matrixes to rotate + * elements. This matrix may be combined with other transformation matrices, as + * usual. + * * @version //autogentag// * @package Graph * @access private diff --git a/src/math/transformation.php b/src/math/transformation.php index 78b95f1..a1ed70b 100644 --- a/src/math/transformation.php +++ b/src/math/transformation.php @@ -9,8 +9,19 @@ * @access private */ /** - * Class defining transformations like scaling and rotation by a - * 3x3 transformation matrix for |R^2 + * Class defining transformations + * + * Three dimensional matrices (3x3) may be used to specify transformation of + * points, vectors and complexer structures in a two dimensional cartesian + * coordinate system. For more details have a look here: + * http://en.wikipedia.org/wiki/Transformation_matrix + * + * There are some classes extending this basic tranformation class, to + * give you more convinient access to the creation of such transformation + * matrices, which are: + * + * - ezcGraphRotation (rotations of objects) + * - ezcGraphTranslation (moving of objects) * * @version //autogentag// * @package Graph diff --git a/src/math/translation.php b/src/math/translation.php index ca22063..a9b1c3c 100644 --- a/src/math/translation.php +++ b/src/math/translation.php @@ -11,6 +11,15 @@ /** * Class creating translation matrices from given movements * + * Three dimensional matrices (3x3) may be used to specify transformation of + * points, vectors and complexer structures in a two dimensional cartesian + * coordinate system. For more details have a look here: + * http://en.wikipedia.org/wiki/Transformation_matrix + * + * This class implements a convenient interface to create matrixes to move + * elements. This matrix may be combined with other transformation matrices, as + * usual. + * * @version //autogentag// * @package Graph * @access private diff --git a/src/math/vector.php b/src/math/vector.php index 9415bca..c34b34d 100644 --- a/src/math/vector.php +++ b/src/math/vector.php @@ -11,6 +11,13 @@ /** * Represents two dimensional vectors * + * This class is internally used to represent vectors for geometric calculation + * in the two dimensional cartesian coordinate system. + * + * Vectors are an extension of the basic coordinate class, and add methods to + * calculate the length of a vector, perform various operations on angles, like + * rotations and the calculation of angles between two vectors. + * * @version //autogentag// * @package Graph * @access private diff --git a/src/options/driver.php b/src/options/driver.php index 5253f25..80e2025 100644 --- a/src/options/driver.php +++ b/src/options/driver.php @@ -10,6 +10,15 @@ /** * Class containing the basic driver options. * + * Most of the options of the driver class, like the width, height and font are + * set internally by the driver and not really relevant to the user of driver + * classes. You can configure how strings are automatically shortened, together + * with the postfix, which is appended to shortened strings, like the following + * example shows. + * + * Configuration options, which special to the actual drivers are configured in + * the driver specific extensions of this option class. + * * * require_once 'tutorial_autoload.php'; * @@ -25,6 +34,8 @@ * 'Konqueror' => 474, * ) ); * + * // Do not shorten strings automatically if they do not fit in the assigned + * // space with the minimum font size. * $graph->driver->options->autoShortenString = false; * * $graph->render( 400, 150, 'tutorial_chart_title.svg' ); @@ -41,9 +52,13 @@ * @property int $font * Font used in the graph. * @property bool $autoShortenString - * Automatically shorten string if it does not fit into a box + * Automatically shorten string if it do not fit into the available + * space, even with the minimum font size used. Deactivating this + * setting will result in ezcGraphFontRenderingException exceptions, + * informing you about the actual string which did not fit. * @property string $autoShortenStringPostFix * String to append to shortened strings, if there is enough space + * left for the postfix. * * @version //autogentag// * @package Graph diff --git a/src/options/flash_driver.php b/src/options/flash_driver.php index 8d34c3f..9bf24b4 100644 --- a/src/options/flash_driver.php +++ b/src/options/flash_driver.php @@ -10,6 +10,10 @@ /** * Class containing the extended configuration options for the flash driver. * + * The flash driver can be configured to use a different circle resolution, as + * circles are only emulated in the flash driver, and to use a diffrent + * compression for the generated SWF files. + * * * $graph = new ezcGraphPieChart(); * $graph->title = 'Access statistics'; diff --git a/src/options/font.php b/src/options/font.php index 358659a..6d13eb0 100644 --- a/src/options/font.php +++ b/src/options/font.php @@ -10,32 +10,37 @@ /** * Class containing the options for font configuration. * - * Global font settings will only affect the font settings of chart elements - * until they were modified once. Form then on the font configuration of one - * chart element has been copied and can only be configured independently. + * We try to fulfill two goals regarding font configuration. First, there + * should be a single point to configure the fonts used for the text areas + * in the chart. On the other hand, it should be possible to configure + * the fonts independently for each chart element. + * + * The solution is that you can modify the global font configuration by + * accessing $graph->options->font. This takes effect on all chart + * elements unless you intentionally access the font configuration of an + * individual chart element. The following example shows, how this works. * * - * $graph = new ezcGraphPieChart(); - * $graph->palette = new ezcGraphPaletteEzBlue(); - * $graph->title = 'Access statistics'; - * - * $graph->options->font->name = 'serif'; - * $graph->options->font->maxFontSize = 12; - * - * $graph->title->background = '#EEEEEC'; - * $graph->title->font->name = 'sans-serif'; - * - * $graph->options->font->maxFontSize = 8; - * - * $graph->data['Access statistics'] = new ezcGraphArrayDataSet( array( - * 'Mozilla' => 19113, - * 'Explorer' => 10917, - * 'Opera' => 1464, - * 'Safari' => 652, - * 'Konqueror' => 474, - * ) ); - * - * $graph->render( 400, 150, 'tutorial_chart_title.svg' ); + * $graph = new ezcGraphPieChart(); + * $graph->title = 'Access statistics'; + * + * // Set the maximum font size to 8 for all chart elements + * $graph->options->font->maxFontSize = 8; + * + * // Set the font size for the title independently to 14 + * $graph->title->font->maxFontSize = 14; + * + * // The following only affects all elements except the // title element, + * // which now has its own font configuration. + * $graph->options->font->name = 'serif'; + * + * $graph->data['Access statistics'] = new ezcGraphArrayDataSet( array( + * 'Mozilla' => 19113, + * 'Explorer' => 10917, + * 'Opera' => 1464, + * 'Safari' => 652, + * 'Konqueror' => 474, + * ) ); * * * @property string $name @@ -47,32 +52,43 @@ * - TTF_FONT Native TTF fonts * - PS_FONT PostScript Type1 fonts * - FT2_FONT FreeType 2 fonts + * The type is normally automatically detected when you set the path + * to the font file. * @property float $minFontSize * Minimum font size for displayed texts. * @property float $maxFontSize * Maximum font size for displayed texts. * @property float $minimalUsedFont - * The minimal used font size for this element. + * The minimal used font size for the current element group. This + * property is set by the driver to maintain this information and + * should not be used to configure the apperance of the chart. See + * $minFontSize instead. * @property ezcGraphColor $color * Font color. * @property ezcGraphColor $background - * Background color + * Background color. The actual area filled with the background color + * is influenced by the settings $padding and $minimizeBorder. * @property ezcGraphColor $border - * Border color + * Border color for the text. The distance between the text and + * border is defined by the properties $padding and $minimizeBorder. * @property int $borderWidth - * Border width + * With of the border. To enable the border you need to set the + * $border property to some color. * @property int $padding - * Padding between text and border + * Padding between text and border. * @property bool $minimizeBorder * Fit the border exactly around the text, or use the complete - * possible space. + * possible space. This setting is only relevant, when a border + * color has been set for the font. * @property bool $textShadow - * Draw shadow for texts + * Draw shadow for texts. The color of the shadow is defined in + * the property $textShadowColor. * @property int $textShadowOffset - * Offset for text shadow + * Offset for text shadow. This defines the distance the shadow + * is moved to the bottom left relative from the text position. * @property ezcGraphColor $textShadowColor - * Color of text shadow. If false the inverse color of the text - * color will be used. + * Color of text shadow. If left at the default value "false"" + * the inverse color of the text color will be used. * * @version //autogentag// * @package Graph diff --git a/src/options/line_chart.php b/src/options/line_chart.php index 0ccb09f..fa963dd 100644 --- a/src/options/line_chart.php +++ b/src/options/line_chart.php @@ -10,6 +10,17 @@ /** * Class containing the basic options for line charts. * + * This class contains basic options relevant for line and bar charts, which + * are just an extension of line charts. + * + * For additional options configuring the apperance of the chart you may also + * want to check the option classes to configure the respective renderer you + * are using: + * + * - ezcGraphRendererOptions + * - ezcGraphRenderer2dOptions + * - ezcGraphRenderer3dOptions + * * * $graph = new ezcGraphLineChart(); * $graph->title = 'Wikipedia articles'; diff --git a/src/options/pie_chart.php b/src/options/pie_chart.php index 070acaa..da7c676 100644 --- a/src/options/pie_chart.php +++ b/src/options/pie_chart.php @@ -10,6 +10,14 @@ /** * Class containing the basic options for pie charts. * + * For additional options configuring the apperance of the chart you may also + * want to check the option classes to configure the respective renderer you + * are using: + * + * - ezcGraphRendererOptions + * - ezcGraphRenderer2dOptions + * - ezcGraphRenderer3dOptions + * * * $graph = new ezcGraphPieChart(); * $graph->palette = new ezcGraphPaletteEzRed(); diff --git a/src/options/renderer.php b/src/options/renderer.php index 7245f60..a896767 100644 --- a/src/options/renderer.php +++ b/src/options/renderer.php @@ -10,6 +10,16 @@ /** * Class containing the basic options for renderers. * + * Renderer options are used to define the general appearance of charts beside + * the palettes. The renderer transforms chart primitives (like the legend, or + * one pie slice) into image primitives, which are then rendered by the + * drivers. The way this transformation is done, and which effects are also + * rendered is specified by the values in this option class. + * + * The example below shows some basic bar rendering options, which are + * available in all renderers. You mya want to check the tutorial sections + * about the renderer, which show example output for more renderer options. + * * * $wikidata = include 'tutorial_wikipedia_data.php'; * @@ -32,6 +42,21 @@ * $graph->render( 400, 150, 'tutorial_bar_chart_options.svg' ); * * + * For additional options, which are special to some chart type you may + * also want to check the option classes for the repective chart type you + * are using and the elements of the chart. The chart type dependant option + * classes are: + * + * - ezcGraphLineChartOptions + * - ezcGraphPieChartOptions + * - ezcGraphRadarChartOptions + * + * There may be additional options dependant on the renderer you are using. + * You may want to check the extensions of this class: + * + * - ezcGraphRenderer2dOptions + * - ezcGraphRenderer3dOptions + * * @property float $maxLabelHeight * Percent of chart height used as maximum height for pie chart * labels. diff --git a/src/options/renderer_3d.php b/src/options/renderer_3d.php index 8cc485b..48262c7 100644 --- a/src/options/renderer_3d.php +++ b/src/options/renderer_3d.php @@ -10,6 +10,10 @@ /** * Class containing the extended options for the three dimensional renderer. * + * The three dimensional renderer offers a visually improved rendering compared + * with the two dimensional renderer. This results in more options configuring + * the three dimensional effeks, shadows and gleams in the chart. + * * * $graph = new ezcGraphPieChart(); * $graph->palette = new ezcGraphPaletteEzRed(); diff --git a/src/structs/context.php b/src/structs/context.php index 370d583..60eefa7 100644 --- a/src/structs/context.php +++ b/src/structs/context.php @@ -7,9 +7,25 @@ * @copyright Copyright (C) 2005-2008 eZ systems as. All rights reserved. * @license http://ez.no/licenses/new_bsd New BSD License */ + /** * Struct to represent the context of a renderer operation * + * Objects of this class are passed to the renderer, so the renderer is able to + * maintain the associations between image primitives and the datpoints. With + * this information the renderer build the array returned by the + * getElementReferences() method of the ezcGraphRenderer classes. In the + * returned array the datapoints are then associated with the identifiers for + * the image primitives returned by the respective driver. + * + * The ezcGraphTools class offers convience methods to handle this data and + * enrich your charts with hyperlinks, so you don't need to handle this + * yourself. + * + * The struct contains information about the $dataset and $datapoint the + * image primitive is associated with. If the dataset or datapoint has an + * URL associated, this URL is also available in the context struct. + * * @version //autogentag// * @package Graph */ diff --git a/src/structs/coordinate.php b/src/structs/coordinate.php index 172320e..9040b21 100644 --- a/src/structs/coordinate.php +++ b/src/structs/coordinate.php @@ -10,6 +10,12 @@ /** * Represents coordinates in two dimensional catesian coordinate system. * + * Coordinates are used to represent the location of objects on the drawing + * plane. They are simple structs conatining the two coordinate values required + * in a two dimensional cartesian coordinate system. The class ezcGraphVector + * extends the Coordinate class and provides additional methods like rotations, + * simple arithmetic operations etc. + * * @version //autogentag// * @package Graph */ diff --git a/src/structs/step.php b/src/structs/step.php index 8cfd73f..50bc6d3 100644 --- a/src/structs/step.php +++ b/src/structs/step.php @@ -10,6 +10,13 @@ /** * Represents a single step on the axis * + * Struct class containg information for single steps in the axis. A step may + * have child steps, which are commonly known as major (bigger) and minor + * (smaller) steps on axis. + * + * The positions of multiple steps in an array generated by the + * ezcGraphChartElementAxis classes is not always distributed evenly. + * * @version //autogentag// * @package Graph */ -- cgit v1.1