# GvaScript.fireEvent

application-specific events

### Table of contents

NAME
SYNOPSIS
DESCRIPTION
METHODS
fireEvent (first syntax)
fireEvent (second syntax)
REGISTERING AN EVENT HANDLER
Event structure

## NAME

GvaScript.fireEvent - 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.