Packages:
default
System
System.Caching
System.Collections
System.Data
System.Data.ActiveRecord
System.Data.ActiveRecord.Relations
System.Data.ActiveRecord.Scaffold
System.Data.ActiveReecord.Scaffold.InputBuilder
System.Data.Commom.Sqlite
System.Data.Common
System.Data.Common.Mssql
System.Data.Common.Mysql
System.Data.Common.Oracle
System.Data.Common.Pgsql
System.Data.Common.Sqlite
System.Data.DataGateway
System.Data.SqlMap
System.Data.SqlMap.Configuration
System.Data.SqlMap.Statements
System.Exceptions
System.I18N
System.IO
System.Security
System.Util
System.Web
System.Web.Services
System.Web.UI
System.Web.UI.ActiveControls
System.Web.UI.WebControls
System.Web.UI.WebControls.assets
System.Xml


Classes:
Keyword

Class TControl

TControl class

TControl is the base class for all components on a page hierarchy. It implements the following features for UI-related functionalities:

  • databinding feature
  • parent and child relationship
  • naming container and containee relationship
  • viewstate and controlstate features
  • rendering scheme
  • control lifecycles
A property can be data-bound with an expression. By calling dataBind, expressions bound to properties will be evaluated and the results will be set to the corresponding properties.

Parent and child relationship determines how the presentation of controls are enclosed within each other. A parent will determine where to place the presentation of its child controls. For example, a TPanel will enclose all its child controls' presentation within a div html tag. A control's parent can be obtained via Parent property, and its Controls property returns a list of the control's children, including controls and static texts. The property can be manipulated like an array for adding or removing a child (see TList for more details).

A naming container control implements INamingContainer and ensures that its containee controls can be differentiated by their ID property values. Naming container and containee realtionship specifies a protocol to uniquely identify an arbitrary control on a page hierarchy by an ID path (concatenation of all naming containers' IDs and the target control's ID).

Viewstate and controlstate are two approaches to preserve state across page postback requests. ViewState is mainly related with UI specific state and can be disabled if not needed. ControlState represents crucial logic state and cannot be disabled.

A control is rendered via its render() method (the method is invoked by the framework.) Descendant control classes may override this method for customized rendering. By default, render() invokes renderChildren() which is responsible for rendering of children of the control. Control's Visible property governs whether the control should be rendered or not.

Each control on a page will undergo a series of lifecycles, including control construction, Init, Load, PreRender, Render, and OnUnload. They work together with page lifecycles to process a page request.

Since: 3.0
Author: Qiang Xue <qiang.xue@gmail.com>

Constructor Summary
public
Constructor.

