Class: TListControl

Source Location: /Web/UI/WebControls/TListControl.php

Class Overview

TComponent
   |
   --TControl
      |
      --TWebControl
         |
         --TListControl

TListControl class

Class Details

[line 120]
TListControl class

TListControl is the parent class for list based controls in the PRADO framework (TListBox, TDropDownList, TCheckBoxList, TRadioButtonList).

There are three possible ways to define items to be listed in a list control:

Inside the template file as a child control of the list control.

By manually adding TListItem controls to the Items property of a list

    $object = new TListBox;
  $item = new TListItem;
  $item->Text="Text to display";
  $item->Value="value";
    $object->Items->add($item);

By binding a dataSource to the list control.

The data source a TListControl can be binded to one of the following types of collection;

An array
A class that implements Traversible (e.g. ArrayObject, TCollection).

Each item in the data source can be one of the following:

An object that implements the IListItemSource interface. This is useful for binding objects to a list source, that can then be asked to provide the Text and Value data for the list item.
A scalar value, or object that can be converted to a string.
An array or an object implementing Traversible interface. If this is the case, the DataTextField and DataValueField properties of the list control MUST be set so the control knows which index of the array to get the Text and Value data for the item in the list.

Properties

EncodeText, boolean, default=true, kept in viewstate
Gets or sets the value indicating whether Text in list items should be HTML-encoded when rendering.
AutoPostBack, boolean, kept in viewstate
Gets or sets whether a postback response will be initiated when the selection of the list changes.
Items, TCollection, read-only, kept in viewstate
Gets the collection of list items defined for this control.
DataSource, object, iterable
Gets or sets the data source this list control will use
DataTextField, string, kept in viewstate
Gets or sets the index to use into a data source item to

retrieve the Text property for the list item

DataValueField, string, kept in viewstate
Gets or sets the index to use into a data source item to

retrieve the Value property for the list item

DataTextFormatString, string, kept in viewstate
Gets or sets the format string to use for the Text property of the

list item. The format string is used as the first parameter to the ssprintf() function to transform the item text.

SelectedItem, TListItem, read-only
Gets the selected item that has the lowest cardinal index.
SelectedIndex, integer, default=-1
Gets or sets the index of the selected item. Note, setting a SelectedIndex will clear all other selected indexes.
SelectedValue, string
Gets or sets the item with a value. Note, when setting a selection by value, if the value is not found, an exception will be raised. If found, the rest selections will be cleared.

Events

OnSelectionChanged Occurs when the selection of the list changes

abstract:
version:	$Revision: 1.38 $, last update on $Date: 2005/09/07 04:11:02 $
author:	Qiang Xue <qiang.xue@gmail.com>
author:	Marcus Nyeholt <tanus@users.sourceforge.net>

[ Top ]

Variables

Methods

Child classes:

TCheckBoxList: TCheckBoxList class

TDropDownList: TDropDownList class

TListBox: TListBox class

Inherited Variables

Class: TComponent

TComponent::$children

Inherited Methods

Class: TWebControl

TWebControl::appendJavascriptEvent(): Append a javascript statement to a particular attribute, e.g. "onclick".
TWebControl::getAccessKey()
TWebControl::getAttributesToRender(): This overrides the parent implementation by rendering more TWebControl-specific attributes.
TWebControl::getBackColor()
TWebControl::getBorderColor()
TWebControl::getBorderStyle()
TWebControl::getBorderWidth()
TWebControl::getCssClass()
TWebControl::getForeColor()
TWebControl::getHeight()
TWebControl::getJavascriptEvents(): Get the list of all the javascript statements.
TWebControl::getStyle()
TWebControl::getTabIndex()
TWebControl::getToolTip()
TWebControl::getWidth()
TWebControl::isEnabled()
TWebControl::parseStyle(): Parses a CSS style string into an array representation.
TWebControl::removeJavascriptEvent(): Remove all or a particular javascript statements.
TWebControl::setAccessKey(): Sets the access key of the control.
TWebControl::setBackColor(): Sets the background color of the control
TWebControl::setBorderColor(): Sets the border color of the control
TWebControl::setBorderStyle(): Sets the border style of the control
TWebControl::setBorderWidth(): Sets the border width of the control
TWebControl::setCssClass(): Sets the CSS class name of the control
TWebControl::setEnabled(): Enables or disables a control.
TWebControl::setForeColor(): Sets the foreground color of the control
TWebControl::setHeight(): Sets the height of the control
TWebControl::setStyle(): Sets the CSS style of the control.
TWebControl::setTabIndex(): Sets the tab index of the control.
TWebControl::setToolTip(): Sets the tooltip of the control.
TWebControl::setWidth(): Sets the width of the control

