## Class TControl

Description

Implements interfaces:

- IRenderable
- IBindable

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
- version: $Revision: $ $Date: $
- author: Qiang Xue <qiang.xue@gmail.com>

Located in /Web/UI/TControl.php (line 71)

    TComponent
       |
       --TApplicationComponent
          |
          --TControl

Direct descendents

Class | Description
--- | ---
TI18NControl | TI18NControl class.
TTranslateParameter | TTranslateParameter component should be used inside the TTranslate component to allow parameter substitution.
TCompositeControl | TCompositeControl class.
TForm | TForm class
TClientScript | TClientScript class
TContent | TContent class
TContentPlaceHolder | TContentPlaceHolder class
TDataSourceControl | TDataSourceControl class
TExpression | TExpression class
THead | THead class
THiddenField | THiddenField class
TLiteral | TLiteral class
TMultiView | TMultiView class
TView | TView class
TPlaceHolder | TPlaceHolder class
TRepeaterItem | TRepeaterItem class
TSafeHtml | TSafeHtml class
TStatements | TStatements class
TWebControl | TWebControl class
TWizardNavigationContainer | TWizardNavigationContainer class.

Class Constant Summary
AUTOMATIC_ID_PREFIX = 'ctl'
CLIENT_ID_SEPARATOR = '_'
CS_CHILD_INITIALIZED = 1
CS_CONSTRUCTED = 0
CS_INITIALIZED = 2
CS_LOADED = 4
CS_PRERENDERED = 5
CS_STATE_LOADED = 3
ID_FORMAT = '/^[a-zA-Z_]\\w*$/'
ID_SEPARATOR = '$'
IS_CHILD_CREATED = 0x20
IS_CREATING_CHILD = 0x40
IS_DISABLE_THEMING = 0x10
IS_DISABLE_VIEWSTATE = 0x02
IS_ID_SET = 0x01
IS_SKIN_APPLIED = 0x04
IS_STYLESHEET_APPLIED = 0x08
RF_ADAPTER = 9
RF_AUTO_BINDINGS = 10
RF_CHILD_STATE = 1
RF_CONTROLS = 0
RF_CONTROLSTATE = 7
RF_DATA_BINDINGS = 5
RF_EVENTS = 6
RF_NAMED_CONTROLS = 2
RF_NAMED_CONTROLS_ID = 3
RF_NAMED_OBJECTS = 8
RF_SKIN_ID = 4
Method Summary
TControl __construct ()
void addedControl (TControl $control)
void addParsedObject (string|TComponent $object)
void applyStyleSheetSkin (TPage $page)
void autoBindProperty (string $name, string $expression)
void autoDataBindProperties ()
void bindProperty (string $name, string $expression)
void broadcastEvent (TControl $sender, TBroadCastEventParameter $param)
void broadcastEventInternal (TControl $sender, TBroadcastEventParameter $param)
boolean bubbleEvent (TControl $sender, TEventParameter $param)
void clearChildState ()
void clearControlState (string $key)
void clearNamingContainer ()
void clearViewState (string $key)
void createChildControls ()
TControlCollection createControlCollection ()
void createdOnTemplate (TControl $parent)
void dataBind ()
void dataBindChildren ()
void dataBindProperties ()
void ensureChildControls ()
TControl|null findControl (string $id)
array findControlsByID (string $id)
array findControlsByType (string $type)
void focus ()
TControlAdapter getAdapter ()
boolean getAllowChildControls ()
string getAttribute (mixed $name)
TAttributeCollection getAttributes ()
boolean getChildControlsCreated ()
string getClientID ()
TControlCollection getControls ()
integer getControlStage ()
mixed getControlState (string $key, [mixed $defaultValue = null])
boolean getEnabled ([boolean $checkParents = false])
boolean getEnableTheming ()
boolean getEnableViewState ([mixed $checkParents = false])
boolean getHasAdapter ()
boolean getHasAttributes ()
boolean getHasControls ()
string getID ([boolean $hideAutoID = true])
TControl getNamingContainer ()
TPage getPage ()
TControl getParent ()
mixed getRegisteredObject (mixed $name)
string getSkinID ()
TTemplateControl getSourceTemplateControl ()
TTemplateControl getTemplateControl ()
string getUniqueID ()
mixed getViewState (string $key, [mixed $defaultValue = null])
boolean getVisible ([boolean $checkParents = true])
boolean hasAttribute (mixed $name)
void initRecursive ([TControl $namingContainer = null])
boolean isDescendentOf (TControl $ancestor)
boolean isObjectRegistered (mixed $name)
void loadRecursive ()
void loadState ()
void loadStateRecursive (TMap &$state, [boolean $needViewState = true])
void onDataBinding (TEventParameter $param)
void onInit (TEventParameter $param)
void onLoad (TEventParameter $param)
void onPreRender (TEventParameter $param)
void onUnload (TEventParameter $param)
void preRenderRecursive ()
void raiseBubbleEvent (TControl $sender, TEventParameter $param)
void registerObject (string $name, object object $object)
string removeAttribute (string $name)
void removedControl (TControl $control)
void render (THtmlWriter $writer)
void renderChildren (THtmlWriter $writer)
void renderControl (THtmlWriter $writer)
void saveState ()
array &saveStateRecursive ([boolean $needViewState = true])
void setAdapter (TControlAdapter $adapter)
void setAttribute (string $name, string $value)
void setChildControlsCreated (boolean $value)
void setControlStage (integer $value)
void setControlState (string $key, mixed $value, [mixed $defaultValue = null])
void setEnabled (boolean $value)
void setEnableTheming (boolean $value)
void setEnableViewState (boolean $value)
void setID (string $id)
void setPage (TPage $page)
void setSkinID (string $value)
void setTemplateControl (TTemplateControl $control)
void setViewState (string $key, mixed $value, [mixed $defaultValue = null])
void setVisible (boolean $value)
void traverseChildControls (mixed $param, [callback $preCallback = null], [callback $postCallback = null])
void unbindProperty (string $name)
void unloadRecursive ()
void unregisterObject (string $name)
mixed __get (string $name)
Methods
Constructor __construct (line 171)

