Class TListControl

Description

Implements interfaces:

TListControl class

TListControl is a base class for list controls, such as TListBox, TDropDownList, 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 getItems returns a list of the items in the control. To specify or determine which item is selected, use the SelectedIndex property that indicates the zero-based index of the selected item in the item list. You may also use SelectedItem and SelectedValue to get the selected item and its value. For multiple selection lists (such as TCheckBoxList and TListBox), property SelectedIndices is useful.

TListControl implements AutoPostBack which allows a list control to postback the page if the selections of the list items are changed. The CausesValidation and 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 DataSource and using DataSourceID. The latter two are covered in TDataBoundControl. To specify items via template, using the following template syntax:

  1. <com:TListControl>
  2. <com:TListItem Value="xxx" Text="yyy" >
  3. <com:TListItem Value="xxx" Text="yyy" Selected="true" >
  4. <com:TListItem Value="xxx" Text="yyy" >
  5. </com:TListControl>

When DataSource or DataSourceID is used to populate list items, the DataTextField and 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,

  1. $dataSource=array(
  2. array('name'=>'John', 'age'=>31),
  3. array('name'=>'Cary', 'age'=>28),
  4. array('name'=>'Rose', 'age'=>35),
  5. );
setting DataTextField and 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 DataTextFormatString property may be further used to format how the item should be displayed. See formatDataValue() for an explanation of the format string.

  • abstract:
  • since: 3.0
  • version: $Id: TListControl.php 2255 2007-09-28 02:01:43Z xue $
  • author: Qiang Xue <qiang.xue@gmail.com>

Located in /Web/UI/WebControls/TListControl.php (line 81)

TComponent
   |
   --TApplicationComponent
      |
      --TControl
         |
         --TWebControl
            |
            --TDataBoundControl
               |
               --TListControl
Direct descendents
Class Description
TBulletedList TBulletedList class
TCheckBoxList TCheckBoxList class
TDropDownList TDropDownList class
TListBox TListBox class
Method Summary
void addParsedObject (mixed $object)
void clearSelection ()
string formatDataValue (string $formatString, mixed $value)
boolean getAutoPostBack ()
boolean getCausesValidation ()
string getClientClassName ()
string getData ()
string getDataGroupField ()
string getDataTextField ()
string getDataValueField ()
boolean getHasItems ()
boolean getIsMultiSelect ()
integer getItemCount ()
string getPromptText ()
string getPromptValue ()
integer getSelectedIndex ()
string getSelectedValue ()
string getTagName ()
string getText ()
string getValidationGroup ()
void loadState ()
void performDataBinding (Traversable $data)
void renderClientControlScript (mixed $writer)
void renderContents (THtmlWriter $writer)
void renderPrompt (THtmlWriter $writer)
void saveState ()
void setAppendDataBoundItems (boolean $value)
void setAutoPostBack (boolean $value)
void setCausesValidation (boolean $value)
void setData (string $value)
void setDataGroupField (string $value)
void setDataTextField (string $value)
void setDataTextFormatString (string $value)
void setDataValueField (string $value)
void setEnableClientScript (boolean $value)
void setPromptText (string $value)
void setPromptValue (string $value)
void setSelectedIndex (integer $index)
void setSelectedIndices (array $indices)
void setSelectedValue (string $value)
void setSelectedValues (array $values)
void setText (string $value)
void setValidationGroup (string $value)
Methods
addAttributesToRender (line 128)

Adds attributes to renderer.

  • access: protected
void addAttributesToRender (THtmlWriter $writer)

Redefinition of:
TWebControl::addAttributesToRender()
Adds attribute name-value pairs to renderer.

Redefined in descendants as:
addParsedObject (line 185)

Adds object parsed from template to the control.

This method adds only TListItem objects into the Items collection. All other objects are ignored.

  • access: public
void addParsedObject (mixed $object)
  • mixed $object: object parsed from template

