From 9d8baefbdf52a83adfb2efed5ebe4bd7b7f765a7 Mon Sep 17 00:00:00 2001 From: Kore Nordmann Date: Wed, 20 Sep 2006 15:12:20 +0000 Subject: - Added and improved documentation --- src/axis/date.php | 44 ++++++++++++++++++++-- src/axis/labeled.php | 22 +++++++++-- src/axis/numeric.php | 8 +++- src/charts/bar.php | 30 ++++++++++++++- src/charts/line.php | 54 ++++++++++++++++++++++++--- src/charts/pie.php | 48 +++++++++++++++++++++--- src/colors/linear_gradient.php | 9 ++++- src/colors/radial_gradient.php | 11 +++++- src/data_container/base.php | 5 ++- src/data_container/single.php | 5 ++- src/datasets/array.php | 4 +- src/datasets/average.php | 32 +++++++++++++++- src/datasets/base.php | 21 +++++++++++ src/graph.php | 72 ++++++++++++++++++++++++++++++++++- src/interfaces/renderer.php | 7 +--- src/math/boundings.php | 54 +++++++++++++++++++++++++-- src/math/matrix.php | 85 ++++++++++++++++++++++++++++++++---------- src/math/polynom.php | 12 +++--- 18 files changed, 453 insertions(+), 70 deletions(-) (limited to 'src') diff --git a/src/axis/date.php b/src/axis/date.php index 601119a..7bb8e1c 100644 --- a/src/axis/date.php +++ b/src/axis/date.php @@ -1,6 +1,6 @@ properties['interval'] = $interval; } + /** + * Calculate lower nice date + * + * Calculates a date which is earlier or equal to the given date, and is + * divisible by the given interval. + * + * @param int $min Date + * @param int $interval Interval + * @return int Earlier date + */ protected function calculateLowerNiceDate( $min, $interval ) { $dateSteps = array( 60, 60, 24, 7, 52 ); @@ -225,11 +241,33 @@ class ezcGraphChartElementDateAxis extends ezcGraphChartElementAxis ); } + /** + * Calculate start date + * + * Use calculateLowerNiceDate to get a date earlier or equal date then the + * minimum date to use it as the start date for the axis depending on the + * selected interval. + * + * @param mixed $min Minimum date + * @param mixed $max Maximum date + * @return void + */ public function calculateMinimum( $min, $max ) { $this->properties['startDate'] = $this->calculateLowerNiceDate( $min, $this->interval ); } + /** + * Calculate end date + * + * Use calculateLowerNiceDate to get a date later or equal date then the + * maximum date to use it as the end date for the axis depending on the + * selected interval. + * + * @param mixed $min Minimum date + * @param mixed $max Maximum date + * @return void + */ public function calculateMaximum( $min, $max ) { $this->properties['endDate'] = $this->calculateLowerNiceDate( $max, $this->interval ); @@ -243,8 +281,6 @@ class ezcGraphChartElementDateAxis extends ezcGraphChartElementAxis /** * Calculate axis bounding values on base of the assigned values * - * @abstract - * @access public * @return void */ public function calculateAxisBoundings() diff --git a/src/axis/labeled.php b/src/axis/labeled.php index 7b1225c..bbfd102 100644 --- a/src/axis/labeled.php +++ b/src/axis/labeled.php @@ -1,6 +1,6 @@ axisLabelRenderer = new ezcGraphAxisCenteredLabelRenderer(); @@ -42,7 +50,15 @@ class ezcGraphChartElementLabeledAxis extends ezcGraphChartElementAxis parent::__construct( $options ); } - protected function increaseKeys( $array, $startKey ) + /** + * Increase the keys of all elements in the array up from the start key, to + * insert an additional element at the correct position. + * + * @param array $array Array + * @param int $startKey Key to increase keys from + * @return array Updated array + */ + protected function increaseKeys( array $array, $startKey ) { foreach ( $array as $key => $value ) { diff --git a/src/axis/numeric.php b/src/axis/numeric.php index 1bf3cfe..85da3f6 100644 --- a/src/axis/numeric.php +++ b/src/axis/numeric.php @@ -8,7 +8,12 @@ * @license http://ez.no/licenses/new_bsd New BSD License */ /** - * Class to represent a axe as a chart element + * Class to represent a numeric axis. The axis tries to calculate "nice" start + * and end values for the axis scale. The used interval is considered as nice, + * if it is equal to [1,2,5] * 10^x with x in [.., -1, 0, 1, ..]. + * + * The start and end value are the next bigger / smaller multiple of the + * intervall compared to the maximum / minimum axis value. * * @property float $min * Minimum value of displayed scale on axis. @@ -19,7 +24,6 @@ * @property float $maxValue * Maximum value to display on this axis. * - * * @package Graph */ class ezcGraphChartElementNumericAxis extends ezcGraphChartElementAxis diff --git a/src/charts/bar.php b/src/charts/bar.php index b20901b..dc183d1 100644 --- a/src/charts/bar.php +++ b/src/charts/bar.php @@ -1,6 +1,6 @@ + * // Create a new line chart + * $chart = new ezcGraphBarChart(); + * + * // Add data to line chart + * $chart->data['sample dataset'] = new ezcGraphArrayDataSet( + * array( + * '100' => 1.2, + * '200' => 43.2, + * '300' => -34.14, + * '350' => 65, + * '400' => 123, + * ) + * ); + * + * // Render chart with default 2d renderer and default SVG driver + * $chart->render( 500, 200, 'bar_chart.svg' ); + * * * @package Graph */ diff --git a/src/charts/line.php b/src/charts/line.php index 9732205..2024ef0 100644 --- a/src/charts/line.php +++ b/src/charts/line.php @@ -1,6 +1,6 @@ + * // Create a new line chart + * $chart = new ezcGraphLineChart(); + * + * // Add data to line chart + * $chart->data['sample dataset'] = new ezcGraphArrayDataSet( + * array( + * '100' => 1.2, + * '200' => 43.2, + * '300' => -34.14, + * '350' => 65, + * '400' => 123, + * ) + * ); + * + * // Render chart with default 2d renderer and default SVG driver + * $chart->render( 500, 200, 'line_chart.svg' ); + * * * @package Graph */ @@ -78,7 +104,18 @@ class ezcGraphLineChart extends ezcGraphChart } } - protected function renderData( $renderer, $boundings ) + /** + * Render the assigned data + * + * Will renderer all charts data in the remaining boundings after drawing + * all other chart elements. The data will be rendered depending on the + * settings in the dataset. + * + * @param ezcGraphRenderer $renderer Renderer + * @param ezcGraphBoundings $boundings Remaining boundings + * @return void + */ + protected function renderData( ezcGraphRenderer $renderer, ezcGraphBoundings $boundings ) { // Apply axis space $xAxisSpace = ( $boundings->x1 - $boundings->x0 ) * $this->yAxis->axisSpace; @@ -240,10 +277,15 @@ class ezcGraphLineChart extends ezcGraphChart } /** - * Render a line chart + * Render the line chart + * + * Renders the chart into a file or stream. The width and height are + * needed to specify the dimensions of the resulting image. For direct + * output use 'php://stdout' as output file. * - * @param ezcGraphRenderer $renderer - * @access public + * @param int $width Image width + * @param int $height Image height + * @param string $file Output file * @return void */ public function render( $width, $height, $file = null ) diff --git a/src/charts/pie.php b/src/charts/pie.php index b21401e..169263d 100644 --- a/src/charts/pie.php +++ b/src/charts/pie.php @@ -1,6 +1,6 @@ + * // Create a new line chart + * $chart = new ezcGraphLineChart(); + * + * // Add data to line chart + * $chart->data['sample dataset'] = new ezcGraphArrayDataSet( + * array( + * 'one' => 1.2, + * 'two' => 43.2, + * 'three' => -34.14, + * 'four' => 65, + * 'five' => 123, + * ) + * ); + * + * // Render chart with default 2d renderer and default SVG driver + * $chart->render( 500, 200, 'line_chart.svg' ); + * * * @package Graph */ @@ -31,7 +51,18 @@ class ezcGraphPieChart extends ezcGraphChart $this->data = new ezcGraphChartSingleDataContainer( $this ); } - protected function renderData( $renderer, $boundings ) + /** + * Render the assigned data + * + * Will renderer all charts data in the remaining boundings after drawing + * all other chart elements. The data will be rendered depending on the + * settings in the dataset. + * + * @param ezcGraphRenderer $renderer Renderer + * @param ezcGraphBoundings $boundings Remaining boundings + * @return void + */ + protected function renderData( ezcGraphRenderer $renderer, ezcGraphBoundings $boundings ) { // Only draw the first (and only) dataset $dataset = $this->data->rewind(); @@ -80,10 +111,15 @@ class ezcGraphPieChart extends ezcGraphChart } /** - * Render a pie chart + * Render the pie chart + * + * Renders the chart into a file or stream. The width and height are + * needed to specify the dimensions of the resulting image. For direct + * output use 'php://stdout' as output file. * - * @param ezcGraphRenderer $renderer - * @access public + * @param int $width Image width + * @param int $height Image height + * @param string $file Output file * @return void */ public function render( $width, $height, $file = null ) diff --git a/src/colors/linear_gradient.php b/src/colors/linear_gradient.php index 3bbde96..6d6fd7b 100644 --- a/src/colors/linear_gradient.php +++ b/src/colors/linear_gradient.php @@ -10,7 +10,8 @@ /** * Class representing linear gradient fills. For drivers which cannot draw - * gradients it falls back to a native ezcGraphColor + * gradients it falls back to a native ezcGraphColor. In this case the start + * color of the gradient will be used. * * @property ezcGraphCoordinate $startPoint * Starting point of the gradient. @@ -132,6 +133,12 @@ class ezcGraphLinearGradient extends ezcGraphColor } } + /** + * Returns a unique string representation for the gradient. + * + * @access public + * @return void + */ public function __toString() { return sprintf( 'LinearGradient_%d_%d_%d_%d_%02x%02x%02x%02x_%02x%02x%02x%02x', diff --git a/src/colors/radial_gradient.php b/src/colors/radial_gradient.php index 78b22ca..54f2946 100644 --- a/src/colors/radial_gradient.php +++ b/src/colors/radial_gradient.php @@ -9,8 +9,9 @@ */ /** - * Class representing linear gradient fills. For drivers which cannot draw - * gradients it falls back to a native ezcGraphColor + * Class representing radial gradient fills. For drivers which cannot draw + * gradients it falls back to a native ezcGraphColor. In this case the start + * color of the gradient will be used. * * @property ezcGraphCoordinate $center * Center point of the gradient. @@ -137,6 +138,12 @@ class ezcGraphRadialGradient extends ezcGraphColor } } + /** + * Returns a unique string representation for the gradient. + * + * @access public + * @return void + */ public function __toString() { return sprintf( 'RadialGradient_%d_%d_%d_%d_%.2f_%02x%02x%02x%02x_%02x%02x%02x%02x', diff --git a/src/data_container/base.php b/src/data_container/base.php index 38bc86c..84c6379 100644 --- a/src/data_container/base.php +++ b/src/data_container/base.php @@ -1,6 +1,6 @@ mixed) + */ protected $properties; /** diff --git a/src/datasets/base.php b/src/datasets/base.php index 8ab6e5d..e7880c7 100644 --- a/src/datasets/base.php +++ b/src/datasets/base.php @@ -6,11 +6,13 @@ * @version //autogentag// * @copyright Copyright (C) 2005, 2006 eZ systems as. All rights reserved. * @license http://ez.no/licenses/new_bsd New BSD License + * @access private */ /** * Basic class to contain the charts data * * @package Graph + * @access private */ abstract class ezcGraphDataSet implements ArrayAccess, Iterator { @@ -73,6 +75,13 @@ abstract class ezcGraphDataSet implements ArrayAccess, Iterator */ protected $pallet; + /** + * Constructor + * + * @param array $options Default option array + * @return void + * @ignore + */ public function __construct() { $this->label = new ezcGraphDataSetStringProperty( $this ); @@ -84,6 +93,18 @@ abstract class ezcGraphDataSet implements ArrayAccess, Iterator $this->highlight->default = false; } + /** + * Options write access + * + * @throws ezcBasePropertyNotFoundException + * If Option could not be found + * @throws ezcBaseValueException + * If value is out of range + * @param mixed $propertyName Option name + * @param mixed $propertyValue Option value; + * @return void + * @ignore + */ public function __set( $propertyName, $propertyValue ) { switch ( $propertyName ) diff --git a/src/graph.php b/src/graph.php index 0a9ffac..ae6c74b 100644 --- a/src/graph.php +++ b/src/graph.php @@ -14,29 +14,97 @@ */ class ezcGraph { + /** + * No symbol, will fallback to a rect in the legend + */ const NO_SYMBOL = 0; + /** + * Rhomb like looking symbol + */ const DIAMOND = 1; + /** + * Filled circle + */ const BULLET = 2; + /** + * Non filled circle + */ const CIRCLE = 3; + /** + * Constant used for background repetition. No repeat. + */ const NO_REPEAT = 0; + /** + * Constant used for background repetition. Repeat along the x axis. May be + * used as a bitmask together with ezcGraph::VERTICAL. + */ const HORIZONTAL = 1; + /** + * Constant used for background repetition. Repeat along the y axis. May be + * used as a bitmask together with ezcGraph::HORIZONTAL. + */ const VERTICAL = 2; + /** + * Constant used for positioning of elements. May be used as a bitmask + * together with other postioning constants. + * Element will be placed at the top of the current boundings. + */ const TOP = 1; + /** + * Constant used for positioning of elements. May be used as a bitmask + * together with other postioning constants. + * Element will be placed at the bottom of the current boundings. + */ const BOTTOM = 2; + /** + * Constant used for positioning of elements. May be used as a bitmask + * together with other postioning constants. + * Element will be placed at the left of the current boundings. + */ const LEFT = 4; + /** + * Constant used for positioning of elements. May be used as a bitmask + * together with other postioning constants. + * Element will be placed at the right of the current boundings. + */ const RIGHT = 8; + /** + * Constant used for positioning of elements. May be used as a bitmask + * together with other postioning constants. + * Element will be placed at the horizontalcenter of the current boundings. + */ const CENTER = 16; + /** + * Constant used for positioning of elements. May be used as a bitmask + * together with other postioning constants. + * Element will be placed at the vertical middle of the current boundings. + */ const MIDDLE = 32; + /** + * Display type for datasets. Pie may only be used with pie charts. + */ const PIE = 1; + /** + * Display type for datasets. Bar and line charts may contain datasets of + * type ezcGraph::LINE. + */ const LINE = 2; + /** + * Display type for datasets. Bar and line charts may contain datasets of + * type ezcGraph::BAR. + */ const BAR = 3; - // native TTF font + /** + * Font type definition. Used for True Type fonts. + */ const TTF_FONT = 1; - // PostScript Type1 fonts + /** + * Font type definition. Used for Postscript Type 1 fonts. + */ const PS_FONT = 2; } diff --git a/src/interfaces/renderer.php b/src/interfaces/renderer.php index 46b5301..6839562 100644 --- a/src/interfaces/renderer.php +++ b/src/interfaces/renderer.php @@ -481,14 +481,9 @@ abstract class ezcGraphRenderer * Method is called before the final image is renderer, so that finishing * operations can be performed here. * - * @abstract - * @access public * @return void */ - protected function finish() - { - return true; - } + abstract protected function finish(); /** * Finally renders the image diff --git a/src/math/boundings.php b/src/math/boundings.php index 78ce6cb..13426a3 100644 --- a/src/math/boundings.php +++ b/src/math/boundings.php @@ -1,17 +1,60 @@ rows, $this->columns ); - - for ( $i = 0; $i < $this->rows; ++$i ) - { - $string .= '| '; - for ( $j = 0; $j < $this->columns; ++$j ) - { - $string .= sprintf( '%04.2f ', $this->get( $i, $j ) ); - } - $string .= "|\n"; - } - - return $string; - } - + /** + * Build LR decomposition from matrix + * + * Use Cholesky-Crout algorithm to get LR decomposition of the current + * matrix. + * + * Will return an array with two matrices: + * array( + * 'l' => (ezcGraphMatrix) $left, + * 'r' => (ezcGraphMatrix) $right, + * ) + * + * @return array( ezcGraphMatrix ) + */ public function LRdecomposition() { /** @@ -451,5 +474,27 @@ class ezcGraphMatrix 'r' => $r, ); } + + /** + * Returns a string representation of the matrix + * + * @return string + */ + public function __toString() + { + $string = sprintf( "%d x %d matrix:\n", $this->rows, $this->columns ); + + for ( $i = 0; $i < $this->rows; ++$i ) + { + $string .= '| '; + for ( $j = 0; $j < $this->columns; ++$j ) + { + $string .= sprintf( '%04.2f ', $this->get( $i, $j ) ); + } + $string .= "|\n"; + } + + return $string; + } } ?> diff --git a/src/math/polynom.php b/src/math/polynom.php index 6939252..42b969d 100644 --- a/src/math/polynom.php +++ b/src/math/polynom.php @@ -6,11 +6,13 @@ * @version //autogentag// * @copyright Copyright (C) 2005, 2006 eZ systems as. All rights reserved. * @license http://ez.no/licenses/new_bsd New BSD License + * @access private */ /** * Provides a class for generic operations on polynoms * * @package Graph + * @access private */ class ezcGraphPolynom { @@ -26,15 +28,13 @@ class ezcGraphPolynom * 2 * x^3 + .5 * x - 3 * Array: * array ( - * 3 => 2, - * 1 => .5, - * 0 => -3, + * (int) 3 => (float) 2, + * (int) 1 => (float) .5, + * (int) 0 => (float) -3, * ) * - * @param int $columns Number of columns - * @param int $rows Number of rows * @param array $values Array with values - * @return void + * @return ezcGraphPolynom */ public function __construct( array $values = array() ) { -- cgit v1.1