Method Summary
void
addedControl ( TControl $control)
Adds a control into the child collection of the control.
void
addParsedObject ( string|TComponent $object)
Adds the object instantiated on a template to the child control collection.
protected  void
Add controls implementing IPostBackDataHandler to post data loaders.
void
Applies a stylesheet skin to a control.
void
autoBindProperty ( string $name, string $expression)
Sets up the binding between a property (or property path) and an expression.
protected  void
Auto databinding properties of the control.
void
bindProperty ( string $name, string $expression)
Sets up the binding between a property (or property path) and an expression.
void
broadcastEvent ( string $name, TControl $sender, TEventParameter $param)
Broadcasts an event.
boolean
bubbleEvent ( TControl $sender, TEventParameter $param)
This method responds to a bubbled event.
protected  void
Clears up the child state data.
protected  void
clearControlState ( string $key)
Clears a controlstate value.
void
Resets the control as a naming container.
void
clearViewState ( string $key)
Clears a viewstate value.
string
convertUniqueIdToClientId ( string $uniqueID)
Converts a unique ID to a client ID.
void
Creates child controls.
protected  TControlCollection
Creates a control collection object that is to be used to hold child controls
void
Performs the databinding for this control.
protected  void
Databinding child controls.
protected  void
Databinding properties of the control.
void
Ensures child controls are created.
TControl|null
findControl ( string $id)
Finds a control by ID path within the current naming container.
array
findControlsByID ( string $id)
Finds all child and grand-child controls with the specified ID.
array
findControlsByType ( string $type, boolean $strict)
Finds all child and grand-child controls that are of the specified type.
void
focus ()
Sets input focus to this control.
TControlAdapter
boolean
string
getAttribute ( mixed $name)
TAttributeCollection
Returns the list of custom attributes.
protected  boolean
string
Returns the client ID of the control.
TControlCollection
protected  integer
Gets the lifecycle step the control is currently at.
protected  mixed
getControlState ( string $key, mixed $defaultValue)
Returns a controlstate value.
mixed
Returns custom data associated with this control.
boolean
getEnabled ( boolean $checkParents)
Returns a value indicating whether the control is enabled.
boolean
boolean
getEnableViewState ( mixed $checkParents)
boolean
boolean
boolean
boolean
boolean
boolean
boolean
boolean
string
getID ( boolean $hideAutoID)
Returns the id of the control.
TControl
TPage
getPage ()
TControl
mixed
getRegisteredObject ( mixed $name)
Returns the named registered object.
string
TTemplateControl
TTemplateControl
string
Returns a unique ID that identifies the control in the page hierarchy.
mixed
getViewState ( string $key, mixed $defaultValue)
Returns a viewstate value.
boolean
getVisible ( boolean $checkParents)
Checks if a control is visible.
boolean
hasAttribute ( mixed $name)
protected  void
initRecursive ( TControl $namingContainer)
Performs the Init step for the control and all its child controls.
protected  boolean
isDescendentOf ( TControl $ancestor)
boolean
isObjectRegistered ( mixed $name)
protected  void
Performs the Load step for the control and all its child controls.
void
This method is invoked right after the control has loaded its state.
protected  void
loadStateRecursive ( array &$state, boolean $needViewState)
Loads state (viewstate and controlstate) into a control and its children.
void
Raises 'OnDataBinding' event.
void
This method is invoked when the control enters 'OnInit' stage.
void
This method is invoked when the control enters 'OnLoad' stage.
void
This method is invoked when the control enters 'OnPreRender' stage.
void
This method is invoked when the control enters 'OnUnload' stage.
protected  void
Performs the PreRender step for the control and all its child controls.
protected  void
Invokes the parent's bubbleEvent method.
void
registerObject ( string $name, object object $object)
Registers an object by a name.
string
removeAttribute ( string $name)
Removes the named attribute.
void
removedControl ( TControl $control)
Removes a control from the child collection of the control.
void
render ( THtmlWriter $writer)
Renders the control.
void
Renders the children of the control.
void
Renders the control.
void
This method is invoked when control state is to be saved.
protected  array
saveStateRecursive ( boolean $needViewState)
Saves all control state (viewstate and controlstate) as a collection.
void
setAdapter ( TControlAdapter $adapter)
void
setAttribute ( string $name, string $value)
Sets a custom control attribute.
protected  void
setChildControlsCreated ( boolean $value)
Sets a value indicating whether child controls are created.
protected  void
setControlStage ( integer $value)
Sets the lifecycle step the control is currently at.
protected  void
setControlState ( string $key, mixed $value, mixed $defaultValue)
Sets a controlstate value.
void
setCustomData ( mixed $value)
Associates custom data with this control.
void
setEnabled ( boolean $value)
void
setEnableTheming ( boolean $value)
void
setEnableViewState ( boolean $value)
void
setID ( string $id)
void
setPage ( TPage $page)
Sets the page for a control.
void
setSkinID ( string $value)
void
Sets the control whose template contains this control.
void
setViewState ( string $key, mixed $value, mixed $defaultValue)
Sets a viewstate value.
void
setVisible ( boolean $value)
void
trackViewState ( boolean $enabled)
Sets a value indicating whether we should keep data in viewstate.
protected  void
traverseChildControls ( mixed $param, callback $preCallback, callback $postCallback)
Traverse the whole control hierarchy rooted at this control.
void
unbindProperty ( string $name)
Breaks the binding between a property (or property path) and an expression.
protected  void
Performs the Unload step for the control and all its child controls.
void
unregisterObject ( string $name)
Unregisters an object by name.
mixed
__get ( string $name)
Returns a property value by name or a control by ID.
Methods Inherited From TApplicationComponent
TApplicationComponent::getApplication(), TApplicationComponent::getRequest(), TApplicationComponent::getResponse(), TApplicationComponent::getService(), TApplicationComponent::getSession(), TApplicationComponent::getUser(), TApplicationComponent::publishAsset(), TApplicationComponent::publishFilePath()
Methods Inherited From TComponent
TComponent::addParsedObject(), TComponent::attachEventHandler(), TComponent::canGetProperty(), TComponent::canSetProperty(), TComponent::createdOnTemplate(), TComponent::detachEventHandler(), TComponent::evaluateExpression(), TComponent::evaluateStatements(), TComponent::getEventHandlers(), TComponent::getSubProperty(), TComponent::hasEvent(), TComponent::hasEventHandler(), TComponent::hasProperty(), TComponent::raiseEvent(), TComponent::setSubProperty(), TComponent::__get(), TComponent::__set()

