Packages:
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:

Class TControl

TComponent
   |
   --TApplicationComponent
      |
      --TControl

Direct Known Sub-classes:

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

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.

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.

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.

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.

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.

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