Constructor.

- access: public

TControl __construct ()

Redefined in descendants as:

- TPage::__construct() : Constructor.
- TReadOnlyDataSource::__construct()
- TRepeaterItem::__construct() : Constructor.
- TCheckBoxList::__construct() : Constructor.
- TRatingList::__construct()
- TDataListItem::__construct() : Constructor.
- TBaseValidator::__construct() : Constructor.
- TDataGridPager::__construct() : Constructor.
- TDataGridItem::__construct() : Constructor.
- THtmlArea::__construct() : Constructor.
- TValidationSummary::__construct() : Constructor.

addedControl (line 1082)

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.

- access: public

void addedControl (TControl $control)

- TControl $control: the new child control

addParsedObject (line 1046)

Processes an object that is created during parsing template.

The object can be either a component or a static text string. By default, the object will be added into the child control collection. This method can be overriden to customize the handling of newly created objects in template. Only framework developers and control developers should use this method.

- access: public
- see: TControl::createdOnTemplate()

void addParsedObject (string|TComponent $object)

- string|TComponent $object: text string or component parsed and instantiated in template

Redefined in descendants as:

- THead::addParsedObject() : Processes an object that is created during parsing template.
- TMultiView::addParsedObject() : Processes an object that is created during parsing template.
- TBaseDataList::addParsedObject() : No body content should be added to data list control.
- TDataGrid::addParsedObject() : Adds objects parsed in template to datagrid.
- TListControl::addParsedObject() : Adds object parsed from template to the control.
- TRepeater::addParsedObject() : No body content should be added to repeater.
- TImageMap::addParsedObject() : Processes an object that is created during parsing template.
- TTable::addParsedObject() : Adds object parsed from template to the control.
- TTableRow::addParsedObject() : Adds object parsed from template to the control.
- TTextProcessor::addParsedObject() : HTML-decodes static text.
- TWizard::addParsedObject() : Adds TWizardStep objects into step collection.