Class: TControl

TControl::__construct(): Constructor.
TControl::addBody(): Appends an object into the body collection of this control.
TControl::addParsedObject(): Adds the object parsed in template as a body of the component.
TControl::allowBody(): Determines whether the control can add the object as a body.
TControl::clearViewState(): Clears viewstate
TControl::findBodyControl()
TControl::getAttribute()
TControl::getAttributes(): Returns the attribute list object.
TControl::getAttributesToRender(): Returns attributes to be rendered.
TControl::getBodies()
TControl::getClientID(): Returns the client ID of the component.
TControl::getContainer(): Returns the container of this component.
TControl::getSkinName()
TControl::getTagName()
TControl::getViewState(): Returns a viewstate value.
TControl::initSkin(): Initializes a skin for the control. If a skin name is provided then that skin will be loaded.
TControl::isViewStateEnabled()
TControl::isVisible(): This method checks whether a control is visible.
TControl::loadViewState(): Loads viewstate into this component and its children.
TControl::onBubbleEvent(): This method responds to a bubbled event.
TControl::onInit(): This method is invoked when the control enters 'Init' stage.
TControl::onInitRecursive(): Calls onInit of this control and its children recursively.
TControl::onLoad(): This method is invoked when the control enters 'Load' stage.
TControl::onLoadRecursive(): Calls onLoad of this control and its children recursively.
TControl::onPreRender(): This method is invoked when the control enters 'PreRender' stage.
TControl::onPreRenderRecursive(): Calls onPreRender of this control and its children recursively.
TControl::onUnload(): This method is invoked when the control enters 'Unload' stage.
TControl::onUnloadRecursive(): Calls onUnload of this control and its children recursively.
TControl::raiseBubbleEvent(): Invokes the parent's onBubbleEvent method.
TControl::removeBodies(): Removes all body content.
TControl::render(): Renders this control.
TControl::renderAttributes(): Renders the attributes.
TControl::renderBody(): Renders the body content.
TControl::saveViewState(): Returns the viewstate of this component and its children.
TControl::setAttribute(): Sets an attribute.
TControl::setContainer(): Sets the container of this component
TControl::setEnableViewState()
TControl::setSkinName(): Sets the skin to use for this control
TControl::setTagName(): Sets the tag name.
TControl::setViewState(): Sets a viewstate value.
TControl::setVisible()
TControl::synchronizeControl(): This method should only be used by framework developer.

Class: TComponent

TComponent::__construct(): Constructor.
TComponent::addChild(): Adds a child component.
TComponent::addParsedObject(): Handles a component or string met in template.
TComponent::attachEventHandler(): Attaches a handler function to an event.
TComponent::bindProperty(): Sets up the binding between a property and an expression.
TComponent::canGetProperty(): Determines whether a property can be read.
TComponent::canSetProperty(): Determines whether a property can be written.
TComponent::createComponent(): Creates a child component.
TComponent::dataBind(): Performs the databinding for this component.
TComponent::evaluateExpression(): Evaluates a PHP expression.
TComponent::evaluateStatements(): Evaluates a list of PHP statements.
TComponent::findObject(): Finds an object by its ID path.
TComponent::getApplication()
TComponent::getChild()
TComponent::getChildren()
TComponent::getDefinition(): Returns or builds a component definition.
TComponent::getGlobalization(): Returns the Globalization instance for the application.
TComponent::getID()
TComponent::getModule(): Returns the module object that contains the component or the page containing the component.
TComponent::getPage()
TComponent::getParent()
TComponent::getPropertyInitValue(): Gets the initial value of a property.
TComponent::getPropertyType(): Returns the type of a property
TComponent::getRequest(): Returns the request object associated with application.
TComponent::getServiceManager(): Returns the service manager for this application.
TComponent::getSession(): Returns the session object associated with the application.
TComponent::getSessionState(): Returns a session variable.
TComponent::getUniqueID(): Returns the unique ID of the component.
TComponent::getUser(): Returns the user object associated with the application.
TComponent::hasChildren()
TComponent::hasEvent(): Determines whether an event is defined.
TComponent::hasProperty(): Determines whether a property is defined.
TComponent::initProperties(): Initializes the property values.
TComponent::instantiateTemplate(): Parses a template string and instantiates the content.
TComponent::onDataBinding(): This method is invoked when dataBind is invoked for the component.
TComponent::raiseEvent(): Invokes all attached event handler functions for a particular event.
TComponent::removeChild(): Removes a child component.
TComponent::removeChildren(): Removes all child components.
TComponent::setAttribute(): Sets an attribute.
TComponent::setDefinition(): Sets a component definition.
TComponent::setID(): Sets a component ID.
TComponent::setParent(): Sets the parent of this component.
TComponent::setPropertyInitValue(): Sets the initial value of a property.
TComponent::setRoot(): Sets the root component in the component hierarchy.
TComponent::setSessionState(): Sets a session variable.
TComponent::unbindProperty(): Breaks the binding between a property and an expression.
TComponent::__get(): Returns a property value by name or a child component by ID.
TComponent::__set(): Sets value of a component property.

