* @link http://www.pradosoft.com/
* @copyright Copyright © 2005 PradoSoft
* @license http://www.pradosoft.com/license/
* @version $Id$
* @package System.Web.UI.WebControls
*/
/**
* Includes the supporting classes
*/
Prado::using('System.Web.UI.WebControls.TDataBoundControl');
Prado::using('System.Web.UI.WebControls.TListItem');
Prado::using('System.Collections.TAttributeCollection');
Prado::using('System.Util.TDataFieldAccessor');
/**
* 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:
*
*
*
*
*
*
*
*
* 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. See {@link formatDataValue()}
* for an explanation of the format string.
*
* @author Qiang Xue
* @version $Id$
* @package System.Web.UI.WebControls
* @since 3.0
*/
abstract class TListControl extends TDataBoundControl implements IDataRenderer
{
/**
* @var TListItemCollection item list
*/
private $_items=null;
/**
* @var boolean whether items are restored from viewstate
*/
private $_stateLoaded=false;
/**
* @var mixed the following selection variables are used
* to keep selections when Items are not available
*/
private $_cachedSelectedIndex=-1;
private $_cachedSelectedValue=null;
private $_cachedSelectedIndices=null;
private $_cachedSelectedValues=null;
/**
* @return string tag name of the list control
*/
protected function getTagName()
{
return 'select';
}
/**
* @return boolean whether to render javascript.
*/
public function getEnableClientScript()
{
return $this->getViewState('EnableClientScript',true);
}
/**
* @param boolean whether to render javascript.
*/
public function setEnableClientScript($value)
{
$this->setViewState('EnableClientScript',TPropertyValue::ensureBoolean($value),true);
}
/**
* Adds attributes to renderer.
* @param THtmlWriter the renderer
*/
protected function addAttributesToRender($writer)
{
$page=$this->getPage();
$page->ensureRenderInForm($this);
if($this->getIsMultiSelect())
$writer->addAttribute('multiple','multiple');
if($this->getEnabled(true))
{
if($this->getAutoPostBack()
&& $this->getEnableClientScript()
&& $page->getClientSupportsJavaScript())
{
$this->renderClientControlScript($writer);
}
}
else if($this->getEnabled())
$writer->addAttribute('disabled','disabled');
parent::addAttributesToRender($writer);
}
/**
* Renders the javascript for list control.
*/
protected function renderClientControlScript($writer)
{
$writer->addAttribute('id',$this->getClientID());
$this->getPage()->getClientScript()->registerPostBackControl($this->getClientClassName(),$this->getPostBackOptions());
}
/**
* Gets the name of the javascript class responsible for performing postback for this control.
* Derived classes may override this method and return customized js class names.
* @return string the javascript class name
*/
protected function getClientClassName()
{
return 'Prado.WebUI.TListControl';
}
/**
* @return array postback options for JS postback code
*/
protected function getPostBackOptions()
{
$options['ID'] = $this->getClientID();
$options['CausesValidation'] = $this->getCausesValidation();
$options['ValidationGroup'] = $this->getValidationGroup();
$options['EventTarget'] = $this->getUniqueID();
return $options;
}
/**
* 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)
{
// Do not add items from template if items are loaded from viewstate
if(!$this->_stateLoaded && ($object instanceof TListItem))
{
$index=$this->getItems()->add($object);
if(($this->_cachedSelectedValue!==null && $this->_cachedSelectedValue===$object->getValue()) || ($this->_cachedSelectedIndex===$index))
{
$object->setSelected(true);
$this->_cachedSelectedValue=null;
$this->_cachedSelectedIndex=-1;
}
}
}
/**
* 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)
{
$items=$this->getItems();
if(!$this->getAppendDataBoundItems())
$items->clear();
$textField=$this->getDataTextField();
if($textField==='')
$textField=0;
$valueField=$this->getDataValueField();
if($valueField==='')
$valueField=1;
$textFormat=$this->getDataTextFormatString();
$groupField=$this->getDataGroupField();
foreach($data as $key=>$object)
{
$item=$items->createListItem();
if(is_array($object) || is_object($object))
{
$text=TDataFieldAccessor::getDataFieldValue($object,$textField);
$value=TDataFieldAccessor::getDataFieldValue($object,$valueField);
$item->setValue($value);
if($groupField!=='')
$item->setAttribute('Group',TDataFieldAccessor::getDataFieldValue($object,$groupField));
}
else
{
$text=$object;
$item->setValue("$key");
}
$item->setText($this->formatDataValue($textFormat,$text));
}
// SelectedValue or SelectedIndex may be set before databinding
// so we make them be effective now
if($this->_cachedSelectedValue!==null)
{
$this->setSelectedValue($this->_cachedSelectedValue);
$this->resetCachedSelections();
}
else if($this->_cachedSelectedIndex!==-1)
{
$this->setSelectedIndex($this->_cachedSelectedIndex);
$this->resetCachedSelections();
}
else if($this->_cachedSelectedValues!==null)
{
$this->setSelectedValues($this->_cachedSelectedValues);
$this->resetCachedSelections();
}
else if($this->_cachedSelectedIndices!==null)
{
$this->setSelectedIndices($this->_cachedSelectedIndices);
$this->resetCachedSelections();
}
}
private function resetCachedSelections()
{
$this->_cachedSelectedValue=null;
$this->_cachedSelectedIndex=-1;
$this->_cachedSelectedValues=null;
$this->_cachedSelectedIndices=null;
}
/**
* Creates a collection object to hold list items.
* This method may be overriden to create a customized collection.
* @return TListItemCollection the collection object
*/
protected function createListItemCollection()
{
return new TListItemCollection;
}
/**
* Saves items into viewstate.
* This method is invoked right before control state is to be saved.
*/
public function saveState()
{
parent::saveState();
if($this->_items)
$this->setViewState('Items',$this->_items->saveState(),null);
else
$this->clearViewState('Items');
}
/**
* Loads items from viewstate.
* This method is invoked right after control state is loaded.
*/
public function loadState()
{
parent::loadState();
$this->_stateLoaded=true;
if(!$this->getIsDataBound())
{
$this->_items=$this->createListItemCollection();
$this->_items->loadState($this->getViewState('Items',null));
}
$this->clearViewState('Items');
}
/**
* @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);
}
/**
* @return boolean a value indicating whether an automatic postback to the server
* will occur whenever the user makes change to the list control and then tabs out of it.
* Defaults to false.
*/
public function getAutoPostBack()
{
return $this->getViewState('AutoPostBack',false);
}
/**
* Sets the value indicating if postback automatically.
* An automatic postback to the server will occur whenever the user
* makes change to the list control and then tabs out of it.
* @param boolean the value indicating if postback automatically
*/
public function setAutoPostBack($value)
{
$this->setViewState('AutoPostBack',TPropertyValue::ensureBoolean($value),false);
}
/**
* @return boolean whether postback event trigger by this list control will cause input validation, default is true.
*/
public function getCausesValidation()
{
return $this->getViewState('CausesValidation',true);
}
/**
* @param boolean whether postback event trigger by this list control will cause input validation.
*/
public function setCausesValidation($value)
{
$this->setViewState('CausesValidation',TPropertyValue::ensureBoolean($value),true);
}
/**
* @return string the field of the data source that provides the text content of the list items.
*/
public function getDataTextField()
{
return $this->getViewState('DataTextField','');
}
/**
* @param string the field of the data source that provides the text content of the list items.
*/
public function setDataTextField($value)
{
$this->setViewState('DataTextField',$value,'');
}
/**
* @return string the formatting string used to control how data bound to the list control is displayed.
*/
public function getDataTextFormatString()
{
return $this->getViewState('DataTextFormatString','');
}
/**
* Sets data text format string.
* The format string is used in {@link TDataValueFormatter::format()} 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.
* @see TDataValueFormatter::format()
*/
public function setDataTextFormatString($value)
{
$this->setViewState('DataTextFormatString',$value,'');
}
/**
* @return string the field of the data source that provides the value of each list item.
*/
public function getDataValueField()
{
return $this->getViewState('DataValueField','');
}
/**
* @param string the field of the data source that provides the value of each list item.
*/
public function setDataValueField($value)
{
$this->setViewState('DataValueField',$value,'');
}
/**
* @return string the field of the data source that provides the label of the list item groups
*/
public function getDataGroupField()
{
return $this->getViewState('DataGroupField','');
}
/**
* @param string the field of the data source that provides the label of the list item groups
*/
public function setDataGroupField($value)
{
$this->setViewState('DataGroupField',$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)
$this->_items=$this->createListItemCollection();
return $this->_items;
}
/**
* @return integer the index (zero-based) of the item being selected, -1 if no item is selected.
*/
public function getSelectedIndex()
{
if($this->_items)
{
$n=$this->_items->getCount();
for($i=0;$i<$n;++$i)
if($this->_items->itemAt($i)->getSelected())
return $i;
}
return -1;
}
/**
* @param integer the index (zero-based) of the item to be selected
*/
public function setSelectedIndex($index)
{
if(($index=TPropertyValue::ensureInteger($index))<0)
$index=-1;
if($this->_items)
{
$this->clearSelection();
if($index>=0 && $index<$this->_items->getCount())
$this->_items->itemAt($index)->setSelected(true);
else if($index!==-1)
throw new TInvalidDataValueException('listcontrol_selectedindex_invalid',get_class($this),$index);
}
$this->_cachedSelectedIndex=$index;
if($this->getAdapter() instanceof IListControlAdapter)
$this->getAdapter()->setSelectedIndex($index);
}
/**
* @return array list of index of items that are selected
*/
public function getSelectedIndices()
{
$selections=array();
if($this->_items)
{
$n=$this->_items->getCount();
for($i=0;$i<$n;++$i)
if($this->_items->itemAt($i)->getSelected())
$selections[]=$i;
}
return $selections;
}
/**
* @param array list of index of items to be selected
*/
public function setSelectedIndices($indices)
{
if($this->getIsMultiSelect())
{
if($this->_items)
{
$this->clearSelection();
$n=$this->_items->getCount();
foreach($indices as $index)
{
if($index>=0 && $index<$n)
$this->_items->itemAt($index)->setSelected(true);
}
}
$this->_cachedSelectedIndices=$indices;
}
else
throw new TNotSupportedException('listcontrol_multiselect_unsupported',get_class($this));
if($this->getAdapter() instanceof IListControlAdapter)
$this->getAdapter()->setSelectedIndices($indices);
}
/**
* @return TListItem|null the selected item with the lowest cardinal index, null if no item is selected.
*/
public function getSelectedItem()
{
if(($index=$this->getSelectedIndex())>=0)
return $this->_items->itemAt($index);
else
return null;
}
/**
* Returns the value of the selected item with the lowest cardinal index.
* This method is required by {@link IDataRenderer}.
* It is the same as {@link getSelectedValue()}.
* @return string the value of the selected item with the lowest cardinal index, empty if no selection.
* @see getSelectedValue
* @since 3.1.0
*/
public function getData()
{
return $this->getSelectedValue();
}
/**
* Selects an item by the specified value.
* This method is required by {@link IDataRenderer}.
* It is the same as {@link setSelectedValue()}.
* @param string the value of the item to be selected.
* @see setSelectedValue
* @since 3.1.0
*/
public function setData($value)
{
$this->setSelectedValue($value);
}
/**
* @return string the value of the selected item with the lowest cardinal index, empty if no selection
*/
public function getSelectedValue()
{
$index=$this->getSelectedIndex();
return $index>=0?$this->getItems()->itemAt($index)->getValue():'';
}
/**
* 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)
{
if($this->_items)
{
if($value===null)
$this->clearSelection();
else if(($item=$this->_items->findItemByValue($value))!==null)
{
$this->clearSelection();
$item->setSelected(true);
}
else
throw new TInvalidDataValueException('listcontrol_selectedvalue_invalid',get_class($this),$value);
}
$this->_cachedSelectedValue=$value;
if($this->getAdapter() instanceof IListControlAdapter)
$this->getAdapter()->setSelectedValue($value);
}
/**
* @return array list of the selected item values (strings)
*/
public function getSelectedValues()
{
$values=array();
if($this->_items)
{
foreach($this->_items as $item)
{
if($item->getSelected())
$values[]=$item->getValue();
}
}
return $values;
}
/**
* @param array list of the selected item values
*/
public function setSelectedValues($values)
{
if($this->getIsMultiSelect())
{
if($this->_items)
{
$this->clearSelection();
$lookup=array();
foreach($this->_items as $item)
$lookup[$item->getValue()]=$item;
foreach($values as $value)
{
if(isset($lookup["$value"]))
$lookup["$value"]->setSelected(true);
else
throw new TInvalidDataValueException('listcontrol_selectedvalue_invalid',get_class($this),$value);
}
}
$this->_cachedSelectedValues=$values;
}
else
throw new TNotSupportedException('listcontrol_multiselect_unsupported',get_class($this));
if($this->getAdapter() instanceof IListControlAdapter)
$this->getAdapter()->setSelectedValues($values);
}
/**
* @return string selected value
*/
public function getText()
{
return $this->getSelectedValue();
}
/**
* @param string value to be selected
*/
public function setText($value)
{
$this->setSelectedValue($value);
}
/**
* Clears all existing selections.
*/
public function clearSelection()
{
if($this->_items)
{
foreach($this->_items as $item)
$item->setSelected(false);
}
if($this->getAdapter() instanceof IListControlAdapter)
$this->getAdapter()->clearSelection();
}
/**
* @return string the group of validators which the list control causes validation upon postback
*/
public function getValidationGroup()
{
return $this->getViewState('ValidationGroup','');
}
/**
* @param string the group of validators which the list control causes validation upon postback
*/
public function setValidationGroup($value)
{
$this->setViewState('ValidationGroup',$value,'');
}
/**
* @return string the prompt text which is to be displayed as the first list item.
* @since 3.1.1
*/
public function getPromptText()
{
return $this->getViewState('PromptText','');
}
/**
* @param string the prompt text which is to be displayed as the first list item.
* @since 3.1.1
*/
public function setPromptText($value)
{
$this->setViewState('PromptText',$value,'');
}
/**
* @return string the prompt selection value.
* @see getPromptText
* @since 3.1.1
*/
public function getPromptValue()
{
return $this->getViewState('PromptValue','');
}
/**
* @param string the prompt selection value. If empty, {@link getPromptText PromptText} will be used as the value.
* @see setPromptText
* @since 3.1.1
*/
public function setPromptValue($value)
{
$this->setViewState('PromptValue',(string)$value,'');
}
/**
* Raises OnSelectedIndexChanged 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('OnSelectedIndexChanged',$this,$param);
$this->onTextChanged($param);
}
/**
* Raises OnTextChanged 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 onTextChanged($param)
{
$this->raiseEvent('OnTextChanged',$this,$param);
}
/**
* Renders the prompt text, if any.
* @param THtmlWriter writer
* @since 3.1.1
*/
protected function renderPrompt($writer)
{
$text=$this->getPromptText();
$value=$this->getPromptValue();
if($value==='')
$value=$text;
if($value!=='')
{
$writer->addAttribute('value',$value);
$writer->renderBeginTag('option');
$writer->write(THttpUtility::htmlEncode($text));
$writer->renderEndTag();
$writer->writeLine();
}
}
/**
* Renders body content of the list control.
* This method renders items contained in the list control as the body content.
* @param THtmlWriter writer
*/
public function renderContents($writer)
{
if($this->_items)
{
$writer->writeLine();
if($this->_items->getCount())
$this->renderPrompt($writer);
$previousGroup=null;
foreach($this->_items as $item)
{
if($item->getEnabled())
{
if($item->getHasAttributes())
{
$group=$item->getAttributes()->remove('Group');
if($group!==$previousGroup)
{
if($previousGroup!==null)
{
$writer->renderEndTag();
$writer->writeLine();
$previousGroup=null;
}
if($group!==null)
{
$writer->addAttribute('label',$group);
$writer->renderBeginTag('optgroup');
$writer->writeLine();
$previousGroup=$group;
}
}
foreach($item->getAttributes() as $name=>$value)
$writer->addAttribute($name,$value);
}
else if($previousGroup!==null)
{
$writer->renderEndTag();
$writer->writeLine();
$previousGroup=null;
}
if($item->getSelected())
$writer->addAttribute('selected','selected');
$writer->addAttribute('value',$item->getValue());
$writer->renderBeginTag('option');
$writer->write(THttpUtility::htmlEncode($item->getText()));
$writer->renderEndTag();
$writer->writeLine();
}
}
if($previousGroup!==null)
{
$writer->renderEndTag();
$writer->writeLine();
}
}
}
/**
* Formats the text value according to a format string.
* If the format string is empty, the original value is converted into
* a string and returned.
* If the format string starts with '#', the string is treated as a PHP expression
* within which the token '{0}' is translated with the data value to be formated.
* Otherwise, the format string and the data value are passed
* as the first and second parameters in {@link sprintf}.
* @param string format string
* @param mixed the data to be formatted
* @return string the formatted result
*/
protected function formatDataValue($formatString,$value)
{
if($formatString==='')
return TPropertyValue::ensureString($value);
else if($formatString[0]==='#')
{
$expression=strtr(substr($formatString,1),array('{0}'=>'$value'));
try
{
if(eval("\$result=$expression;")===false)
throw new Exception('');
return $result;
}
catch(Exception $e)
{
throw new TInvalidDataValueException('listcontrol_expression_invalid',get_class($this),$expression,$e->getMessage());
}
}
else
return sprintf($formatString,$value);
}
}
/**
* TListItemCollection class.
*
* TListItemCollection maintains a list of {@link TListItem} for {@link TListControl}.
*
* @author Qiang Xue
* @version $Id$
* @package System.Web.UI.WebControls
* @since 3.0
*/
class TListItemCollection extends TList
{
/**
* Creates a list item object.
* This method may be overriden to provide a customized list item object.
* @param integer index where the newly created item is to be inserted at.
* If -1, the item will be appended to the end.
* @return TListItem list item object
*/
public function createListItem($index=-1)
{
$item=$this->createNewListItem();
if($index<0)
$this->add($item);
else
$this->insertAt($index,$item);
return $item;
}
/**
* @return TListItem new item.
*/
protected function createNewListItem($text=null)
{
$item = new TListItem;
if(!is_null($text))
$item->setText($text);
return $item;
}
/**
* 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 insertAt($index,$item)
{
if(is_string($item))
$item = $this->createNewListItem($item);
if(!($item instanceof TListItem))
throw new TInvalidDataTypeException('listitemcollection_item_invalid',get_class($this));
parent::insertAt($index,$item);
}
/**
* 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);
$index=0;
foreach($this as $item)
{
if($item->getValue()===$value && ($includeDisabled || $item->getEnabled()))
return $index;
$index++;
}
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);
$index=0;
foreach($this as $item)
{
if($item->getText()===$text && ($includeDisabled || $item->getEnabled()))
return $index;
$index++;
}
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)
return $this->itemAt($index);
else
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)
return $this->itemAt($index);
else
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();
if($state!==null)
$this->copyFrom($state);
}
/**
* Saves state of items.
* This method should only be used by framework and control developers.
* @return array|null the saved state
*/
public function saveState()
{
return ($this->getCount()>0) ? $this->toArray() : null;
}
}
/**
* IListControlAdapter interface
*
* @author Wei Zhuo
* @version $Revision: $ Sun Jun 25 04:53:43 EST 2006 $
* @package System.Web.UI.ActiveControls
* @since 3.0
*/
interface IListControlAdapter
{
/**
* Selects an item based on zero-base index on the client side.
* @param integer the index (zero-based) of the item to be selected
*/
public function setSelectedIndex($index);
/**
* Selects a list of item based on zero-base indices on the client side.
* @param array list of index of items to be selected
*/
public function setSelectedIndices($indices);
/**
* Sets selection by item value on the client side.
* @param string the value of the item to be selected.
*/
public function setSelectedValue($value);
/**
* Sets selection by a list of item values on the client side.
* @param array list of the selected item values
*/
public function setSelectedValues($values);
/**
* Clears all existing selections on the client side.
*/
public function clearSelection();
}
?>