applyStyleSheetSkin (line 1574)

Applies a stylesheet skin to a control.

- access: public
- throws: TInvalidOperationException if the stylesheet skin is applied already

void applyStyleSheetSkin (TPage $page)

- TPage $page: the page containing the control

autoBindProperty (line 752)

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).

- access: public

void autoBindProperty (string $name, string $expression)

- string $name: the property name, or property path
- string $expression: the expression

autoDataBindProperties (line 787)

Auto databinding properties of the control.

- access: protected

void autoDataBindProperties ()
bindProperty (line 730)

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).

- access: public

void bindProperty (string $name, string $expression)

- string $name: the property name, or property path
- string $expression: the expression

broadcastEvent (line 1359)

Broadcasts an event.

The event will be sent to all controls on the current page hierarchy. If this control is not on a page, the event will be sent to all its child controls recursively. Controls implementing IBroadcastEventReceiver will get a chance to respond to the event.

- access: protected

void broadcastEvent (TControl $sender, TBroadCastEventParameter $param)

- TControl $sender: sender of the event
- TBroadcastEventParameter $param: event parameter

broadcastEventInternal (line 1371)

Recursively broadcasts an event.

This method should only be used by framework developers.

- access: protected

void broadcastEventInternal (TControl $sender, TBroadcastEventParameter $param)

- TControl $sender: sender of the event
- TBroadcastEventParameter $param: event parameter

bubbleEvent (line 1344)

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.

- return: true if the event bubbling is handled and no more bubbling.
- access: public
- see: TControl::raiseBubbleEvent()

boolean bubbleEvent (TControl $sender, TEventParameter $param)

- TControl $sender: sender of the event
- TEventParameter $param: event parameters

Redefined in descendants as:

- TMultiView::bubbleEvent() : Processes the events bubbled from child controls.
- TRepeaterItem::bubbleEvent() : This method overrides parent's implementation by wrapping event parameter for Command event with item information.
- TDataGrid::bubbleEvent() : This method overrides parent's implementation to handle onItemCommand event which is bubbled from TDataGridItem child controls.
- TDataList::bubbleEvent() : This method overrides parent's implementation to handle onItemCommand event which is bubbled from TDataListItem child controls.
- TRepeater::bubbleEvent() : This method overrides parent's implementation to handle onItemCommand event which is bubbled from TRepeaterItem child controls.
- TDataListItem::bubbleEvent() : This method overrides parent's implementation by wrapping event parameter for Command event with item information.
- TDataGridPager::bubbleEvent() : This method overrides parent's implementation by wrapping event parameter for OnCommand event with item information.
- TDataGridItem::bubbleEvent() : This method overrides parent's implementation by wrapping event parameter for OnCommand event with item information.
- TWizard::bubbleEvent() : Handles bubbled events.

clearChildState (line 1058)

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.

- access: protected

void clearChildState ()
clearControlState (line 678)

Clears a controlstate value.

- access: protected

void clearControlState (string $key)

- string $key: the name of the controlstate value to be cleared

clearNamingContainer (line 961)

Resets the control as a naming container.

Only framework developers should use this method.

- access: public

void clearNamingContainer ()
clearViewState (line 719)

Clears a viewstate value.

- access: public

void clearViewState (string $key)

- string $key: the name of the viewstate value to be cleared

createChildControls (line 870)

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.

- access: public

void createChildControls ()

Redefined in descendants as:

- TTemplateControl::createChildControls() : Creates child controls.
- TTemplatedWizardStep::createChildControls() : Creates child controls.
- TWizard::createChildControls() : Creates child controls within the wizard

createControlCollection (line 477)

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

- return: control collection
- access: protected
- see: TControl::getControls()

TControlCollection createControlCollection ()

Redefined in descendants as:

