Month: October 2016

Implementing simple DOM Events in Gecko is fairly straight forward. A number of C/C++ macros have been written over the years to take away some of the pain.

In this post, I’ll explain how “window.onappinstalled” is implemented.

Web IDL

In this case, I’m interested in implementing the “appinstalled” event handler on the Window object. To do that, we start by defining the WebIDL in Window.webidl:

partial interface Window {
  // Pref'ed - see how to pref things in Gecko.
  [Pref="dom.manifest.onappinstalled"]
  attribute EventHandler onappinstalled;
};

Window only events

The events in Gecko are defined in the EventNameList.h header file. This allows you to define a variety of different event types.

For our case, we are interested in a “window only” event, so we can use the “WINDOW_ONLY_EVENT” macro.

As stated in EventNameList.h, each event entry in this file consists of 4 pieces of information:

The name of the event

This needs to match a GkAtom in nsGkAtomList.h

The event message

This is also generated with a macro, but needs to be defined via EventMessageList.h

The event type

See the EventNameType enum in nsContentUtils.h)

The event struct type for this event.

so, basically, for “window.onappinstall”, we define:

// Install events as per W3C Manifest spec
WINDOW_ONLY_EVENT(appinstalled, // nsGkAtomList.h
                  eAppInstalled, // EventMessageList.h
                  EventNameType_None,
                  eBasicEventClass) 

Event Message (EventMessageList.h)

As stated in the file, an event message must be defined as follows:

1. Starting with “e” prefix and use camelcase.
2. Basically, use same name as the DOM name which is fired at dispatching the event.
3. If the event message name becomes too generic, e.g., “eInvalid”, that may conflict with another enum’s item name, append something after the “e”
   prefix, e.g., “eFormInvalid”.

So, in our case, we just want “eAppInstalled” as the message:

NS_EVENT_MESSAGE(eAppInstalled)

That should do it.