Constant Summary
string AUTOMATIC_ID_PREFIX prefix to an ID automatically generated
string CLIENT_ID_SEPARATOR separator char between IDs in a ClientID
int CS_CHILD_INITIALIZED
int CS_CONSTRUCTED the stage of lifecycles that the control is currently at
int CS_INITIALIZED
int CS_LOADED
int CS_PRERENDERED
int CS_STATE_LOADED
string ID_FORMAT format of control ID
string ID_SEPARATOR separator char between IDs in a UniqueID
int IS_CHILD_CREATED
int IS_CREATING_CHILD
int IS_DISABLE_THEMING
int IS_DISABLE_VIEWSTATE
int IS_ID_SET State bits.
int IS_SKIN_APPLIED
int IS_STYLESHEET_APPLIED
int RF_ADAPTER
int RF_AUTO_BINDINGS
int RF_CHILD_STATE
int RF_CONTROLS Indexes for the rare fields.

In order to save memory, rare fields will only be created if they are needed.

int RF_CONTROLSTATE
int RF_DATA_BINDINGS
int RF_EVENTS
int RF_NAMED_CONTROLS
int RF_NAMED_CONTROLS_ID
int RF_NAMED_OBJECTS
int RF_SKIN_ID

Constructor Details

__construct

public __construct

Constructor.


Method Details

addedControl

public void addedControl (TControl $control )

Adds a control into the child collection of the control.

Control lifecycles will be caught up during the addition. Only framework developers should use this method.

Input
TControl$controlthe new child control
Output
Exception

addParsedObject

public void addParsedObject (string|TComponent $object )

Adds the object instantiated on a template to the child control collection.

This method overrides the parent implementation. Only framework developers and control developers should use this method.

Input
string|TComponent$objecttext string or component parsed and instantiated in template
Output
Exception

addToPostDataLoader

protected void addToPostDataLoader ()

Add controls implementing IPostBackDataHandler to post data loaders.

Output
Exception

applyStyleSheetSkin

public void applyStyleSheetSkin (TPage $page )

Applies a stylesheet skin to a control.

Input
TPage$pagethe page containing the control
Output
Exception
throwsTInvalidOperationException if the stylesheet skin is applied already

autoBindProperty

public void autoBindProperty (string $name , string $expression )

Sets up the binding between a property (or property path) and an expression.

Unlike regular databinding, the expression bound by this method is automatically evaluated during prerenderRecursive(). The context of the expression is the template control (or the control itself if it is a page).

Input
string$namethe property name, or property path
string$expressionthe expression
Output
Exception

autoDataBindProperties

protected void autoDataBindProperties ()

Auto databinding properties of the control.

Output
Exception

bindProperty

public void bindProperty (string $name , string $expression )

Sets up the binding between a property (or property path) and an expression.

The context of the expression is the template control (or the control itself if it is a page).

Input
string$namethe property name, or property path
string$expressionthe expression
Output
Exception

broadcastEvent

public void broadcastEvent (string $name , TControl $sender , TEventParameter $param )

Broadcasts an event.

The event will be sent to all controls on the current page hierarchy. If a control defines the event, the event will be raised for the control. If a control implements IBroadcastEventReceiver, its IBroadcastEventReceiver::broadcastEventReceived method will be invoked which gives the control a chance to respond to the event. For example, when broadcasting event 'OnClick', all controls having 'OnClick' event will have this event raised, and all controls implementing IBroadcastEventReceiver will also have its IBroadcastEventReceiver::broadcastEventReceived invoked.

Input
string$namename of the broadcast event
TControl$sendersender of this event
TEventParameter$paramevent parameter
Output
Exception

bubbleEvent

public boolean bubbleEvent (TControl $sender , TEventParameter $param )

This method responds to a bubbled event.