- TMultiView::createControlCollection() : Creates a control collection object that is to be used to hold child controls
- TTable::createControlCollection() : Creates a control collection object that is to be used to hold child controls
- TTableRow::createControlCollection() : Creates a control collection object that is to be used to hold child controls

createdOnTemplate (line 1032)

This method is invoked after the control is instantiated by a template.

When this method is invoked, the control should have a valid TemplateControl and has its properties initialized according to template configurations. The control, however, has not been added to the page hierarchy yet. The default implementation of this method will invoke the potential parent control's addParsedObject to add the control as a child. This method can be overriden.

- access: public
- see: TControl::addParsedObject()

void createdOnTemplate (TControl $parent)

- TControl $parent: potential parent of this control

Redefined in descendants as:

- TContent::createdOnTemplate() : This method is invoked after the control is instantiated on a template.
- TContentPlaceHolder::createdOnTemplate() : This method is invoked after the control is instantiated on a template.

dataBind (line 760)

Performs the databinding for this control.

- access: public

void dataBind ()

Redefined in descendants as:

- TDataBoundControl::dataBind() : Performs databinding.

dataBindChildren (line 801)

Databinding child controls.

- access: protected

void dataBindChildren ()
dataBindProperties (line 773)

Databinding properties of the control.

- access: protected

void dataBindProperties ()
ensureChildControls (line 841)

Ensures child controls are created.

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

- access: public

void ensureChildControls ()
findControl (line 885)

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'.

- return: the control found, null if not found
- access: public
- throws: TInvalidDataValueException if a control's ID is found not unique within its naming container.

TControl|null findControl (string $id)

- string $id: ID of the control to be looked up

Redefined in descendants as:

- TCheckBoxList::findControl() : Finds a control by ID.

findControlsByID (line 939)

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.

- return: list of controls found
- access: public

array findControlsByID (string $id)

- string $id: the ID being looked for

findControlsByType (line 914)

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

- return: list of controls found
- access: public

array findControlsByType (string $type)

- string $type: the class name

focus (line 391)

Sets input focus to this control.

- access: public

void focus ()

Redefined in descendants as:

- TDataSourceControl::focus()
- THiddenField::focus() : Sets focus to this control.

getAdapter (line 210)

- return: control adapter. Null if not exists.
- access: public

TControlAdapter getAdapter ()
getAllowChildControls (line 1016)

- return: whether body contents are allowed for this control. Defaults to true.
- access: public

boolean getAllowChildControls ()
getAttribute (line 584)

- return: attribute value, null if attribute does not exist
- access: public

string getAttribute (mixed $name)
getAttributes (line 558)

Returns the list of custom attributes.

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

- return: the list of custom attributes
- access: public

TAttributeCollection getAttributes ()
getChildControlsCreated (line 814)

- return: whether child controls have been created
- access: protected

boolean getChildControlsCreated ()
getClientID (line 403)

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.

- return: the client ID of the control
- access: public

string getClientID ()
getControls (line 465)

- return: the child control collection
- access: public

TControlCollection getControls ()
getControlStage (line 314)

Gets the lifecycle step the control is currently at.

This method should only be used by control developers.

- return: 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.
- access: protected

integer getControlStage ()
getControlState (line 651)

Returns a controlstate value.

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

- return: the controlstate value corresponding to $key
- access: protected

mixed getControlState (string $key, [mixed $defaultValue = null])

- 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

getEnabled (line 520)

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.

- return: whether the control is enabled.
- access: public

boolean getEnabled ([boolean $checkParents = false])

- boolean $checkParents: whether the parents should also be checked enabled

getEnableTheming (line 432)

- return: whether theming is enabled for this control. The theming is enabled if the control and all its parents have it enabled.
- access: public

boolean getEnableTheming ()

Redefined in descendants as:

- TDataSourceControl::getEnableTheming()
- THiddenField::getEnableTheming()

getEnableViewState (line 618)

- return: whether viewstate is enabled
- access: public

