## 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: $Id: TControl.php 2122 2007-08-16 11:46:47Z xue $
- 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.
TCallback | TCallback component class.
TCallbackOptions | TCallbackOptions class.
TCompositeControl | TCompositeControl class.
TForm | TForm class
TClientScript | TClientScript class
TConditional | TConditional 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
TOutputCache | TOutputCache class.
TPlaceHolder | TPlaceHolder class
TRepeaterItem | TRepeaterItem class
TSafeHtml | TSafeHtml class
TStatements | TStatements class
TStyleSheet | TStyleSheet class.
TWebControl | TWebControl class
TWizardNavigationContainer | TWizardNavigationContainer class.
TXmlTransform | TXmlTransform 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 addToPostDataLoader ()
void applyStyleSheetSkin (TPage $page)
void autoBindProperty (string $name, string $expression)
void autoDataBindProperties ()
void bindProperty (string $name, string $expression)
void broadcastEvent (string $name, TControl $sender, TEventParameter $param)
boolean bubbleEvent (TControl $sender, TEventParameter $param)
void clearChildState ()
void clearControlState (string $key)
void clearNamingContainer ()
void clearViewState (string $key)
string convertUniqueIdToClientId (string $uniqueID)
void createChildControls ()
TControlCollection createControlCollection ()
void dataBind ()
void dataBindChildren ()
void dataBindProperties ()
void ensureChildControls ()
TControl|null findControl (string $id)
array findControlsByID (string $id)
array findControlsByType (string $type, [boolean $strict = true])
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])
mixed getCustomData ()
boolean getEnabled ([boolean $checkParents = false])
boolean getEnableTheming ()
boolean getEnableViewState ([mixed $checkParents = false])
boolean getHasAdapter ()
boolean getHasAttributes ()
boolean getHasChildInitialized ()
boolean getHasControls ()
boolean getHasInitialized ()
boolean getHasLoaded ()
boolean getHasLoadedPostData ()
boolean getHasPreRendered ()
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 (array &$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 setCustomData (mixed $value)
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 trackViewState (boolean $enabled)
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 179)

Constructor.

- access: public

TControl __construct ()

Redefined in descendants as:

- TCallback::__construct() : Creates a new callback control, sets the adapter to TActiveControlAdapter. If you override this class, be sure to set the adapter appropriately by, for example, call this constructor.
- TPage::__construct() : Constructor.
- TReadOnlyDataSource::__construct()
- TActiveHiddenField::__construct() : Creates a new callback control, sets the adapter to TActiveControlAdapter. If you override this class, be sure to set the adapter appropriately by, for example, by calling this constructor.
- TActiveButton::__construct() : Creates a new callback control, sets the adapter to TActiveControlAdapter. If you override this class, be sure to set the adapter appropriately by, for example, by calling this constructor.
- TActiveCheckBox::__construct() : Creates a new callback control, sets the adapter to TActiveControlAdapter. If you override this class, be sure to set the adapter appropriately by, for example, by calling this constructor.
- TRadioButton::__construct() : Constructor.
- TActiveRadioButton::__construct() : Creates a new callback control, sets the adapter to TActiveControlAdapter. If you override this class, be sure to set the adapter appropriately by, for example, by calling this constructor.
- TCheckBoxList::__construct() : Constructor.
- TActiveCheckBoxList::__construct() : Creates a new callback control, sets the adapter to TActiveListControlAdapter. If you override this class, be sure to set the adapter appropriately by, for example, by calling this constructor.
- TActiveRadioButtonList::__construct() : Creates a new callback control, sets the adapter to TActiveListControlAdapter. If you override this class, be sure to set the adapter appropriately by, for example, by calling this constructor.
- TActiveRatingList::__construct() : Sets the default repeat direction to horizontal.
- TRatingList::__construct()
- TActiveDropDownList::__construct() : Creates a new callback control, sets the adapter to TActiveListControlAdapter. If you override this class, be sure to set the adapter appropriately by, for example, by calling this constructor.
- TActiveListBox::__construct() : Creates a new callback control, sets the adapter to TActiveListControlAdapter. If you override this class, be sure to set the adapter appropriately by, for example, by calling this constructor.
- TActiveHyperLink::__construct() : Creates a new callback control, sets the adapter to TActiveControlAdapter. If you override this class, be sure to set the adapter appropriately by, for example, by calling this constructor.
- TActiveImage::__construct() : Creates a new callback control, sets the adapter to TActiveControlAdapter. If you override this class, be sure to set the adapter appropriately by, for example, by calling this constructor.
- TActiveImageButton::__construct() : Creates a new callback control, sets the adapter to TActiveControlAdapter. If you override this class, be sure to set the adapter appropriately by, for example, by calling this constructor.
- TActiveLabel::__construct() : Creates a new callback control, sets the adapter to TActiveControlAdapter. If you override this class, be sure to set the adapter appropriately by, for example, by calling this constructor.
- TBaseValidator::__construct() : Constructor.
- TActiveCustomValidator::__construct() : Creates a new callback control, sets the adapter to TActiveControlAdapter. If you override this class, be sure to set the adapter appropriately by, for example, by calling this constructor.
- TActiveLinkButton::__construct() : Creates a new callback control, sets the adapter to TActiveControlAdapter. If you override this class, be sure to set the adapter appropriately by, for example, by calling this constructor.
- TActivePanel::__construct() : Creates a new callback control, sets the adapter to TActiveControlAdapter. If you override this class, be sure to set the adapter appropriately by, for example, by calling this constructor.
- TDataGridPager::__construct() : Constructor.
- TDataGridItem::__construct() : Constructor.
- TActiveTextBox::__construct() : Creates a new callback control, sets the adapter to TActiveControlAdapter. If you override this class, be sure to set the adapter appropriately by, for example, by calling this constructor.
- TInPlaceTextBox::__construct() : Sets the auto post back to true by default.
- THtmlArea::__construct() : Constructor.
- TValidationSummary::__construct() : Constructor.
- TXmlTransform::__construct() : Constructor

