From d1384deb9b3ac872defd08fd01fbf8cf11442b45 Mon Sep 17 00:00:00 2001 From: xue <> Date: Wed, 4 Jan 2006 04:59:01 +0000 Subject: Added documentation. --- framework/Web/UI/WebControls/TListControl.php | 344 +++++++++++++++++++++----- 1 file changed, 288 insertions(+), 56 deletions(-) (limited to 'framework/Web/UI/WebControls/TListControl.php') diff --git a/framework/Web/UI/WebControls/TListControl.php b/framework/Web/UI/WebControls/TListControl.php index 860cbc48..582e03bd 100644 --- a/framework/Web/UI/WebControls/TListControl.php +++ b/framework/Web/UI/WebControls/TListControl.php @@ -1,11 +1,83 @@ + * @link http://www.pradosoft.com/ + * @copyright Copyright © 2005 PradoSoft + * @license http://www.pradosoft.com/license/ + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + */ + +/** + * TListControl class + * + * TListControl is a base class for list controls, such as {@link TListBox}, + * {@link TDropDownList}, {@link TCheckBoxList}, etc. + * It manages the items and their status in a list control. + * It also implements how the items can be populated from template and + * data source. + * + * The property {@link getItems} returns a list of the items in the control. + * To specify or determine which item is selected, use the + * {@link getSelectedIndex SelectedIndex} property that indicates the zero-based + * index of the selected item in the item list. You may also use + * {@link getSelectedItem SelectedItem} and {@link getSelectedValue SelectedValue} + * to get the selected item and its value. For multiple selection lists + * (such as {@link TCheckBoxList} and {@link TListBox}), property + * {@link getSelectedIndices SelectedIndices} is useful. + * + * TListControl implements {@link setAutoPostBack AutoPostBack} which allows + * a list control to postback the page if the selections of the list items are changed. + * The {@link setCausesValidation CausesValidation} and {@link setValidationGroup ValidationGroup} + * properties may be used to specify that validation be performed when auto postback occurs. + * + * There are three ways to populate the items in a list control: from template, + * using {@link setDataSource DataSource} and using {@link setDataSourceID DataSourceID}. + * The latter two are covered in {@link TDataBoundControl}. To specify items via + * template, using the following template syntax: + * + * <com:TListControl> + * <com:TListItem Value="xxx" Text="yyy" > + * <com:TListItem Value="xxx" Text="yyy" Selected="true" > + * <com:TListItem Value="xxx" Text="yyy" > + * </com:TListControl> + * + * + * When {@link setDataSource DataSource} or {@link setDataSourceID DataSourceID} + * is used to populate list items, the {@link setDataTextField DataTextField} and + * {@link setDataValueField DataValueField} properties are used to specify which + * columns of the data will be used to populate the text and value of the items. + * For example, if a data source is as follows, + * + * $dataSource=array( + * array('name'=>'John', 'age'=>31), + * array('name'=>'Cary', 'age'=>28), + * array('name'=>'Rose', 'age'=>35), + * ); + * + * setting {@link setDataTextField DataTextField} and {@link setDataValueField DataValueField} + * to 'name' and 'age' will make the first item's text be 'John', value be 31, + * the second item's text be 'Cary', value be 28, and so on. + * The {@link setDataTextFormatString DataTextFormatString} property may be further + * used to format how the item should be displayed. The formatting function is + * the sprintf() PHP function. + * + * @author Qiang Xue + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + * @since 3.0 + */ abstract class TListControl extends TDataBoundControl { + /** + * @var TListItemCollection item list + */ private $_items=null; /** - * @return string tag name of the textbox + * @return string tag name of the list control */ protected function getTagName() { @@ -35,6 +107,9 @@ abstract class TListControl extends TDataBoundControl parent::addAttributesToRender($writer); } + /** + * @return TPostBackOptions postback options for JS postback code + */ protected function getAutoPostBackOptions() { $option=new TPostBackOptions(); @@ -49,28 +124,28 @@ abstract class TListControl extends TDataBoundControl return $option; } + /** + * Adds object parsed from template to the control. + * This method adds only {@link TListItem} objects into the {@link getItems Items} collection. + * All other objects are ignored. + * @param mixed object parsed from template + */ public function addParsedObject($object) { if($object instanceof TListItem) $this->getItems()->add($object); } - protected function validateDataSource($value) - { - if(is_string($value)) - { - $list=new TList; - foreach(TPropertyValue::ensureArray($value) as $key=>$value) - $list->add(array($value,is_string($key)?$key:$value)); - return $list; - } - else - return parent::validateDataSource($value); - return $value; - } - + /** + * Performs databinding to populate list items from data source. + * This method is invoked by dataBind(). + * You may override this function to provide your own way of data population. + * @param Traversable the data + */ protected function performDataBinding($data) { + if(!$this->getAppendDataBoundItems()) + $items->clear(); if($data instanceof Traversable) { $textField=$this->getDataTextField(); @@ -81,8 +156,6 @@ abstract class TListControl extends TDataBoundControl $valueField=1; $textFormat=$this->getDataTextFormatString(); $items=$this->getItems(); - if(!$this->getAppendDataBoundItems()) - $items->clear(); foreach($data as $object) { $item=new TListItem; @@ -98,6 +171,11 @@ abstract class TListControl extends TDataBoundControl } } + /** + * Saves items into viewstate. + * This method is invoked right before control state is to be saved. + * @param mixed event parameter + */ protected function onSaveState($param) { if($this->_items) @@ -106,22 +184,36 @@ abstract class TListControl extends TDataBoundControl $this->clearViewState('Items'); } + /** + * Loads items into from viewstate. + * This method is invoked right after control state is loaded. + * @param mixed event parameter + */ protected function onLoadState($param) { $this->_items=new TListItemCollection; $this->_items->loadState($this->getViewState('Items',null)); } + /** + * @return boolean whether this is a multiselect control. Defaults to false. + */ protected function getIsMultiSelect() { return false; } + /** + * @return boolean whether performing databind should append items or clear the existing ones. Defaults to false. + */ public function getAppendDataBoundItems() { return $this->getViewState('AppendDataBoundItems',false); } + /** + * @param boolean whether performing databind should append items or clear the existing ones. + */ public function setAppendDataBoundItems($value) { $this->setViewState('AppendDataBoundItems',TPropertyValue::ensureBoolean($value),false); @@ -129,8 +221,8 @@ abstract class TListControl extends TDataBoundControl /** * @return boolean a value indicating whether an automatic postback to the server - * will occur whenever the user modifies the text in the TTextBox control and - * then tabs out of the component. Defaults to false. + * will occur whenever the user makes change to the list control and then tabs out of it. + * Defaults to false. */ public function getAutoPostBack() { @@ -140,7 +232,7 @@ abstract class TListControl extends TDataBoundControl /** * Sets the value indicating if postback automatically. * An automatic postback to the server will occur whenever the user - * modifies the text in the TTextBox control and then tabs out of the component. + * makes change to the list control and then tabs out of it. * @param boolean the value indicating if postback automatically */ public function setAutoPostBack($value) @@ -149,7 +241,7 @@ abstract class TListControl extends TDataBoundControl } /** - * @return boolean whether postback event trigger by this text box will cause input validation, default is true. + * @return boolean whether postback event trigger by this list control will cause input validation, default is true. */ public function getCausesValidation() { @@ -157,8 +249,7 @@ abstract class TListControl extends TDataBoundControl } /** - * Sets the value indicating whether postback event trigger by this text box will cause input validation. - * @param boolean whether postback event trigger by this button will cause input validation. + * @param boolean whether postback event trigger by this list control will cause input validation. */ public function setCausesValidation($value) { @@ -190,6 +281,9 @@ abstract class TListControl extends TDataBoundControl } /** + * Sets data text format string. + * The format string is used in sprintf() to format the Text property value + * of each item in the list control. * @param string the formatting string used to control how data bound to the list control is displayed. */ public function setDataTextFormatString($value) @@ -213,11 +307,25 @@ abstract class TListControl extends TDataBoundControl $this->setViewState('DataValueField',$value,''); } + /** + * @return integer the number of items in the list control + */ + public function getItemCount() + { + return $this->_items?$this->_items->getCount():0; + } + + /** + * @return boolean whether the list control contains any items. + */ public function getHasItems() { return ($this->_items && $this->_items->getCount()>0); } + /** + * @return TListItemCollection the item collection + */ public function getItems() { if(!$this->_items) @@ -226,7 +334,7 @@ abstract class TListControl extends TDataBoundControl } /** - * @return integer the index of the item being selected, -1 if no selection + * @return integer the index (zero-based) of the item being selected, -1 if no item is selected. */ public function getSelectedIndex() { @@ -241,7 +349,7 @@ abstract class TListControl extends TDataBoundControl } /** - * @param integer the index of the item to be selected + * @param integer the index (zero-based) of the item to be selected */ public function setSelectedIndex($index) { @@ -254,6 +362,9 @@ abstract class TListControl extends TDataBoundControl } } + /** + * @return array list of index of items that are selected + */ public function getSelectedIndices() { $selections=array(); @@ -267,6 +378,9 @@ abstract class TListControl extends TDataBoundControl return $selections; } + /** + * @param array list of index of items to be selected + */ public function setSelectedIndices($indices) { if($this->_items) @@ -282,7 +396,7 @@ abstract class TListControl extends TDataBoundControl } /** - * @return TListItem|null the selected item with the lowest cardinal index, null if no selection. + * @return TListItem|null the selected item with the lowest cardinal index, null if no item is selected. */ public function getSelectedItem() { @@ -303,6 +417,8 @@ abstract class TListControl extends TDataBoundControl /** * Sets selection by item value. + * Existing selections will be cleared if the item value is found in the item collection. + * Note, if the value is null, existing selections will also be cleared. * @param string the value of the item to be selected. */ public function setSelectedValue($value) @@ -319,6 +435,9 @@ abstract class TListControl extends TDataBoundControl } } + /** + * Clears all existing selections. + */ public function clearSelection() { if($this->_items) @@ -329,24 +448,7 @@ abstract class TListControl extends TDataBoundControl } /** - * @return string the text content of the TTextBox control. - */ - public function getText() - { - return $this->getSelectedValue(); - } - - /** - * Sets the text content of the TTextBox control. - * @param string the text content - */ - public function setText($value) - { - $this->setSelectedValue($value); - } - - /** - * @return string the group of validators which the text box causes validation upon postback + * @return string the group of validators which the list control causes validation upon postback */ public function getValidationGroup() { @@ -354,24 +456,29 @@ abstract class TListControl extends TDataBoundControl } /** - * @param string the group of validators which the text box causes validation upon postback + * @param string the group of validators which the list control causes validation upon postback */ public function setValidationGroup($value) { $this->setViewState('ValidationGroup',$value,''); } + /** + * Raises SelectedIndexChanged event when selection is changed. + * This method is invoked when the list control has its selection changed + * by end-users. + * @param TEventParameter event parameter + */ public function onSelectedIndexChanged($param) { $this->raiseEvent('SelectedIndexChanged',$this,$param); } - // ???? - public function onTextChanged($param) - { - $this->raiseEvent('TextChanged',$this,$param); - } - + /** + * Renders body content of the list control. + * This method renders items contained in the list control as the body content. + * @param THtmlWriter writer + */ protected function renderContents($writer) { if($this->_items) @@ -399,10 +506,23 @@ abstract class TListControl extends TDataBoundControl } } +/** + * TListItemCollection class. + * + * TListItemCollection maintains a list of {@link TListItem} for {@link TListControl}. + * + * @author Qiang Xue + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + * @since 3.0 + */ class TListItemCollection extends TList { - private $_items=null; - + /** + * Appends an item to the collection. + * @param TListItem the item to be appended. + * @throws TInvalidDataTypeException if the item being appended is neither a string nor a TListItem + */ public function add($item) { if(is_string($item)) @@ -413,6 +533,13 @@ class TListItemCollection extends TList throw new TInvalidDataTypeException('listitemcollection_item_invalid'); } + /** + * Inserts an item into the collection. + * @param integer the location where the item will be inserted. + * The current item at the place and the following ones will be moved backward. + * @param TListItem the item to be inserted. + * @throws TInvalidDataTypeException if the item being inserted is neither a string nor TListItem + */ public function insert($index,$item) { if(is_string($item)) @@ -423,6 +550,12 @@ class TListItemCollection extends TList throw new TInvalidDataTypeException('listitemcollection_item_invalid'); } + /** + * Finds the lowest cardinal index of the item whose value is the one being looked for. + * @param string the value to be looked for + * @param boolean whether to look for disabled items also + * @return integer the index of the item found, -1 if not found. + */ public function findIndexByValue($value,$includeDisabled=true) { $value=TPropertyValue::ensureString($value); @@ -436,6 +569,12 @@ class TListItemCollection extends TList return -1; } + /** + * Finds the lowest cardinal index of the item whose text is the one being looked for. + * @param string the text to be looked for + * @param boolean whether to look for disabled items also + * @return integer the index of the item found, -1 if not found. + */ public function findIndexByText($text,$includeDisabled=true) { $text=TPropertyValue::ensureString($text); @@ -449,6 +588,12 @@ class TListItemCollection extends TList return -1; } + /** + * Finds the item whose value is the one being looked for. + * @param string the value to be looked for + * @param boolean whether to look for disabled items also + * @return TListItem the item found, null if not found. + */ public function findItemByValue($value,$includeDisabled=true) { if(($index=$this->findIndexByValue($value,$includeDisabled))>=0) @@ -457,6 +602,12 @@ class TListItemCollection extends TList return null; } + /** + * Finds the item whose text is the one being looked for. + * @param string the text to be looked for + * @param boolean whether to look for disabled items also + * @return TListItem the item found, null if not found. + */ public function findItemByText($text,$includeDisabled=true) { if(($index=$this->findIndexByText($text,$includeDisabled))>=0) @@ -465,6 +616,11 @@ class TListItemCollection extends TList return null; } + /** + * Loads state into every item in the collection. + * This method should only be used by framework and control developers. + * @param array|null state to be loaded. + */ public function loadState($state) { $this->clear(); @@ -475,6 +631,11 @@ class TListItemCollection extends TList } } + /** + * Saves state of items. + * This method should only be used by framework and control developers. + * @return array|null the saved state + */ public function saveState() { if($this->getCount()>0) @@ -489,14 +650,51 @@ class TListItemCollection extends TList } } +/** + * TListItem class. + * + * TListItem represents an item in a list control. Each item has a {@link setText Text} + * property and a {@link setValue Value} property. If either one of them is not set, + * it will take the value of the other property. + * An item can be {@link setSelected Selected} or {@link setEnabled Enabled}, + * and it can have additional {@link getAttributes Attributes} which may be rendered + * if the list control supports so. + * + * @author Qiang Xue + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + * @since 3.0 + */ class TListItem extends TComponent { + /** + * @var TMap list of custom attributes + */ private $_attributes=null; + /** + * @var string text of the item + */ private $_text; + /** + * @var string value of the item + */ private $_value; + /** + * @var boolean whether the item is enabled + */ private $_enabled; + /** + * @var boolean whether the item is selected + */ private $_selected; + /** + * Constructor. + * @param string text of the item + * @param string value of the item + * @param boolean whether the item is enabled + * @param boolean whether the item is selected + */ public function __construct($text='',$value='',$enabled=true,$selected=false) { $this->setText($text); @@ -505,46 +703,73 @@ class TListItem extends TComponent $this->setSelected($selected); } + /** + * @return boolean whether the item is enabled + */ public function getEnabled() { return $this->_enabled; } + /** + * @param boolean whether the item is enabled + */ public function setEnabled($value) { $this->_enabled=TPropertyValue::ensureBoolean($value); } + /** + * @return boolean whether the item is selected + */ public function getSelected() { return $this->_selected; } + /** + * @param boolean whether the item is selected + */ public function setSelected($value) { $this->_selected=TPropertyValue::ensureBoolean($value); } + /** + * @return string text of the item + */ public function getText() { return $this->_text===''?$this->_value:$this->_text; } + /** + * @param string text of the item + */ public function setText($value) { $this->_text=TPropertyValue::ensureString($value); } + /** + * @return string value of the item + */ public function getValue() { return $this->_value===''?$this->_text:$this->_value; } + /** + * @param string value of the item + */ public function setValue($value) { $this->_value=TPropertyValue::ensureString($value); } + /** + * @return TMap custom attributes + */ public function getAttributes() { if(!$this->_attributes) @@ -552,18 +777,25 @@ class TListItem extends TComponent return $this->_attributes; } + /** + * @return boolean whether the item has any custom attribute + */ public function getHasAttributes() { - return $this->_attributes!==null; + return $this->_attributes && $this->_attributes->getCount()>0; } + /** + * @param string name of the attribute + * @return boolean whether the named attribute exists + */ public function hasAttribute($name) { return $this->_attributes?$this->_attributes->contains($name):false; } /** - * @return string attribute value, '' if attribute does not exist + * @return string the named attribute value, null if attribute does not exist */ public function getAttribute($name) { -- cgit v1.2.3