Class TControl

Description

Implements interfaces:

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 2434 2008-04-18 09:47:05Z mikl $
  • 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
Method Summary
TControl __construct ()
void addedControl (TControl $control)
void addParsedObject (string|TComponent $object)
void applyStyleSheetSkin (TPage $page)
void autoBindProperty (string $name, string $expression)
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 clearViewState (string $key)
string convertUniqueIdToClientId (string $uniqueID)
void dataBind ()
TControl|null findControl (string $id)
array findControlsByID (string $id)
array findControlsByType (string $type, [boolean $strict = true])
void focus ()
string getAttribute (mixed $name)
string getClientID ()
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 getHasControls ()
boolean getHasInitialized ()
boolean getHasLoaded ()
boolean getHasPreRendered ()
string getID ([boolean $hideAutoID = true])
mixed getRegisteredObject (mixed $name)
string getSkinID ()
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 onInit (TEventParameter $param)
void onLoad (TEventParameter $param)
void onPreRender (TEventParameter $param)
void onUnload (TEventParameter $param)
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 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.
  • TActivePager::__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.

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:
addToPostDataLoader (line 1332)

Add controls implementing IPostBackDataHandler to post data loaders.

  • access: protected
void addToPostDataLoader ()

Redefined in descendants as:
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.

boolean bubbleEvent (TControl $sender, TEventParameter $param)

Redefined in descendants as:
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:
createControlCollection (line 518)

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

TControlCollection createControlCollection ()

Redefined in descendants as:
dataBind (line 828)

Performs the databinding for this control.

  • access: public
void dataBind ()

Redefined in descendants as:
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:
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:
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:
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:
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:
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:
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:
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)
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:
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:
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:
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:
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:
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:
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:
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:
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.

void raiseBubbleEvent (TControl $sender, TEventParameter $param)
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.

void registerObject (string $name, object object $object)
  • string $name: name of the object
  • object object $object: to be declared
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:
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:
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:
setAdapter (line 226)
  • access: public
void setAdapter (TControlAdapter $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:
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:
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:
setTemplateControl (line 284)

Sets the control whose template contains this control.

Only framework developers should use this method.

  • access: public
void setTemplateControl (TTemplateControl $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:
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:

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

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

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,

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

  • 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 Mon, 21 Apr 2008 11:34:08 -0400 by phpDocumentor 1.3.0RC4