addedControl (line 1172)

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

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.

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

void addParsedObject (string|TComponent $object)

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

Redefinition of:

TComponent::addParsedObject()
  Processes an object that is created during parsing template.

Redefined in descendants as:

- TConditional::addParsedObject() : Processes an object that is created during parsing template.
- THead::addParsedObject() : Processes an object that is created during parsing template.
- TMultiView::addParsedObject() : Processes an object that is created during parsing template.
- TDataGrid::addParsedObject() : Adds objects parsed in template to datagrid.
- TListControl::addParsedObject() : Adds object parsed from template to the control.
- 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.
- TTabPanel::addParsedObject() : Adds object parsed from template to the control.
- TTextProcessor::addParsedObject() : HTML-decodes static text.
- TWizard::addParsedObject() : Adds TWizardStep objects into step collection.

addToPostDataLoader (line 1332)

Add controls implementing IPostBackDataHandler to post data loaders.

- access: protected

void addToPostDataLoader ()

Redefined in descendants as:

- TRadioButton::addToPostDataLoader() : Add the group name as post data loader if group name is set.

applyStyleSheetSkin (line 1683)

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

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

Auto databinding properties of the control.

- access: protected

void autoDataBindProperties ()
bindProperty (line 798)

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

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.

- access: public

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

- string $name: name of the broadcast event
- TControl $sender: sender of this event
- TEventParameter $param: event parameter

bubbleEvent (line 1444)

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:

- TScaffoldEditView::bubbleEvent() : Bubble the command name event. Stops bubbling when the page validator false.
- TScaffoldListView::bubbleEvent() : Continue bubbling the "edit" command, "delete" command is handled in this class.
- TScaffoldSearch::bubbleEvent() : Sets the SearchCondition of the TScaffoldListView as the search terms given by the text of the search text box.
- TScaffoldView::bubbleEvent() : Handle the "edit" and "new" commands by displaying the edit view.
- TDataListItemRenderer::bubbleEvent() : This method overrides parent's implementation by wrapping event parameter for OnCommand event with item information.
- TRepeaterItemRenderer::bubbleEvent() : This method overrides parent's implementation by wrapping event parameter for OnCommand event with item information.
- TMultiView::bubbleEvent() : Processes the events bubbled from child controls.
- TRepeaterItem::bubbleEvent() : This method overrides parent's implementation by wrapping event parameter for OnCommand 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 datalist items and their child controls.
- TRepeater::bubbleEvent() : This method overrides parent's implementation to handle onItemCommand event which is bubbled from repeater items and their child controls.
- TDataListItem::bubbleEvent() : This method overrides parent's implementation by wrapping event parameter for OnCommand event with item information.
- TPager::bubbleEvent() : Processes a bubbled event.
- 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 1148)

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

Clears a controlstate value.

- access: protected

