- Home
- About
- Testimonials
- Demos
- Download
- Documentation
- Blogs
- Forum
- Support

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:
IBroadcastEventReceiver
IButtonControl
INamingContainer
IPageStatePersister
IPostBackDataHandler
IPostBackEventHandler
ISurroundable
ITemplate
ITheme
IValidatable
IValidator
TBroadcastEventParameter
TCachePageStatePersister
TClientScriptManager
TClientSideOptions
TCommandEventParameter
TCompositeControl
TCompositeLiteral
TControl
TControlAdapter
TControlCollection
TEmptyControlCollection
TForm
THead
THtmlWriter
TPage
TPageStateFormatter
TPageStatePersister
TSessionPageStatePersister
TTemplate
TTemplateControl
TTemplateManager
TTextProcessor
TTheme
TThemeManager

Keyword

# Class TControl

    TComponent
       |
       --TApplicationComponent
          |
          --TControl

#### Direct Known Sub-classes:

TForm , TCallback , TCallbackOptions , TContent , TClientScript , TXmlTransform , TWebControl , TLiteral , TSafeHtml , TContentPlaceHolder , TConditional , TExpression , TMultiView , TView , TDataSourceControl , TStyleSheet , THead , TPlaceHolder , TWizardNavigationContainer , TRepeaterItem , TOutputCache , TStatements , THiddenField , TCompositeControl , TI18NControl , TTranslateParameter

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 | __construct 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 | addToPostDataLoader () Add controls implementing IPostBackDataHandler to post data loaders.
void | applyStyleSheetSkin ( TPage $page) 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 | autoDataBindProperties () 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 | clearChildState () Clears up the child state data.
protected void | clearControlState ( string $key) Clears a controlstate value.
void | clearNamingContainer () 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 | createChildControls () Creates child controls.
protected TControlCollection | createControlCollection () Creates a control collection object that is to be used to hold child controls
void | dataBind () Performs the databinding for this control.
protected void | dataBindChildren () Databinding child controls.
protected void | dataBindProperties () Databinding properties of the control.
void | ensureChildControls () 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 | getAdapter ()
boolean | getAllowChildControls ()
string | getAttribute ( mixed $name)
TAttributeCollection | getAttributes () Returns the list of custom attributes.
protected boolean | getChildControlsCreated ()
string | getClientID () Returns the client ID of the control.
TControlCollection | getControls ()
protected integer | getControlStage () Gets the lifecycle step the control is currently at.
protected mixed | getControlState ( string $key, mixed $defaultValue) Returns a controlstate value.
mixed | getCustomData () Returns custom data associated with this control.
boolean | getEnabled ( boolean $checkParents) Returns a value indicating whether the control is enabled.
boolean | getEnableTheming ()
boolean | getEnableViewState ( mixed $checkParents)
boolean | getHasAdapter ()
boolean | getHasAttributes ()
boolean | getHasChildInitialized ()
boolean | getHasControls ()
boolean | getHasInitialized ()
boolean | getHasLoaded ()
boolean | getHasLoadedPostData ()
boolean | getHasPreRendered ()
string | getID ( boolean $hideAutoID) Returns the id of the control.
TControl | getNamingContainer ()
TPage | getPage ()
TControl | getParent ()
mixed | getRegisteredObject ( mixed $name) Returns the named registered object.
string | getSkinID ()
TTemplateControl | getSourceTemplateControl ()
TTemplateControl | getTemplateControl ()
string | getUniqueID () 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 | loadRecursive () Performs the Load step for the control and all its child controls.
void | loadState () 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 | onDataBinding ( TEventParameter $param) Raises 'OnDataBinding' event.
void | onInit ( TEventParameter $param) This method is invoked when the control enters 'OnInit' stage.
void | onLoad ( TEventParameter $param) This method is invoked when the control enters 'OnLoad' stage.
void | onPreRender ( TEventParameter $param) This method is invoked when the control enters 'OnPreRender' stage.
void | onUnload ( TEventParameter $param) This method is invoked when the control enters 'OnUnload' stage.
protected void | preRenderRecursive () Performs the PreRender step for the control and all its child controls.
protected void | raiseBubbleEvent ( TControl $sender, TEventParameter $param) 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 | renderChildren ( THtmlWriter $writer) Renders the children of the control.
void | renderControl ( THtmlWriter $writer) Renders the control.
void | saveState () 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 | setTemplateControl ( TTemplateControl $control) 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 | unloadRecursive () 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 | $control | the 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 | $object | text 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 | $page | the page containing the control
Output
Exception
throws | TInvalidOperationException 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 | $name | the property name, or property path
string | $expression | the 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 | $name | the property name, or property path
string | $expression | the 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 | $name | name of the broadcast event
TControl | $sender | sender of this event
TEventParameter | $param | event 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 | $sender | sender of the event
TEventParameter | $param | event 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 | $key | the 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 | $key | the 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 | $uniqueID | the 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 | $id | ID of the control to be looked up
Output
TControl|null | the control found, null if not found
Exception
throws | TInvalidDataValueException 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 | $id | the 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 | $type | the class name
boolean | $strict | whether 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 | $key | the name of the controlstate value to be returned
mixed | $defaultValue | the 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 | $checkParents | whether 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 | $hideAutoID | whether 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 | $key | the name of the viewstate value to be returned
mixed | $defaultValue | the 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 | $checkParents | whether 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 | $namingContainer | the naming container control
Output
Exception

