List Controls

List controls covered in this section all inherit directly or indirectly from TListControl. Therefore, they share the same set of commonly used properties, including,

Items - list of items in the control. The items are of type TListItem. The item list can be populated via databinding or specified in templates like the following:

<com:TListBox>
  <com:TListItem Text="text 1" Value="value 1" />
  <com:TListItem Text="text 2" Value="value 2" Selected="true" />
  <com:TListItem Text="text 3" Value="value 3" />
</com:TListBox>

SelectedIndex - the zero-based index of the first selected item in the item list.
SelectedIndices - the indices of all selected items.
SelectedItem - the first selected item in the item list.
SelectedValue - the value of the first selected item in the item list.
AutoPostBack - whether changing the selection of the control should trigger postback.
CausesValidation - whether validation should be performed when postback is triggered by the list control.

Since TListControl inherits from TDataBoundControl, these list controls also share a common operation known as databinding. The Items can be populated from preexisting data specified by DataSource or DataSourceID. A function call to dataBind() will cause the data population. For list controls, data can be specified in the following two kinds of format:

one-dimensional array or objects implementing ITraversable : array keys will be used as list item values, and array values will be used as list item texts. For example
```
$listbox->DataSource=array(
	'key 1'=>'item 1',
	'key 2'=>'item 2',
	'key 3'=>'item 3');
$listbox->dataBind();
```

tabular (two-dimensional) data : each row of data populates a single list item. The list item value is specified by the data member indexed with DataValueField, and the list item text by DataTextField. For example,

$listbox->DataTextField='name';
$listbox->DataValueField='id';
$listbox->DataSource=array(
	array('id'=>'001','name'=>'John','age'=>31),
	array('id'=>'002','name'=>'Mary','age'=>30),
	array('id'=>'003','name'=>'Cary','age'=>20));
$listbox->dataBind();

TListBox

API Manual

TListBox displays a list box that allows single or multiple selection. Set the property SelectionMode as Single to make a single selection list box, and Multiple a multiple selection list box. The number of rows displayed in the box is specified via the Rows property value.

Run Sample View Source

TDropDownList

API Manual

TDropDownList displays a dropdown list box that allows users to select a single option from a few prespecified ones.

Since v3.1.1, TDropDownList starts to support prompt text (something like 'Please select:' as the first list item). To use this feature, set either PromptText or PromptValue, or both. If the user chooses the prompt item, the dropdown list will be unselected.

Run Sample View Source

TCheckBoxList

API Manual

TCheckBoxList displays a list of checkboxes on a Web page. The alignment of the text besides each checkbox can be specified TextAlign. The layout of the checkboxes can be controlled by the following properties:

RepeatLayout - can be either Table or Flow. A Table uses HTML table cells to organize the checkboxes, while a Flow uses HTML span tags and breaks for the organization. With Table layout, you can set CellPadding and CellSpacing.
RepeatColumns - how many columns the checkboxes should be displayed in.
RepeatDirection - how to traverse the checkboxes, in a horizontal way or a vertical way (because the checkboxes are displayed in a matrix-like layout).

Run Sample View Source

TRadioButtonList

API Manual

TRadioButtonList is similar to TCheckBoxList in every aspect except that each TRadioButtonList displays a group of radiobuttons. Only one of the radiobuttions can be selected (TCheckBoxList allows multiple selections.)

Run Sample View Source

TBulletedList

API Manual

TBulletedList displays items in a bullet format on a Web page. The style of the bullets can be specified by BulletStyle. When the style is CustomImage, the bullets are displayed as images, which is specified by BulletImageUrl.

TBulletedList displays the item texts in three different modes,

Text - the item texts are displayed as static texts;
HyperLink - each item is displayed as a hyperlink whose URL is given by the item value, and Target property can be used to specify the target browser window;
LinkButton - each item is displayed as a link button which posts back to the page if a user clicks on that, and the event OnClick will be raised under such a circumstance.

Run Sample View Source

TRatingList

API Manual

This is an EXPERIMENTAL class that displays clickable images that represent a TRadioButtonList.

Run Sample View Source