boolean getEnableViewState ([mixed $checkParents = false])
getHasAdapter (line 202)

- return: whether there is an adapter for this control
- access: public

boolean getHasAdapter ()
getHasAttributes (line 544)

- return: whether the control has custom attributes
- access: public

boolean getHasAttributes ()
getHasControls (line 457)

- return: whether the control has child controls
- access: public

boolean getHasControls ()
getID (line 338)

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.

- return: the ID of the control
- access: public

string getID ([boolean $hideAutoID = true])

- boolean $hideAutoID: whether to hide automatically generated ID

getNamingContainer (line 234)

- return: the naming container of this control
- access: public

TControl getNamingContainer ()
getPage (line 249)

- return: the page that contains this control
- access: public

TPage getPage ()
getParent (line 226)

- return: the parent of this control
- access: public

TControl getParent ()
getRegisteredObject (line 1008)

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.

- return: the named registered object. Null if object is not found.
- access: public

mixed getRegisteredObject (mixed $name)
getSkinID (line 411)

- return: the skin ID of this control, '' if not set
- access: public

string getSkinID ()

Redefined in descendants as:

- TDataSourceControl::getSkinID()

getSourceTemplateControl (line 296)

- return: the control whose template is loaded from some external storage, such as file, db, and whose template ultimately contains this control.
- access: public

TTemplateControl getSourceTemplateControl ()
getTemplateControl (line 284)

- return: the control whose template contains this control
- access: public

TTemplateControl getTemplateControl ()
getUniqueID (line 368)

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.

- return: a unique ID that identifies the control in the page hierarchy
- access: public

string getUniqueID ()
getViewState (line 692)

Returns a viewstate value.

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

- return: the viewstate value corresponding to $key
- access: public

mixed getViewState (string $key, [mixed $defaultValue = null])

- 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

getVisible (line 489)

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.

- return: whether the control is visible (default=true).
- access: public

boolean getVisible ([boolean $checkParents = true])

- boolean $checkParents: whether the parents should also be checked if visible

Redefined in descendants as:

- TDataSourceControl::getVisible()
- TView::getVisible()

hasAttribute (line 573)

- return: whether the named attribute exists
- access: public

boolean hasAttribute (mixed $name)
initRecursive (line 1148)

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

Only framework developers should use this method.

- access: protected

void initRecursive ([TControl $namingContainer = null])

- TControl $namingContainer: the naming container control

Redefined in descendants as:

- TCompositeControl::initRecursive() : Performs the OnInit step for the control and all its child controls.
- TTemplateControl::initRecursive() : Performs the OnInit step for the control and all its child controls.

isDescendentOf (line 1068)

- return: if the control is a descendent (parent, parent of parent, etc.) of the specified control
- access: protected

boolean isDescendentOf (TControl $ancestor)

- TControl $ancestor: the potential ancestor control

isObjectRegistered (line 996)

- return: whether an object has been registered with the name
- access: public
- see: TControl::registerObject()

boolean isObjectRegistered (mixed $name)
loadRecursive (line 1187)

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

Only framework developers should use this method.

- access: protected

void loadRecursive ()
loadState (line 1484)

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.

- access: public

void loadState ()

Redefined in descendants as:

- TPage::loadState() : This method is invoked right after the control has loaded its state.
- TMultiView::loadState() : Loads state into the wizard.
- TDataGrid::loadState() : Loads item count information from viewstate.
- TDataList::loadState() : Loads item count information from viewstate.
- TListControl::loadState() : Loads items from viewstate.
- TRepeater::loadState() : Loads item count information from viewstate.

loadStateRecursive (line 1493)

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

- access: protected

void loadStateRecursive (TMap &$state, [boolean $needViewState = true])

- TMap &$state: the collection of the state
- boolean $needViewState: whether the viewstate should be loaded

onDataBinding (line 1288)

Raises 'OnDataBinding' event.

This method is invoked when dataBind is invoked.

- access: public

void onDataBinding (TEventParameter $param)