## isDescendentOf

protected boolean isDescendentOf | (TControl $ancestor )

Input
TControl | $ancestor | the 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 | &$state | the collection of the state
boolean | $needViewState | whether 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 | $param | event 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 | $param | event 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 | $param | event 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 | $param | event 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 | $param | event 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 | $sender | sender of the event
TEventParameter | $param | event 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 | $name | name of the object
object object | $object | to be declared
Output
Exception

## removeAttribute

public string removeAttribute | (string $name )

Removes the named attribute.

Input
string | $name | the 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 | $control | the 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 | $writer | the 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 | $writer | the 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 | $writer | the 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 | $needViewState | whether 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 | $adapter | control adapter
Output
Exception

## setAttribute

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

Sets a custom control attribute.

Input
string | $name | attribute name
string | $value | value 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 | $value | whether 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 | $value | the 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 | $key | the name of the controlstate value
mixed | $value | the controlstate value to be set
mixed | $defaultValue | default 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 | $value | custom data
Output
Exception

## setEnabled

public void setEnabled | (boolean $value )

Input
boolean | $value | whether the control is to be enabled.
Output
Exception

## setEnableTheming

public void setEnableTheming | (boolean $value )

Input
boolean | $value | whether to enable theming
Output
Exception
throws | TInvalidOperationException if this method is invoked after OnPreInit

## setEnableViewState

public void setEnableViewState | (boolean $value )

Input
boolean | $value | set whether to enable viewstate
Output
Exception

## setID

public void setID | (string $id )

Input
string | $id | the new control ID. The value must consist of word characters [a-zA-Z0-9_] only
Output
Exception
throws | TInvalidDataValueException 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 | $page | the page that contains this control
Output
Exception

## setSkinID

public void setSkinID | (string $value )

Input
string | $value | the skin ID of this control
Output
Exception
throws | TInvalidOperationException 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 | $control | the 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 | $key | the name of the viewstate value
mixed | $value | the viewstate value to be set
mixed | $defaultValue | default value. If $value===$defaultValue, the item will be cleared from the viewstate.
Output
Exception

## setVisible

public void setVisible | (boolean $value )

Input
boolean | $value | whether 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 | $enabled | whether 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:

     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 | $param | parameter to be passed to callbacks for each control
callback | $preCallback | callback invoked before traversing child controls. If null, it is ignored.
callback | $postCallback | callback 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 | $name | the 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 | $name | name 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,

     $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 | $name | the property name or control ID
Output
mixed | the property value or the target control
Exception
throws | TInvalidOperationException 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