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.