- TEventParameter $param: event parameter to be passed to the event handlers

onInit (line 1266)

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.

- access: public

void onInit (TEventParameter $param)

- TEventParameter $param: event parameter to be passed to the event handlers

Redefined in descendants as:

- TForm::onInit() : Registers the form with the page.
- THead::onInit() : Registers the head control with the current page.
- TMultiView::onInit() : Initializes the active view if any.
- TTemplatedWizardStep::onInit() : Ensures child controls are created.
- TDataBoundControl::onInit() : Sets page's OnPreLoad event handler as pagePreLoad.
- TBaseValidator::onInit() : Registers the validator with page.
- TWizard::onInit() : Creates the child controls of the wizard.

onLoad (line 1278)

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.

- access: public

void onLoad (TEventParameter $param)

- TEventParameter $param: event parameter to be passed to the event handlers

onPreRender (line 1313)

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.

- access: public

void onPreRender (TEventParameter $param)

- TEventParameter $param: event parameter to be passed to the event handlers

Redefined in descendants as:

- TClientScript::onPreRender() : Calls the client script manager to add each of the requested client script libraries.
- TCheckBox::onPreRender() : Registers the checkbox to receive postback data during postback.
- TDataBoundControl::onPreRender() : Ensures any pending databind is performed.
- TCheckBoxList::onPreRender() : Registers for post data on postback.
- TRatingList::onPreRender()
- TListBox::onPreRender() : Registers the list control to load post data on postback.
- TFileUpload::onPreRender() : Sets Enctype of the form on the page.
- TImageButton::onPreRender() : Registers the image button to receive postback data during postback.
- TJavascriptLogger::onPreRender() : Registers the required logger javascript.
- TBaseValidator::onPreRender() : Renders the javascript code to the end script.
- TColorPicker::onPreRender() : Publish the color picker Css asset files.
- TDatePicker::onPreRender() : Publish the date picker Css asset files.
- TTextHighlighter::onPreRender() : Registers css style for the highlighted result.

onUnload (line 1301)

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.

- access: public

void onUnload (TEventParameter $param)

- TEventParameter $param: event parameter to be passed to the event handlers

Redefined in descendants as:

- TBaseValidator::onUnload() : Unregisters the validator from page.

preRenderRecursive (line 1214)

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

Only framework developers should use this method.

- access: protected

void preRenderRecursive ()
raiseBubbleEvent (line 1325)

Invokes the parent's bubbleEvent method.

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

- access: protected
- see: TControl::bubbleEvent()

void raiseBubbleEvent (TControl $sender, TEventParameter $param)

- TControl $sender: sender of the event
- TEventParameter $param: event parameter

registerObject (line 975)

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.

- access: public
- see: TControl::__get()

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

- string $name: name of the object
- object object $object: to be declared

removeAttribute (line 607)

Removes the named attribute.

- return: attribute value removed, null if attribute does not exist.
- access: public

string removeAttribute (string $name)

- string $name: the name of the attribute to be removed.

removedControl (line 1126)

Removes a control from the child collection of the control.

Only framework developers should use this method.

- access: public

void removedControl (TControl $control)

- TControl $control: the child control removed

render (line 1443)

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.

- access: public

void render (THtmlWriter $writer)

- THtmlWriter $writer: the writer used for the rendering purpose

Redefined in descendants as:

- TDateFormat::render()
- TNumberFormat::render()
- TTranslate::render() : renders the translated string.
- TForm::render() : Renders the form.
- TExpression::render() : Renders the evaluation result of the expression.
- THead::render() : Renders the head control.
- THiddenField::render() : Renders the control.
- TLiteral::render() : Renders the literal control.
- TMultiView::render() : Renders the currently active view.
- TSafeHtml::render() : Renders body content.
- TStatements::render() : Renders the evaluation result of the statements.
- TWebControl::render() : Renders the control.
- TCheckBox::render() : Renders the checkbox control.
- TDataGrid::render() : Renders the datagrid.
- TDataList::render() : Renders the data list control.
- TBulletedList::render() : Renders the control.
- TCheckBoxList::render() : Renders the checkbox list control.
- TRepeater::render() : Renders the repeater.
- TImageMap::render() : Renders this imagemap.
- TColorPicker::render() : Renders body content.
- TDatePicker::render() : Renders body content.
- TWizard::render() : Renders the wizard.