Class Variables

$dataSource = null

[line 131]

A datasource for this control

access:

protected

Type:

object

[ Top ]

$items =

[line 125]

list of TListItem controls

access:

protected

Type:

mixed

[ Top ]

$selectedValue =

[line 137]

Set the selected value of a given item.

access:

protected

Type:

mixed

[ Top ]

Class Methods

constructor __construct [line 143]

void __construct(
)

Set the items list to be empty.

access:

public

Overridden in child classes as:

TDropDownList::__construct()

TListBox::__construct(): Sets the HTML tag displaying the listbox.

Overrides TControl::__construct() (Constructor.)

[ Top ]

method addParsedObject [line 411]

void addParsedObject(
TComponent|string
$object, TComponent
$context)

This method overrides the parent implementation to handle TListItem.

access:

public

Overrides TControl::addParsedObject() (Adds the object parsed in template as a body of the component.)

Parameters:

TComponent\|string	$object	the newly parsed object
TComponent	$context	the template owner

[ Top ]

method allowBody [line 422]

boolean allowBody(
mixed
$object)

Overrides parent implementation to disable body addition.

access:

public

Overrides TControl::allowBody() (Determines whether the control can add the object as a body.)

Parameters:

mixed

$object

the object to be added

[ Top ]

method allSelection [line 311]

void allSelection(
)

Sets all items selected.

access:

public

[ Top ]

method clearSelection [line 302]

void clearSelection(
)

Sets all items not selected.

access:

public

[ Top ]

method getDataSource [line 332]

mixed getDataSource(
)

return:	the data source that populates the items of the list control.
access:	public

[ Top ]

method getDataTextField [line 198]

string getDataTextField(
)

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

[ Top ]

method getDataTextFormatString [line 214]

string getDataTextFormatString(
)

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

[ Top ]

method getDataValueField [line 230]

string getDataValueField(
)

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

[ Top ]

method getItems [line 190]

ArrayObject getItems(
)

return:	list of TListItem components
access:	public

[ Top ]

method getSelectedIndex [line 269]

integer getSelectedIndex(
)

return:	the index of the item being selected, -1 if no selection
access:	public

Overridden in child classes as:

TListBox::getSelectedIndex()

[ Top ]

method getSelectedItem [line 246]

TListItem|null getSelectedItem(
)

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

Overridden in child classes as:

TListBox::getSelectedItem()

[ Top ]

method getSelectedValue [line 280]

string getSelectedValue(
)

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

Overridden in child classes as:

TListBox::getSelectedValue()

[ Top ]

method getValidationPropertyValue [line 513]

mixed getValidationPropertyValue(
)

Returns the value of the property that needs validation.

return:	the property value to be validated
access:	public

[ Top ]

method invertSelection [line 320]

void invertSelection(
)

Invert items selection.

access:

public

[ Top ]

method isAutoPostBack [line 171]

boolean isAutoPostBack(
)