This method should be overriden to provide customized response to a bubbled event. Check the type of event parameter to determine what event is bubbled currently.

Input
TControl$sendersender of the event
TEventParameter$paramevent parameters
Output
boolean true if the event bubbling is handled and no more bubbling.
Exception

clearChildState

protected void clearChildState ()

Clears up the child state data.

After a control loads its state, those state that do not belong to any existing child controls are stored as child state. This method will remove these state. Only frameworker developers and control developers should use this method.

Output
Exception

clearControlState

protected void clearControlState (string $key )

Clears a controlstate value.

Input
string$keythe name of the controlstate value to be cleared
Output
Exception

clearNamingContainer

public void clearNamingContainer ()

Resets the control as a naming container.

Only framework developers should use this method.

Output
Exception

clearViewState

public void clearViewState (string $key )

Clears a viewstate value.

Input
string$keythe name of the viewstate value to be cleared
Output
Exception

convertUniqueIdToClientId

public string convertUniqueIdToClientId (string $uniqueID )

Converts a unique ID to a client ID.

Input
string$uniqueIDthe unique ID of a control
Output
string the client ID of the control
Exception

createChildControls

public void createChildControls ()

Creates child controls.

This method can be overriden for controls who want to have their controls. Do not call this method directly. Instead, call ensureChildControls to ensure child controls are created only once.

Output
Exception

createControlCollection

protected TControlCollection createControlCollection ()

Creates a control collection object that is to be used to hold child controls

Output
TControlCollection control collection
Exception

dataBind

public void dataBind ()

Performs the databinding for this control.

Output
Exception

dataBindChildren

protected void dataBindChildren ()

Databinding child controls.

Output
Exception

dataBindProperties

protected void dataBindProperties ()

Databinding properties of the control.

Output
Exception

ensureChildControls

public void ensureChildControls ()

Ensures child controls are created.

If child controls are not created yet, this method will invoke createChildControls to create them.

Output
Exception

findControl

public TControl|null findControl (string $id )

Finds a control by ID path within the current naming container.

The current naming container is either the control itself if it implements INamingContainer or the control's naming container. The ID path is an ID sequence separated by TControl::ID_SEPARATOR. For example, 'Repeater1.Item1.Button1' looks for a control with ID 'Button1' whose naming container is 'Item1' whose naming container is 'Repeater1'.

Input
string$idID of the control to be looked up
Output
TControl|null the control found, null if not found
Exception
throwsTInvalidDataValueException if a control's ID is found not unique within its naming container.

findControlsByID

public array findControlsByID (string $id )

Finds all child and grand-child controls with the specified ID.

Note, this method is different from findControl in that it searches through all controls that have this control as the ancestor while findcontrol only searches through controls that have this control as the direct naming container.

Input
string$idthe ID being looked for
Output
array list of controls found
Exception

findControlsByType

public array findControlsByType (string $type , boolean $strict )

Finds all child and grand-child controls that are of the specified type.

Input
string$typethe class name
boolean$strictwhether the type comparison is strict or not. If false, controls of the parent classes of the specified class will also be returned.
Output
array list of controls found
Exception

focus

public void focus ()

Sets input focus to this control.

Output
Exception

getAdapter

public TControlAdapter getAdapter ()

Output
TControlAdapter control adapter. Null if not exists.
Exception

getAllowChildControls

public boolean getAllowChildControls ()

Output
boolean whether body contents are allowed for this control. Defaults to true.
Exception

getAttribute

public string getAttribute (mixed $name )

Input
mixed$name
Output
string attribute value, null if attribute does not exist
Exception

getAttributes

public TAttributeCollection getAttributes ()

Returns the list of custom attributes.

Custom attributes are name-value pairs that may be rendered as HTML tags' attributes.

Output
TAttributeCollection the list of custom attributes
Exception

getChildControlsCreated

protected boolean getChildControlsCreated ()

Output
boolean whether child controls have been created
Exception

getClientID

public string getClientID ()

Returns the client ID of the control.

The client ID can be used to uniquely identify the control in client-side scripts (such as JavaScript). Do not rely on the explicit format of the return ID.

Output
string the client ID of the control
Exception

getControls

public TControlCollection getControls ()

Output
TControlCollection the child control collection
Exception

getControlStage

protected integer getControlStage ()

Gets the lifecycle step the control is currently at.

