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:

  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.

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 addParsedObject (mixed $object)
void clearSelection ()
string formatDataValue (string $formatString, mixed $value)
boolean getAutoPostBack ()
boolean getCausesValidation ()
string getDataTextField ()
string getDataValueField ()
boolean getHasItems ()
boolean getIsMultiSelect ()
integer getItemCount ()
integer getSelectedIndex ()
string getSelectedValue ()
string getTagName ()
string getText ()
string getValidationGroup ()
void loadState ()
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)

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

Redefined in descendants as:
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:
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:
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:
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:
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)
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)
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)

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

Redefined in descendants as:
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:
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:
setSelectedIndices (line 440)
  • access: public
void setSelectedIndices (array $indices)
  • array $indices: list of index of items to be selected

Redefined in descendants as:
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:
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