Skip to end of metadata
Go to start of metadata

Instructions for utilizing events

Introduction

One of the more common needs in a scripted plugin is the ability for the plugin to fire events into the page javascript. Here are some things you should know about using events with FireBreath:

Naming events

Due to browser differences, we recommend following these guidelines when naming your events:

  • Event names should be entirely lower case
  • Event names must start with "on"

For example:

  • onload
  • onstart
  • ondead
  • oncaughtsomeobnoxiousexceptionandnowiwanttodie
  • onsomethingelse

New in 1.5.0: Typed event firing methods!

This is the recommended way to register and fire events from JSAPI as of FireBreath 1.5.0!

Ideally, events should always be fired using the same number of parameters and the same types to keep things consistent. To that end, we have added a macro to create methods on your JSAPI class that will fire events into Javascript. This is done using the FB_JSAPI_EVENT macro in your JSAPI class definition.

The syntax for the macro is:
FB_JSAPI_EVENT({name}, {arg count}, ({arg types}))

  • {name} is the name of the event and does not include "on", it is added automatically (note there are no quotation marks)
  • {arg count} is the number of arguments expected
  • {arg types} is a comma separated list of {arg count} types that should be expected

In the example above four events are declared. The preprocessor will expand these macros to full methods on your class that can be used to fire the events to javascript with the provided arguments. The methods will be called fire_{name}, without the leading "on".
In the following example the previously generated methods are called:

Note: Never fire an event from a deconstructor. This leads to undefined behavior, probably including a plugin crash on page reloads.

Handling events in javascript

To process the event you fired in the plugin in JavaScript, you need to listen for it on the plugin object.

Internet Explorer

In all IE versions and most expecially IE9, attachEvent method must be used. Note that even though addEventListener is valid on IE9, IE never passes the event handler to the plugin and so it will silently fail to work if you do not use attachEvent:

Notice that with attachEvent(.) the "on" must be specified.

Several users have reported that events do not work in Internet Explorer if you use the EMBED tag for your plugin. Please use the OBJECT tag instead.

Other browsers

On most other browsers (not IE9, see above), you can use addEventListener:

addEventListener(.) prepends "on" to the event name automatically.

Note that FireBreath does not support the "useCapture" parameter (parameter 3) and will ignore it.

Detaching event handlers

Assuming you have kept a reference to the function specified as the handler function, you can detach the handler with the detachEvent() or removeEventListener() functions, as appropriate.

Events in FireBreath <1.5.0

Registering events on the JSAPI object

Note: This is no longer needed as of FireBreath-1.5.0

In your JSAPI object (usually a class named <plugin name>API), add a registerEvent() call in the constructor for each event you want to support on your object:

Firing events from the JSAPI object

Note: Firing events in this manner is deprecated as of FireBreath 1.5.0

Remember that events are asynchronous; in fact, when you fire the event it will be marshaled to the main JavaScript thread (in case your plugin is multithreaded) and it will be fired there. When you fire an event, you should not worry about whether or not there are any handlers attached to that event, simply fire it.

The basic syntax to fire an event is:
this->FireEvent("event name", params);

"event name" is the name of the event (including "on") as specified in the constructor. params is a FB::VariantList (std::vector<FB::variant>) with the parameters that should be passed to each event handler.

There are two examples in the codebase:

  • No labels

1 Comment

  1. Pnd

    注册事件与事件后函数

    事实上事件需要以相同参数和类型输入. 为此,用了宏指令 FB_JSAPI_EVENT 在JSAPI对象中使用.
    FB_JSAPI_EVENT({name}, {arg count}, ({arg types}))格式

    • {name} 事件名称不含 "on",也无引号。宏会自动添加
    • {arg count} 参数数量
    • {arg types} 参数类型
      宏指令对应的事件函数是 fire_{name}, 是在JSAPI对象的设置, 见例子
      在JS中加入插件的事件的设置方法:IE .attachEvent("Onxx",on); Other: .attachEventListener("xx",onxx,false);
    • 移除事件,用detachEvent, detachEventListener
    • FB1.5以下的操作-忽略