Class TControl
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 TControl::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 getParent Parent property, and its getControls
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 TControl::render()
method (the method is invoked
by the framework.) Descendant control classes may override this method for
customized rendering. By default, TControl::render()
invokes TControl::renderChildren()
which is responsible for rendering of children of the control.
Control's getVisible 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.
- TComponent
-
TApplicationComponent
-
TControl implements IRenderable, IBindable
Direct known subclasses
TCallback, TCallbackOptions, TForm, THead, THiddenField, TI18NControl, TLiteral, TMultiView, TOutputCache, TPlaceHolder, TRepeaterItem, TSafeHtml, TClientScript, TStatements, TStyleSheet, TTranslateParameter, TView, TWebControl, TWizardNavigationContainer, TXmlTransform, TCompositeControl, TConditional, TContent, TContentPlaceHolder, TDataSourceControl, TExpression, TFlushOutputIndirect known subclasses
TAccordion, TAccordionView, TActiveDatePicker, TRequiredFieldValidator, TScaffoldBase, TScaffoldEditView, TScaffoldListView, TScaffoldSearch, TScaffoldView, TSlider, TTable, TTableCell, TTableFooterRow, TActiveDropDownList, TTableHeaderCell, TTableHeaderRow, TTableRow, TTabPanel, TTabView, TTemplateControl, TTemplateControlInheritable, TTemplatedWizardStep, TTextBox, TTextHighlighter, TActiveFileUpload, TTextProcessor, TTimeTriggeredCallback, TTranslate, TTriggeredCallback, TValidationSummary, TValueTriggeredCallback, TWizard, TWizardStep, TWsatGenerateAR, TWsatHome, TActiveHiddenField, TWsatLayout, TWsatLogin, TWsatScaffolding, TActiveHyperLink, TActiveImage, TActiveImageButton, TActiveLabel, TActiveLinkButton, TActiveListBox, TActiveButton, TActiveMultiView, TActivePager, TActivePanel, TActiveRadioButton, TActiveRadioButtonList, TActiveRatingList, TActiveRepeater, TActiveTableCell, TActiveTableRow, TActiveTextBox, TActiveCheckBox, TAutoComplete, TBaseDataList, TBaseValidator, TBulletedList, TButton, TCaptcha, TCaptchaValidator, TCheckBox, TCheckBoxList, TChoiceFormat, TActiveCheckBoxList, TColorPicker, TCompareValidator, TCompleteWizardStep, TCustomValidator, TDataBoundControl, TDataGrid, TDataGridItem, TDataGridItemRenderer, TDataGridPager, TDataList, TActiveClientScript, TDataListItem, TDataListItemRenderer, TDataRenderer, TDataTypeValidator, TDateFormat, TDatePicker, TDraggable, TDropContainer, TDropDownList, TEmailAddressValidator, TActiveCustomValidator, TEventTriggeredCallback, TFileUpload, THeader1, THeader2, THeader3, THeader4, THeader5, THeader6, THtmlArea, THtmlArea4, TActiveDataGrid, THtmlElement, THyperLink, TImage, TImageButton, TImageMap, TInlineFrame, TInPlaceTextBox, TItemDataRenderer, TJavascriptLogger, TKeyboard, TActiveDataGridPager, TLabel, TLinkButton, TListBox, TListControl, TListControlValidator, TMarkdown, TNumberFormat, TPage, TPager, TPanel, TActiveDataList, TRadioButton, TRadioButtonList, TRangeValidator, TRatingList, TReadOnlyDataSource, TReCaptcha, TReCaptchaValidator, TRegularExpressionValidator, TRepeater, TRepeaterItemRendererCopyright: Copyright © 2005-2014 PradoSoft
License: http://www.pradosoft.com/license/
Author: Qiang Xue <qiang.xue@gmail.com>
Since: 3.0
Located at Web/UI/TControl.php
public
|
|
public
mixed
|
#
__get( string $name )
Returns a property value by name or a control by ID. This overrides the parent implementation by allowing accessing a control via its ID using the following syntax, $menuBar=$this->menuBar; Note, the control must be configured in the template with explicit ID. If the name matches both a property and a control ID, the control ID will take the precedence. |
public
boolean
|
|
public
|
|
public
|
|
public
|
|
public
|
|
public
|
|
public
|
|
public
|
#
setTemplateControl(
Sets the control whose template contains this control. Only framework developers should use this method. |
public
|
|
public
|
|
protected
integer
|
#
getControlStage( )
Gets the lifecycle step the control is currently at. This method should only be used by control developers. |
protected
|
#
setControlStage( integer $value )
Sets the lifecycle step the control is currently at. This method should only be used by control developers. |
public
string
|
#
getID( boolean $hideAutoID = true )
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. |
public
|
|
public
string
|
#
getUniqueID( )
Returns a unique ID that identifies the control in the page hierarchy. A unique ID is the contenation of all naming container controls' IDs and the control ID. These IDs are separated by '$' character. Control users should not rely on the specific format of UniqueID, however. |
public
|
|
public
string
|
#
getClientID( )
Returns the client ID of the control. The client ID can be used to uniquely identify the control in client-side scripts (such as JavaScript). Do not rely on the explicit format of the return ID. |
public static
string
|
|
public
string
|
|
public
|
|
public
|
|
public
boolean
|
|
public
|
|
public
mixed
|
#
getCustomData( )
Returns custom data associated with this control. A control may be associated with some custom data for various purposes. For example, a button may be associated with a string to identify itself in a generic OnClick event handler. |
public
|
#
setCustomData( mixed $value )
Associates custom data with this control. Note, the custom data must be serializable and unserializable. |
public
boolean
|
|
public
|
|
protected
|
#
createControlCollection( )
Creates a control collection object that is to be used to hold child controls |
public
boolean
|
#
getVisible( boolean $checkParents = true )
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. |
public
|
|
public
boolean
|
#
getEnabled( boolean $checkParents = false )
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 |
public
|
|
public
boolean
|
|
public
|
#
getAttributes( )
Returns the list of custom attributes. Custom attributes are name-value pairs that may be rendered as HTML tags' attributes. |
public
boolean
|
|
public
string
|
|
public
|
|
public
string
|
|
public
boolean
|
|
public
|
|
protected
mixed
|
|
protected
|
#
setControlState( string $key, mixed $value, mixed $defaultValue = null )
Sets a controlstate value. |
protected
|
|
public
|
#
trackViewState( boolean $enabled )
Sets a value indicating whether we should keep data in viewstate. When it is false, data saved via setViewState() will not be persisted. By default, it is true, meaning data will be persisted across postbacks. |
public
mixed
|
|
public
|
|
public
|
|
public
|
#
bindProperty( string $name, string $expression )
Sets up the binding between a property (or property path) and an expression. The context of the expression is the template control (or the control itself if it is a page). |
public
|
#
unbindProperty( string $name )
Breaks the binding between a property (or property path) and an expression. |
public
|
#
autoBindProperty( string $name, string $expression )
Sets up the binding between a property (or property path) and an expression. Unlike regular databinding, the expression bound by this method is automatically evaluated during prerenderRecursive(). The context of the expression is the template control (or the control itself if it is a page). |
public
|
|
protected
|
|
protected
|
|
protected
|
|
final protected
boolean
|
|
final protected
|
#
setChildControlsCreated( boolean $value )
Sets a value indicating whether child controls are created. If false, any existing child controls will be cleared up. |
public
|
#
ensureChildControls( )
Ensures child controls are created. If child controls are not created yet,
this method will invoke |
public
|
#
createChildControls( )
Creates child controls. This method can be overriden for controls who want to
have their controls. Do not call this method directly. Instead, call |
public
|
#
findControl( string $id )
Finds a control by ID path within the current naming container. The current
naming container is either the control itself if it implements |
public
array
|
#
findControlsByType( string $type, boolean $strict = true )
Finds all child and grand-child controls that are of the specified type. |
public
array
|
#
findControlsByID( string $id )
Finds all child and grand-child controls with the specified ID. Note, this
method is different from |
public
|
#
clearNamingContainer( )
Resets the control as a naming container. Only framework developers should use this method. |
public
|
#
registerObject( string $name, object $object )
Registers an object by a name. A registered object can be accessed like a public member variable. This method should only be used by framework and control developers. |
public
|
|
public
boolean
|
|
public
boolean
|
|
public
boolean
|
|
public
boolean
|
|
public
boolean
|
|
public
boolean
|
|
public
mixed
|
#
getRegisteredObject( mixed $name )
Returns the named registered object. A component with explicit ID on a template will be registered to the template owner. This method allows you to obtain this component with the ID. |
public
boolean
|
|
public
|
#
addParsedObject( string|
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. |
final protected
|
#
clearChildState( )
Clears up the child state data. After a control loads its state, those state that do not belong to any existing child controls are stored as child state. This method will remove these state. Only frameworker developers and control developers should use this method. |
final protected
boolean
|
|
public
|
|
public
|
|
protected
|
|
protected
|
#
loadRecursive( )
Performs the Load step for the control and all its child controls. Only framework developers should use this method. |
protected
|
#
preRenderRecursive( )
Performs the PreRender step for the control and all its child controls. Only framework developers should use this method. |
protected
|
|
protected
|
#
unloadRecursive( )
Performs the Unload step for the control and all its child controls. Only framework developers should use this method. |
public
|
#
onInit(
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. |
public
|
#
onLoad(
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. |
public
|
#
onDataBinding(
Raises 'OnDataBinding' event. This method is invoked when |
public
|
#
onUnload(
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. |
public
|
#
onPreRender(
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. |
protected
|
#
raiseBubbleEvent(
Invokes the parent's bubbleEvent method. A control who wants to bubble an event must call this method in its onEvent method. |
public
boolean
|
#
bubbleEvent(
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. |
public
|
#
broadcastEvent( string $name,
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 |
protected
|
#
traverseChildControls( mixed $param, callable $preCallback = null, callable $postCallback = null )
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. |
public
|
#
renderControl(
Renders the control. Only when the control is visible will the control be rendered. |
public
|
#
render(
Renders the control. This method is invoked by |
public
|
#
renderChildren(
Renders the children of the control. This method iterates through all child controls and static text strings and renders them in order. |
public
|
#
saveState( )
This method is invoked when control state is to be saved. You can override this method to do last step state saving. Parent implementation must be invoked. |
public
|
#
loadState( )
This method is invoked right after the control has loaded its state. You can override this method to initialize data from the control state. Parent implementation must be invoked. |
protected
|
#
loadStateRecursive( array & $state, boolean $needViewState = true )
Loads state (viewstate and controlstate) into a control and its children. This method should only be used by framework developers. |
protected
array
&
|
#
saveStateRecursive( boolean $needViewState = true )
Saves all control state (viewstate and controlstate) as a collection. This method should only be used by framework developers. |
public
|
getApplication(),
getRequest(),
getResponse(),
getService(),
getSession(),
getUser(),
publishAsset(),
publishFilePath()
|
string |
ID_FORMAT |
'/^[a-zA-Z_]\\w*$/' |
#
format of control ID |
string |
ID_SEPARATOR |
'$' |
#
separator char between IDs in a UniqueID |
string |
CLIENT_ID_SEPARATOR |
'_' |
#
separator char between IDs in a ClientID |
string |
AUTOMATIC_ID_PREFIX |
'ctl' |
#
prefix to an ID automatically generated |
integer |
CS_CONSTRUCTED |
0 |
#
the stage of lifecycles that the control is currently at |
integer |
CS_CHILD_INITIALIZED |
1 |
|
integer |
CS_INITIALIZED |
2 |
|
integer |
CS_STATE_LOADED |
3 |
|
integer |
CS_LOADED |
4 |
|
integer |
CS_PRERENDERED |
5 |
|
integer |
IS_ID_SET |
0x01 |
#
State bits. |
integer |
IS_DISABLE_VIEWSTATE |
0x02 |
|
integer |
IS_SKIN_APPLIED |
0x04 |
|
integer |
IS_STYLESHEET_APPLIED |
0x08 |
|
integer |
IS_DISABLE_THEMING |
0x10 |
|
integer |
IS_CHILD_CREATED |
0x20 |
|
integer |
IS_CREATING_CHILD |
0x40 |
|
integer |
RF_CONTROLS |
0 |
#
Indexes for the rare fields. In order to save memory, rare fields will only be created if they are needed. |
integer |
RF_CHILD_STATE |
1 |
|
integer |
RF_NAMED_CONTROLS |
2 |
|
integer |
RF_NAMED_CONTROLS_ID |
3 |
|
integer |
RF_SKIN_ID |
4 |
|
integer |
RF_DATA_BINDINGS |
5 |
|
integer |
RF_EVENTS |
6 |
|
integer |
RF_CONTROLSTATE |
7 |
|
integer |
RF_NAMED_OBJECTS |
8 |
|
integer |
RF_ADAPTER |
9 |
|
integer |
RF_AUTO_BINDINGS |
10 |
GLOBAL_RAISE_EVENT_LISTENER
|