This method should only be used by control developers.

Output
integer the lifecycle step the control is currently at. The value can be CS_CONSTRUCTED, CS_CHILD_INITIALIZED, CS_INITIALIZED, CS_STATE_LOADED, CS_LOADED, CS_PRERENDERED.
Exception

getControlState

protected mixed getControlState (string $key , mixed $defaultValue )

Returns a controlstate value.

This function is mainly used in defining getter functions for control properties that must be kept in controlstate.

Input
string$keythe name of the controlstate value to be returned
mixed$defaultValuethe default value. If $key is not found in controlstate, $defaultValue will be returned
Output
mixed the controlstate value corresponding to $key
Exception

getCustomData

public mixed getCustomData ()

Returns custom data associated with this control.

A control may be associated with some custom data for various purposes. For example, a button may be associated with a string to identify itself in a generic OnClick event handler.

Output
mixed custom data associated with this control. Defaults to null.
Exception

getEnabled

public boolean getEnabled (boolean $checkParents )

Returns a value indicating whether the control is enabled.

A control is enabled if it allows client user interaction. If $checkParents is true, all parent controls will be checked, and unless they are all enabled, false will be returned. The property Enabled is mainly used for TWebControl derived controls.

Input
boolean$checkParentswhether the parents should also be checked enabled
Output
boolean whether the control is enabled.
Exception

getEnableTheming

public boolean getEnableTheming ()

Output
boolean whether theming is enabled for this control. The theming is enabled if the control and all its parents have it enabled.
Exception

getEnableViewState

public boolean getEnableViewState (mixed $checkParents )

Input
mixed$checkParents
Output
boolean whether viewstate is enabled
Exception

getHasAdapter

public boolean getHasAdapter ()

Output
boolean whether there is an adapter for this control
Exception

getHasAttributes

public boolean getHasAttributes ()

Output
boolean whether the control has custom attributes
Exception

getHasChildInitialized

public boolean getHasChildInitialized ()

Output
boolean true if the child control has been initialized.
Exception

getHasControls

public boolean getHasControls ()

Output
boolean whether the control has child controls
Exception

getHasInitialized

public boolean getHasInitialized ()

Output
boolean true if the onInit event has raised.
Exception

getHasLoaded

public boolean getHasLoaded ()

Output
boolean true if the onLoad event has raised.
Exception

getHasLoadedPostData

public boolean getHasLoadedPostData ()

Output
boolean true if the control has loaded post data.
Exception

getHasPreRendered

public boolean getHasPreRendered ()

Output
boolean true if onPreRender event has raised.
Exception

getID

public string getID (boolean $hideAutoID )

Returns the id of the control.

Control ID can be either manually set or automatically generated. If $hideAutoID is true, automatically generated ID will be returned as an empty string.

Input
boolean$hideAutoIDwhether to hide automatically generated ID
Output
string the ID of the control
Exception

getNamingContainer

public TControl getNamingContainer ()

Output
TControl the naming container of this control
Exception

getPage

public TPage getPage ()

Output
TPage the page that contains this control
Exception

getParent

public TControl getParent ()

Output
TControl the parent of this control
Exception

getRegisteredObject

public mixed getRegisteredObject (mixed $name )

Returns the named registered object.

A component with explicit ID on a template will be registered to the template owner. This method allows you to obtain this component with the ID.

Input
mixed$name
Output
mixed the named registered object. Null if object is not found.
Exception

getSkinID

public string getSkinID ()

Output
string the skin ID of this control, '' if not set
Exception

getSourceTemplateControl

public TTemplateControl getSourceTemplateControl ()

Output
TTemplateControl the control whose template is loaded from some external storage, such as file, db, and whose template ultimately contains this control.
Exception

getTemplateControl

public TTemplateControl getTemplateControl ()

Output
TTemplateControl the control whose template contains this control
Exception

getUniqueID

public string getUniqueID ()

Returns a unique ID that identifies the control in the page hierarchy.

A unique ID is the contenation of all naming container controls' IDs and the control ID. These IDs are separated by '$' character. Control users should not rely on the specific format of UniqueID, however.

Output
string a unique ID that identifies the control in the page hierarchy
Exception

getViewState

public mixed getViewState (string $key , mixed $defaultValue )

Returns a viewstate value.

This function is very useful in defining getter functions for component properties that must be kept in viewstate.

