[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * File containing the abstract ezcGraphChartElementLegend 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   * Class to represent a legend as a chart element
  12   *
  13   * Chart elements can be understood as widgets or layout container inside the
  14   * chart. The actual transformation to images happens inside the renderers.
  15   * They represent all elements inside the chart and contain mostly general
  16   * formatting options, while the renderer itself might define additional
  17   * formatting options for some chart elments. You can find more about the
  18   * general formatting options for chart elements in the base class
  19   * ezcGraphChartElement.
  20   *
  21   * The legend chart element is used to display the legend of a chart. It can be
  22   * deactivated by setting the legend to false, like:
  23   *
  24   * <code>
  25   *  $chart->legend = false;
  26   * </code>
  27   *
  28   * The position of the legend in the chart can be influenced by the postion
  29   * property, set to one of the position constants from the ezcGraph base class,
  30   * like ezcGraph::BOTTOM, ezcGraph::LEFT, ezcGraph::RIGHT, ezcGraph::TOP.
  31   *
  32   * Depending on the position of the legend, either the $portraitSize (RIGHT,
  33   * LEFT) or the $landscapeSize (TOP, BOTTOM) defines how much space will be
  34   * aqquired for the legend.
  35   *
  36   * <code>
  37   *  $graph = new ezcGraphPieChart();
  38   *  $graph->data['example'] = new ezcGraphArrayDataSet( array(
  39   *      'Foo' => 23,
  40   *      'Bar' => 42,
  41   *  ) );
  42   *  
  43   *  // Format the legend element
  44   *  $graph->legend->background    = '#FFFFFF80';
  45   *
  46   *  // Place at the bottom of the chart, with a height of 5% of the remaining
  47   *  // chart space.
  48   *  $graph->legend->position      = ezcGraph::BOTTOM;
  49   *  $graph->legend->landscapeSize = .05;
  50   *  
  51   *  $graph->render( 400, 250, 'legend.svg' );
  52   * </code>
  53   *
  54   * @property float $portraitSize
  55   *           Size of a portrait style legend in percent of the size of the 
  56   *           complete chart.
  57   * @property float $landscapeSize
  58   *           Size of a landscape style legend in percent of the size of the 
  59   *           complete chart.
  60   * @property int $symbolSize
  61   *           Standard size of symbols and text in legends.
  62   * @property float $minimumSymbolSize
  63   *           Scale symbol size up to to percent of complete legends size for 
  64   *           very big legends.
  65   * @property int $spacing
  66   *           Space between labels elements in pixel.
  67   *
  68   * @version 1.5
  69   * @package Graph
  70   * @mainclass
  71   */
  72  class ezcGraphChartElementLegend extends ezcGraphChartElement
  73  {
  74  
  75      /**
  76       * Contains data which should be shown in the legend
  77       *  array(
  78       *      array(
  79       *          'label' => (string) 'Label of data element',
  80       *          'color' => (ezcGraphColor) $color,
  81       *          'symbol' => (integer) ezcGraph::DIAMOND,
  82       *      ),
  83       *      ...
  84       *  )
  85       * 
  86       * @var array
  87       */
  88      protected $labels;
  89  
  90      /**
  91       * Constructor
  92       * 
  93       * @param array $options Default option array
  94       * @return void
  95       * @ignore
  96       */
  97      public function __construct( array $options = array() )
  98      {
  99          $this->properties['portraitSize'] = .2;
 100          $this->properties['landscapeSize'] = .1;
 101          $this->properties['symbolSize'] = 14;
 102          $this->properties['padding'] = 1;
 103          $this->properties['minimumSymbolSize'] = .05;
 104          $this->properties['spacing'] = 2;
 105  
 106          parent::__construct( $options );
 107      }
 108  
 109      /**
 110       * __set 
 111       * 
 112       * @param mixed $propertyName 
 113       * @param mixed $propertyValue 
 114       * @throws ezcBaseValueException
 115       *          If a submitted parameter was out of range or type.
 116       * @throws ezcBasePropertyNotFoundException
 117       *          If a the value for the property options is not an instance of
 118       * @return void
 119       * @ignore
 120       */
 121      public function __set( $propertyName, $propertyValue )
 122      {
 123          switch ( $propertyName )
 124          {
 125              case 'padding':
 126                  if ( !is_numeric( $propertyValue ) ||
 127                       ( $propertyValue < 0 ) )
 128                  {
 129                      throw new ezcBaseValueException( $propertyName, $propertyValue, 'int >= 0' );
 130                  }
 131  
 132                  $this->properties['padding'] = (int) $propertyValue;
 133                  break;
 134              case 'symbolSize':
 135                  if ( !is_numeric( $propertyValue ) ||
 136                       ( $propertyValue < 1 ) )
 137                  {
 138                      throw new ezcBaseValueException( $propertyName, $propertyValue, 'int >= 1' );
 139                  }
 140  
 141                  $this->properties['symbolSize'] = (int) $propertyValue;
 142                  break;
 143              case 'landscapeSize':
 144                  if ( !is_numeric( $propertyValue ) ||
 145                       ( $propertyValue < 0 ) ||
 146                       ( $propertyValue > 1 ) )
 147                  {
 148                      throw new ezcBaseValueException( $propertyName, $propertyValue, '0 <= int <= 1' );
 149                  }
 150  
 151                  $this->properties['landscapeSize'] = (float) $propertyValue;
 152                  break;
 153              case 'portraitSize':
 154                  if ( !is_numeric( $propertyValue ) ||
 155                       ( $propertyValue < 0 ) ||
 156                       ( $propertyValue > 1 ) )
 157                  {
 158                      throw new ezcBaseValueException( $propertyName, $propertyValue, '0 <= int <= 1' );
 159                  }
 160  
 161                  $this->properties['portraitSize'] = (float) $propertyValue;
 162                  break;
 163              case 'minimumSymbolSize':
 164                  if ( !is_numeric( $propertyValue ) ||
 165                       ( $propertyValue < 0 ) ||
 166                       ( $propertyValue > 1 ) )
 167                  {
 168                      throw new ezcBaseValueException( $propertyName, $propertyValue, '0 <= int <= 1' );
 169                  }
 170  
 171                  $this->properties['minimumSymbolSize'] = (float) $propertyValue;
 172                  break;
 173              case 'spacing':
 174                  if ( !is_numeric( $propertyValue ) ||
 175                       ( $propertyValue < 0 ) )
 176                  {
 177                      throw new ezcBaseValueException( $propertyName, $propertyValue, 'int >= 0' );
 178                  }
 179  
 180                  $this->properties['spacing'] = (int) $propertyValue;
 181                  break;
 182              default:
 183                  parent::__set( $propertyName, $propertyValue );
 184                  break;
 185          }
 186      }
 187      
 188      /**
 189       * __get 
 190       * 
 191       * @param mixed $propertyName 
 192       * @throws ezcBasePropertyNotFoundException
 193       *          If a the value for the property options is not an instance of
 194       * @return mixed
 195       * @ignore
 196       */
 197      public function __get( $propertyName )
 198      {
 199          switch ( $propertyName )
 200          {
 201              case 'labels':
 202                  return $this->labels;
 203              default:
 204                  return parent::__get( $propertyName );
 205          }
 206      }
 207  
 208      /**
 209       * Generate legend from several datasets with on entry per dataset
 210       * 
 211       * @param ezcGraphChartDataContainer $datasets 
 212       * @return void
 213       */
 214      public function generateFromDataSets( ezcGraphChartDataContainer $datasets )
 215      {
 216          $this->labels = array();
 217          foreach ( $datasets as $dataset )
 218          {
 219              $this->labels[] = array(
 220                  'label' => $dataset->label->default,
 221                  'url' => $dataset->url->default,
 222                  'color' => $dataset->color->default,
 223                  'symbol' => ( $dataset->symbol->default === null ?
 224                                ezcGraph::NO_SYMBOL :
 225                                $dataset->symbol->default ),
 226              );
 227          }
 228      }
 229  
 230      /**
 231       * Generate legend from single dataset with on entry per data element 
 232       * 
 233       * @param ezcGraphDataSet $dataset 
 234       * @return void
 235       */
 236      public function generateFromDataSet( ezcGraphDataSet $dataset )
 237      {
 238          $this->labels = array();
 239          foreach ( $dataset as $label => $data )
 240          {
 241              $this->labels[] = array(
 242                  'label' => $label,
 243                  'url' => $dataset->url[$label],
 244                  'color' => $dataset->color[$label],
 245                  'symbol' => ( $dataset->symbol[$label] === null ?
 246                                ezcGraph::NO_SYMBOL :
 247                                $dataset->symbol[$label] ),
 248              );
 249          }
 250      }
 251      
 252      /**
 253       * Calculated boundings needed for the legend.
 254       *
 255       * Uses the position and the configured horizontal or vertical size of a 
 256       * legend to calculate the boundings for the legend.
 257       * 
 258       * @param ezcGraphBoundings $boundings Avalable boundings
 259       * @return ezcGraphBoundings Remaining boundings
 260       */
 261      protected function calculateBoundings( ezcGraphBoundings $boundings )
 262      {
 263          $this->properties['boundings'] = clone $boundings;
 264  
 265          switch ( $this->position )
 266          {
 267              case ezcGraph::LEFT:
 268                  $size = ( $boundings->width ) * $this->portraitSize;
 269  
 270                  $boundings->x0 += $size;
 271                  $this->boundings->x1 = $boundings->x0;
 272                  break;
 273              case ezcGraph::RIGHT:
 274                  $size = ( $boundings->width ) * $this->portraitSize;
 275  
 276                  $boundings->x1 -= $size;
 277                  $this->boundings->x0 = $boundings->x1;
 278                  break;
 279              case ezcGraph::TOP:
 280                  $size = ( $boundings->height ) * $this->landscapeSize;
 281  
 282                  $boundings->y0 += $size;
 283                  $this->boundings->y1 = $boundings->y0;
 284                  break;
 285              case ezcGraph::BOTTOM:
 286                  $size = ( $boundings->height ) * $this->landscapeSize;
 287  
 288                  $boundings->y1 -= $size;
 289                  $this->boundings->y0 = $boundings->y1;
 290                  break;
 291          }
 292  
 293          return $boundings;
 294      }
 295  
 296      /**
 297       * Render a legend
 298       * 
 299       * @param ezcGraphRenderer $renderer Renderer
 300       * @param ezcGraphBoundings $boundings Boundings for the axis
 301       * @return ezcGraphBoundings Remaining boundings
 302       */
 303      public function render( ezcGraphRenderer $renderer, ezcGraphBoundings $boundings )
 304      {
 305          $boundings = $this->calculateBoundings( $boundings );
 306          
 307          if ( $this->position === ezcGraph::LEFT || $this->position === ezcGraph::RIGHT )
 308          {
 309              $type = ezcGraph::VERTICAL;
 310          }
 311          else
 312          {
 313              $type = ezcGraph::HORIZONTAL;
 314          }
 315  
 316          // Render standard elements
 317          $this->properties['boundings'] = $renderer->drawBox(
 318              $this->properties['boundings'],
 319              $this->properties['background'],
 320              $this->properties['border'],
 321              $this->properties['borderWidth'],
 322              $this->properties['margin'],
 323              $this->properties['padding'],
 324              $this->properties['title'],
 325              $this->getTitleSize( $this->properties['boundings'], $type )
 326          );
 327  
 328          // Render legend
 329          $renderer->drawLegend(
 330              $this->boundings,
 331              $this,
 332              $type
 333          );
 334  
 335          return $boundings;  
 336      }
 337  }
 338  
 339  ?>