renderChildren (line 1454)

Renders the children of the control.

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

- access: public

void renderChildren (THtmlWriter $writer)

- THtmlWriter $writer: the writer used for the rendering purpose

renderControl (line 1425)

Renders the control.

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

- access: public

void renderControl (THtmlWriter $writer)

- THtmlWriter $writer: the writer used for the rendering purpose

saveState (line 1475)

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.

- access: public

void saveState ()

Redefined in descendants as:

- TPage::saveState() : This method is invoked when control state is to be saved.
- TDataGrid::saveState() : Saves item count in viewstate.
- TDataList::saveState() : Saves item count in viewstate.
- TListControl::saveState() : Saves items into viewstate.
- TRepeater::saveState() : Saves item count in viewstate.
- TWizard::saveState() : Saves the current active step index into history.

saveStateRecursive (line 1546)

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

- return: the collection of the control state (including its children's state).
- access: protected

array &saveStateRecursive ([boolean $needViewState = true])

- boolean $needViewState: whether the viewstate should be saved

setAdapter (line 218)

- access: public

void setAdapter (TControlAdapter $adapter)

- TControlAdapter $adapter: control adapter

setAttribute (line 597)

Sets a custom control attribute.

- access: public

void setAttribute (string $name, string $value)

- string $name: attribute name
- string $value: value of the attribute

setChildControlsCreated (line 824)

Sets a value indicating whether child controls are created.

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

- access: protected

void setChildControlsCreated (boolean $value)

- boolean $value: whether child controls are created

setControlStage (line 326)

Sets the lifecycle step the control is currently at.

This method should only be used by control developers.

- access: protected

void setControlStage (integer $value)

- 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.

setControlState (line 666)

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.

- access: protected

void setControlState (string $key, mixed $value, [mixed $defaultValue = null])

- 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

setEnabled (line 536)

- access: public

void setEnabled (boolean $value)

- boolean $value: whether the control is to be enabled.

Redefined in descendants as:

- TBaseValidator::setEnabled() : This method overrides parent's implementation by setting setIsValid to true if disabled.

setEnableTheming (line 444)

- access: public
- throws: TInvalidOperationException if this method is invoked after OnPreInit

void setEnableTheming (boolean $value)

- boolean $value: whether to enable theming

Redefined in descendants as:

- TDataSourceControl::setEnableTheming()
- THiddenField::setEnableTheming()

setEnableViewState (line 634)

- access: public

void setEnableViewState (boolean $value)

- boolean $value: set whether to enable viewstate

setID (line 350)

- access: public
- throws: TInvalidDataValueException if ID is in a bad format

void setID (string $id)

- string $id: the new control ID. The value must consist of word characters [a-zA-Z0-9_] only

setPage (line 266)

Sets the page for a control.

Only framework developers should use this method.

- access: public

void setPage (TPage $page)

- TPage $page: the page that contains this control

setSkinID (line 420)

- access: public
- throws: TInvalidOperationException if the SkinID is set in a stage later than PreInit, or if the skin is applied already.

void setSkinID (string $value)

- string $value: the skin ID of this control

Redefined in descendants as:

- TDataSourceControl::setSkinID()
- THiddenField::setSkinID()

setTemplateControl (line 276)

Sets the control whose template contains this control.

Only framework developers should use this method.

- access: public

void setTemplateControl (TTemplateControl $control)

- TTemplateControl $control: the control whose template contains this control

setViewState (line 707)

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.

- access: public

void setViewState (string $key, mixed $value, [mixed $defaultValue = null])

- 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.

setVisible (line 505)

- access: public

void setVisible (boolean $value)

- boolean $value: whether the control is visible

Redefined in descendants as:

- TDataSourceControl::setVisible()
- TView::setVisible()

traverseChildControls (line 1402)

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.

- access: protected

void traverseChildControls (mixed $param, [callback $preCallback = null], [callback $postCallback = null])

- 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.

unbindProperty (line 739)

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

- access: public

void unbindProperty (string $name)

- string $name: the property name (or property path)

unloadRecursive (line 1243)

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

Only framework developers should use this method.

- access: protected

void unloadRecursive ()
unregisterObject (line 987)

Unregisters an object by name.

- access: public
- see: TControl::registerObject()

void unregisterObject (string $name)

- string $name: name of the object

__get (line 191)

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.

- return: the property value or the target control
- access: public
- see: TControl::registerObject()
- throws: TInvalidOperationException if the property is not defined.

mixed __get (string $name)

- string $name: the property name or control ID

Redefinition of:

TComponent::__get()
  Returns a property value or an event handler list by property or event name.

#### Inherited Methods

Inherited From TApplicationComponent

> TApplicationComponent::getApplication()
> TApplicationComponent::getRequest()
> TApplicationComponent::getResponse()
> TApplicationComponent::getService()
> TApplicationComponent::getSession()
> TApplicationComponent::getUser()
> TApplicationComponent::publishAsset()
> TApplicationComponent::publishFilePath()

Inherited From TComponent

> TComponent::attachEventHandler()
> TComponent::canGetProperty()
> TComponent::canSetProperty()
> TComponent::detachEventHandler()
> TComponent::evaluateExpression()
> TComponent::evaluateStatements()
> TComponent::getEventHandlers()
> TComponent::getSubProperty()
> TComponent::hasEvent()
> TComponent::hasEventHandler()
> TComponent::hasProperty()
> TComponent::raiseEvent()
> TComponent::setSubProperty()
> TComponent::__get()
> TComponent::__set()

Class Constants
AUTOMATIC_ID_PREFIX = 'ctl' (line 88)

prefix to an ID automatically generated

CLIENT_ID_SEPARATOR = '_' (line 84)

separator char between IDs in a ClientID

CS_CHILD_INITIALIZED = 1 (line 94)
CS_CONSTRUCTED = 0 (line 93)

the stage of lifecycles that the control is currently at

CS_INITIALIZED = 2 (line 95)
CS_LOADED = 4 (line 97)
CS_PRERENDERED = 5 (line 98)
CS_STATE_LOADED = 3 (line 96)
ID_FORMAT = '/^[a-zA-Z_]\\w*$/' (line 76)

format of control ID

ID_SEPARATOR = '$' (line 80)

separator char between IDs in a UniqueID

IS_CHILD_CREATED = 0x20 (line 108)
IS_CREATING_CHILD = 0x40 (line 109)
IS_DISABLE_THEMING = 0x10 (line 107)
IS_DISABLE_VIEWSTATE = 0x02 (line 104)
IS_ID_SET = 0x01 (line 103)

State bits.

IS_SKIN_APPLIED = 0x04 (line 105)
IS_STYLESHEET_APPLIED = 0x08 (line 106)
RF_ADAPTER = 9 (line 124)
RF_AUTO_BINDINGS = 10 (line 125)
RF_CHILD_STATE = 1 (line 116)
RF_CONTROLS = 0 (line 115)

Indexes for the rare fields.

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

RF_CONTROLSTATE = 7 (line 122)
RF_DATA_BINDINGS = 5 (line 120)
RF_EVENTS = 6 (line 121)
RF_NAMED_CONTROLS = 2 (line 117)
RF_NAMED_CONTROLS_ID = 3 (line 118)
RF_NAMED_OBJECTS = 8 (line 123)
RF_SKIN_ID = 4 (line 119)

Documentation generated on Sun, 04 Jun 2006 18:58:55 -0400 by phpDocumentor 1.3.0RC4