TListControl is a base class for list controls, such as {@link TListBox},
{@link TDropDownList}, {@link 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 {@link getItems} returns a list of the items in the control.
To specify or determine which item is selected, use the
{@link getSelectedIndex SelectedIndex} property that indicates the zero-based
index of the selected item in the item list. You may also use
{@link getSelectedItem SelectedItem} and {@link getSelectedValue SelectedValue}
to get the selected item and its value. For multiple selection lists
(such as {@link TCheckBoxList} and {@link TListBox}), property
{@link getSelectedIndices SelectedIndices} is useful.
TListControl implements {@link setAutoPostBack AutoPostBack} which allows
a list control to postback the page if the selections of the list items are changed.
The {@link setCausesValidation CausesValidation} and {@link setValidationGroup 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 {@link setDataSource DataSource} and using {@link setDataSourceID DataSourceID}.
The latter two are covered in {@link TDataBoundControl}. To specify items via
template, using the following template syntax:
When {@link setDataSource DataSource} or {@link setDataSourceID DataSourceID}
is used to populate list items, the {@link setDataTextField DataTextField} and
{@link setDataValueField 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 {@link setDataTextField DataTextField} and {@link setDataValueField 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 {@link setDataTextFormatString DataTextFormatString} property may be further
used to format how the item should be displayed. See {@link formatDataValue()}
for an explanation of the format string.
The {@link setPromptText PromptText} and {@link setPromptValue PromptValue} properties can
be used to add a dummy list item that will be rendered first.