[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * File containing the abstract ezcGraphChartElement class
   4   *
   5   * @package Graph
   6   * @version 1.5
   7   * @copyright Copyright (C) 2005-2009 eZ Systems AS. All rights reserved.
   8   * @license http://ez.no/licenses/new_bsd New BSD License
   9   */
  10  
  11  /**
  12   * Base class for chart elements
  13   *
  14   * The base class for chart elements. Chart elements can be understood as
  15   * widgets or layout container inside the chart. The actual transformation to
  16   * images happens inside the renderers. They represent all elements inside the
  17   * chart and contain mostly general formatting options, while the renderer
  18   * itself might define additional formatting options for some chart elments.
  19   *
  20   * Important chart elements for example are:
  21   *
  22   * - Chart title (ezcGraphChartElementText)
  23   * - Chart legend (ezcGraphChartElementLegend)
  24   * - The axis (ezcGraphChartElementNumericAxis,
  25   *   ezcGraphChartElementLogarithmicalAxis, ezcGraphChartElementLabeledAxis,
  26   *   ezcGraphChartElementDateAxis)
  27   * - ...
  28   * 
  29   * The position of chart elements is defined in the $position property. The
  30   * effect this has on the visual representation depends on the actual type of
  31   * the chart element.
  32   *
  33   * Each chart element may be configured with options similar to CSS, used with
  34   * HTML to define the general style of the repsective element:
  35   *
  36   * - $padding & $margin defne the distance of the border from inner elements /
  37   *   other chart elements.
  38   * - $borderWidth & $border define the style of the border used around the
  39   *   chart element
  40   * - $background defines the background color of the chart element. As always
  41   *   this may be a (semi-) transparent color.
  42   *
  43   * A typical example with some layout for the chart title element could look
  44   * like:
  45   *
  46   * <code>
  47   *  $graph = new ezcGraphPieChart();
  48   *  $graph->data['example'] = new ezcGraphArrayDataSet( array(
  49   *      'Foo' => 23,
  50   *      'Bar' => 42,
  51   *  ) );
  52   *  
  53   *  // Set a title and format the title element
  54   *  $graph->title              = 'Example formatted pie chart';
  55   *  $graph->title->margin      = 2;
  56   *  $graph->title->background  = '#FFFFFF80';
  57   *  $graph->title->border      = '#FFFFFF';
  58   *  $graph->title->borderWidth = 1;
  59   *  $graph->title->margin      = 1;
  60   *  $graph->title->padding     = 1;
  61   *  
  62   *  // Format the legend element
  63   *  $graph->legend->margin      = 2;
  64   *  $graph->legend->background  = '#FFFFFF80';
  65   *  $graph->legend->border      = '#FFFFFF';
  66   *  $graph->legend->borderWidth = 1;
  67   *  $graph->legend->margin      = 1;
  68   *  $graph->legend->padding     = 1;
  69   *  
  70   *  $graph->background->background = '#888a85';
  71   *  
  72   *  $graph->render( 400, 250, 'element.svg' );
  73   * </code>
  74   *
  75   * @property string $title
  76   *           Title of chart element.
  77   * @property ezcGraphColor $background
  78   *           Background color of chart element.
  79   * @property ezcGraphColor $border
  80   *           Border color of chart element.
  81   * @property int $padding
  82   *           Distance between border and content of element.
  83   * @property int $margin
  84   *           Distance between outer boundings and border of an element.
  85   * @property int $borderWidth
  86   *           Border width.
  87   * @property int $position
  88   *           Integer defining the elements position in the chart.
  89   * @property int $maxTitleHeight
  90   *           Maximum size of the title.
  91   * @property float $portraitTitleSize
  92   *           Percentage of boundings which are used for the title with 
  93   *           position left, right or center.
  94   * @property float $landscapeTitleSize
  95   *           Percentage of boundings which are used for the title with 
  96   *           position top or bottom.
  97   * @property ezcGraphFontOptions $font
  98   *           Font used for this element.
  99   * @property-read bool $fontCloned
 100   *                Indicates if font configuration was already cloned for this 
 101   *                specific element.
 102   * @property-read ezcGraphBoundings $boundings
 103   *                Boundings of this elements.
 104   *
 105   * @version 1.5
 106   * @package Graph
 107   */
 108  abstract class ezcGraphChartElement extends ezcBaseOptions
 109  {
 110  
 111      /**
 112       * Constructor
 113       * 
 114       * @param array $options Default option array
 115       * @return void
 116       * @ignore
 117       */
 118      public function __construct( array $options = array() )
 119      {
 120          $this->properties['title'] = false;
 121          $this->properties['background'] = false;
 122          $this->properties['boundings'] = new ezcGraphBoundings();
 123          $this->properties['border'] = false;
 124          $this->properties['borderWidth'] = 0;
 125          $this->properties['padding'] = 0;
 126          $this->properties['margin'] = 0;
 127          $this->properties['position'] = ezcGraph::LEFT;
 128          $this->properties['maxTitleHeight'] = 16;
 129          $this->properties['portraitTitleSize'] = .15;
 130          $this->properties['landscapeTitleSize'] = .2;
 131          $this->properties['font'] = new ezcGraphFontOptions();
 132          $this->properties['fontCloned'] = false;
 133  
 134          parent::__construct( $options );
 135      }
 136  
 137      /**
 138       * Set colors and border fro this element
 139       * 
 140       * @param ezcGraphPalette $palette Palette
 141       * @return void
 142       */
 143      public function setFromPalette( ezcGraphPalette $palette )
 144      {
 145          $this->properties['border'] = $palette->elementBorderColor;
 146          $this->properties['borderWidth'] = $palette->elementBorderWidth;
 147          $this->properties['background'] = $palette->elementBackground;
 148          $this->properties['padding'] = $palette->padding;
 149          $this->properties['margin'] = $palette->margin;
 150      }
 151  
 152      /**
 153       * __set 
 154       * 
 155       * @param mixed $propertyName 
 156       * @param mixed $propertyValue 
 157       * @throws ezcBaseValueException
 158       *          If a submitted parameter was out of range or type.
 159       * @throws ezcBasePropertyNotFoundException
 160       *          If a the value for the property options is not an instance of
 161       * @return void
 162       * @ignore
 163       */
 164      public function __set( $propertyName, $propertyValue )
 165      {
 166          switch ( $propertyName )
 167          {
 168              case 'title':
 169                  $this->properties['title'] = (string) $propertyValue;
 170                  break;
 171              case 'background':
 172                  $this->properties['background'] = ezcGraphColor::create( $propertyValue );
 173                  break;
 174              case 'border':
 175                  $this->properties['border'] = ezcGraphColor::create( $propertyValue );
 176                  break;
 177              case 'padding':
 178                  if ( !is_numeric( $propertyValue ) ||
 179                       ( $propertyValue < 0 ) )
 180                  {
 181                      throw new ezcBaseValueException( $propertyName, $propertyValue, 'int >= 0' );
 182                  }
 183  
 184                  $this->properties['padding'] = (int) $propertyValue;
 185                  break;
 186              case 'margin':
 187                  if ( !is_numeric( $propertyValue ) ||
 188                       ( $propertyValue < 0 ) )
 189                  {
 190                      throw new ezcBaseValueException( $propertyName, $propertyValue, 'int >= 0' );
 191                  }
 192  
 193                  $this->properties['margin'] = (int) $propertyValue;
 194                  break;
 195              case 'borderWidth':
 196                  if ( !is_numeric( $propertyValue ) ||
 197                       ( $propertyValue < 0 ) )
 198                  {
 199                      throw new ezcBaseValueException( $propertyName, $propertyValue, 'int >= 0' );
 200                  }
 201  
 202                  $this->properties['borderWidth'] = (int) $propertyValue;
 203                  break;
 204              case 'font':
 205                  if ( $propertyValue instanceof ezcGraphFontOptions )
 206                  {
 207                      $this->properties['font'] = $propertyValue;
 208                  }
 209                  elseif ( is_string( $propertyValue ) )
 210                  {
 211                      if ( !$this->fontCloned )
 212                      {
 213                          $this->properties['font'] = clone $this->font;
 214                          $this->properties['fontCloned'] = true;
 215                      }
 216  
 217                      $this->properties['font']->path = $propertyValue;
 218                  }
 219                  else
 220                  {
 221                      throw new ezcBaseValueException( $propertyName, $propertyValue, 'ezcGraphFontOptions' );
 222                  }
 223                  break;
 224              case 'position':
 225                  $positions = array(
 226                      ezcGraph::TOP,
 227                      ezcGraph::BOTTOM,
 228                      ezcGraph::LEFT,
 229                      ezcGraph::RIGHT,
 230                  );
 231  
 232                  if ( in_array( $propertyValue, $positions, true ) )
 233                  {
 234                      $this->properties['position'] = $propertyValue;
 235                  }
 236                  else 
 237                  {
 238                      throw new ezcBaseValueException( 'position', $propertyValue, 'integer' );
 239                  }
 240                  break;
 241              case 'maxTitleHeight':
 242                  if ( !is_numeric( $propertyValue ) ||
 243                       ( $propertyValue < 0 ) )
 244                  {
 245                      throw new ezcBaseValueException( $propertyName, $propertyValue, 'int >= 0' );
 246                  }
 247  
 248                  $this->properties['maxTitleHeight'] = (int) $propertyValue;
 249                  break;
 250              case 'portraitTitleSize':
 251                  if ( !is_numeric( $propertyValue ) ||
 252                       ( $propertyValue < 0 ) ||
 253                       ( $propertyValue > 1 ) )
 254                  {
 255                      throw new ezcBaseValueException( $propertyName, $propertyValue, '0 <= float <= 1' );
 256                  }
 257  
 258                  $this->properties['portraitTitleSize'] = (float) $propertyValue;
 259                  break;
 260              case 'landscapeTitleSize':
 261                  if ( !is_numeric( $propertyValue ) ||
 262                       ( $propertyValue < 0 ) ||
 263                       ( $propertyValue > 1 ) )
 264                  {
 265                      throw new ezcBaseValueException( $propertyName, $propertyValue, '0 <= float <= 1' );
 266                  }
 267  
 268                  $this->properties['landscapeTitleSize'] = (float) $propertyValue;
 269                  break;
 270              default:
 271                  throw new ezcBasePropertyNotFoundException( $propertyName );
 272                  break;
 273          }
 274      }
 275      
 276      /**
 277       * __get 
 278       * 
 279       * @param mixed $propertyName 
 280       * @throws ezcBasePropertyNotFoundException
 281       *          If a the value for the property options is not an instance of
 282       * @return mixed
 283       * @ignore
 284       */
 285      public function __get( $propertyName )
 286      {
 287          switch ( $propertyName )
 288          {
 289              case 'font':
 290                  // Clone font configuration when requested for this element
 291                  if ( !$this->fontCloned )
 292                  {
 293                      $this->properties['font'] = clone $this->properties['font'];
 294                      $this->properties['fontCloned'] = true;
 295                  }
 296                  return $this->properties['font'];
 297              default:
 298                  return parent::__get( $propertyName );
 299          }
 300      }
 301  
 302      /**
 303       * Renders this chart element
 304       *
 305       * This method receives and returns a part of the canvas where it can be 
 306       * rendered on.
 307       * 
 308       * @param ezcGraphRenderer $renderer
 309       * @param ezcGraphBoundings $boundings
 310       * @return ezcGraphBoundings Part of canvas, which is still free to draw on
 311       */
 312      abstract public function render( ezcGraphRenderer $renderer, ezcGraphBoundings $boundings );
 313  
 314      /**
 315       * Returns calculated boundings based on available percentual space of 
 316       * given bounding box specified in the elements options and direction of 
 317       * the box.
 318       * 
 319       * @param ezcGraphBoundings $boundings 
 320       * @param int $direction 
 321       * @return ezcGraphBoundings
 322       */
 323      protected function getTitleSize( ezcGraphBoundings $boundings, $direction = ezcGraph::HORIZONTAL )
 324      {
 325          if ( $direction === ezcGraph::HORIZONTAL )
 326          {
 327              return min(
 328                  $this->maxTitleHeight,
 329                  ( $boundings->y1 - $boundings->y0 ) * $this->landscapeTitleSize
 330              );
 331          }
 332          else
 333          {
 334              return min(
 335                  $this->maxTitleHeight,
 336                  ( $boundings->y1 - $boundings->y0 ) * $this->portraitTitleSize
 337              );
 338          }
 339      }
 340  }
 341  
 342  ?>