Input
string$keythe name of the viewstate value to be returned
mixed$defaultValuethe default value. If $key is not found in viewstate, $defaultValue will be returned
Output
mixed the viewstate value corresponding to $key
Exception

getVisible

public boolean getVisible (boolean $checkParents )

Checks if a control is visible.

If parent check is required, then a control is visible only if the control and all its ancestors are visible.

Input
boolean$checkParentswhether the parents should also be checked if visible
Output
boolean whether the control is visible (default=true).
Exception

hasAttribute

public boolean hasAttribute (mixed $name )

Input
mixed$name
Output
boolean whether the named attribute exists
Exception

initRecursive

protected void initRecursive (TControl $namingContainer )

Performs the Init step for the control and all its child controls.

Only framework developers should use this method.

Input
TControl$namingContainerthe naming container control
Output
Exception

isDescendentOf

protected boolean isDescendentOf (TControl $ancestor )

Input
TControl$ancestorthe potential ancestor control
Output
boolean if the control is a descendent (parent, parent of parent, etc.) of the specified control
Exception

isObjectRegistered

public boolean isObjectRegistered (mixed $name )

Input
mixed$name
Output
boolean whether an object has been registered with the name
Exception

loadRecursive

protected void loadRecursive ()

Performs the Load step for the control and all its child controls.

Only framework developers should use this method.

Output
Exception

loadState

public void loadState ()

This method is invoked right after the control has loaded its state.

You can override this method to initialize data from the control state. Parent implementation must be invoked.

Output
Exception

loadStateRecursive

protected void loadStateRecursive (array &$state , boolean $needViewState )

Loads state (viewstate and controlstate) into a control and its children.

This method should only be used by framework developers.

Input
array&$statethe collection of the state
boolean$needViewStatewhether the viewstate should be loaded
Output
Exception

onDataBinding

public void onDataBinding (TEventParameter $param )

Raises 'OnDataBinding' event.

This method is invoked when dataBind is invoked.

Input
TEventParameter$paramevent parameter to be passed to the event handlers
Output
Exception

onInit

public void onInit (TEventParameter $param )

This method is invoked when the control enters 'OnInit' stage.

The method raises 'OnInit' event. If you override this method, be sure to call the parent implementation so that the event handlers can be invoked.

Input
TEventParameter$paramevent parameter to be passed to the event handlers
Output
Exception

onLoad

public void onLoad (TEventParameter $param )

This method is invoked when the control enters 'OnLoad' stage.

The method raises 'OnLoad' event. If you override this method, be sure to call the parent implementation so that the event handlers can be invoked.

Input
TEventParameter$paramevent parameter to be passed to the event handlers
Output
Exception

onPreRender

public void onPreRender (TEventParameter $param )

This method is invoked when the control enters 'OnPreRender' stage.

The method raises 'OnPreRender' event. If you override this method, be sure to call the parent implementation so that the event handlers can be invoked.

Input
TEventParameter$paramevent parameter to be passed to the event handlers
Output
Exception

onUnload

public void onUnload (TEventParameter $param )

This method is invoked when the control enters 'OnUnload' stage.

The method raises 'OnUnload' event. If you override this method, be sure to call the parent implementation so that the event handlers can be invoked.

Input
TEventParameter$paramevent parameter to be passed to the event handlers
Output
Exception

preRenderRecursive

protected void preRenderRecursive ()

Performs the PreRender step for the control and all its child controls.

Only framework developers should use this method.

Output
Exception

raiseBubbleEvent

protected void raiseBubbleEvent (TControl $sender , TEventParameter $param )

Invokes the parent's bubbleEvent method.

A control who wants to bubble an event must call this method in its onEvent method.

Input
TControl$sendersender of the event
TEventParameter$paramevent parameter
Output
Exception

registerObject

public void registerObject (string $name , object object $object )

Registers an object by a name.

A registered object can be accessed like a public member variable. This method should only be used by framework and control developers.

Input
string$namename of the object
object object$objectto be declared
Output
Exception

removeAttribute

public string removeAttribute (string $name )

Removes the named attribute.

Input
string$namethe name of the attribute to be removed.
Output
string attribute value removed, null if attribute does not exist.
Exception

removedControl

public void removedControl (TControl $control )

Removes a control from the child collection of the control.