Redefinition of:
TControl::addParsedObject()
Adds the object instantiated on a template to the child control collection.
clearSelection (line 678)

Clears all existing selections.

  • access: public
void clearSelection ()
createListItemCollection (line 274)

Creates a collection object to hold list items.

This method may be overriden to create a customized collection.

  • return: the collection object
  • access: protected
TListItemCollection createListItemCollection ()

Redefined in descendants as:
formatDataValue (line 862)

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 http://www.php.net/sprintf.

  • return: the formatted result
  • access: protected
string formatDataValue (string $formatString, mixed $value)
  • string $formatString: format string
  • mixed $value: the data to be formatted
getAppendDataBoundItems (line 319)
  • return: whether performing databind should append items or clear the existing ones. Defaults to false.
  • access: public
boolean getAppendDataBoundItems ()
getAutoPostBack (line 337)
  • return: 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.
  • access: public
boolean getAutoPostBack ()
getCausesValidation (line 356)
  • return: whether postback event trigger by this list control will cause input validation, default is true.
  • access: public
boolean getCausesValidation ()
getClientClassName (line 162)

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: the javascript class name
  • access: protected
string getClientClassName ()

Redefined in descendants as:
getData (line 559)

Returns the value of the selected item with the lowest cardinal index.

This method is required by IDataRenderer. It is the same as getSelectedValue().

  • return: the value of the selected item with the lowest cardinal index, empty if no selection.
  • access: public
  • since: 3.1.0
  • see: TListControl::getSelectedValue()
string getData ()
getDataGroupField (line 424)
  • return: the field of the data source that provides the label of the list item groups
  • access: public
string getDataGroupField ()
getDataTextField (line 372)
  • return: the field of the data source that provides the text content of the list items.
  • access: public
string getDataTextField ()
getDataTextFormatString (line 388)
  • return: the formatting string used to control how data bound to the list control is displayed.
  • access: public
string getDataTextFormatString ()
getDataValueField (line 408)
  • return: the field of the data source that provides the value of each list item.
  • access: public
string getDataValueField ()
getEnableClientScript (line 111)
  • return: whether to render javascript.
  • access: public
boolean getEnableClientScript ()
getHasItems (line 448)
  • return: whether the list control contains any items.
  • access: public
boolean getHasItems ()
getIsMultiSelect (line 311)
  • return: whether this is a multiselect control. Defaults to false.
  • access: protected
boolean getIsMultiSelect ()

Redefined in descendants as:
getItemCount (line 440)
  • return: the number of items in the list control
  • access: public
integer getItemCount ()
getItems (line 456)
  • return: the item collection
  • access: public
TListItemCollection getItems ()
getPostBackOptions (line 170)
  • return: postback options for JS postback code
  • access: protected
array getPostBackOptions ()

Redefined in descendants as:
getPromptText (line 710)
  • return: the prompt text which is to be displayed as the first list item.
  • access: public
  • since: 3.1.1
string getPromptText ()
getPromptValue (line 729)
string getPromptValue ()
getSelectedIndex (line 466)
  • return: the index (zero-based) of the item being selected, -1 if no item is selected.
  • access: public
integer getSelectedIndex ()
getSelectedIndices (line 501)
  • return: list of index of items that are selected
  • access: public
array getSelectedIndices ()
getSelectedItem (line 543)
  • return: the selected item with the lowest cardinal index, null if no item is selected.
  • access: public
TListItem|null getSelectedItem ()
getSelectedValue (line 580)
  • return: the value of the selected item with the lowest cardinal index, empty if no selection
  • access: public
string getSelectedValue ()
getSelectedValues (line 615)
  • return: list of the selected item values (strings)
  • access: public
array getSelectedValues ()
getTagName (line 103)
  • return: tag name of the list control
  • access: protected
string getTagName ()

Redefinition of:
TWebControl::getTagName()
Returns the tag name used for this control.

