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) }
function handlerName($sender, $param, $name) }
where $sender represents the object that raises the event,
and $param is the event parameter. $name refers to the event name
being handled.
This is a convenient method to add an event handler.
It is equivalent to {@link getEventHandlers}($name)->add($handler).
For complete management of event handlers, use {@link getEventHandlers}
to get the event handler list first, and then do various
{@link TPriorityList} 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'));
Due to the nature of {@link getEventHandlers}, any active behaviors defining
new 'on' events, this method will pass through to the behavior transparently.
