## Class TComponent

Description

TComponent class

TComponent is the base class for all PRADO components. TComponent implements the protocol of defining, using properties and events.

A property is defined by a getter method, and/or a setter method. Properties can be accessed in the way like accessing normal object members. Reading or writing a property will cause the invocation of the corresponding getter or setter method, e.g.,

     $a=$this->Text;     // equivalent to $a=$this->getText();
      $this->Text='abc';  // equivalent to $this->setText('abc');

The signatures of getter and setter methods are as follows,

     // getter, defines a readable property 'Text'
      function getText() { ... }
     // setter, defines a writable property 'Text', with $value being the value to be set to the property
      function setText($value) { ... }

Property names are case-insensitive. It is recommended that they are written in the format of concatenated words, with the first letter of each word capitalized (e.g. DisplayMode, ItemStyle).

An event is defined by the presence of a method whose name starts with 'on'. The event name is the method name and is thus case-insensitive. An event can be attached with one or several methods (called event handlers). An event can be raised by calling raiseEvent method, upon which the attached event handlers will be invoked automatically in the order they are attached to the event. Event handlers must have the following signature,

     function eventHandlerFuncName($sender,$param) { ... }

where $sender refers to the object who is responsible for the raising of the event, and $param refers to a structure that may contain event-specific information. To raise an event (assuming named as 'Click') of a component, use

     $component->raiseEvent('OnClick');

To attach an event handler to an event, use one of the following ways,

     $component->OnClick=$callback;  // or $component->OnClick->add($callback);
      $$component->attachEventHandler('OnClick',$callback);

The first two ways make use of the fact that $component->OnClick refers to the event handler list TList for the 'OnClick' event. The variable $callback contains the definition of the event handler that can be either a string referring to a global function name, or an array whose first element refers to an object and second element a method name/path that is reachable by the object, e.g.

- 'buttonClicked' : buttonClicked($sender,$param);
- array($object,'buttonClicked') : $object->buttonClicked($sender,$param);
- array($object,'MainContent.SubmitButton.buttonClicked') : $object->MainContent->SubmitButton->buttonClicked($sender,$param);

- since: 3.0
- version: $Revision: $ $Date: $
- author: Qiang Xue <qiang.xue@gmail.com>

Located in /TComponent.php (line 74)

Direct descendents

Class | Description
--- | ---
TDummyDataSource | TDummyDataSource class
TList | TList class
TMap | TMap class
TPagedDataSource | TPagedDataSource class
TStack | TStack class
Translation | Translation class.
TTextWriter | TTextWriter class.
TAuthorizationRule | TAuthorizationRule class
TUser | TUser class
TApplication | TApplication class.
TApplicationConfiguration | TApplicationConfiguration class.
TApplicationComponent | TApplicationComponent class
TEventParameter | TEventParameter class.
TComponentReflection | TComponentReflection class.
TLogger | TLogger class.
TPageConfiguration | TPageConfiguration class
THttpCookie | THttpCookie class.
TUri | TUri class
TCompositeLiteral | TCompositeLiteral class
TValidatorClientScript | TValidatorClientScript class.
TDataSourceSelectParameters | TDataSourceSelectParameters class
TDataSourceView | TDataSourceView class
TFont | TFont class
TMetaTag | TMetaTag class.
THotSpot | THotSpot class.
TListItem | TListItem class.
TRepeatInfo | TRepeatInfo class.
TStyle | TStyle class
TValidationSummaryClientScript | TValidationSummaryClientScript class.
TWizardSideBarTemplate | TWizardSideBarTemplate class.
TWizardSideBarListItemTemplate | TWizardSideBarListItemTemplate class.
TWizardNavigationTemplate | TWizardNavigationTemplate class.
TXmlElement | TXmlElement class.

Method Summary
void attachEventHandler (string $name, callback $handler)
boolean canGetProperty (string $name)
boolean canSetProperty (string $name)
boolean detachEventHandler (string $name, callback $handler)
mixed evaluateExpression (mixed $expression)
string evaluateStatements (string $statements)
TList getEventHandlers (mixed $name)
mixed getSubProperty (string $path)
boolean hasEvent (string $name)
boolean hasEventHandler (mixed $name)
boolean hasProperty (string $name)
void raiseEvent (string $name, mixed $sender, TEventParameter $param)
void setSubProperty (string $path, mixed $value)
mixed __get (string $name)
void __set (string $name, mixed $value)
Methods
attachEventHandler (line 301)

Attaches an event handler to an event.

The handler must be a valid PHP callback, i.e., a string referring to a global function name, or an array containing two elements with the first element being an object and the second element a method name of the object. In Prado, you can also use method path to refer to an event handler. For example, array($object,'Parent.buttonClicked') uses a method path that refers to the method $object->Parent->buttonClicked(...).

The event handler must be of the following signature,

     function handlerName($sender,$param) {}

where $sender represents the object that raises the event, and $param is the event parameter.