Redefined in descendants as:
getText (line 662)
  • return: selected value
  • access: public
string getText ()
getValidationGroup (line 693)
  • return: the group of validators which the list control causes validation upon postback
  • access: public
string getValidationGroup ()
loadState (line 296)

Loads items from viewstate.

This method is invoked right after control state is loaded.

  • access: public
void loadState ()

Redefinition of:
TControl::loadState()
This method is invoked right after the control has loaded its state.
onSelectedIndexChanged (line 750)

Raises OnSelectedIndexChanged event when selection is changed.

This method is invoked when the list control has its selection changed by end-users.

  • access: public
void onSelectedIndexChanged (TEventParameter $param)
onTextChanged (line 762)

Raises OnTextChanged event when selection is changed.

This method is invoked when the list control has its selection changed by end-users.

  • access: public
void onTextChanged (TEventParameter $param)
performDataBinding (line 206)

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.

  • access: protected
void performDataBinding (Traversable $data)
  • Traversable $data: the data

Redefinition of:
TDataBoundControl::performDataBinding()
renderClientControlScript (line 151)

Renders the javascript for list control.

  • access: protected
void renderClientControlScript (mixed $writer)

Redefined in descendants as:
renderContents (line 793)

Renders body content of the list control.

This method renders items contained in the list control as the body content.

  • access: public
void renderContents (THtmlWriter $writer)

Redefinition of:
TWebControl::renderContents()
Renders the body content enclosed between the control tag.

Redefined in descendants as:
renderPrompt (line 772)

Renders the prompt text, if any.

  • access: protected
  • since: 3.1.1
void renderPrompt (THtmlWriter $writer)
saveState (line 283)

Saves items into viewstate.

This method is invoked right before control state is to be saved.

  • access: public
void saveState ()

Redefinition of:
TControl::saveState()
This method is invoked when control state is to be saved.
setAppendDataBoundItems (line 327)
  • access: public
void setAppendDataBoundItems (boolean $value)
  • boolean $value: whether performing databind should append items or clear the existing ones.
setAutoPostBack (line 348)

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.

  • access: public
void setAutoPostBack (boolean $value)
  • boolean $value: the value indicating if postback automatically

Redefined in descendants as:
setCausesValidation (line 364)
  • access: public
void setCausesValidation (boolean $value)
  • boolean $value: whether postback event trigger by this list control will cause input validation.
setData (line 572)

Selects an item by the specified value.

This method is required by IDataRenderer. It is the same as setSelectedValue().

void setData (string $value)
  • string $value: the value of the item to be selected.
setDataGroupField (line 432)
  • access: public
void setDataGroupField (string $value)
  • string $value: the field of the data source that provides the label of the list item groups
setDataTextField (line 380)
  • access: public
void setDataTextField (string $value)
  • string $value: the field of the data source that provides the text content of the list items.
setDataTextFormatString (line 400)

Sets data text format string.

The format string is used in TDataValueFormatter::format() to format the Text property value of each item in the list control.

  • access: public
  • see: TDataValueFormatter::format()
void setDataTextFormatString (string $value)
  • string $value: the formatting string used to control how data bound to the list control is displayed.
setDataValueField (line 416)
  • access: public
void setDataValueField (string $value)
  • string $value: the field of the data source that provides the value of each list item.
setEnableClientScript (line 119)
  • access: public
void setEnableClientScript (boolean $value)
  • boolean $value: whether to render javascript.
setPromptText (line 719)
  • access: public
  • since: 3.1.1
void setPromptText (string $value)
  • string $value: the prompt text which is to be displayed as the first list item.
setPromptValue (line 739)
void setPromptValue (string $value)
  • string $value: the prompt selection value. If empty, PromptText will be used as the value.
setSelectedIndex (line 481)
  • access: public
void setSelectedIndex (integer $index)
  • integer $index: the index (zero-based) of the item to be selected

