git.sur5r.net Git - bacula/bacula/blob - gui/baculum/framework/Web/UI/WebControls/TWebControl.php

   1 <?php
   2 /**
   3  * TWebControl class file.
   4  *
   5  * @author Qiang Xue <qiang.xue@gmail.com>
   6  * @link http://www.pradosoft.com/
   7  * @copyright Copyright &copy; 2005-2014 PradoSoft
   8  * @license http://www.pradosoft.com/license/
   9  * @package System.Web.UI.WebControls
  10  */
  11
  12 /**
  13  * Includes TStyle and TWebAdapter definition
  14  */
  15 Prado::using('System.Web.UI.WebControls.TStyle');
  16 Prado::using('System.Web.UI.WebControls.TWebControlAdapter');
  17 Prado::using('System.Web.UI.WebControls.TWebControlDecorator');
  18
  19 /**
  20  * TWebControl class
  21  *
  22  * TWebControl is the base class for controls that share a common set
  23  * of UI-related properties and methods. TWebControl-derived controls
  24  * are usually associated with HTML tags. They thus have tag name, attributes
  25  * and body contents. You can override {@link getTagName} to specify the tag name,
  26  * {@link addAttributesToRender} to specify the attributes to be rendered,
  27  * and {@link renderContents} to customize the body content rendering.
  28  * TWebControl encapsulates a set of properties related with CSS style fields,
  29  * such as {@link getBackColor BackColor}, {@link getBorderWidth BorderWidth}, etc.
  30  *
  31  * Subclasses of TWebControl typically needs to override {@link addAttributesToRender}
  32  * and {@link renderContents}. The former is used to render the attributes
  33  * of the HTML tag associated with the control, while the latter is to render
  34  * the body contents enclosed within the HTML tag.
  35  *
  36  * @author Qiang Xue <qiang.xue@gmail.com>
  37  * @package System.Web.UI.WebControls
  38  * @since 3.0
  39  */
  40 class TWebControl extends TControl implements IStyleable
  41 {
  42         /**
  43          *      @var boolean ensures the inclusion the id in the tag rendering.
  44          */
  45         private $_ensureid=false;
  46
  47         /**
  48          *      @var TWebControlDecorator this render things before and after both the open and close tag
  49          */
  50         protected $_decorator;
  51
  52
  53         /**
  54          * Subclasses can override getEnsureId or just set this property.  eg. If your subclass
  55          * control does work with javascript and your class wants to flag that it requires an id
  56          * to operate properly.  Once set to true, it stays that way.
  57          * @param boolean pass true to enable enforcement of the tag attribute id.
  58          */
  59         public function setEnsureId($value)
  60         {
  61                 $this->_ensureid |= TPropertyValue::ensureBoolean($value);
  62         }
  63
  64         /**
  65          * @return whether this web control must have an id
  66          */
  67         public function getEnsureId()
  68         {
  69                 return $this->_ensureid;
  70         }
  71
  72         /**
  73          * @return TWebControlDecorator
  74          */
  75         public function getDecorator($create=true)
  76         {
  77                 if($create && !$this->_decorator)
  78                         $this->_decorator = Prado::createComponent('TWebControlDecorator', $this);
  79                 return $this->_decorator;
  80         }
  81
  82         /**
  83          * Copies basic control attributes from another control.
  84          * Properties including AccessKey, ToolTip, TabIndex, Enabled
  85          * and Attributes are copied.
  86          * @param TWebControl source control
  87          */
  88         public function copyBaseAttributes(TWebControl $control)
  89         {
  90                 $this->setAccessKey($control->getAccessKey());
  91                 $this->setToolTip($control->getToolTip());
  92                 $this->setTabIndex($control->getTabIndex());
  93                 if(!$control->getEnabled())
  94                         $this->setEnabled(false);
  95                 if($control->getHasAttributes())
  96                         $this->getAttributes()->copyFrom($control->getAttributes());
  97         }
  98
  99         /**
 100          * @return string the access key of the control
 101          */
 102         public function getAccessKey()
 103         {
 104                 return $this->getViewState('AccessKey','');
 105         }
 106
 107         /**
 108          * Sets the access key of the control.
 109          * Only one-character string can be set, or an exception will be raised.
 110          * Pass in an empty string if you want to disable access key.
 111          * @param string the access key to be set
 112          * @throws TInvalidDataValueException if the access key is specified with more than one character
 113          */
 114         public function setAccessKey($value)
 115         {
 116                 if(strlen($value)>1)
 117                         throw new TInvalidDataValueException('webcontrol_accesskey_invalid',get_class($this),$value);
 118                 $this->setViewState('AccessKey',$value,'');
 119         }
 120
 121         /**
 122          * @return string the background color of the control
 123          */
 124         public function getBackColor()
 125         {
 126                 if($style=$this->getViewState('Style',null))
 127                         return $style->getBackColor();
 128                 else
 129                         return '';
 130         }
 131
 132         /**
 133          * @param string the background color of the control
 134          */
 135         public function setBackColor($value)
 136         {
 137                 $this->getStyle()->setBackColor($value);
 138         }
 139
 140         /**
 141          * @return string the border color of the control
 142          */
 143         public function getBorderColor()
 144         {
 145                 if($style=$this->getViewState('Style',null))
 146                         return $style->getBorderColor();
 147                 else
 148                         return '';
 149         }
 150
 151         /**
 152          * @param string the border color of the control
 153          */
 154         public function setBorderColor($value)
 155         {
 156                 $this->getStyle()->setBorderColor($value);
 157         }
 158
 159         /**
 160          * @return string the border style of the control
 161          */
 162         public function getBorderStyle()
 163         {
 164                 if($style=$this->getViewState('Style',null))
 165                         return $style->getBorderStyle();
 166                 else
 167                         return '';
 168         }
 169
 170         /**
 171          * @param string the border style of the control
 172          */
 173         public function setBorderStyle($value)
 174         {
 175                 $this->getStyle()->setBorderStyle($value);
 176         }
 177
 178         /**
 179          * @return string the border width of the control
 180          */
 181         public function getBorderWidth()
 182         {
 183                 if($style=$this->getViewState('Style',null))
 184                         return $style->getBorderWidth();
 185                 else
 186                         return '';
 187         }
 188
 189         /**
 190          * @param string the border width of the control
 191          */
 192         public function setBorderWidth($value)
 193         {
 194                 $this->getStyle()->setBorderWidth($value);
 195         }
 196
 197         /**
 198          * @return TFont the font of the control
 199          */
 200         public function getFont()
 201         {
 202                 return $this->getStyle()->getFont();
 203         }
 204
 205         /**
 206          * @return string the foreground color of the control
 207          */
 208         public function getForeColor()
 209         {
 210                 if($style=$this->getViewState('Style',null))
 211                         return $style->getForeColor();
 212                 else
 213                         return '';
 214         }
 215
 216         /**
 217          * @param string the foreground color of the control
 218          */
 219         public function setForeColor($value)
 220         {
 221                 $this->getStyle()->setForeColor($value);
 222         }
 223
 224         /**
 225          * @return string the height of the control
 226          */
 227         public function getHeight()
 228         {
 229                 if($style=$this->getViewState('Style',null))
 230                         return $style->getHeight();
 231                 else
 232                         return '';
 233         }
 234
 235         /**
 236          * @param TDisplayStyle display style of the control, default is TDisplayStyle::Fixed
 237          */
 238         public function setDisplay($value)
 239         {
 240                 $this->getStyle()->setDisplayStyle($value);
 241         }
 242
 243         /**
 244          * @return TDisplayStyle display style of the control, default is TDisplayStyle::Fixed
 245          */
 246         public function getDisplay()
 247         {
 248                 return $this->getStyle()->getDisplayStyle();
 249         }
 250
 251         /**
 252          * @param string the css class of the control
 253          */
 254         public function setCssClass($value)
 255         {
 256                 $this->getStyle()->setCssClass($value);
 257         }
 258
 259         /**
 260          * @return string the css class of the control
 261          */
 262         public function getCssClass()
 263         {
 264                 if($style=$this->getViewState('Style',null))
 265                         return $style->getCssClass();
 266                 else
 267                         return '';
 268         }
 269
 270         /**
 271          * @param string the height of the control
 272          */
 273         public function setHeight($value)
 274         {
 275                 $this->getStyle()->setHeight($value);
 276         }
 277
 278         /**
 279          * @return boolean whether the control has defined any style information
 280          */
 281         public function getHasStyle()
 282         {
 283                 return $this->getViewState('Style',null)!==null;
 284         }
 285
 286         /**
 287          * Creates a style object to be used by the control.
 288          * This method may be overriden by controls to provide customized style.
 289          * @return TStyle the default style created for TWebControl
 290          */
 291         protected function createStyle()
 292         {
 293                 return new TStyle;
 294         }
 295
 296         /**
 297          * @return TStyle the object representing the css style of the control
 298          */
 299         public function getStyle()
 300         {
 301                 if($style=$this->getViewState('Style',null))
 302                         return $style;
 303                 else
 304                 {
 305                         $style=$this->createStyle();
 306                         $this->setViewState('Style',$style,null);
 307                         return $style;
 308                 }
 309         }
 310
 311         /**
 312          * Sets the css style string of the control.
 313          * The style string will be prefixed to the styles set via other control properties (e.g. Height, Width).
 314          * @param string the css style string
 315          * @throws TInvalidDataValueException if the parameter is not a string
 316          */
 317         public function setStyle($value)
 318         {
 319                 if(is_string($value))
 320                         $this->getStyle()->setCustomStyle($value);
 321                 else
 322                         throw new TInvalidDataValueException('webcontrol_style_invalid',get_class($this));
 323         }
 324
 325         /**
 326          * Removes all style data.
 327          */
 328         public function clearStyle()
 329         {
 330                 $this->clearViewState('Style');
 331         }
 332
 333         /**
 334          * @return integer the tab index of the control
 335          */
 336         public function getTabIndex()
 337         {
 338                 return $this->getViewState('TabIndex',0);
 339         }
 340
 341         /**
 342          * Sets the tab index of the control.
 343          * Pass 0 if you want to disable tab index.
 344          * @param integer the tab index to be set
 345          */
 346         public function setTabIndex($value)
 347         {
 348                 $this->setViewState('TabIndex',TPropertyValue::ensureInteger($value),0);
 349         }
 350
 351         /**
 352          * Returns the tag name used for this control.
 353          * By default, the tag name is 'span'.
 354          * You can override this method to provide customized tag names.
 355          * @return string tag name of the control to be rendered
 356          */
 357         protected function getTagName()
 358         {
 359                 return 'span';
 360         }
 361
 362         /**
 363          * @return string the tooltip of the control
 364          */
 365         public function getToolTip()
 366         {
 367                 return $this->getViewState('ToolTip','');
 368         }
 369
 370         /**
 371          * Sets the tooltip of the control.
 372          * Pass an empty string if you want to disable tooltip.
 373          * @param string the tooltip to be set
 374          */
 375         public function setToolTip($value)
 376         {
 377                 $this->setViewState('ToolTip',$value,'');
 378         }
 379
 380         /**
 381          * @return string the width of the control
 382          */
 383         public function getWidth()
 384         {
 385                 if($style=$this->getViewState('Style',null))
 386                         return $style->getWidth();
 387                 else
 388                         return '';
 389         }
 390
 391         /**
 392          * @param string the width of the control
 393          */
 394         public function setWidth($value)
 395         {
 396                 $this->getStyle()->setWidth($value);
 397         }
 398
 399
 400         /**
 401          * If your subclass overrides the onPreRender method be sure to call
 402          * this method through parent::onPreRender($param); so your sub-class can be decorated,
 403          * among other things.
 404          * @param TEventParameter event parameter to be passed to the event handlers
 405          */
 406         public function onPreRender($param) {
 407                 if($decorator = $this->getDecorator(false))
 408                         $decorator->instantiate();
 409
 410                 parent::onPreRender($param);
 411         }
 412
 413         /**
 414          * Adds attribute name-value pairs to renderer.
 415          * By default, the method will render 'id', 'accesskey', 'disabled',
 416          * 'tabindex', 'title' and all custom attributes.
 417          * The method can be overriden to provide customized attribute rendering.
 418          * @param THtmlWriter the writer used for the rendering purpose
 419          */
 420         protected function addAttributesToRender($writer)
 421         {
 422                 if($this->getID()!=='' || $this->getEnsureId())
 423                         $writer->addAttribute('id',$this->getClientID());
 424                 if(($accessKey=$this->getAccessKey())!=='')
 425                         $writer->addAttribute('accesskey',$accessKey);
 426                 if(!$this->getEnabled())
 427                         $writer->addAttribute('disabled','disabled');
 428                 if(($tabIndex=$this->getTabIndex())>0)
 429                         $writer->addAttribute('tabindex',"$tabIndex");
 430                 if(($toolTip=$this->getToolTip())!=='')
 431                         $writer->addAttribute('title',$toolTip);
 432                 if($style=$this->getViewState('Style',null))
 433                         $style->addAttributesToRender($writer);
 434                 if($this->getHasAttributes())
 435                 {
 436                         foreach($this->getAttributes() as $name=>$value)
 437                                 $writer->addAttribute($name,$value);
 438                 }
 439         }
 440
 441         /**
 442          * Renders the control.
 443          * This method overrides the parent implementation by replacing it with
 444          * the following sequence:
 445          * - {@link renderBeginTag}
 446          * - {@link renderContents}
 447          * - {@link renderEndTag}
 448          * @param THtmlWriter the writer used for the rendering purpose
 449          */
 450         public function render($writer)
 451         {
 452                 $this->renderBeginTag($writer);
 453                 $this->renderContents($writer);
 454                 $this->renderEndTag($writer);
 455         }
 456
 457         /**
 458          * Renders the openning tag for the control (including attributes)
 459          * @param THtmlWriter the writer used for the rendering purpose
 460          */
 461         public function renderBeginTag($writer)
 462         {
 463                 if($decorator = $this->getDecorator(false)) {
 464                         $decorator->renderPreTagText($writer);
 465                         $this->addAttributesToRender($writer);
 466                         $writer->renderBeginTag($this->getTagName());
 467                         $decorator->renderPreContentsText($writer);
 468                 } else {
 469                         $this->addAttributesToRender($writer);
 470                         $writer->renderBeginTag($this->getTagName());
 471                 }
 472         }
 473
 474         /**
 475          * Renders the body content enclosed between the control tag.
 476          * By default, child controls and text strings will be rendered.
 477          * You can override this method to provide customized content rendering.
 478          * @param THtmlWriter the writer used for the rendering purpose
 479          */
 480         public function renderContents($writer)
 481         {
 482                 parent::renderChildren($writer);
 483         }
 484
 485         /**
 486          * Renders the closing tag for the control
 487          * @param THtmlWriter the writer used for the rendering purpose
 488          */
 489         public function renderEndTag($writer)
 490         {
 491                 if($decorator = $this->getDecorator(false)) {
 492                         $decorator->renderPostContentsText($writer);
 493                         $writer->renderEndTag();
 494                         $decorator->renderPostTagText($writer);
 495                 } else
 496                         $writer->renderEndTag($writer);
 497         }
 498 }