## Class TListControl

Description

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:

     <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 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,

     $dataSource=array(
        array('name'=>'John', 'age'=>31),
        array('name'=>'Cary', 'age'=>28),
        array('name'=>'Rose', 'age'=>35),
     );

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: $Revision: $ $Date: $
- author: Qiang Xue <qiang.xue@gmail.com>

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

    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 addAttributesToRender (THtmlWriter $writer)
void addParsedObject (mixed $object)
void clearSelection ()
TListItemCollection createListItemCollection ()
string formatDataValue (string $formatString, mixed $value)
boolean getAppendDataBoundItems ()
boolean getAutoPostBack ()
boolean getCausesValidation ()
string getDataTextField ()
string getDataTextFormatString ()
string getDataValueField ()
boolean getHasItems ()
boolean getIsMultiSelect ()
integer getItemCount ()
TListItemCollection getItems ()
array getPostBackOptions ()
integer getSelectedIndex ()
array getSelectedIndices ()
TListItem|null getSelectedItem ()
string getSelectedValue ()
array getSelectedValues ()
string getTagName ()
string getText ()
string getValidationGroup ()
void loadState ()
void onSelectedIndexChanged (TEventParameter $param)
void onTextChanged (TEventParameter $param)
void performDataBinding (Traversable $data)
void renderContents (THtmlWriter $writer)
void saveState ()
void setAppendDataBoundItems (boolean $value)
void setAutoPostBack (boolean $value)
void setCausesValidation (boolean $value)
void setDataTextField (string $value)
void setDataTextFormatString (string $value)
void setDataValueField (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 109)

Adds attributes to renderer.

- access: protected

void addAttributesToRender (THtmlWriter $writer)

- THtmlWriter $writer: the renderer

Redefinition of:

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

Redefined in descendants as:

- TBulletedList::addAttributesToRender() : Adds attribute name-value pairs to renderer.
- TDropDownList::addAttributesToRender() : Adds attributes to renderer.
- TListBox::addAttributesToRender() : Adds attribute name-value pairs to renderer.

addParsedObject (line 143)

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()
  Processes an object that is created during parsing template.

clearSelection (line 555)

Clears all existing selections.

- access: public

void clearSelection ()
createListItemCollection (line 215)

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 ()
formatDataValue (line 646)

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 260)

- return: whether performing databind should append items or clear the existing ones. Defaults to false.
- access: public

boolean getAppendDataBoundItems ()
getAutoPostBack (line 278)

- 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 297)

- return: whether postback event trigger by this list control will cause input validation, default is true.
- access: public

boolean getCausesValidation ()
getDataTextField (line 313)

- return: the field of the data source that provides the text content of the list items.
- access: public

string getDataTextField ()
getDataTextFormatString (line 329)

- return: the formatting string used to control how data bound to the list control is displayed.
- access: public

string getDataTextFormatString ()
getDataValueField (line 349)

- return: the field of the data source that provides the value of each list item.
- access: public

string getDataValueField ()
getHasItems (line 373)

- return: whether the list control contains any items.
- access: public

boolean getHasItems ()
getIsMultiSelect (line 252)

- return: whether this is a multiselect control. Defaults to false.
- access: protected

boolean getIsMultiSelect ()

Redefined in descendants as:

- TCheckBoxList::getIsMultiSelect()
- TRadioButtonList::getIsMultiSelect()
- TListBox::getIsMultiSelect()

getItemCount (line 365)

- return: the number of items in the list control
- access: public

integer getItemCount ()
getItems (line 381)

- return: the item collection
- access: public

TListItemCollection getItems ()
getPostBackOptions (line 128)

- return: postback options for JS postback code
- access: protected

array getPostBackOptions ()

Redefined in descendants as:

- TBulletedList::getPostBackOptions()

getSelectedIndex (line 391)

- return: the index (zero-based) of the item being selected, -1 if no item is selected.
- access: public

integer getSelectedIndex ()

Redefined in descendants as:

- TDropDownList::getSelectedIndex()

getSelectedIndices (line 424)

- return: list of index of items that are selected
- access: public

array getSelectedIndices ()
getSelectedItem (line 457)

- return: the selected item with the lowest cardinal index, null if no item is selected.
- access: public

TListItem|null getSelectedItem ()
getSelectedValue (line 468)

- return: the value of the selected item with the lowest cardinal index, empty if no selection
- access: public

string getSelectedValue ()
getSelectedValues (line 501)

- return: list of the selected item values (strings)
- access: public

array getSelectedValues ()
getTagName (line 100)

- 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:

- TBulletedList::getTagName()

getText (line 539)

- return: selected value
- access: public

string getText ()
getValidationGroup (line 567)

- return: the group of validators which the list control causes validation upon postback
- access: public

string getValidationGroup ()
loadState (line 237)

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 586)

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)

- TEventParameter $param: event parameter