Redefined in descendants as:
setSelectedIndices (line 517)
  • access: public
void setSelectedIndices (array $indices)
  • array $indices: list of index of items to be selected

Redefined in descendants as:
setSelectedValue (line 592)

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.

  • access: public
void setSelectedValue (string $value)
  • string $value: the value of the item to be selected.

Redefined in descendants as:
setSelectedValues (line 632)
  • access: public
void setSelectedValues (array $values)
  • array $values: list of the selected item values

Redefined in descendants as:
setText (line 670)
  • access: public
void setText (string $value)
  • string $value: value to be selected
setValidationGroup (line 701)
  • access: public
void setValidationGroup (string $value)
  • string $value: the group of validators which the list control causes validation upon postback

Inherited Methods

Inherited From TDataBoundControl

TDataBoundControl::createPagedDataSource()
TDataBoundControl::dataBind()
TDataBoundControl::dataSourceViewChanged()
TDataBoundControl::determineDataSource()
TDataBoundControl::ensureDataBound()
TDataBoundControl::getAllowCustomPaging()
TDataBoundControl::getAllowPaging()
TDataBoundControl::getCurrentPageIndex()
TDataBoundControl::getDataMember()
TDataBoundControl::getDataSource()
TDataBoundControl::getDataSourceID()
TDataBoundControl::getDataSourceView()
TDataBoundControl::getInitialized()
TDataBoundControl::getIsDataBound()
TDataBoundControl::getPageCount()
TDataBoundControl::getPageSize()
TDataBoundControl::getRequiresDataBinding()
TDataBoundControl::getSelectParameters()
TDataBoundControl::getUsingDataSourceID()
TDataBoundControl::getVirtualItemCount()
TDataBoundControl::onDataBound()
TDataBoundControl::onDataSourceChanged()
TDataBoundControl::onInit()
TDataBoundControl::onPreRender()
TDataBoundControl::pagePreLoad()
TDataBoundControl::performDataBinding()
TDataBoundControl::setAllowCustomPaging()
TDataBoundControl::setAllowPaging()
TDataBoundControl::setCurrentPageIndex()
TDataBoundControl::setDataMember()
TDataBoundControl::setDataSource()
TDataBoundControl::setDataSourceID()
TDataBoundControl::setInitialized()
TDataBoundControl::setIsDataBound()
TDataBoundControl::setPageSize()
TDataBoundControl::setRequiresDataBinding()
TDataBoundControl::setVirtualItemCount()
TDataBoundControl::validateDataSource()

Inherited From TWebControl

TWebControl::addAttributesToRender()
TWebControl::clearStyle()
TWebControl::copyBaseAttributes()
TWebControl::createStyle()
TWebControl::getAccessKey()
TWebControl::getBackColor()
TWebControl::getBorderColor()
TWebControl::getBorderStyle()
TWebControl::getBorderWidth()
TWebControl::getCssClass()
TWebControl::getDisplay()
TWebControl::getFont()
TWebControl::getForeColor()
TWebControl::getHasStyle()
TWebControl::getHeight()
TWebControl::getStyle()
TWebControl::getTabIndex()
TWebControl::getTagName()
TWebControl::getToolTip()
TWebControl::getWidth()
TWebControl::render()
TWebControl::renderBeginTag()
TWebControl::renderContents()
TWebControl::renderEndTag()
TWebControl::setAccessKey()
TWebControl::setBackColor()
TWebControl::setBorderColor()
TWebControl::setBorderStyle()
TWebControl::setBorderWidth()
TWebControl::setCssClass()
TWebControl::setDisplay()
TWebControl::setForeColor()
TWebControl::setHeight()
TWebControl::setStyle()
TWebControl::setTabIndex()
TWebControl::setToolTip()
TWebControl::setWidth()

Inherited From TControl