This is a convenient method to add an event handler. It is equivalent to getEventHandlers($name)->add($handler). For complete management of event handlers, use getEventHandlers to get the event handler list first, and then do various TList operations to append, insert or remove event handlers. You may also do these operations like getting and setting properties, e.g.,

     $component->OnClick[]=array($object,'buttonClicked');
     $component->OnClick->insertAt(0,array($object,'buttonClicked'));

which are equivalent to the following

     $component->getEventHandlers('OnClick')->add(array($object,'buttonClicked'));
     $component->getEventHandlers('OnClick')->insertAt(0,array($object,'buttonClicked'));

- access: public
- throws: TInvalidOperationException if the event does not exist

void attachEventHandler (string $name, callback $handler)

- string $name: the event name
- callback $handler: the event handler

canGetProperty (line 170)

Determines whether a property can be read.

A property can be read if the class has a getter method for the property name. Note, property name is case-insensitive.

- return: whether the property can be read
- access: public

boolean canGetProperty (string $name)

- string $name: the property name

Redefined in descendants as:

- TAttributeCollection::canGetProperty() : Determines whether a property can be read.

canSetProperty (line 182)

Determines whether a property can be set.

A property can be written if the class has a setter method for the property name. Note, property name is case-insensitive.

- return: whether the property can be written
- access: public

boolean canSetProperty (string $name)

- string $name: the property name

Redefined in descendants as:

- TAttributeCollection::canSetProperty() : Determines whether a property can be set.

detachEventHandler (line 313)

Detaches an existing event handler.

This method is the opposite of attachEventHandler.

- return: if the removal is successful
- access: public

boolean detachEventHandler (string $name, callback $handler)

- string $name: event name
- callback $handler: the event handler to be removed

evaluateExpression (line 382)

Evaluates a PHP expression in the context of this control.

- return: the expression result
- access: public
- throws: TInvalidOperationException if the expression is invalid

mixed evaluateExpression (mixed $expression)
evaluateStatements (line 402)

Evaluates a list of PHP statements.

- return: content echoed or printed by the PHP statements
- access: public
- throws: TInvalidOperationException if the statements are invalid

string evaluateStatements (string $statements)

- string $statements: PHP statements

getEventHandlers (line 250)

Returns the list of attached event handlers for an event.

- return: list of attached event handlers for an event
- access: public
- throws: TInvalidOperationException if the event is not defined

TList getEventHandlers (mixed $name)
getSubProperty (line 195)

Evaluates a property path.

A property path is a sequence of property names concatenated by '.' character. For example, 'Parent.Page' refers to the 'Page' property of the component's 'Parent' property value (which should be a component also).

- return: the property path value
- access: public

mixed getSubProperty (string $path)

- string $path: property path

hasEvent (line 231)

Determines whether an event is defined.

An event is defined if the class has a method whose name is the event name prefixed with 'on'. Note, event name is case-insensitive.

- access: public

boolean hasEvent (string $name)

- string $name: the event name

hasEventHandler (line 239)

- return: whether an event has been attached one or several handlers
- access: public

boolean hasEventHandler (mixed $name)
hasProperty (line 158)

Determines whether a property is defined.

A property is defined if there is a getter or setter method defined in the class. Note, property names are case-insensitive.

- return: whether the property is defined
- access: public

boolean hasProperty (string $name)

- string $name: the property name

Redefined in descendants as:

- TAttributeCollection::hasProperty() : Determines whether a property is defined.

raiseEvent (line 339)

Raises an event.

This method represents the happening of an event and will invoke all attached event handlers for the event.

- access: public
- throws: TInvalidOperationException if the event is undefined
- throws: TInvalidDataValueException If an event handler is invalid

void raiseEvent (string $name, mixed $sender, TEventParameter $param)

- string $name: the event name
- mixed $sender: the event sender object
- TEventParameter $param: the event parameter

setSubProperty (line 211)

Sets a value to a property path.

A property path is a sequence of property names concatenated by '.' character. For example, 'Parent.Page' refers to the 'Page' property of the component's 'Parent' property value (which should be a component also).

- access: public

void setSubProperty (string $path, mixed $value)

- string $path: property path
- mixed $value: the property path value

__get (line 96)

Returns a property value or an event handler list by property or event name.

Do not call this method. This is a PHP magic method that we override to allow using the following syntax to read a property:

     $value=$component->PropertyName;

and to obtain the event handler list for an event,

     $eventHandlerList=$component->EventName;

- return: the property value or the event handler list
- access: public
- throws: TInvalidOperationException if the property/event is not defined.

mixed __get (string $name)

- string $name: the property name or the event name

Redefined in descendants as:

- TAttributeCollection::__get() : Returns a property value or an event handler list by property or event name.
- TControl::__get() : Returns a property value by name or a control by ID.

__set (line 130)

Sets value of a component property.

Do not call this method. This is a PHP magic method that we override to allow using the following syntax to set a property or attach an event handler.

     $this->PropertyName=$value;
     $this->EventName=$handler;

- access: public
- throws: TInvalidOperationException If the property is not defined or read-only.

void __set (string $name, mixed $value)

- string $name: the property name or event name
- mixed $value: the property value or event handler

Redefined in descendants as:

- TAttributeCollection::__set() : Sets value of a component property.

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