onTextChanged (line 598)

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)

- TEventParameter $param: event parameter

performDataBinding (line 164)

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()

renderContents (line 608)

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)

- THtmlWriter $writer: writer

Redefinition of:

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

Redefined in descendants as:

- TBulletedList::renderContents() : Renders the body contents.

saveState (line 224)

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 268)

- access: public

void setAppendDataBoundItems (boolean $value)

- boolean $value: whether performing databind should append items or clear the existing ones.

setAutoPostBack (line 289)

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:

- TBulletedList::setAutoPostBack()

setCausesValidation (line 305)

- access: public

void setCausesValidation (boolean $value)

- boolean $value: whether postback event trigger by this list control will cause input validation.

setDataTextField (line 321)

- 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 341)

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 357)

- access: public

void setDataValueField (string $value)

- string $value: the field of the data source that provides the value of each list item.

setSelectedIndex (line 406)

- access: public

void setSelectedIndex (integer $index)

- integer $index: the index (zero-based) of the item to be selected

Redefined in descendants as:

- TBulletedList::setSelectedIndex()

setSelectedIndices (line 440)

- access: public

void setSelectedIndices (array $indices)

- array $indices: list of index of items to be selected

Redefined in descendants as:

- TBulletedList::setSelectedIndices()
- TRadioButtonList::setSelectedIndices()
- TDropDownList::setSelectedIndices()

setSelectedValue (line 480)

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:

- TBulletedList::setSelectedValue()

setSelectedValues (line 518)

- access: public

void setSelectedValues (array $values)

- array $values: list of the selected item values

setText (line 547)

- access: public

void setText (string $value)

- string $value: value to be selected

setValidationGroup (line 575)

- 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::dataBind()
> TDataBoundControl::dataSourceViewChanged()
> TDataBoundControl::determineDataSource()
> TDataBoundControl::ensureDataBound()
> TDataBoundControl::getData()
> TDataBoundControl::getDataMember()
> TDataBoundControl::getDataSource()
> TDataBoundControl::getDataSourceID()
> TDataBoundControl::getDataSourceView()
> TDataBoundControl::getInitialized()
> TDataBoundControl::getIsDataBound()
> TDataBoundControl::getRequiresDataBinding()
> TDataBoundControl::getSelectParameters()
> TDataBoundControl::getUsingDataSourceID()
> TDataBoundControl::onDataBound()
> TDataBoundControl::onDataSourceChanged()
> TDataBoundControl::onInit()
> TDataBoundControl::onPreRender()
> TDataBoundControl::pagePreLoad()
> TDataBoundControl::performDataBinding()
> TDataBoundControl::setDataMember()
> TDataBoundControl::setDataSource()
> TDataBoundControl::setDataSourceID()
> TDataBoundControl::setInitialized()
> TDataBoundControl::setIsDataBound()
> TDataBoundControl::setRequiresDataBinding()
> TDataBoundControl::validateDataSource()

Inherited From TWebControl

> TWebControl::addAttributesToRender()
> TWebControl::copyBaseAttributes()
> TWebControl::createStyle()
> TWebControl::getAccessKey()
> TWebControl::getBackColor()
> TWebControl::getBorderColor()
> TWebControl::getBorderStyle()
> TWebControl::getBorderWidth()
> TWebControl::getCssClass()
> 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::setForeColor()
> TWebControl::setHeight()
> TWebControl::setStyle()
> TWebControl::setTabIndex()
> TWebControl::setToolTip()
> TWebControl::setWidth()

Inherited From TControl

> TControl::__construct()
> TControl::addedControl()
> TControl::addParsedObject()
> TControl::applyStyleSheetSkin()
> TControl::autoBindProperty()
> TControl::autoDataBindProperties()
> TControl::bindProperty()
> TControl::broadcastEvent()
> TControl::broadcastEventInternal()
> TControl::bubbleEvent()
> TControl::clearChildState()
> TControl::clearControlState()
> TControl::clearNamingContainer()
> TControl::clearViewState()
> TControl::createChildControls()
> TControl::createControlCollection()
> TControl::createdOnTemplate()
> 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::getEnabled()
> TControl::getEnableTheming()
> TControl::getEnableViewState()
> TControl::getHasAdapter()
> TControl::getHasAttributes()
> TControl::getHasControls()
> 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::setEnabled()
> TControl::setEnableTheming()
> TControl::setEnableViewState()
> TControl::setID()
> TControl::setPage()
> TControl::setSkinID()
> TControl::setTemplateControl()
> TControl::setViewState()
> TControl::setVisible()
> 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::attachEventHandler()
> TComponent::canGetProperty()
> TComponent::canSetProperty()
> 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

#### Inherited Constants

Inherited from TControl

Documentation generated on Sun, 04 Jun 2006 18:59:46 -0400 by phpDocumentor 1.3.0RC4