TControl::__construct()
TControl::addedControl()
TControl::addParsedObject()
TControl::addToPostDataLoader()
TControl::applyStyleSheetSkin()
TControl::autoBindProperty()
TControl::autoDataBindProperties()
TControl::bindProperty()
TControl::broadcastEvent()
TControl::bubbleEvent()
TControl::clearChildState()
TControl::clearControlState()
TControl::clearNamingContainer()
TControl::clearViewState()
TControl::convertUniqueIdToClientId()
TControl::createChildControls()
TControl::createControlCollection()
TControl::dataBind()
TControl::dataBindChildren()
TControl::dataBindProperties()
TControl::ensureChildControls()
TControl::findControl()
TControl::findControlsByID()
TControl::findControlsByType()
TControl::focus()
TControl::getAdapter()
TControl::getAllowChildControls()
TControl::getAttribute()
TControl::getAttributes()
TControl::getChildControlsCreated()
TControl::getClientID()
TControl::getControls()
TControl::getControlStage()
TControl::getControlState()
TControl::getCustomData()
TControl::getEnabled()
TControl::getEnableTheming()
TControl::getEnableViewState()
TControl::getHasAdapter()
TControl::getHasAttributes()
TControl::getHasChildInitialized()
TControl::getHasControls()
TControl::getHasInitialized()
TControl::getHasLoaded()
TControl::getHasLoadedPostData()
TControl::getHasPreRendered()
TControl::getID()
TControl::getNamingContainer()
TControl::getPage()
TControl::getParent()
TControl::getRegisteredObject()
TControl::getSkinID()
TControl::getSourceTemplateControl()
TControl::getTemplateControl()
TControl::getUniqueID()
TControl::getViewState()
TControl::getVisible()
TControl::hasAttribute()
TControl::initRecursive()
TControl::isDescendentOf()
TControl::isObjectRegistered()
TControl::loadRecursive()
TControl::loadState()
TControl::loadStateRecursive()
TControl::onDataBinding()
TControl::onInit()
TControl::onLoad()
TControl::onPreRender()
TControl::onUnload()
TControl::preRenderRecursive()
TControl::raiseBubbleEvent()
TControl::registerObject()
TControl::removeAttribute()
TControl::removedControl()
TControl::render()
TControl::renderChildren()
TControl::renderControl()
TControl::saveState()
TControl::saveStateRecursive()
TControl::setAdapter()
TControl::setAttribute()
TControl::setChildControlsCreated()
TControl::setControlStage()
TControl::setControlState()
TControl::setCustomData()
TControl::setEnabled()
TControl::setEnableTheming()
TControl::setEnableViewState()
TControl::setID()
TControl::setPage()
TControl::setSkinID()
TControl::setTemplateControl()
TControl::setViewState()
TControl::setVisible()
TControl::trackViewState()
TControl::traverseChildControls()
TControl::unbindProperty()
TControl::unloadRecursive()
TControl::unregisterObject()
TControl::__get()

Inherited From TApplicationComponent

TApplicationComponent::getApplication()
TApplicationComponent::getRequest()
TApplicationComponent::getResponse()
TApplicationComponent::getService()
TApplicationComponent::getSession()
TApplicationComponent::getUser()
TApplicationComponent::publishAsset()
TApplicationComponent::publishFilePath()

Inherited From TComponent

TComponent::addParsedObject()
TComponent::attachEventHandler()
TComponent::canGetProperty()
TComponent::canSetProperty()
TComponent::createdOnTemplate()
TComponent::detachEventHandler()
TComponent::evaluateExpression()
TComponent::evaluateStatements()
TComponent::getEventHandlers()
TComponent::getSubProperty()
TComponent::hasEvent()
TComponent::hasEventHandler()
TComponent::hasProperty()
TComponent::raiseEvent()
TComponent::setSubProperty()
TComponent::__get()
TComponent::__set()
Class Constants

Documentation generated on Mon, 21 Apr 2008 11:35:27 -0400 by phpDocumentor 1.3.0RC4