PRADO Component Framework for PHP 5
  • Home
  • About
  • Testimonials
  • Demos
  • Download
  • Documentation
  • Forum
  • Development
  • Tutorials
  • Class Docs
  • API Manual
  • Wiki

Packages

  • None
  • System
    • Caching
    • Collections
    • Data
      • ActiveRecord
        • Relations
        • Scaffold
          • InputBuilder
      • Commom
        • Sqlite
      • Common
        • Mssql
        • Mysql
        • Oracle
        • Pgsql
        • Sqlite
      • DataGateway
      • SqlMap
        • Configuration
        • Statements
    • Exceptions
    • I18N
    • IO
    • Security
    • Util
    • Web
      • Javascripts
      • Services
      • UI
        • ActiveControls
        • WebControls
    • Xml
  • Wsat
    • pages
  • Overview
  • Package
  • Class
  • Tree
  • Deprecated
  • Todo

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
Extended by TApplicationComponent
Extended by TControl implements IRenderable, IBindable
Extended by TWebControl implements IStyleable
Extended by TDataBoundControl
Extended by TListControl implements IDataRenderer

Direct known subclasses

TBulletedList, TCheckBoxList, TDropDownList, TListBox

Indirect known subclasses

TActiveCheckBoxList, TActiveDropDownList, TActiveListBox, TActiveRadioButtonList, TActiveRatingList, TRadioButtonList, TRatingList
Abstract
Package: System\Web\UI\WebControls
Copyright: Copyright © 2005-2014 PradoSoft
License: http://www.pradosoft.com/license/
Author: Qiang Xue <qiang.xue@gmail.com>
Since: 3.0
Located at Web/UI/WebControls/TListControl.php
Methods summary
protected string
# getTagName( )

Returns

string
tag name of the list control

Overrides

TWebControl::getTagName()
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

$writer
THtmlWriter
the renderer

Overrides

TWebControl::addAttributesToRender()
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

TControl::addParsedObject()
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

TListItemCollection
the collection object
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

TControl::saveState()
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

TControl::loadState()
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
# getItems( )

Returns

TListItemCollection
the item collection
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 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

TListControl::getSelectedValue()

Implementation of

IDataRenderer::getData()
public
# setData( string $value )

Selects an item by the specified value. This method is required by IDataRenderer. It is the same as TListControl::setSelectedValue().

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

TListControl::setSelectedValue()

Implementation of

IDataRenderer::setData()
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

TListControl::getPromptText()
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

TListControl::setPromptText()
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

$param
TEventParameter
event parameter
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

$param
TEventParameter
event parameter
protected
# renderPrompt( THtmlWriter $writer )

Renders the prompt text, if any.

Renders the prompt text, if any.

Parameters

$writer
THtmlWriter
writer

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

$writer
THtmlWriter
writer

Overrides

TWebControl::renderContents()
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 TApplicationComponent
getApplication(), getRequest(), getResponse(), getService(), getSession(), getUser(), publishAsset(), publishFilePath()
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
Constants inherited from TComponent
GLOBAL_RAISE_EVENT_LISTENER
Properties inherited from TWebControl
$_decorator
Terms of Service | Contact Us
PRADO v3.2.4 API Manual API documentation generated by ApiGen 2.8.0
Copyright © 2006-2014 by the PRADO Group.
Powered by PRADO