[Sommaire] [Imprimer]

   1  <?php
   2  /**
   3   * TImageButton class file
   4   *
   5   * @author Qiang Xue <qiang.xue@gmail.com>
   6   * @link http://www.pradosoft.com/
   7   * @copyright Copyright &copy; 2005 PradoSoft
   8   * @license http://www.pradosoft.com/license/
   9   * @version $Id: TImageButton.php 1397 2006-09-07 07:55:53Z wei $
  10   * @package System.Web.UI.WebControls
  11   */
  12  
  13  /**
  14   * Includes TImage class file
  15   */
  16  Prado::using('System.Web.UI.WebControls.TImage');
  17  
  18  /**
  19   * TImageButton class
  20   *
  21   * TImageButton creates an image button on the page. It is used to submit data to a page.
  22   * You can create either a <b>submit</b> button or a <b>command</b> button.
  23   *
  24   * A <b>command</b> button has a command name (specified by
  25   * the {@link setCommandName CommandName} property) and and a command parameter
  26   * (specified by {@link setCommandParameter CommandParameter} property)
  27   * associated with the button. This allows you to create multiple TLinkButton
  28   * components on a Web page and programmatically determine which one is clicked
  29   * with what parameter. You can provide an event handler for
  30   * {@link onCommand OnCommand} event to programmatically control the actions performed
  31   * when the command button is clicked. In the event handler, you can determine
  32   * the {@link setCommandName CommandName} property value and
  33   * the {@link setCommandParameter CommandParameter} property value
  34   * through the {@link TCommandParameter::getName Name} and
  35   * {@link TCommandParameter::getParameter Parameter} properties of the event
  36   * parameter which is of type {@link TCommandEventParameter}.
  37   *
  38   * A <b>submit</b> button does not have a command name associated with the button
  39   * and clicking on it simply posts the Web page back to the server.
  40   * By default, a TImageButton control is a submit button.
  41   * You can provide an event handler for the {@link onClick OnClick} event
  42   * to programmatically control the actions performed when the submit button is clicked.
  43   * The coordinates of the clicking point can be obtained from the {@link onClick OnClick}
  44   * event parameter, which is of type {@link TImageClickEventParameter}.
  45   *
  46   * Clicking on button can trigger form validation, if
  47   * {@link setCausesValidation CausesValidation} is true.
  48   * And the validation may be restricted within a certain group of validator
  49   * controls by setting {@link setValidationGroup ValidationGroup} property.
  50   * If validation is successful, the data will be post back to the same page.
  51   *
  52   * TImageButton displays the {@link setText Text} property as the hint text to the displayed image.
  53   *
  54   * @author Qiang Xue <qiang.xue@gmail.com>
  55   * @version $Id: TImageButton.php 1397 2006-09-07 07:55:53Z wei $
  56   * @package System.Web.UI.WebControls
  57   * @since 3.0
  58   */
  59  class TImageButton extends TImage implements IPostBackDataHandler, IPostBackEventHandler, IButtonControl
  60  {
  61      /**
  62       * @var integer x coordinate that the image is being clicked at
  63       */
  64      private $_x=0;
  65      /**
  66       * @var integer y coordinate that the image is being clicked at
  67       */
  68      private $_y=0;
  69  
  70      /**
  71       * @return string tag name of the button
  72       */
  73  	protected function getTagName()
  74      {
  75          return 'input';
  76      }
  77  
  78      /**
  79       * Adds attribute name-value pairs to renderer.
  80       * This overrides the parent implementation with additional button specific attributes.
  81       * @param THtmlWriter the writer used for the rendering purpose
  82       */
  83  	protected function addAttributesToRender($writer)
  84      {
  85          $page=$this->getPage();
  86          $page->ensureRenderInForm($this);
  87          $writer->addAttribute('type','image');
  88          if(($uniqueID=$this->getUniqueID())!=='')
  89              $writer->addAttribute('name',$uniqueID);
  90          if($this->getEnabled(true))
  91          {
  92              if($this->canCauseValidation())
  93              {
  94                  $writer->addAttribute('id',$this->getClientID());
  95                  $this->getPage()->getClientScript()->registerPostBackControl('Prado.WebUI.TImageButton',$this->getPostBackOptions());
  96              }
  97          }
  98          else if($this->getEnabled()) // in this case, parent will not render 'disabled'
  99              $writer->addAttribute('disabled','disabled');
 100          parent::addAttributesToRender($writer);
 101      }
 102  
 103      /**
 104       * @return boolean whether to perform validation if the button is clicked
 105       */
 106  	protected function canCauseValidation()
 107      {
 108          if($this->getCausesValidation())
 109          {
 110              $group=$this->getValidationGroup();
 111              return $this->getPage()->getValidators($group)->getCount()>0;
 112          }
 113          else
 114              return false;
 115      }
 116  
 117      /**
 118       * Returns postback specifications for the button.
 119       * This method is used by framework and control developers.
 120       * @return array parameters about how the button defines its postback behavior.
 121       */
 122  	protected function getPostBackOptions()
 123      {
 124          $options['ID'] = $this->getClientID();
 125          $options['CausesValidation'] = $this->getCausesValidation();
 126          $options['ValidationGroup'] = $this->getValidationGroup();
 127          $options['EventTarget'] = $this->getUniqueID();
 128  
 129          return $options;
 130      }
 131  
 132      /**
 133       * This method checks if the TImageButton is clicked and loads the coordinates of the clicking position.
 134       * This method is primarly used by framework developers.
 135       * @param string the key that can be used to retrieve data from the input data collection
 136       * @param array the input data collection
 137       * @return boolean whether the data of the component has been changed
 138       */
 139  	public function loadPostData($key,$values)
 140      {
 141          $uid=$this->getUniqueID();
 142          if(isset($values["{$uid}_x"]) && isset($values["{$uid}_y"]))
 143          {
 144              $this->_x=intval($values["{$uid}_x"]);
 145              $this->_y=intval($values["{$uid}_y"]);
 146              $this->getPage()->setPostBackEventTarget($this);
 147          }
 148          return false;
 149      }
 150  
 151      /**
 152       * A dummy implementation for the IPostBackDataHandler interface.
 153       */
 154  	public function raisePostDataChangedEvent()
 155      {
 156          // no post data to handle
 157      }
 158  
 159      /**
 160       * This method is invoked when the button is clicked.
 161       * The method raises 'OnClick' event to fire up the event handlers.
 162       * If you override this method, be sure to call the parent implementation
 163       * so that the event handler can be invoked.
 164       * @param TImageClickEventParameter event parameter to be passed to the event handlers
 165       */
 166  	public function onClick($param)
 167      {
 168          $this->raiseEvent('OnClick',$this,$param);
 169      }
 170  
 171      /**
 172       * This method is invoked when the button is clicked.
 173       * The method raises 'OnCommand' event to fire up the event handlers.
 174       * If you override this method, be sure to call the parent implementation
 175       * so that the event handlers can be invoked.
 176       * @param TCommandEventParameter event parameter to be passed to the event handlers
 177       */
 178  	public function onCommand($param)
 179      {
 180          $this->raiseEvent('OnCommand',$this,$param);
 181          $this->raiseBubbleEvent($this,$param);
 182      }
 183  
 184      /**
 185       * Raises the postback event.
 186       * This method is required by {@link IPostBackEventHandler} interface.
 187       * If {@link getCausesValidation CausesValidation} is true, it will
 188       * invoke the page's {@link TPage::validate validate} method first.
 189       * It will raise {@link onClick OnClick} and {@link onCommand OnCommand} events.
 190       * This method is mainly used by framework and control developers.
 191       * @param TEventParameter the event parameter
 192       */
 193  	public function raisePostBackEvent($param)
 194      {
 195          if($this->getCausesValidation())
 196              $this->getPage()->validate($this->getValidationGroup());
 197          $this->onClick(new TImageClickEventParameter($this->_x,$this->_y));
 198          $this->onCommand(new TCommandEventParameter($this->getCommandName(),$this->getCommandParameter()));
 199      }
 200  
 201      /**
 202       * @return boolean whether postback event trigger by this button will cause input validation, default is true
 203       */
 204  	public function getCausesValidation()
 205      {
 206          return $this->getViewState('CausesValidation',true);
 207      }
 208  
 209      /**
 210       * @param boolean whether postback event trigger by this button will cause input validation
 211       */
 212  	public function setCausesValidation($value)
 213      {
 214          $this->setViewState('CausesValidation',TPropertyValue::ensureBoolean($value),true);
 215      }
 216  
 217      /**
 218       * @return string the command name associated with the {@link onCommand OnCommand} event.
 219       */
 220  	public function getCommandName()
 221      {
 222          return $this->getViewState('CommandName','');
 223      }
 224  
 225      /**
 226       * @param string the command name associated with the {@link onCommand OnCommand} event.
 227       */
 228  	public function setCommandName($value)
 229      {
 230          $this->setViewState('CommandName',$value,'');
 231      }
 232  
 233      /**
 234       * @return string the parameter associated with the {@link onCommand OnCommand} event
 235       */
 236  	public function getCommandParameter()
 237      {
 238          return $this->getViewState('CommandParameter','');
 239      }
 240  
 241      /**
 242       * @param string the parameter associated with the {@link onCommand OnCommand} event.
 243       */
 244  	public function setCommandParameter($value)
 245      {
 246          $this->setViewState('CommandParameter',$value,'');
 247      }
 248  
 249      /**
 250       * @return string the group of validators which the button causes validation upon postback
 251       */
 252  	public function getValidationGroup()
 253      {
 254          return $this->getViewState('ValidationGroup','');
 255      }
 256  
 257      /**
 258       * @param string the group of validators which the button causes validation upon postback
 259       */
 260  	public function setValidationGroup($value)
 261      {
 262          $this->setViewState('ValidationGroup',$value,'');
 263      }
 264  
 265      /**
 266       * @return string caption of the button
 267       */
 268  	public function getText()
 269      {
 270          return $this->getAlternateText();
 271      }
 272  
 273      /**
 274       * @param string caption of the button
 275       */
 276  	public function setText($value)
 277      {
 278          $this->setAlternateText($value);
 279      }
 280  
 281      /**
 282       * Registers the image button to receive postback data during postback.
 283       * This is necessary because an image button, when postback, does not have
 284       * direct mapping between post data and the image button name.
 285       * This method overrides the parent implementation and is invoked before render.
 286       * @param mixed event parameter
 287       */
 288  	public function onPreRender($param)
 289      {
 290          parent::onPreRender($param);
 291          $this->getPage()->registerRequiresPostData($this);
 292      }
 293  
 294      /**
 295       * Renders the body content enclosed between the control tag.
 296       * This overrides the parent implementation with nothing to be rendered.
 297       * @param THtmlWriter the writer used for the rendering purpose
 298       */
 299  	public function renderContents($writer)
 300      {
 301      }
 302  }
 303  
 304  /**
 305   * TImageClickEventParameter class
 306   *
 307   * TImageClickEventParameter encapsulates the parameter data for
 308   * {@link TImageButton::onClick Click} event of {@link TImageButton} controls.
 309   *
 310   * @author Qiang Xue <qiang.xue@gmail.com>
 311   * @version $Id: TImageButton.php 1397 2006-09-07 07:55:53Z wei $
 312   * @package System.Web.UI.WebControls
 313   * @since 3.0
 314   */
 315  class TImageClickEventParameter extends TEventParameter
 316  {
 317      /**
 318       * the X coordinate of the clicking point
 319       * @var integer
 320       */
 321      public $_x=0;
 322      /**
 323       * the Y coordinate of the clicking point
 324       * @var integer
 325       */
 326      public $_y=0;
 327  
 328      /**
 329       * Constructor.
 330       * @param integer X coordinate of the clicking point
 331       * @param integer Y coordinate of the clicking point
 332       */
 333  	public function __construct($x,$y)
 334      {
 335          $this->_x=$x;
 336          $this->_y=$y;
 337      }
 338  
 339      /**
 340       * @return integer X coordinate of the clicking point, defaults to 0
 341       */
 342  	public function getX()
 343      {
 344          return $this->_x;
 345      }
 346  
 347      /**
 348       * @param integer X coordinate of the clicking point
 349       */
 350  	public function setX($value)
 351      {
 352          $this->_x=TPropertyValue::ensureInteger($value);
 353      }
 354  
 355      /**
 356       * @return integer Y coordinate of the clicking point, defaults to 0
 357       */
 358  	public function getY()
 359      {
 360          return $this->_y;
 361      }
 362  
 363      /**
 364       * @param integer Y coordinate of the clicking point
 365       */
 366  	public function setY($value)
 367      {
 368          $this->_y=TPropertyValue::ensureInteger($value);
 369      }
 370  }
 371  
 372  ?>