Handling Events

Introduction

The O3D plug-in supports several ways of receiving events from the host operating system. This support is modeled after standard DOM3 mechanisms as much as possible and includes support for the following:

• Event callbacks
• Event listeners for multiple handlers
• Keyboard events

Event Callbacks

The lowest-level interface to O3D events, for those who want things as fast and unfiltered as possible, is through the event callback API:

pluginObject.client.setEventCallback(type, handler);
pluginObject.client.clearEventCallback(type);

Both functions are idempotent and return void.

The pluginObject is the plug-in's DOM element. Most commonly you'll get that element from the array passed in to the callback you supplied to o3djs.util.makeClients().

The currently supported values for type are

The handler gets called with an O3D Event object as its only argument. This interface is as consistent as possible across browsers and operating systems. It is modeled after the DOM3 Event interface and its subinterfaces but has some differences.

Important differences are that since an O3D event just comes to a single handler via a direct call, there's no bubbling, capturing, cancellation, default action, phase, or target. In addition, there is currently no timeStamp field.

Mouse events contain only two coordinate pairs:

Event Listeners for Multiple Handlers

In cases where you have more than one handler for a given event type, you can use an optional utility function that manages multiple handlers. Its interface is very similar to the standard addEventListener API:

o3djs.event.addEventListener(pluginObject, type, eventListener);
o3djs.event.removeEventListener(pluginObject, type, eventListener);

As in the API for a single handler, both of these functions are idempotent and return void.

The pluginObject is the plug-in's DOM element; most commonly you'll get that from the array passed into the callback you supplied to o3djs.util.makeClients().

The currently supported values for type are the same as for the event callback methods, namely:

The eventListener is either a function or something that implements the EventListener interface. Either way, it will be invoked with an O3D Event object as its only argument.

If you use this API, you should not also use the lower-level API for the same event types. You can, however, use it for other event types.

Keyboard Events

Since web developers commonly handle keystrokes by placing a top-level event handler on the document, O3D includes a special helper API to make this technique work. o3djs.util.makeClients() calls o3djs.event.startKeyboardEventSynthesis(). This sets up event listeners (via the above o3djs.event.addEventListener) for the keyboard event types. These handlers attempt to simulate standard DOM keyboard events for those actions. On Internet Explorer, startKeyboardEventSynthesis() currently does nothing, since keyboard events will come both to the document (via Internet Explorer directly) and through the plug-in's low-level calls. This is a known issue.

These synthesized events, dispatched via dispatchEvent, will bubble, capture, and cancel just like normal events that happen when the plug-in region doesn't have keyboard focus. However, since the O3D code can't precisely duplicate the events that your browser creates itself, some of the fields may not be quite right. Exactly which differ depends on which browser and host operating system you're using, so O3D supplies a helper function o3djs.event.getEventKeyChar() to help hide those differences.

Since this API uses o3djs.event.addEventListener(), you shouldn't use the event callback functions setEventCallback() and clearEventCallback() (as described earlier in the Event Callbacks section) for keyboard events if you use this one. If you'd rather use the low-level callback interface, remove the call to startKeyboardEventSynthesis().

KeyCodes for Mac (Known Issue)

On the Mac, keypress events work as expected. Each keypress event has a keyChar value equal to the Unicode character for that key. However, keyup and keydown events on the Mac have keyCode values that do not always match the keyCode seen in the native browser events. There are two cases:

• If the key is a letter key, an arrow key, or Return/Enter, the O3D keyCodes match the standard browser keyCodes.
• If the key is a punctuation mark, the keyCode returned by O3D is the Unicode value for that key, not the standard browser keyCode. For example the "[" character would return a keyCode of 91, which is the Unicode value for "[". It would not return 219, which is the standard keyCode for browsers.

This discrepancy is a known issue on the Mac.