Class TListControl
Direct Known Sub-classes:
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: 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.
Constants Inherited From TControl |
AUTOMATIC_ID_PREFIX,
CLIENT_ID_SEPARATOR,
CS_CHILD_INITIALIZED,
CS_CONSTRUCTED,
CS_INITIALIZED,
CS_LOADED,
CS_PRERENDERED,
CS_STATE_LOADED,
ID_FORMAT,
ID_SEPARATOR,
IS_CHILD_CREATED,
IS_CREATING_CHILD,
IS_DISABLE_THEMING,
IS_DISABLE_VIEWSTATE,
IS_ID_SET,
IS_SKIN_APPLIED,
IS_STYLESHEET_APPLIED,
RF_ADAPTER,
RF_AUTO_BINDINGS,
RF_CHILD_STATE,
RF_CONTROLS,
RF_CONTROLSTATE,
RF_DATA_BINDINGS,
RF_EVENTS,
RF_NAMED_CONTROLS,
RF_NAMED_CONTROLS_ID,
RF_NAMED_OBJECTS,
RF_SKIN_ID,
|
Method Summary |
protected
void
|
Adds attributes to renderer.
|
void
|
Adds object parsed from template to the control.
|
void
|
Clears all existing selections.
|
protected
TListItemCollection
|
Creates a collection object to hold list items.
|
protected
string
|
Formats the text value according to a format string.
|
boolean
|
|
boolean
|
|
boolean
|
|
protected
string
|
Gets the name of the javascript class responsible for performing postback for this control.
|
string
|
Returns the value of the selected item with the lowest cardinal index.
|
string
|
|
string
|
|
string
|
|
string
|
|
boolean
|
|
boolean
|
|
protected
boolean
|
|
integer
|
|
TListItemCollection
|
|
protected
array
|
|
string
|
|
string
|
|
integer
|
|
array
|
|
TListItem|null
|
|
string
|
|
array
|
|
protected
string
|
|
string
|
|
string
|
|
void
|
Loads items from viewstate.
|
void
|
Raises OnSelectedIndexChanged event when selection is changed.
|
void
|
Raises OnTextChanged event when selection is changed.
|
protected
void
|
Performs databinding to populate list items from data source.
|
protected
void
|
Renders the javascript for list control.
|
void
|
Renders body content of the list control.
|
protected
void
|
Renders the prompt text, if any.
|
void
|
Saves items into viewstate.
|
void
|
|
void
|
Sets the value indicating if postback automatically.
|
void
|
|
void
|
Selects an item by the specified value.
|
void
|
|
void
|
|
void
|
Sets data text format string.
|
void
|
|
void
|
|
void
|
|
void
|
|
void
|
|
void
|
|
void
|
Sets selection by item value.
|
void
|
|
void
|
|
void
|
|
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::setAllowCustomPaging(), TDataBoundControl::setAllowPaging(), TDataBoundControl::setCurrentPageIndex(), TDataBoundControl::setDataMember(), TDataBoundControl::setDataSource(), TDataBoundControl::setDataSourceID(), TDataBoundControl::setInitialized(), TDataBoundControl::setIsDataBound(), TDataBoundControl::setPageSize(), TDataBoundControl::setRequiresDataBinding(), TDataBoundControl::setVirtualItemCount(), TDataBoundControl::validateDataSource()
|
Methods 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()
|
Methods Inherited From TControl |
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()
|
Methods 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()
|
Method Details |
addAttributesToRender
protected void addAttributesToRender |
(THtmlWriter $writer ) |
Adds attributes to renderer.
|
addParsedObject
public void addParsedObject |
(mixed $object ) |
Adds object parsed from template to the control.
This method adds only TListItem objects into the Items collection. All other objects are ignored.
Input |
mixed | $object | object parsed from template |
Output |
Exception |
|
clearSelection
public void clearSelection |
() |
Clears all existing selections.
|
createListItemCollection
Creates a collection object to hold list items.
This method may be overriden to create a customized collection.
|
formatDataValue
protected string formatDataValue |
(string $formatString , mixed $value ) |
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.
Input |
string | $formatString | format string |
mixed | $value | the data to be formatted |
Output |
string
| the formatted result |
Exception |
|
getAppendDataBoundItems
public boolean getAppendDataBoundItems |
() |
Output |
boolean
| whether performing databind should append items or clear the existing ones. Defaults to false. |
Exception |
|
getAutoPostBack
public boolean getAutoPostBack |
() |
Output |
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. |
Exception |
|
getCausesValidation
public boolean getCausesValidation |
() |
Output |
boolean
| whether postback event trigger by this list control will cause input validation, default is true. |
Exception |
|
getClientClassName
protected string getClientClassName |
() |
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.
Output |
string
| the javascript class name |
Exception |
|
getData
Returns the value of the selected item with the lowest cardinal index.
This method is required by IDataRenderer. It is the same as getSelectedValue().
Output |
string
| the value of the selected item with the lowest cardinal index, empty if no selection. |
Exception |
|
getDataGroupField
public string getDataGroupField |
() |
Output |
string
| the field of the data source that provides the label of the list item groups |
Exception |
|
getDataTextField
public string getDataTextField |
() |
Output |
string
| the field of the data source that provides the text content of the list items. |
Exception |
|
getDataTextFormatString
public string getDataTextFormatString |
() |
Output |
string
| the formatting string used to control how data bound to the list control is displayed. |
Exception |
|
getDataValueField
public string getDataValueField |
() |
Output |
string
| the field of the data source that provides the value of each list item. |
Exception |
|
getEnableClientScript
public boolean getEnableClientScript |
() |
Output |
boolean
| whether to render javascript. |
Exception |
|
getHasItems
public boolean getHasItems |
() |
Output |
boolean
| whether the list control contains any items. |
Exception |
|
getIsMultiSelect
protected boolean getIsMultiSelect |
() |
Output |
boolean
| whether this is a multiselect control. Defaults to false. |
Exception |
|
getItemCount
public integer getItemCount |
() |
Output |
integer
| the number of items in the list control |
Exception |
|
getItems
|
getPostBackOptions
protected array getPostBackOptions |
() |
Output |
array
| postback options for JS postback code |
Exception |
|
getPromptText
public string getPromptText |
() |
Output |
string
| the prompt text which is to be displayed as the first list item. |
Exception |
|
getPromptValue
public string getPromptValue |
() |
Output |
string
| the prompt selection value. |
Exception |
|
getSelectedIndex
public integer getSelectedIndex |
() |
Output |
integer
| the index (zero-based) of the item being selected, -1 if no item is selected. |
Exception |
|
getSelectedIndices
public array getSelectedIndices |
() |
Output |
array
| list of index of items that are selected |
Exception |
|
getSelectedItem
Output |
TListItem|null
| the selected item with the lowest cardinal index, null if no item is selected. |
Exception |
|
getSelectedValue
public string getSelectedValue |
() |
Output |
string
| the value of the selected item with the lowest cardinal index, empty if no selection |
Exception |
|
getSelectedValues
public array getSelectedValues |
() |
Output |
array
| list of the selected item values (strings) |
Exception |
|
getTagName
protected string getTagName |
() |
Output |
string
| tag name of the list control |
Exception |
|
getText
Output |
string
| selected value |
Exception |
|
getValidationGroup
public string getValidationGroup |
() |
Output |
string
| the group of validators which the list control causes validation upon postback |
Exception |
|
loadState
Loads items from viewstate.
This method is invoked right after control state is loaded.
|
onSelectedIndexChanged
Raises OnSelectedIndexChanged event when selection is changed.
This method is invoked when the list control has its selection changed by end-users.
|
onTextChanged
Raises OnTextChanged event when selection is changed.
This method is invoked when the list control has its selection changed by end-users.
|
performDataBinding
protected void performDataBinding |
(Traversable $data ) |
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.
Input |
Traversable | $data | the data |
Output |
Exception |
|
renderClientControlScript
protected void renderClientControlScript |
(mixed $writer ) |
Renders the javascript for list control.
Input |
mixed | $writer | |
Output |
Exception |
|
renderContents
Renders body content of the list control.
This method renders items contained in the list control as the body content.
|
renderPrompt
Renders the prompt text, if any.
|
saveState
Saves items into viewstate.
This method is invoked right before control state is to be saved.
|
setAppendDataBoundItems
public void setAppendDataBoundItems |
(boolean $value ) |
Input |
boolean | $value | whether performing databind should append items or clear the existing ones. |
Output |
Exception |
|
setAutoPostBack
public void setAutoPostBack |
(boolean $value ) |
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.
Input |
boolean | $value | the value indicating if postback automatically |
Output |
Exception |
|
setCausesValidation
public void setCausesValidation |
(boolean $value ) |
Input |
boolean | $value | whether postback event trigger by this list control will cause input validation. |
Output |
Exception |
|
setData
public void setData |
(string $value ) |
Selects an item by the specified value.
This method is required by IDataRenderer. It is the same as setSelectedValue().
Input |
string | $value | the value of the item to be selected. |
Output |
Exception |
|
setDataGroupField
public void setDataGroupField |
(string $value ) |
Input |
string | $value | the field of the data source that provides the label of the list item groups |
Output |
Exception |
|
setDataTextField
public void setDataTextField |
(string $value ) |
Input |
string | $value | the field of the data source that provides the text content of the list items. |
Output |
Exception |
|
setDataTextFormatString
public void setDataTextFormatString |
(string $value ) |
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.
Input |
string | $value | the formatting string used to control how data bound to the list control is displayed. |
Output |
Exception |
|
setDataValueField
public void setDataValueField |
(string $value ) |
Input |
string | $value | the field of the data source that provides the value of each list item. |
Output |
Exception |
|
setEnableClientScript
public void setEnableClientScript |
(boolean $value ) |
Input |
boolean | $value | whether to render javascript. |
Output |
Exception |
|
setPromptText
public void setPromptText |
(string $value ) |
Input |
string | $value | the prompt text which is to be displayed as the first list item. |
Output |
Exception |
|
setPromptValue
public void setPromptValue |
(string $value ) |
Input |
string | $value | the prompt selection value. If empty, PromptText will be used as the value. |
Output |
Exception |
|
setSelectedIndex
public void setSelectedIndex |
(integer $index ) |
Input |
integer | $index | the index (zero-based) of the item to be selected |
Output |
Exception |
|
setSelectedIndices
public void setSelectedIndices |
(array $indices ) |
Input |
array | $indices | list of index of items to be selected |
Output |
Exception |
|
setSelectedValue
public void setSelectedValue |
(string $value ) |
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.
Input |
string | $value | the value of the item to be selected. |
Output |
Exception |
|
setSelectedValues
public void setSelectedValues |
(array $values ) |
Input |
array | $values | list of the selected item values |
Output |
Exception |
|
setText
public void setText |
(string $value ) |
Input |
string | $value | value to be selected |
Output |
Exception |
|
setValidationGroup
public void setValidationGroup |
(string $value ) |
Input |
string | $value | the group of validators which the list control causes validation upon postback |
Output |
Exception |
|
|