|
Class TListControl
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 TListControl::getItems() returns a list of the items in the control. To
specify or determine which item is selected, use the getSelectedIndex
SelectedIndex property that indicates the zero-based index of the selected item
in the item list. You may also use getSelectedItem SelectedItem and
getSelectedValue SelectedValue to get the selected item and its value.
For multiple selection lists (such as TCheckBoxList and TListBox ), property getSelectedIndices SelectedIndices is useful.
TListControl implements setAutoPostBack AutoPostBack which allows a
list control to postback the page if the selections of the list items are
changed. The setCausesValidation CausesValidation and 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 setDataSource DataSource and using setDataSourceID
DataSourceID. The latter two are covered in TDataBoundControl . To
specify items via template, using the following template syntax:
<com:TListControl>
<com:TListItem Value="xxx" Text="yyy" >
<com:TListItem Value="xxx" Text="yyy" Selected="true" >
<com:TListItem Value="xxx" Text="yyy" >
</com:TListControl>
When setDataSource DataSource or setDataSourceID DataSourceID
is used to populate list items, the setDataTextField DataTextField and
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 setDataTextField DataTextField and 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
setDataTextFormatString DataTextFormatString property may be further
used to format how the item should be displayed. See TListControl::formatDataValue()
for an explanation of the format string.
The setPromptText PromptText and setPromptValue PromptValue
properties can be used to add a dummy list item that will be rendered first.
-
TComponent
-
TApplicationComponent
-
TControl
implements
IRenderable,
IBindable
-
TWebControl
implements
IStyleable
-
TDataBoundControl
-
TListControl
implements
IDataRenderer
Methods summary
protected
string
|
#
getTagName( )
Returns
string tag name of the list control
Overrides
|
public
boolean
|
#
getEnableClientScript( )
Returns
boolean whether to render javascript.
|
public
|
#
setEnableClientScript( boolean $value )
Parameters
- $value
boolean whether to render javascript.
|
protected
|
#
addAttributesToRender( THtmlWriter $writer )
Adds attributes to renderer.
Adds attributes to renderer.
Parameters
Overrides
|
protected
|
#
renderClientControlScript( mixed $writer )
Renders the javascript for list control.
Renders the javascript for list control.
|
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.
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.
Returns
string the javascript class name
|
protected
array
|
#
getPostBackOptions( )
Returns
array postback options for JS postback code
|
public
|
#
addParsedObject( mixed $object )
Adds object parsed from template to the control. This method adds only TListItem objects into the getItems Items collection. All other objects
are ignored.
Adds object parsed from template to the control. This method adds only TListItem objects into the getItems Items collection. All other objects
are ignored.
Parameters
- $object
mixed object parsed from template
Overrides
|
protected
|
#
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.
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.
Parameters
- $data
Traversable the data
|
protected
TListItemCollection
|
#
createListItemCollection( )
Creates a collection object to hold list items. This method may be overriden
to create a customized collection.
Creates a collection object to hold list items. This method may be overriden
to create a customized collection.
Returns
|
public
|
#
saveState( )
Saves items into viewstate. This method is invoked right before control state
is to be saved.
Saves items into viewstate. This method is invoked right before control state
is to be saved.
Overrides
|
public
|
#
loadState( )
Loads items from viewstate. This method is invoked right after control state
is loaded.
Loads items from viewstate. This method is invoked right after control state
is loaded.
Overrides
|
protected
boolean
|
#
getIsMultiSelect( )
Returns
boolean whether this is a multiselect control. Defaults to false.
|
public
boolean
|
#
getAppendDataBoundItems( )
Returns
boolean whether performing databind should append items or clear the existing ones.
Defaults to false.
|
public
|
#
setAppendDataBoundItems( boolean $value )
Parameters
- $value
boolean whether performing databind should append items or clear the existing ones.
|
public
boolean
|
#
getAutoPostBack( )
Returns
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.
|
public
|
#
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.
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.
Parameters
- $value
boolean the value indicating if postback automatically
|
public
boolean
|
#
getCausesValidation( )
Returns
boolean whether postback event trigger by this list control will cause input validation,
default is true.
|
public
|
#
setCausesValidation( boolean $value )
Parameters
- $value
boolean whether postback event trigger by this list control will cause input validation.
|
public
string
|
#
getDataTextField( )
Returns
string the field of the data source that provides the text content of the list items.
|
public
|
#
setDataTextField( string $value )
Parameters
- $value
string the field of the data source that provides the text content of the list items.
|
public
string
|
#
getDataTextFormatString( )
Returns
string the formatting string used to control how data bound to the list control is
displayed.
|
public
|
#
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.
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.
Parameters
- $value
string the formatting string used to control how data bound to the list control is
displayed.
See
TDataValueFormatter::format()
|
public
string
|
#
getDataValueField( )
Returns
string the field of the data source that provides the value of each list item.
|
public
|
#
setDataValueField( string $value )
Parameters
- $value
string the field of the data source that provides the value of each list item.
|
public
string
|
#
getDataGroupField( )
Returns
string the field of the data source that provides the label of the list item groups
|
public
|
#
setDataGroupField( string $value )
Parameters
- $value
string the field of the data source that provides the label of the list item groups
|
public
integer
|
#
getItemCount( )
Returns
integer the number of items in the list control
|
public
boolean
|
#
getHasItems( )
Returns
boolean whether the list control contains any items.
|
public
TListItemCollection
|
|
public
integer
|
#
getSelectedIndex( )
Returns
integer the index (zero-based) of the item being selected, -1 if no item is selected.
|
public
|
#
setSelectedIndex( integer $index )
Parameters
- $index
integer the index (zero-based) of the item to be selected
|
public
array
|
#
getSelectedIndices( )
Returns
array list of index of items that are selected
|
public
|
#
setSelectedIndices( array $indices )
Parameters
- $indices
array list of index of items to be selected
|
public
TListItem |null
|
#
getSelectedItem( )
Returns
TListItem |null
the selected item with the lowest cardinal index, null if no item is selected.
|
public
string
|
#
getData( )
Returns the value of the selected item with the lowest cardinal index. This
method is required by IDataRenderer . It is the same as TListControl::getSelectedValue() .
Returns
string the value of the selected item with the lowest cardinal index, empty if no
selection.
Since
3.1.0
See
Implementation of
|
public
|
#
setData( string $value )
Selects an item by the specified value. This method is required by IDataRenderer . It is the same as TListControl::setSelectedValue() .
Parameters
- $value
string the value of the item to be selected.
Since
3.1.0
See
Implementation of
|
public
string
|
#
getSelectedValue( )
Returns
string the value of the selected item with the lowest cardinal index, empty if no
selection
|
public
|
#
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.
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.
Parameters
- $value
string the value of the item to be selected.
|
public
array
|
#
getSelectedValues( )
Returns
array list of the selected item values (strings)
|
public
|
#
setSelectedValues( array $values )
Parameters
- $values
array list of the selected item values
|
public
string
|
#
getText( )
Returns
string selected value
|
public
|
#
setText( string $value )
Parameters
- $value
string value to be selected
|
public
|
#
clearSelection( )
Clears all existing selections.
Clears all existing selections.
|
public
string
|
#
getValidationGroup( )
Returns
string the group of validators which the list control causes validation upon postback
|
public
|
#
setValidationGroup( string $value )
Parameters
- $value
string the group of validators which the list control causes validation upon postback
|
public
string
|
#
getPromptText( )
Returns
string the prompt text which is to be displayed as the first list item.
Since
3.1.1
|
public
|
#
setPromptText( string $value )
Parameters
- $value
string the prompt text which is to be displayed as the first list item.
Since
3.1.1
|
public
string
|
#
getPromptValue( )
Returns
string the prompt selection value.
Since
3.1.1
See
|
public
|
#
setPromptValue( string $value )
Parameters
- $value
string the prompt selection value. If empty, getPromptText PromptText will be
used as the value.
Since
3.1.1
See
|
public
|
#
onSelectedIndexChanged( TEventParameter $param )
Raises OnSelectedIndexChanged event when selection is changed. This method is
invoked when the list control has its selection changed by end-users.
Raises OnSelectedIndexChanged event when selection is changed. This method is
invoked when the list control has its selection changed by end-users.
Parameters
|
public
|
#
onTextChanged( TEventParameter $param )
Raises OnTextChanged event when selection is changed. This method is invoked
when the list control has its selection changed by end-users.
Raises OnTextChanged event when selection is changed. This method is invoked
when the list control has its selection changed by end-users.
Parameters
|
protected
|
#
renderPrompt( THtmlWriter $writer )
Renders the prompt text, if any.
Renders the prompt text, if any.
Parameters
Since
3.1.1
|
public
|
#
renderContents( THtmlWriter $writer )
Renders body content of the list control. This method renders items contained
in the list control as the body content.
Renders body content of the list control. This method renders items contained
in the list control as the body content.
Parameters
Overrides
|
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 sprintf.
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 sprintf.
Parameters
- $formatString
string format string
- $value
mixed the data to be formatted
Returns
string the formatted result
|
Methods inherited from TDataBoundControl
createPagedDataSource(),
dataBind(),
dataSourceViewChanged(),
determineDataSource(),
ensureDataBound(),
getAllowCustomPaging(),
getAllowPaging(),
getCurrentPageIndex(),
getDataMember(),
getDataSource(),
getDataSourceID(),
getDataSourceView(),
getInitialized(),
getIsDataBound(),
getPageCount(),
getPageSize(),
getRequiresDataBinding(),
getSelectParameters(),
getUsingDataSourceID(),
getVirtualItemCount(),
onDataBound(),
onDataSourceChanged(),
onInit(),
onPreRender(),
pagePreLoad(),
setAllowCustomPaging(),
setAllowPaging(),
setCurrentPageIndex(),
setDataMember(),
setDataSource(),
setDataSourceID(),
setInitialized(),
setIsDataBound(),
setPageSize(),
setRequiresDataBinding(),
setVirtualItemCount(),
validateDataSource()
|
Methods inherited from TWebControl
clearStyle(),
copyBaseAttributes(),
createStyle(),
getAccessKey(),
getBackColor(),
getBorderColor(),
getBorderStyle(),
getBorderWidth(),
getCssClass(),
getDecorator(),
getDisplay(),
getEnsureId(),
getFont(),
getForeColor(),
getHasStyle(),
getHeight(),
getStyle(),
getTabIndex(),
getToolTip(),
getWidth(),
render(),
renderBeginTag(),
renderEndTag(),
setAccessKey(),
setBackColor(),
setBorderColor(),
setBorderStyle(),
setBorderWidth(),
setCssClass(),
setDisplay(),
setEnsureId(),
setForeColor(),
setHeight(),
setStyle(),
setTabIndex(),
setToolTip(),
setWidth()
|
Methods inherited from TControl
__construct(),
__get(),
addToPostDataLoader(),
addedControl(),
applyStyleSheetSkin(),
autoBindProperty(),
autoDataBindProperties(),
bindProperty(),
broadcastEvent(),
bubbleEvent(),
clearChildState(),
clearControlState(),
clearNamingContainer(),
clearViewState(),
convertUniqueIdToClientId(),
createChildControls(),
createControlCollection(),
dataBindChildren(),
dataBindProperties(),
ensureChildControls(),
findControl(),
findControlsByID(),
findControlsByType(),
focus(),
getAdapter(),
getAllowChildControls(),
getAttribute(),
getAttributes(),
getChildControlsCreated(),
getClientID(),
getControlStage(),
getControlState(),
getControls(),
getCustomData(),
getEnableTheming(),
getEnableViewState(),
getEnabled(),
getHasAdapter(),
getHasAttributes(),
getHasChildInitialized(),
getHasControls(),
getHasInitialized(),
getHasLoaded(),
getHasLoadedPostData(),
getHasPreRendered(),
getID(),
getIsSkinApplied(),
getNamingContainer(),
getPage(),
getParent(),
getRegisteredObject(),
getSkinID(),
getSourceTemplateControl(),
getTemplateControl(),
getUniqueID(),
getViewState(),
getVisible(),
hasAttribute(),
initRecursive(),
isDescendentOf(),
isObjectRegistered(),
loadRecursive(),
loadStateRecursive(),
onDataBinding(),
onLoad(),
onUnload(),
preRenderRecursive(),
raiseBubbleEvent(),
registerObject(),
removeAttribute(),
removedControl(),
renderChildren(),
renderControl(),
saveStateRecursive(),
setAdapter(),
setAttribute(),
setChildControlsCreated(),
setControlStage(),
setControlState(),
setCustomData(),
setEnableTheming(),
setEnableViewState(),
setEnabled(),
setID(),
setPage(),
setSkinID(),
setTemplateControl(),
setViewState(),
setVisible(),
trackViewState(),
traverseChildControls(),
unbindProperty(),
unloadRecursive(),
unregisterObject()
|
Methods inherited from TComponent
__call(),
__destruct(),
__isset(),
__set(),
__sleep(),
__unset(),
__wakeup(),
asa(),
attachBehavior(),
attachBehaviors(),
attachClassBehavior(),
attachEventHandler(),
canGetProperty(),
canSetProperty(),
clearBehaviors(),
createdOnTemplate(),
detachBehavior(),
detachBehaviors(),
detachClassBehavior(),
detachEventHandler(),
disableBehavior(),
disableBehaviors(),
enableBehavior(),
enableBehaviors(),
evaluateExpression(),
evaluateStatements(),
fxAttachClassBehavior(),
fxDetachClassBehavior(),
getAutoGlobalListen(),
getBehaviorsEnabled(),
getClassHierarchy(),
getEventHandlers(),
getListeningToGlobalEvents(),
getSubProperty(),
hasEvent(),
hasEventHandler(),
hasProperty(),
isa(),
listen(),
raiseEvent(),
setSubProperty(),
unlisten()
|
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
|
|