Alien::GvaScript::Event(3)

NAME
Alien::GvaScript::Event - application-specific events

SYNOPSIS
  MyConstructor = function (...) {...};

  MyContructor.prototype = {

    fireEvent = GvaScript.fireEvent, // copy into the target object

    someMethod: function(...) {
      ...
      this.fireEvent(eventName, target1, target2, ...);
      // OR ...
      this.fireEvent({type: eventName,
                      prop1: value1,
                      ...            }, target1, target2, ...);
    }
  };

DESCRIPTION
Extension of the HTML event model with specific events. Various "GvaScript" controllers use this to manage interactions between the DOM elements and the controller. Client code can register a an event handler either within the HTML code, or through Javascript.

Events have names specific to the controller (for example "choiceList" uses events "Highlight" and "Ping"; "treeNavigator" uses events "Close", "Open", "BeforeLoadContent", etc.).

METHODS

  fireEvent (first syntax)
If a class needs to fire specific events, it must copy the "GvaScript.fireEvent" method into its own methods (so that "this" is properly bound to an instance of that class).

The first argument to "fireEvent" is usually an event name. This can be any string, without the "on" prefix :

  this.fireEvent("Ping", this.htmlElement, otherElement1, ...);

The method will inspect all HTML elements supplied in the argument list, trying to find an "onPing" handler. If none is found, the method also tries to find an "onPing" property within the calling object ("this").

If an event handler is found, that handler is called with an "event" argument as described below; the return value of the handler becomes the return value of "fireEvent". If not handler is found, "fireEvent" returns "null".

  fireEvent (second syntax)
For more sophisticated needs, the first argument to "fireEvent" can be an object with several properties. In that case, all properties will be copied into the generated event structure. The "type" property should contain the event name, in order to be compatible with the first syntax. So for example

  this.fireEvent({type  : "Ping",
                  prop1 : "value1",
                  prop2 : "value2"}, this.htmlElement, otherElement1, ...);

will generate "Ping" events with all default properties described below, plus the properties "prop1" and "prop2".

REGISTERING AN EVENT HANDLER
  <div onEventName="doSomethingWith(this)">
    <span onEventName="doSomethingMoreSpecificWith(this, controller)">
    <span onEventName="doYetAnotherThing">
  </div>

  myController.onEventName = function(event){...};

There are three ways to register a handler:

javascript statement in an HTML attribute
    This works as for ordinary HTML DOM events. The javascript statement will be evaluated in a context where the following variables are defined:

    this
        The object that registered the event handler.

    target
        The HTML element that first received the event.

    currentTarget
        The object that registered the event handler (equivalent to "this").

    controller
        The GvaScript controller object that generated the event.

    event
        A structure containing various information about the generated event, described below.

name of a javascript function inside an HTML attribute
    The given function will be called with a single "event" argument.

property assigned from Javascript
    This works exactly like the previous case : the event handling function receives a single "event" argument.

  Event structure
The "event" object passed to event handlers contains the following properties :

type
    name of the triggered event (i.e. "Ping", "Highlight", etc.)

target
    The HTML element that first received the event.

srcElement
    Synonym for "target".

currentTarget
    The object that registered the event handler.

controller
    The GvaScript controller object that generated the event.