return:	a value indicating whether an automatic postback to the server will occur whenever the user modifies the selection of the list control and then tabs out of it.
access:	public

[ Top ]

method isEncodeText [line 152]

boolean isEncodeText(
)

return:	whether the text in list items should be HTML encoded before rendering
access:	public

[ Top ]

method loadPostData [line 461]

boolean loadPostData(
string
$key, array
&$values)

Loads user input data.

This method is primarly used by framework developers.

return:	whether the data of the component has been changed
access:	public

Parameters:

string	$key	the key that can be used to retrieve data from the input data collection
array	&$values	the input data collection

[ Top ]

method loadViewState [line 434]

void loadViewState(
array
$viewState)

Loads viewstate into this control and its children.

This method is overriden to load the items data from view state, as well as the mapping between indexes and text/value pairs for the list items.

access:

public

Overrides TControl::loadViewState() (Loads viewstate into this component and its children.)

Parameters:

array

$viewState

viewstate to be loaded

[ Top ]

method onDataBinding [line 357]

void onDataBinding(
TEventParameter
$param)

This method is invoked when OnDataBinding event is raised.

Opens up the data source and creates all the TListItem controls needed to render the data source.

access:

protected

Overrides TComponent::onDataBinding() (This method is invoked when dataBind is invoked for the component.)

Parameters:

TEventParameter

$param

event parameter

[ Top ]

method onSelectionChanged [line 504]

void onSelectionChanged(
TEventParameter
$param)

This method is invoked when the value of the Selection property changes between posts to the server.

The method raises 'OnSelectionChanged' event to fire up the event delegates. If you override this method, be sure to call the parent implementation so that the event delegates can be invoked.

access:

public

Parameters:

TEventParameter

$param

event parameter to be passed to the event handlers

[ Top ]

method raisePostDataChangedEvent [line 492]

void raisePostDataChangedEvent(
)

Raises postdata changed event.

This method calls OnSelectionChanged method. This method is primarly used by framework and component developers.

access:

public

[ Top ]

method saveViewState [line 447]

array|null saveViewState(
)

Returns the viewstate of this control and its children.

This method is overriden to save the items data in view state, as well as the mapping between indexes and text/value pairs for the list items.

return:	viewstate to be saved
access:	public

Overridden in child classes as:

TDropDownList::saveViewState(): Returns the viewstate of this control and its children.

Overrides TControl::saveViewState() (Returns the viewstate of this component and its children.)

[ Top ]

method setAutoPostBack [line 182]

void setAutoPostBack(
boolean
$value)

Sets the value indicating if postback automatically.

An automatic postback to the server will occur whenever the user modifies the selection of the list control and then tabs out of it.

access:

public

Parameters:

boolean

$value

the value indicating if postback automatically

[ Top ]

method setDataSource [line 341]

void setDataSource(
mixed
$value)

Sets the data source that populates the items of the list control.

access:

public

Parameters:

mixed

$value

the data source.

[ Top ]

method setDataTextField [line 206]

void setDataTextField(
string
$value)

access:

public

Parameters:

string

$value

the field of the data source that provides the text content of the list items.

[ Top ]

method setDataTextFormatString [line 222]

void setDataTextFormatString(
string
$value)

access:

public

Parameters:

string

$value

the formatting string used to control how data bound to the list control is displayed.

[ Top ]

method setDataValueField [line 238]

void setDataValueField(
string
$value)

access:

public

Parameters:

string

$value

the field of the data source that provides the value of each list item.

[ Top ]

method setEncodeText [line 161]

void setEncodeText(
boolean
$value)

Sets the value indicating whether the text in list items should be HTML encoded before rendering

access:

public

Parameters:

boolean

$value

whether the text should be HTML encoded before rendering

[ Top ]

method setSelectedIndex [line 255]

void setSelectedIndex(
integer
$index)

access:

public

Overridden in child classes as:

TListBox::setSelectedIndex()

Parameters:

integer

$index

the index of the item to be selected

[ Top ]

method setSelectedValue [line 290]

void setSelectedValue(
string
$value)

Sets selection by item value.

access:

public

Overridden in child classes as:

TListBox::setSelectedValue(): Sets selection by item value.

Parameters:

string

$value

the value of the item to be selected.

[ Top ]