void clearControlState (string $key)

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

clearNamingContainer (line 1029)

Resets the control as a naming container.

Only framework developers should use this method.

- access: public

void clearNamingContainer ()
clearViewState (line 786)

Clears a viewstate value.

- access: public

void clearViewState (string $key)

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

convertUniqueIdToClientId (line 422)

Converts a unique ID to a client ID.

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

string convertUniqueIdToClientId (string $uniqueID)

- string $uniqueID: the unique ID of a control

createChildControls (line 937)

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.
- TConditional::createChildControls() : Creates child controls.
- TTemplatedWizardStep::createChildControls() : Creates child controls.
- TWizard::createChildControls() : Creates child controls within the wizard

createControlCollection (line 518)

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
- TTabPanel::createControlCollection() : Creates a control collection object that is to be used to hold child controls

dataBind (line 828)

Performs the databinding for this control.

- access: public

void dataBind ()

Redefined in descendants as:

- TDataBoundControl::dataBind() : Performs databinding.
- TAutoComplete::dataBind() : Overrides parent implementation. Callback renderSuggestions() when page's IsCallback property is true.

dataBindChildren (line 867)

Databinding child controls.

- access: protected

void dataBindChildren ()
dataBindProperties (line 838)

Databinding properties of the control.

- access: protected

void dataBindProperties ()
ensureChildControls (line 908)

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

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

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

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

- return: list of controls found
- access: public

array findControlsByType (string $type, [boolean $strict = true])

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

focus (line 400)

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

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

TControlAdapter getAdapter ()
getAllowChildControls (line 1124)

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

boolean getAllowChildControls ()

Redefined in descendants as:

- TOutputCache::getAllowChildControls() : Returns a value indicating whether body contents are allowed for this control.

getAttribute (line 625)

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

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

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

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

boolean getChildControlsCreated ()
getClientID (line 412)

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

- return: the child control collection
- access: public

TControlCollection getControls ()
getControlStage (line 322)

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

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

getCustomData (line 480)

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.

- return: custom data associated with this control. Defaults to null.
- access: public

mixed getCustomData ()
getEnabled (line 561)

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

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

- return: whether viewstate is enabled
- access: public

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

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

boolean getHasAdapter ()
getHasAttributes (line 585)

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

boolean getHasAttributes ()
getHasChildInitialized (line 1072)

- return: true if the child control has been initialized.
- access: public

boolean getHasChildInitialized ()
getHasControls (line 498)

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

boolean getHasControls ()
getHasInitialized (line 1080)

- return: true if the onInit event has raised.
- access: public

boolean getHasInitialized ()
getHasLoaded (line 1096)

- return: true if the onLoad event has raised.
- access: public

boolean getHasLoaded ()
getHasLoadedPostData (line 1088)

- return: true if the control has loaded post data.
- access: public

boolean getHasLoadedPostData ()
getHasPreRendered (line 1104)

- return: true if onPreRender event has raised.
- access: public

boolean getHasPreRendered ()
getID (line 346)

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

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

TControl getNamingContainer ()
getPage (line 257)

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

TPage getPage ()
getParent (line 234)

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

TControl getParent ()
getRegisteredObject (line 1116)

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

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

string getSkinID ()

Redefined in descendants as:

- TDataSourceControl::getSkinID()

getSourceTemplateControl (line 304)

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

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

TTemplateControl getTemplateControl ()
getUniqueID (line 376)

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

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

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

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

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

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.
- TOutputCache::initRecursive() : Performs the Init step for the control and all its child controls.

isDescendentOf (line 1158)

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

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

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

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

Only framework developers should use this method.

- access: protected

void loadRecursive ()

Redefined in descendants as:

- TOutputCache::loadRecursive() : Performs the Load step for the control and all its child controls.

loadState (line 1593)

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.
- TPager::loadState() : Restores the pager state.

loadStateRecursive (line 1603)

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

This method should only be used by framework developers.

- access: protected

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

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

Redefined in descendants as:

- TOutputCache::loadStateRecursive() : Loads state (viewstate and controlstate) into a control and its children.

onDataBinding (line 1387)

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

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.
- TRadioButton::onInit() : Registers the radio button groupings. If overriding onInit method, ensure to call parent implemenation.
- 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 1377)

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

Redefined in descendants as:

- TScaffoldEditView::onLoad() : Initialize the editor form if it is Visible.

onPreRender (line 1413)

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:

- TScaffoldBase::onPreRender() : Publish the default stylesheet file.
- TScaffoldListView::onPreRender() : Loads and display the data.
- TScaffoldView::onPreRender() : Copy basic record details to the list/edit/search controls.
- TClientScript::onPreRender() : Calls the client script manager to add each of the requested client script libraries.
- TStyleSheet::onPreRender() : Registers the stylesheet file and content to be rendered.
- 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.
- TActiveRatingList::onPreRender() : Publish the the rating style css file and rating image files.
- TRatingList::onPreRender()
- TActiveDropDownList::onPreRender() : Updates the client-side options if the item list has changed after the OnLoad event.
- TListBox::onPreRender() : Registers the list control to load post data on postback.
- TActiveListBox::onPreRender() : Updates the client-side options if the item list has changed after the OnLoad event.
- TFileUpload::onPreRender() : Sets Enctype of the form on the page.
- TCaptcha::onPreRender() : Configures the image URL that shows the token.
- TImageButton::onPreRender() : Registers the image button to receive postback data during postback.
- TActiveImageButton::onPreRender() : Register the x and y hidden input names of the position clicked.
- TJavascriptLogger::onPreRender() : Registers the required logger javascript.
- TKeyboard::onPreRender() : Registers CSS and JS.
- TPager::onPreRender() : Performs databinding to populate data items from data source.
- TSlider::onPreRender() : Registers CSS and JS.
- TTabPanel::onPreRender() : Registers CSS and JS.
- 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 1401)

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

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

Only framework developers should use this method.

- access: protected

void preRenderRecursive ()

Redefined in descendants as:

- TOutputCache::preRenderRecursive() : Performs the PreRender step for the control and all its child controls.

raiseBubbleEvent (line 1425)

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

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

Redefined in descendants as:

- TConditional::registerObject() : Registers an object defined in the template.

removeAttribute (line 648)

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

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

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.
- TTimeTriggeredCallback::render() : Registers the javascript code for initializing the active control.
- TEventTriggeredCallback::render() : Registers the javascript code for initializing the active control.
- TValueTriggeredCallback::render() : Registers the javascript code for initializing the active control.
- TDataListItemRenderer::render() : Renders the control.
- TForm::render() : Renders the form.
- TClientScript::render() : Renders the body content as javascript block.
- 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.
- TOutputCache::render() : Renders the output cache control.
- TSafeHtml::render() : Renders body content.
- TStatements::render() : Renders the evaluation result of the statements.
- TStyleSheet::render() : Renders the control.
- 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.
- TActiveRatingList::render() : Add rating style class name to the class attribute when setReadOnly property is true and when the setCssClass property is empty.
- TRepeater::render() : Renders the repeater.
- TImageMap::render() : Renders this imagemap.
- TLabel::render() : Renders the label.
- TPager::render() : Renders the control.
- TActivePanel::render() : Renders and replaces the panel's content on the client-side.
- TDatePicker::render() : Renders body content.
- TWizard::render() : Renders the wizard.
- TXmlTransform::render() : Performs XSL transformation and render the output.

renderChildren (line 1563)

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

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

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

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

This method should only be used by framework developers.

- 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

Redefined in descendants as:

- TOutputCache::saveStateRecursive() : Saves all control state (viewstate and controlstate) as a collection.

setAdapter (line 226)

- access: public

void setAdapter (TControlAdapter $adapter)

- TControlAdapter $adapter: control adapter

setAttribute (line 638)

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

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

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

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

setCustomData (line 490)

Associates custom data with this control.

Note, the custom data must be serializable and unserializable.

- access: public

void setCustomData (mixed $value)

- mixed $value: custom data

setEnabled (line 577)

- access: public

void setEnabled (boolean $value)

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

Redefined in descendants as:

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

setEnableTheming (line 463)

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

- access: public

void setEnableViewState (boolean $value)

- boolean $value: set whether to enable viewstate

setID (line 358)

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

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

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

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

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

- access: public

void setVisible (boolean $value)

- boolean $value: whether the control is visible

Redefined in descendants as:

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

trackViewState (line 730)

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.

- access: public

void trackViewState (boolean $enabled)

- boolean $enabled: whether data should be persisted

traverseChildControls (line 1511)

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

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

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

Unregisters an object by name.

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

void unregisterObject (string $name)

- string $name: name of the object

__get (line 199)

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

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, 30 Sep 2007 19:15:09 -0400 by phpDocumentor 1.3.0RC4