The typical format of registration functions is as follows (some methods may omit various parameters):

EMSCRIPTEN_RESULTemscripten_set_some_callback(constchar*target,// ID of the target HTML element.void*userData,// User-defined data to be passed to the callback.EM_BOOLuseCapture,// Whether or not to use capture.em_someevent_callback_funccallback// Callback function.);

The target parameter is the ID of the HTML element to which the callback registration is to be applied. This field has the following special meanings:

0 or NULL: A default element is chosen automatically based on the event type, which should be reasonable most of the time.

#window: The event listener is applied to the JavaScript window object.

#document: The event listener is applied to the JavaScript document object.

#screen: The event listener is applied to the JavaScript window.screen object.

#canvas: The event listener is applied to the Emscripten default WebGL canvas element.

Any other string without a leading hash “#” sign: The event listener is applied to the element on the page with the given ID.

The userData parameter is a user-defined value that is passed (unchanged) to the registered event callback. This can be used to, for example, pass a pointer to a C++ class or similarly to enclose the C API in a clean object-oriented manner.

The useCapture parameter maps to useCapture in EventTarget.addEventListener. It indicates whether or not to initiate capture: if true the callback will be invoked only for the DOM capture and target phases; if false the callback will be triggered during the target and bubbling phases. See DOM Level 3 Events for a more detailed explanation.

Most functions return the result using the type EMSCRIPTEN_RESULT. Zero and positive values denote success. Negative values signal failure. None of the functions fail or abort by throwing a JavaScript or C++ exception. If a particular browser does not support the given feature, the value EMSCRIPTEN_RESULT_NOT_SUPPORTED will be returned at the time the callback is registered.

When the event occurs the callback is invoked with the relevant event “type” (for example EMSCRIPTEN_EVENT_CLICK), a struct containing the details of the event that occurred, and the userData that was originally passed to the registration function. The general format of the callback function is:

typedefEM_BOOL(*em_someevent_callback_func)// Callback function. Return true if event is "consumed".(inteventType,// The type of event.constEmscriptenSomeEvent*someEvent,// Information about the event.void*userData// User data passed from the registration function.);

Callback handlers that return an EM_BOOL may specify true to signal that the handler consumed the event (this suppresses the default action for that event by calling its .preventDefault(); member). Returning false indicates that the event was not consumed — the default browser event action is carried out and the event is allowed to pass on/bubble up as normal.

Calling a registration function with a null pointer for the callback causes a de-registration of that callback from the given target element. All event handlers are also automatically unregistered when the C exit() function is invoked during the atexit handler pass. Either use the function emscripten_set_main_loop() or set Module.noExitRuntime=true; to make sure that leaving main() will not immediately cause an exit() and clean up the event handlers.

While the functions can be called anywhere, the actual “requests” can only be raised inside the handler for a user-generated event (for example a key, mouse or touch press/release).

When porting code, it may be difficult to ensure that the functions are called inside appropriate event handlers (so that the requests are raised immediately). As a convenience, developers can set deferUntilInEventHandler=true to automatically defer insecure requests until the user next presses a keyboard or mouse button. This simplifies porting, but often results in a poorer user experience. For example, the user must click once on the canvas to hide the pointer or transition to full screen.

Where possible, the functions should only be called inside appropriate event handlers. Setting deferUntilInEventHandler=false causes the functions to abort with an error if the request is refused due to a security restriction: this is a useful mechanism for discovering instances where the functions are called outside the handler for a user-generated event.

Most functions in this API return a result of type EMSCRIPTEN_RESULT. None of the functions fail or abort by throwing a JavaScript or C++ exception. If a particular browser does not support the given feature, the value EMSCRIPTEN_RESULT_NOT_SUPPORTED will be returned at the time the callback is registered.

Note that since the DOM Level 3 Events spec is very recent at the time of writing (2014-03), uniform support for the different fields in the spec is still in flux. Be sure to check the results in multiple browsers. See the unmerged pull request #2222 for an example of how to interpret the legacy key events.

The following fields are values from previous versions of the DOM key events specifications. See the character representation of the key. This is the field char from the docs, but renamed to charValue to avoid a C reserved word.

The Unicode reference number of the key; this attribute is used only by the keypress event. For keys whose char attribute contains multiple characters, this is the Unicode value of the first character in that attribute.

Warning

This attribute is deprecated, you should use the field key instead, if available.

A system and implementation dependent numeric code identifying the unmodified value of the pressed key; this is usually the same as keyCode.

Warning

This attribute is deprecated, you should use the field key instead, if available. Note thought that while this field is deprecated, the cross-browser support for which may be better than for the other fields, so experimentation is recommended. Read issue https://github.com/kripken/emscripten/issues/2817 for more information.

callback (em_key_callback_func) – A callback function. The function is called with the type of event, information about the event, and user data passed from this registration function. The callback should return true if the event is consumed.

callback (em_mouse_callback_func) – A callback function. The function is called with the type of event, information about the event, and user data passed from this registration function. The callback should return true if the event is consumed.

Note that for this function call to succeed, emscripten_set_xxx_callback must have first been called with one of the mouse event types and a non-zero callback function pointer to enable the Mouse state capture.

Movement of the wheel on each of the axis. Note that these values may be fractional, so you should avoid simply casting them to integer, or it might result
in scroll values of 0. The positive Y scroll direction is when scrolling the page downwards (page CSS pixel +Y direction), which corresponds to scrolling
the mouse wheel downwards (away from the screen) on Windows, Linux, and also on OSX when the ‘natural scroll’ option is disabled.

callback (em_wheel_callback_func) – A callback function. The function is called with the type of event, information about the event, and user data passed from this registration function. The callback should return true if the event is consumed.

For the resize callback, pass in target = 0 to get resize events from the Window object.

The DOM3 Events specification only requires that the Window object sends resize events. It is valid to register a resize callback on other DOM elements, but the browser is not required to fire resize events for these.

callback (em_ui_callback_func) – A callback function. The function is called with the type of event, information about the event, and user data passed from this registration function. The callback should return true if the event is consumed.

callback (em_focus_callback_func) – A callback function. The function is called with the type of event, information about the event, and user data passed from this registration function. The callback should return true if the event is consumed.

callback (em_deviceorientation_callback_func) – A callback function. The function is called with the type of event, information about the event, and user data passed from this registration function. The callback should return true if the event is consumed.

Note that for this function call to succeed, emscripten_set_deviceorientation_callback() must have first been called with one of the mouse event types and a non-zero callback function pointer to enable the deviceorientation state capture.

callback (em_devicemotion_callback_func) – A callback function. The function is called with the type of event, information about the event, and user data passed from this registration function. The callback should return true if the event is consumed.

Note that for this function call to succeed, emscripten_set_devicemotion_callback() must have first been called with one of the mouse event types and a non-zero callback function pointer to enable the devicemotion state capture.

callback (em_orientationchange_callback_func) – A callback function. The function is called with the type of event, information about the event, and user data passed from this registration function. The callback should return true if the event is consumed.

Specifies that the DOM element should not be resized by Emscripten runtime when transitioning between fullscreen and windowed modes. The browser will be responsible for
scaling the DOM element to the fullscreen size. The proper browser behavior in this mode is to stretch the element to fit the full display ignoring aspect ratio, but at the
time of writing, browsers implement different behavior here. See the discussion at https://github.com/kripken/emscripten/issues/2556 for more information.

Specifies that the Emscripten runtime should explicitly stretch the CSS size of the target element to cover the whole screen when transitioning to fullscreen mode. This
will change the aspect ratio of the displayed content.

Specifies that the Emscripten runtime should explicitly scale the CSS size of the target element to cover the whole screen, while adding either vertical or horizontal
black letterbox padding to preserve the aspect ratio of the content. The aspect ratio that is used here is the render target size of the canvas element. To change the
desired aspect ratio, call emscripten_set_canvas_size() before entering fullscreen mode.

Specifies that the Emscripten runtime should not do any changes to the render target resolution of the target canvas element that is displayed in fullscreen mode. Use
this mode when your application is set up to render to a single fixed resolution that cannot be changed under any condition.

Specifies that the Emscripten runtime should resize the render target of the canvas element to match 1:1 with the CSS size of the element in fullscreen mode. On high DPI
displays (window.devicePixelRatio > 1), the CSS size is not the same as the physical screen resolution of the device. Call emscripten_get_device_pixel_ratio()
to obtain the pixel ratio between CSS pixels and actual device pixels of the screen. Use this mode when you want to render to a pixel resolution that is DPI-independent.

Specifies that the Emscripten runtime should resize the canvas render target size to match 1:1 with the physical screen resolution on the device. This corresponds to high
definition displays on retina iOS and other mobile and desktop devices with high DPI. Use this mode to match and render 1:1 to the native display resolution.

If nonzero, points to a user-provided callback function which will be called whenever either the CSS or the canvas render target size changes. Use this callback to reliably
obtain information about canvas resize events.

callback (em_fullscreenchange_callback_func) – A callback function. The function is called with the type of event, information about the event, and user data passed from this registration function. The callback should return true if the event is consumed.

This function can be called anywhere, but for web security reasons its associated request can only be raised inside the event handler for a user-generated event (for example a key, mouse or touch press/release). This has implications for porting and the value of deferUntilInEventHandler — see Functions affected by web security for more information.

Note

This function only performs a fullscreen request without changing any parameters of the DOM element that is to be displayed in fullscreen mode. At the time of writing, there are differences in how browsers present elements in fullscreen mode. For more information, read the discussion at https://github.com/kripken/emscripten/issues/2556. To display an element in fullscreen mode in a way that is consistent across browsers, prefer calling the function emscripten_request_fullscreen_strategy() instead. This function is best called only in scenarios where the preconfigured presets defined by emscripten_request_fullscreen_strategy() conflict with the developer’s use case in some way.

deferUntilInEventHandler (EM_BOOL) – If true requests made outside of a user-generated event handler are automatically deferred until the user next presses a keyboard or mouse button. If false the request will fail if called outside of a user-generated event handler.

Requests the given target element to transition to full screen mode, using a custom presentation mode for the element. This function is otherwise the same as emscripten_request_fullscreen(), but this function adds options to control how resizing and aspect ratio, and ensures that the behavior is consistent across browsers.

Note

This function makes changes to the DOM to satisfy consistent presentation across browsers. These changes have been designed to intrude as little as possible, and the changes are cleared once windowed browsing is restored. If any of these changes are conflicting, see the function emscripten_request_fullscreen() instead, which performs a bare fullscreen request without any modifications to the DOM.

Parameters:

fullscreenStrategy (const EmscriptenFullscreenStrategy*) – [in] Points to a configuration structure filled by the caller which specifies display options for the fullscreen mode.

Enters a “soft” fullscreen mode, where the given target element is displayed in the whole client area of the page and all other elements are hidden, but does not actually request fullscreen mode for the browser. This function is useful in cases where the actual Fullscreen API is not desirable or needed, for example in packaged apps for Firefox OS, where applications essentially already cover the whole screen.

Pressing the esc button does not automatically exit the soft fullscreen mode. To return to windowed presentation mode, manually call the function emscripten_exit_soft_fullscreen().

callback (em_pointerlockchange_callback_func) – A callback function. The function is called with the type of event, information about the event, and user data passed from this registration function. The callback should return true if the event is consumed.

callback (em_pointerlockerror_callback_func) – A callback function. The function is called with the type of event, information about the event, and user data passed from this registration function. The callback should return true if the event is consumed.

This function can be called anywhere, but for web security reasons its associated request can only be raised inside the event handler for a user-generated event (for example a key, mouse or touch press/release). This has implications for porting and the value of deferUntilInEventHandler — see Functions affected by web security for more information.

deferUntilInEventHandler (EM_BOOL) – If true requests made outside of a user-generated event handler are automatically deferred until the user next presses a keyboard or mouse button. If false the request will fail if called outside of a user-generated event handler.

callback (em_visibilitychange_callback_func) – A callback function. The function is called with the type of event, information about the event, and user data passed from this registration function. The callback should return true if the event is consumed.

callback (em_touch_callback_func) – A callback function. The function is called with the type of event, information about the event, and user data passed from this registration function. The callback should return true if the event is consumed.

callback (em_gamepad_callback_func) – A callback function. The function is called with the type of event, information about the event, and user data passed from this registration function. The callback should return true if the event is consumed.

A gamepad does not show up as connected until a button on it is pressed.

Note

Gamepad API uses an array of gamepad state objects to return the state of each device. The devices are identified via the index they are present in in

this array. Because of that, if one first connects gamepad A, then gamepad B, and then disconnects gamepad A, the gamepad B shall not take the place of gamepad A,
so in this scenario, this function will still keep returning two for the count of connected gamepads, even though gamepad A is no longer present. To find the actual
number of connected gamepads, listen for the gamepadconnected and gamepaddisconnected events.
Consider the return value of this function as the largest value (-1) that can be passed to the function emscripten_get_gamepad_status().

Registers a callback function for receiving the batterymanager events: chargingchange and levelchange.

Parameters:

userData (void*) – User-defined data to be passed to the callback (opaque to the API).

callback (em_battery_callback_func) – A callback function. The function is called with the type of event, information about the event, and user data passed from this registration function. The callback should return true if the event is consumed.

Registers a callback function for receiving the page beforeunload event.

Hook into this event to perform actions immediately prior to page close (for example, to display a notification to ask if the user really wants to leave the page).

Parameters:

userData (void*) – User-defined data to be passed to the callback (opaque to the API).

callback (em_beforeunload_callback) – A callback function. The function is called with the type of event, information about the event, and user data passed from this registration function. The callback should return true if the event is consumed.

If true, the contents of the drawing buffer are preserved between consecutive requestAnimationFrame() calls. If false, color, depth and stencil are cleared at the beginning of each requestAnimationFrame(). Generally setting this to false gives better performance. Default value: false.

If true, all GLES2-compatible non-performance-impacting WebGL extensions will automatically be enabled for you after the context has been created. If false, no extensions are enabled by default, and you need to manually call emscripten_webgl_enable_extension() to enable each extension that you want to use. Default value: true.

callback (em_webgl_context_callback) – A callback function. The function is called with the type of event, information about the event, and user data passed from this registration function. The callback should return true if the event is consumed.

Call this function as a forward-compatible way to ensure that if there are new fields added to the EmscriptenWebGLContextAttributes structure in the future, that they also will get default-initialized without having to change any code.

On success, a strictly positive value that represents a handle to the created context. On failure, a negative number that can be cast to an EMSCRIPTEN_RESULT field to get the reason why the context creation failed.

Returns the currently active WebGL rendering context, or 0 if no context is active. Calling any WebGL functions when there is no active rendering context is undefined and may throw a JavaScript exception.

Returns:

The currently active WebGL rendering context, or 0 if no context is active.