Only framework developers should use this method.

Input
TControl$controlthe child control removed
Output
Exception

render

public void render (THtmlWriter $writer )

Renders the control.

This method is invoked by renderControl when the control is visible. You can override this method to provide customized rendering of the control. By default, the control simply renders all its child contents.

Input
THtmlWriter$writerthe writer used for the rendering purpose
Output
Exception

renderChildren

public void renderChildren (THtmlWriter $writer )

Renders the children of the control.

This method iterates through all child controls and static text strings and renders them in order.

Input
THtmlWriter$writerthe writer used for the rendering purpose
Output
Exception

renderControl

public void renderControl (THtmlWriter $writer )

Renders the control.

Only when the control is visible will the control be rendered.

Input
THtmlWriter$writerthe writer used for the rendering purpose
Output
Exception

saveState

public void saveState ()

This method is invoked when control state is to be saved.

You can override this method to do last step state saving. Parent implementation must be invoked.

Output
Exception

saveStateRecursive

protected array saveStateRecursive (boolean $needViewState )

Saves all control state (viewstate and controlstate) as a collection.

This method should only be used by framework developers.

Input
boolean$needViewStatewhether the viewstate should be saved
Output
array the collection of the control state (including its children's state).
Exception

setAdapter

public void setAdapter (TControlAdapter $adapter )

Input
TControlAdapter$adaptercontrol adapter
Output
Exception

setAttribute

public void setAttribute (string $name , string $value )

Sets a custom control attribute.

Input
string$nameattribute name
string$valuevalue of the attribute
Output
Exception

setChildControlsCreated

protected void setChildControlsCreated (boolean $value )

Sets a value indicating whether child controls are created.

If false, any existing child controls will be cleared up.

Input
boolean$valuewhether child controls are created
Output
Exception

setControlStage

protected void setControlStage (integer $value )

Sets the lifecycle step the control is currently at.

This method should only be used by control developers.

Input
integer$valuethe lifecycle step the control is currently at. Valid values include CS_CONSTRUCTED, CS_CHILD_INITIALIZED, CS_INITIALIZED, CS_STATE_LOADED, CS_LOADED, CS_PRERENDERED.
Output
Exception

setControlState

protected void setControlState (string $key , mixed $value , mixed $defaultValue )

Sets a controlstate value.

This function is very useful in defining setter functions for control properties that must be kept in controlstate. Make sure that the controlstate value must be serializable and unserializable.

Input
string$keythe name of the controlstate value
mixed$valuethe controlstate value to be set
mixed$defaultValuedefault value. If $value===$defaultValue, the item will be cleared from controlstate
Output
Exception

setCustomData

public void setCustomData (mixed $value )

Associates custom data with this control.

Note, the custom data must be serializable and unserializable.

Input
mixed$valuecustom data
Output
Exception

setEnabled

public void setEnabled (boolean $value )

Input
boolean$valuewhether the control is to be enabled.
Output
Exception

setEnableTheming

public void setEnableTheming (boolean $value )

Input
boolean$valuewhether to enable theming
Output
Exception
throwsTInvalidOperationException if this method is invoked after OnPreInit

setEnableViewState

public void setEnableViewState (boolean $value )

Input
boolean$valueset whether to enable viewstate
Output
Exception

setID

public void setID (string $id )

Input
string$idthe new control ID. The value must consist of word characters [a-zA-Z0-9_] only
Output
Exception
throwsTInvalidDataValueException if ID is in a bad format

setPage

public void setPage (TPage $page )

Sets the page for a control.

Only framework developers should use this method.

Input
TPage$pagethe page that contains this control
Output
Exception

setSkinID

public void setSkinID (string $value )

Input
string$valuethe skin ID of this control
Output
Exception
throwsTInvalidOperationException if the SkinID is set in a stage later than PreInit, or if the skin is applied already.

setTemplateControl

public void setTemplateControl (TTemplateControl $control )

Sets the control whose template contains this control.

Only framework developers should use this method.

Input
TTemplateControl$controlthe control whose template contains this control
Output
Exception

setViewState

public void setViewState (string $key , mixed $value , mixed $defaultValue )

Sets a viewstate value.

This function is very useful in defining setter functions for control properties that must be kept in viewstate. Make sure that the viewstate value must be serializable and unserializable.

Input
string$keythe name of the viewstate value
mixed$valuethe viewstate value to be set
mixed$defaultValuedefault value. If $value===$defaultValue, the item will be cleared from the viewstate.
Output
Exception

setVisible

public void setVisible (boolean $value )

Input
boolean$valuewhether the control is visible
Output
Exception

trackViewState

public void trackViewState (boolean $enabled )

Sets a value indicating whether we should keep data in viewstate.

When it is false, data saved via setViewState() will not be persisted. By default, it is true, meaning data will be persisted across postbacks.

Input
boolean$enabledwhether data should be persisted
Output
Exception

traverseChildControls

protected void traverseChildControls (mixed $param , callback $preCallback , callback $postCallback )

Traverse the whole control hierarchy rooted at this control.

Callback function may be invoked for each control being visited. A pre-callback is invoked before traversing child controls; A post-callback is invoked after traversing child controls. Callback functions can be global functions or class methods. They must be of the following signature:

  1. function callback_func($control,$param) {...}
where $control refers to the control being visited and $param is the parameter that is passed originally when calling this traverse function.

Input
mixed$paramparameter to be passed to callbacks for each control
callback$preCallbackcallback invoked before traversing child controls. If null, it is ignored.
callback$postCallbackcallback invoked after traversing child controls. If null, it is ignored.
Output
Exception

unbindProperty

public void unbindProperty (string $name )

Breaks the binding between a property (or property path) and an expression.

Input
string$namethe property name (or property path)
Output
Exception

unloadRecursive

protected void unloadRecursive ()

Performs the Unload step for the control and all its child controls.

Only framework developers should use this method.

Output
Exception

unregisterObject

public void unregisterObject (string $name )

Unregisters an object by name.

Input
string$namename of the object
Output
Exception

__get

public mixed __get (string $name )

Returns a property value by name or a control by ID.

This overrides the parent implementation by allowing accessing a control via its ID using the following syntax,

  1. $menuBar=$this->menuBar;
Note, the control must be configured in the template with explicit ID. If the name matches both a property and a control ID, the control ID will take the precedence.

Input
string$namethe property name or control ID
Output
mixed the property value or the target control
Exception
throwsTInvalidOperationException if the property is not defined.


Constant Details

AUTOMATIC_ID_PREFIX

prefix to an ID automatically generated

Type:

string

Value:

'ctl'

CLIENT_ID_SEPARATOR

separator char between IDs in a ClientID

Type:

string

Value:

'_'

CS_CHILD_INITIALIZED

Type:

int

Value:

1

CS_CONSTRUCTED

the stage of lifecycles that the control is currently at

Type:

int

Value:

0

CS_INITIALIZED

Type:

int

Value:

2

CS_LOADED

Type:

int

Value:

4

CS_PRERENDERED

Type:

int

Value:

5

CS_STATE_LOADED

Type:

int

Value:

3

ID_FORMAT

format of control ID

Type:

string

Value:

'/^[a-zA-Z_]\\w*$/'

ID_SEPARATOR

separator char between IDs in a UniqueID

Type:

string

Value:

'$'

IS_CHILD_CREATED

Type:

int

Value:

0x20

IS_CREATING_CHILD

Type:

int

Value:

0x40

IS_DISABLE_THEMING

Type:

int

Value:

0x10

IS_DISABLE_VIEWSTATE

Type:

int

Value:

0x02

IS_ID_SET

State bits.

Type:

int

Value:

0x01

IS_SKIN_APPLIED

Type:

int

Value:

0x04

IS_STYLESHEET_APPLIED

Type:

int

Value:

0x08

RF_ADAPTER

Type:

int

Value:

9

RF_AUTO_BINDINGS

Type:

int

Value:

10

RF_CHILD_STATE

Type:

int

Value:

1

RF_CONTROLS

Indexes for the rare fields.

In order to save memory, rare fields will only be created if they are needed.

Type:

int

Value:

0

RF_CONTROLSTATE

Type:

int

Value:

7

RF_DATA_BINDINGS

Type:

int

Value:

5

RF_EVENTS

Type:

int

Value:

6

RF_NAMED_CONTROLS

Type:

int

Value:

2

RF_NAMED_CONTROLS_ID

Type:

int

Value:

3

RF_NAMED_OBJECTS

Type:

int

Value:

8

RF_SKIN_ID

Type:

int

Value:

4