[Sommaire] [Imprimer]

   1  <?php
   2  /**
   3   * TListControl 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: TListControl.php 1397 2006-09-07 07:55:53Z wei $
  10   * @package System.Web.UI.WebControls
  11   */
  12  
  13  /**
  14   * Includes the supporting classes
  15   */
  16  Prado::using('System.Web.UI.WebControls.TDataBoundControl');
  17  Prado::using('System.Web.UI.WebControls.TListItem');
  18  Prado::using('System.Collections.TAttributeCollection');
  19  Prado::using('System.Util.TDataFieldAccessor');
  20  
  21  
  22  /**
  23   * TListControl class
  24   *
  25   * TListControl is a base class for list controls, such as {@link TListBox},
  26   * {@link TDropDownList}, {@link TCheckBoxList}, etc.
  27   * It manages the items and their status in a list control.
  28   * It also implements how the items can be populated from template and
  29   * data source.
  30   *
  31   * The property {@link getItems} returns a list of the items in the control.
  32   * To specify or determine which item is selected, use the
  33   * {@link getSelectedIndex SelectedIndex} property that indicates the zero-based
  34   * index of the selected item in the item list. You may also use
  35   * {@link getSelectedItem SelectedItem} and {@link getSelectedValue SelectedValue}
  36   * to get the selected item and its value. For multiple selection lists
  37   * (such as {@link TCheckBoxList} and {@link TListBox}), property
  38   * {@link getSelectedIndices SelectedIndices} is useful.
  39   *
  40   * TListControl implements {@link setAutoPostBack AutoPostBack} which allows
  41   * a list control to postback the page if the selections of the list items are changed.
  42   * The {@link setCausesValidation CausesValidation} and {@link setValidationGroup ValidationGroup}
  43   * properties may be used to specify that validation be performed when auto postback occurs.
  44   *
  45   * There are three ways to populate the items in a list control: from template,
  46   * using {@link setDataSource DataSource} and using {@link setDataSourceID DataSourceID}.
  47   * The latter two are covered in {@link TDataBoundControl}. To specify items via
  48   * template, using the following template syntax:
  49   * <code>
  50   * <com:TListControl>
  51   *   <com:TListItem Value="xxx" Text="yyy" >
  52   *   <com:TListItem Value="xxx" Text="yyy" Selected="true" >
  53   *   <com:TListItem Value="xxx" Text="yyy" >
  54   * </com:TListControl>
  55   * </code>
  56   *
  57   * When {@link setDataSource DataSource} or {@link setDataSourceID DataSourceID}
  58   * is used to populate list items, the {@link setDataTextField DataTextField} and
  59   * {@link setDataValueField DataValueField} properties are used to specify which
  60   * columns of the data will be used to populate the text and value of the items.
  61   * For example, if a data source is as follows,
  62   * <code>
  63   * $dataSource=array(
  64   *    array('name'=>'John', 'age'=>31),
  65   *    array('name'=>'Cary', 'age'=>28),
  66   *    array('name'=>'Rose', 'age'=>35),
  67   * );
  68   * </code>
  69   * setting {@link setDataTextField DataTextField} and {@link setDataValueField DataValueField}
  70   * to 'name' and 'age' will make the first item's text be 'John', value be 31,
  71   * the second item's text be 'Cary', value be 28, and so on.
  72   * The {@link setDataTextFormatString DataTextFormatString} property may be further
  73   * used to format how the item should be displayed. See {@link formatDataValue()}
  74   * for an explanation of the format string.
  75   *
  76   * @author Qiang Xue <qiang.xue@gmail.com>
  77   * @version $Id: TListControl.php 1397 2006-09-07 07:55:53Z wei $
  78   * @package System.Web.UI.WebControls
  79   * @since 3.0
  80   */
  81  abstract class TListControl extends TDataBoundControl
  82  {
  83      /**
  84       * @var TListItemCollection item list
  85       */
  86      private $_items=null;
  87      /**
  88       * @var boolean whether items are restored from viewstate
  89       */
  90      private $_stateLoaded=false;
  91      /**
  92       * @var mixed the following selection variables are used
  93       * to keep selections when Items are not available
  94       */
  95      private $_cachedSelectedIndex=-1;
  96      private $_cachedSelectedValue=null;
  97      private $_cachedSelectedIndices=null;
  98      private $_cachedSelectedValues=null;
  99  
 100      /**
 101       * @return string tag name of the list control
 102       */
 103  	protected function getTagName()
 104      {
 105          return 'select';
 106      }
 107  
 108      /**
 109       * Adds attributes to renderer.
 110       * @param THtmlWriter the renderer
 111       */
 112  	protected function addAttributesToRender($writer)
 113      {
 114          $page=$this->getPage();
 115          $page->ensureRenderInForm($this);
 116          if($this->getIsMultiSelect())
 117              $writer->addAttribute('multiple','multiple');
 118          if($this->getEnabled(true) && $this->getAutoPostBack() && $page->getClientSupportsJavaScript())
 119          {
 120              $writer->addAttribute('id',$this->getClientID());
 121              $this->getPage()->getClientScript()->registerPostBackControl($this->getClientClassName(),$this->getPostBackOptions());
 122          }
 123          if(!$this->getEnabled(true) && $this->getEnabled())
 124              $writer->addAttribute('disabled','disabled');
 125          parent::addAttributesToRender($writer);
 126      }
 127  
 128      /**
 129       * Gets the name of the javascript class responsible for performing postback for this control.
 130       * Derived classes may override this method and return customized js class names.
 131       * @return string the javascript class name
 132       */
 133  	protected function getClientClassName()
 134      {
 135          return 'Prado.WebUI.TListControl';
 136      }
 137  
 138      /**
 139       * @return array postback options for JS postback code
 140       */
 141  	protected function getPostBackOptions()
 142      {
 143          $options['ID'] = $this->getClientID();
 144          $options['CausesValidation'] = $this->getCausesValidation();
 145          $options['ValidationGroup'] = $this->getValidationGroup();
 146          $options['EventTarget'] = $this->getUniqueID();
 147          return $options;
 148      }
 149  
 150      /**
 151       * Adds object parsed from template to the control.
 152       * This method adds only {@link TListItem} objects into the {@link getItems Items} collection.
 153       * All other objects are ignored.
 154       * @param mixed object parsed from template
 155       */
 156  	public function addParsedObject($object)
 157      {
 158          // Do not add items from template if items are loaded from viewstate
 159          if(!$this->_stateLoaded && ($object instanceof TListItem))
 160          {
 161              $index=$this->getItems()->add($object);
 162              if(($this->_cachedSelectedValue!==null && $this->_cachedSelectedValue===$object->getValue()) || ($this->_cachedSelectedIndex===$index))
 163              {
 164                  $object->setSelected(true);
 165                  $this->_cachedSelectedValue=null;
 166                  $this->_cachedSelectedIndex=-1;
 167              }
 168          }
 169      }
 170  
 171      /**
 172       * Performs databinding to populate list items from data source.
 173       * This method is invoked by dataBind().
 174       * You may override this function to provide your own way of data population.
 175       * @param Traversable the data
 176       */
 177  	protected function performDataBinding($data)
 178      {
 179          $items=$this->getItems();
 180          if(!$this->getAppendDataBoundItems())
 181              $items->clear();
 182          $textField=$this->getDataTextField();
 183          if($textField==='')
 184              $textField=0;
 185          $valueField=$this->getDataValueField();
 186          if($valueField==='')
 187              $valueField=1;
 188          $textFormat=$this->getDataTextFormatString();
 189          $groupField=$this->getDataGroupField();
 190          foreach($data as $key=>$object)
 191          {
 192              $item=$items->createListItem();
 193              if(is_array($object) || is_object($object))
 194              {
 195                  $text=TDataFieldAccessor::getDataFieldValue($object,$textField);
 196                  $value=TDataFieldAccessor::getDataFieldValue($object,$valueField);
 197                  $item->setValue($value);
 198                  if($groupField!=='')
 199                      $item->setAttribute('Group',TDataFieldAccessor::getDataFieldValue($object,$groupField));
 200              }
 201              else
 202              {
 203                  $text=$object;
 204                  $item->setValue("$key");
 205              }
 206              $item->setText($this->formatDataValue($textFormat,$text));
 207          }
 208          // SelectedValue or SelectedIndex may be set before databinding
 209          // so we make them be effective now
 210          if($this->_cachedSelectedValue!==null)
 211          {
 212              $this->setSelectedValue($this->_cachedSelectedValue);
 213              $this->resetCachedSelections();
 214          }
 215          else if($this->_cachedSelectedIndex!==-1)
 216          {
 217              $this->setSelectedIndex($this->_cachedSelectedIndex);
 218              $this->resetCachedSelections();
 219          }
 220          else if($this->_cachedSelectedValues!==null)
 221          {
 222              $this->setSelectedValues($this->_cachedSelectedValues);
 223              $this->resetCachedSelections();
 224          }
 225          else if($this->_cachedSelectedIndices!==null)
 226          {
 227              $this->setSelectedIndices($this->_cachedSelectedIndices);
 228              $this->resetCachedSelections();
 229          }
 230      }
 231  
 232  	private function resetCachedSelections()
 233      {
 234          $this->_cachedSelectedValue=null;
 235          $this->_cachedSelectedIndex=-1;
 236          $this->_cachedSelectedValues=null;
 237          $this->_cachedSelectedIndices=null;
 238      }
 239  
 240      /**
 241       * Creates a collection object to hold list items.
 242       * This method may be overriden to create a customized collection.
 243       * @return TListItemCollection the collection object
 244       */
 245  	protected function createListItemCollection()
 246      {
 247          return new TListItemCollection;
 248      }
 249  
 250      /**
 251       * Saves items into viewstate.
 252       * This method is invoked right before control state is to be saved.
 253       */
 254  	public function saveState()
 255      {
 256          parent::saveState();
 257          if($this->_items)
 258              $this->setViewState('Items',$this->_items->saveState(),null);
 259          else
 260              $this->clearViewState('Items');
 261      }
 262  
 263      /**
 264       * Loads items from viewstate.
 265       * This method is invoked right after control state is loaded.
 266       */
 267  	public function loadState()
 268      {
 269          parent::loadState();
 270          $this->_stateLoaded=true;
 271          if(!$this->getIsDataBound())
 272          {
 273              $this->_items=$this->createListItemCollection();
 274              $this->_items->loadState($this->getViewState('Items',null));
 275          }
 276          $this->clearViewState('Items');
 277      }
 278  
 279      /**
 280       * @return boolean whether this is a multiselect control. Defaults to false.
 281       */
 282  	protected function getIsMultiSelect()
 283      {
 284          return false;
 285      }
 286  
 287      /**
 288       * @return boolean whether performing databind should append items or clear the existing ones. Defaults to false.
 289       */
 290  	public function getAppendDataBoundItems()
 291      {
 292          return $this->getViewState('AppendDataBoundItems',false);
 293      }
 294  
 295      /**
 296       * @param boolean whether performing databind should append items or clear the existing ones.
 297       */
 298  	public function setAppendDataBoundItems($value)
 299      {
 300          $this->setViewState('AppendDataBoundItems',TPropertyValue::ensureBoolean($value),false);
 301      }
 302  
 303      /**
 304       * @return boolean a value indicating whether an automatic postback to the server
 305       * will occur whenever the user makes change to the list control and then tabs out of it.
 306       * Defaults to false.
 307       */
 308  	public function getAutoPostBack()
 309      {
 310          return $this->getViewState('AutoPostBack',false);
 311      }
 312  
 313      /**
 314       * Sets the value indicating if postback automatically.
 315       * An automatic postback to the server will occur whenever the user
 316       * makes change to the list control and then tabs out of it.
 317       * @param boolean the value indicating if postback automatically
 318       */
 319  	public function setAutoPostBack($value)
 320      {
 321          $this->setViewState('AutoPostBack',TPropertyValue::ensureBoolean($value),false);
 322      }
 323  
 324      /**
 325       * @return boolean whether postback event trigger by this list control will cause input validation, default is true.
 326       */
 327  	public function getCausesValidation()
 328      {
 329          return $this->getViewState('CausesValidation',true);
 330      }
 331  
 332      /**
 333       * @param boolean whether postback event trigger by this list control will cause input validation.
 334       */
 335  	public function setCausesValidation($value)
 336      {
 337          $this->setViewState('CausesValidation',TPropertyValue::ensureBoolean($value),true);
 338      }
 339  
 340      /**
 341       * @return string the field of the data source that provides the text content of the list items.
 342       */
 343  	public function getDataTextField()
 344      {
 345          return $this->getViewState('DataTextField','');
 346      }
 347  
 348      /**
 349       * @param string the field of the data source that provides the text content of the list items.
 350       */
 351  	public function setDataTextField($value)
 352      {
 353          $this->setViewState('DataTextField',$value,'');
 354      }
 355  
 356      /**
 357       * @return string the formatting string used to control how data bound to the list control is displayed.
 358       */
 359  	public function getDataTextFormatString()
 360      {
 361          return $this->getViewState('DataTextFormatString','');
 362      }
 363  
 364      /**
 365       * Sets data text format string.
 366       * The format string is used in {@link TDataValueFormatter::format()} to format the Text property value
 367       * of each item in the list control.
 368       * @param string the formatting string used to control how data bound to the list control is displayed.
 369       * @see TDataValueFormatter::format()
 370       */
 371  	public function setDataTextFormatString($value)
 372      {
 373          $this->setViewState('DataTextFormatString',$value,'');
 374      }
 375  
 376      /**
 377       * @return string the field of the data source that provides the value of each list item.
 378       */
 379  	public function getDataValueField()
 380      {
 381          return $this->getViewState('DataValueField','');
 382      }
 383  
 384      /**
 385       * @param string the field of the data source that provides the value of each list item.
 386       */
 387  	public function setDataValueField($value)
 388      {
 389          $this->setViewState('DataValueField',$value,'');
 390      }
 391  
 392      /**
 393       * @return string the field of the data source that provides the label of the list item groups
 394       */
 395  	public function getDataGroupField()
 396      {
 397          return $this->getViewState('DataGroupField','');
 398      }
 399  
 400      /**
 401       * @param string the field of the data source that provides the label of the list item groups
 402       */
 403  	public function setDataGroupField($value)
 404      {
 405          $this->setViewState('DataGroupField',$value,'');
 406      }
 407  
 408      /**
 409       * @return integer the number of items in the list control
 410       */
 411  	public function getItemCount()
 412      {
 413          return $this->_items?$this->_items->getCount():0;
 414      }
 415  
 416      /**
 417       * @return boolean whether the list control contains any items.
 418       */
 419  	public function getHasItems()
 420      {
 421          return ($this->_items && $this->_items->getCount()>0);
 422      }
 423  
 424      /**
 425       * @return TListItemCollection the item collection
 426       */
 427  	public function getItems()
 428      {
 429          if(!$this->_items)
 430              $this->_items=$this->createListItemCollection();
 431          return $this->_items;
 432      }
 433  
 434      /**
 435       * @return integer the index (zero-based) of the item being selected, -1 if no item is selected.
 436       */
 437  	public function getSelectedIndex()
 438      {
 439          if($this->_items)
 440          {
 441              $n=$this->_items->getCount();
 442              for($i=0;$i<$n;++$i)
 443                  if($this->_items->itemAt($i)->getSelected())
 444                      return $i;
 445          }
 446          return -1;
 447      }
 448  
 449      /**
 450       * @param integer the index (zero-based) of the item to be selected
 451       */
 452  	public function setSelectedIndex($index)
 453      {
 454          if(($index=TPropertyValue::ensureInteger($index))<0)
 455              $index=-1;
 456          if($this->_items)
 457          {
 458              $this->clearSelection();
 459              if($index>=0 && $index<$this->_items->getCount())
 460                  $this->_items->itemAt($index)->setSelected(true);
 461              else if($index!==-1)
 462                  throw new TInvalidDataValueException('listcontrol_selectedindex_invalid',get_class($this),$index);
 463          }
 464          $this->_cachedSelectedIndex=$index;
 465      }
 466  
 467      /**
 468       * @return array list of index of items that are selected
 469       */
 470  	public function getSelectedIndices()
 471      {
 472          $selections=array();
 473          if($this->_items)
 474          {
 475              $n=$this->_items->getCount();
 476              for($i=0;$i<$n;++$i)
 477                  if($this->_items->itemAt($i)->getSelected())
 478                      $selections[]=$i;
 479          }
 480          return $selections;
 481      }
 482  
 483      /**
 484       * @param array list of index of items to be selected
 485       */
 486  	public function setSelectedIndices($indices)
 487      {
 488          if($this->getIsMultiSelect())
 489          {
 490              if($this->_items)
 491              {
 492                  $this->clearSelection();
 493                  $n=$this->_items->getCount();
 494                  foreach($indices as $index)
 495                  {
 496                      if($index>=0 && $index<$n)
 497                          $this->_items->itemAt($index)->setSelected(true);
 498                  }
 499              }
 500              $this->_cachedSelectedIndices=$indices;
 501          }
 502          else
 503              throw new TNotSupportedException('listcontrol_multiselect_unsupported',get_class($this));
 504      }
 505  
 506      /**
 507       * @return TListItem|null the selected item with the lowest cardinal index, null if no item is selected.
 508       */
 509  	public function getSelectedItem()
 510      {
 511          if(($index=$this->getSelectedIndex())>=0)
 512              return $this->_items->itemAt($index);
 513          else
 514              return null;
 515      }
 516  
 517      /**
 518       * @return string the value of the selected item with the lowest cardinal index, empty if no selection
 519       */
 520  	public function getSelectedValue()
 521      {
 522          $index=$this->getSelectedIndex();
 523          return $index>=0?$this->getItems()->itemAt($index)->getValue():'';
 524      }
 525  
 526      /**
 527       * Sets selection by item value.
 528       * Existing selections will be cleared if the item value is found in the item collection.
 529       * Note, if the value is null, existing selections will also be cleared.
 530       * @param string the value of the item to be selected.
 531       */
 532  	public function setSelectedValue($value)
 533      {
 534          if($this->_items)
 535          {
 536              if($value===null)
 537                  $this->clearSelection();
 538              else if(($item=$this->_items->findItemByValue($value))!==null)
 539              {
 540                  $this->clearSelection();
 541                  $item->setSelected(true);
 542              }
 543              else
 544                  throw new TInvalidDataValueException('listcontrol_selectedvalue_invalid',get_class($this),$value);
 545          }
 546          $this->_cachedSelectedValue=$value;
 547      }
 548  
 549  
 550      /**
 551       * @return array list of the selected item values (strings)
 552       */
 553  	public function getSelectedValues()
 554      {
 555          $values=array();
 556          if($this->_items)
 557          {
 558              foreach($this->_items as $item)
 559              {
 560                  if($item->getSelected())
 561                      $values[]=$item->getValue();
 562              }
 563          }
 564          return $values;
 565      }
 566  
 567      /**
 568       * @param array list of the selected item values
 569       */
 570  	public function setSelectedValues($values)
 571      {
 572          if($this->getIsMultiSelect())
 573          {
 574              if($this->_items)
 575              {
 576                  $this->clearSelection();
 577                  $lookup=array();
 578                  foreach($this->_items as $item)
 579                      $lookup[$item->getValue()]=$item;
 580                  foreach($values as $value)
 581                  {
 582                      if(isset($lookup["$value"]))
 583                          $lookup["$value"]->setSelected(true);
 584                      else
 585                          throw new TInvalidDataValueException('listcontrol_selectedvalue_invalid',get_class($this),$value);
 586                  }
 587              }
 588              $this->_cachedSelectedValues=$values;
 589          }
 590          else
 591              throw new TNotSupportedException('listcontrol_multiselect_unsupported',get_class($this));
 592      }
 593  
 594      /**
 595       * @return string selected value
 596       */
 597      public function getText()
 598      {
 599          return $this->getSelectedValue();
 600      }
 601  
 602      /**
 603       * @param string value to be selected
 604       */
 605      public function setText($value)
 606      {
 607          $this->setSelectedValue($value);
 608      }
 609  
 610      /**
 611       * Clears all existing selections.
 612       */
 613      public function clearSelection()
 614      {
 615          if($this->_items)
 616          {
 617              foreach($this->_items as $item)
 618                  $item->setSelected(false);
 619          }
 620      }
 621  
 622      /**
 623       * @return string the group of validators which the list control causes validation upon postback
 624       */
 625  	public function getValidationGroup()
 626      {
 627          return $this->getViewState('ValidationGroup','');
 628      }
 629  
 630      /**
 631       * @param string the group of validators which the list control causes validation upon postback
 632       */
 633  	public function setValidationGroup($value)
 634      {
 635          $this->setViewState('ValidationGroup',$value,'');
 636      }
 637  
 638      /**
 639       * Raises OnSelectedIndexChanged event when selection is changed.
 640       * This method is invoked when the list control has its selection changed
 641       * by end-users.
 642       * @param TEventParameter event parameter
 643       */
 644  	public function onSelectedIndexChanged($param)
 645      {
 646          $this->raiseEvent('OnSelectedIndexChanged',$this,$param);
 647          $this->onTextChanged($param);
 648      }
 649  
 650      /**
 651       * Raises OnTextChanged event when selection is changed.
 652       * This method is invoked when the list control has its selection changed
 653       * by end-users.
 654       * @param TEventParameter event parameter
 655       */
 656  	public function onTextChanged($param)
 657      {
 658          $this->raiseEvent('OnTextChanged',$this,$param);
 659      }
 660  
 661      /**
 662       * Renders body content of the list control.
 663       * This method renders items contained in the list control as the body content.
 664       * @param THtmlWriter writer
 665       */
 666  	public function renderContents($writer)
 667      {
 668          if($this->_items)
 669          {
 670              $writer->writeLine();
 671              $previousGroup=null;
 672              foreach($this->_items as $item)
 673              {
 674                  if($item->getEnabled())
 675                  {
 676                      if($item->getHasAttributes())
 677                      {
 678                          $group=$item->getAttributes()->remove('Group');
 679                          if($group!==$previousGroup)
 680                          {
 681                              if($previousGroup!==null)
 682                              {
 683                                  $writer->renderEndTag();
 684                                  $writer->writeLine();
 685                                  $previousGroup=null;
 686                              }
 687                              if($group!==null)
 688                              {
 689                                  $writer->addAttribute('label',$group);
 690                                  $writer->renderBeginTag('optgroup');
 691                                  $writer->writeLine();
 692                                  $previousGroup=$group;
 693                              }
 694                          }
 695                          foreach($item->getAttributes() as $name=>$value)
 696                              $writer->addAttribute($name,$value);
 697                      }
 698                      else if($previousGroup!==null)
 699                      {
 700                          $writer->renderEndTag();
 701                          $writer->writeLine();
 702                          $previousGroup=null;
 703                      }
 704                      if($item->getSelected())
 705                          $writer->addAttribute('selected','selected');
 706                      $writer->addAttribute('value',$item->getValue());
 707                      $writer->renderBeginTag('option');
 708                      $writer->write(THttpUtility::htmlEncode($item->getText()));
 709                      $writer->renderEndTag();
 710                      $writer->writeLine();
 711                  }
 712              }
 713              if($previousGroup!==null)
 714              {
 715                  $writer->renderEndTag();
 716                  $writer->writeLine();
 717              }
 718          }
 719      }
 720  
 721      /**
 722       * Formats the text value according to a format string.
 723       * If the format string is empty, the original value is converted into
 724       * a string and returned.
 725       * If the format string starts with '#', the string is treated as a PHP expression
 726       * within which the token '{0}' is translated with the data value to be formated.
 727       * Otherwise, the format string and the data value are passed
 728       * as the first and second parameters in {@link sprintf}.
 729       * @param string format string
 730       * @param mixed the data to be formatted
 731       * @return string the formatted result
 732       */
 733  	protected function formatDataValue($formatString,$value)
 734      {
 735          if($formatString==='')
 736              return TPropertyValue::ensureString($value);
 737          else if($formatString[0]==='#')
 738          {
 739              $expression=strtr(substr($formatString,1),array('{0}'=>'$value'));
 740              try
 741              {
 742                  if(eval("\$result=$expression;")===false)
 743                      throw new Exception('');
 744                  return $result;
 745              }
 746              catch(Exception $e)
 747              {
 748                  throw new TInvalidDataValueException('listcontrol_expression_invalid',get_class($this),$expression,$e->getMessage());
 749              }
 750          }
 751          else
 752              return sprintf($formatString,$value);
 753      }
 754  }
 755  
 756  /**
 757   * TListItemCollection class.
 758   *
 759   * TListItemCollection maintains a list of {@link TListItem} for {@link TListControl}.
 760   *
 761   * @author Qiang Xue <qiang.xue@gmail.com>
 762   * @version $Id: TListControl.php 1397 2006-09-07 07:55:53Z wei $
 763   * @package System.Web.UI.WebControls
 764   * @since 3.0
 765   */
 766  class TListItemCollection extends TList
 767  {
 768      /**
 769       * Creates a list item object.
 770       * This method may be overriden to provide a customized list item object.
 771       * @param integer index where the newly created item is to be inserted at.
 772       * If -1, the item will be appended to the end.
 773       * @return TListItem list item object
 774       */
 775  	public function createListItem($index=-1)
 776      {
 777          $item=new TListItem;
 778          if($index<0)
 779              $this->add($item);
 780          else
 781              $this->insertAt($index,$item);
 782          return $item;
 783      }
 784  
 785      /**
 786       * Inserts an item into the collection.
 787       * @param integer the location where the item will be inserted.
 788       * The current item at the place and the following ones will be moved backward.
 789       * @param TListItem the item to be inserted.
 790       * @throws TInvalidDataTypeException if the item being inserted is neither a string nor TListItem
 791       */
 792  	public function insertAt($index,$item)
 793      {
 794          if($item instanceof TListItem)
 795              parent::insertAt($index,$item);
 796          else if(is_string($item))
 797          {
 798              $item=$this->createListItem($index);
 799              $item->setText($item);
 800          }
 801          else
 802              throw new TInvalidDataTypeException('listitemcollection_item_invalid',get_class($this));
 803      }
 804  
 805      /**
 806       * Finds the lowest cardinal index of the item whose value is the one being looked for.
 807       * @param string the value to be looked for
 808       * @param boolean whether to look for disabled items also
 809       * @return integer the index of the item found, -1 if not found.
 810       */
 811  	public function findIndexByValue($value,$includeDisabled=true)
 812      {
 813          $value=TPropertyValue::ensureString($value);
 814          $index=0;
 815          foreach($this as $item)
 816          {
 817              if($item->getValue()===$value && ($includeDisabled || $item->getEnabled()))
 818                  return $index;
 819              $index++;
 820          }
 821          return -1;
 822      }
 823  
 824      /**
 825       * Finds the lowest cardinal index of the item whose text is the one being looked for.
 826       * @param string the text to be looked for
 827       * @param boolean whether to look for disabled items also
 828       * @return integer the index of the item found, -1 if not found.
 829       */
 830  	public function findIndexByText($text,$includeDisabled=true)
 831      {
 832          $text=TPropertyValue::ensureString($text);
 833          $index=0;
 834          foreach($this as $item)
 835          {
 836              if($item->getText()===$text && ($includeDisabled || $item->getEnabled()))
 837                  return $index;
 838              $index++;
 839          }
 840          return -1;
 841      }
 842  
 843      /**
 844       * Finds the item whose value is the one being looked for.
 845       * @param string the value to be looked for
 846       * @param boolean whether to look for disabled items also
 847       * @return TListItem the item found, null if not found.
 848       */
 849  	public function findItemByValue($value,$includeDisabled=true)
 850      {
 851          if(($index=$this->findIndexByValue($value,$includeDisabled))>=0)
 852              return $this->itemAt($index);
 853          else
 854              return null;
 855      }
 856  
 857      /**
 858       * Finds the item whose text is the one being looked for.
 859       * @param string the text to be looked for
 860       * @param boolean whether to look for disabled items also
 861       * @return TListItem the item found, null if not found.
 862       */
 863  	public function findItemByText($text,$includeDisabled=true)
 864      {
 865          if(($index=$this->findIndexByText($text,$includeDisabled))>=0)
 866              return $this->itemAt($index);
 867          else
 868              return null;
 869      }
 870  
 871      /**
 872       * Loads state into every item in the collection.
 873       * This method should only be used by framework and control developers.
 874       * @param array|null state to be loaded.
 875       */
 876  	public function loadState($state)
 877      {
 878          $this->clear();
 879          if($state!==null)
 880              $this->copyFrom($state);
 881      }
 882  
 883      /**
 884       * Saves state of items.
 885       * This method should only be used by framework and control developers.
 886       * @return array|null the saved state
 887       */
 888  	public function saveState()
 889      {
 890          return ($this->getCount()>0) ? $this->toArray() : null;
 891      }
 892  }
 893  
 894  ?>