html5.h — Emscripten 1.20.0 documentation

# html5.h

The C++ APIs in html5.h define the Emscripten low-level glue bindings to interact with HTML5 events from native code.

Tip

The C++ APIs map closely to their equivalent HTML5 JavaScript APIs. The HTML5 specifications listed below provide additional detailed reference “over and above” the information provided in this document.

In addition, the Test/Example code can be reviewed to see how the code is used.

The HTML5 specifications for APIs that are mapped by html5.h include:

> - DOM Level 3 Events: Keyboard, Mouse, Mouse Wheel, Resize, Scroll, Focus.
> - Device Orientation Events for gyro and accelerometer.
> - Screen Orientation Events for portrait/landscape handling.
> - Fullscreen Events for browser canvas fullscreen modes transitioning.
> - Pointer Lock Events for relative-mode mouse motion control.
> - Vibration API for mobile device haptic vibration feedback control.
> - Page Visibility Events for power management control.
> - Touch Events.
> - Gamepad API.
> - Beforeunload event.
> - WebGL context events

Table of Contents

- How to use this API
- General types
- Function result values
- Keys
- Mouse
- Wheel
- UI
- Focus
- Device orientation
- Device motion
- Orientation
- Fullscreen
- Pointerlock
- Visibility
- Touch
- Gamepad
- Battery
- Vibration
- Page unload
- WebGL context

## How to use this API

Most of these APIs use an event-based architecture; functionality is accessed by registering a callback function that will be called when the event occurs.

Note

The Gamepad API is currently an exception, as only a polling API is available. For some APIs, both an event-based and a polling-based model are exposed.

### Registration functions

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

>     EMSCRIPTEN_RESULT emscripten_set_some_callback(
>             const char *target,     // ID of the target HTML element.
>             void *userData,         // User-defined data to be passed to the callback.
>             EM_BOOL useCapture,     // Whether or not to use capture.
>             em_someevent_callback_func callback     // 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`. Non-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.

### Callback functions

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:

    typedef EM_BOOL (*em_someevent_callback_func) // Callback function. Return true if event is "consumed".
            (
            int eventType, // The type of event.
            const EmscriptenSomeEvent *keyEvent, // 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.

### Functions affected by web security

Some functions, including `emscripten_request_pointerlock()` and `emscripten_request_fullscreen()`, are affected by web security.

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.

### Test/Example code

The HTML5 test code demonstrates how to use this API:

> - test_html5.c
> - test_html5_fullscreen.c
> - test_html5_mouse.c

## General types

`EM_BOOL`

  This is the Emscripten type for a `bool`.

`EM_UTF8`

  This is the Emscripten type for a UTF8 string (maps to a `char`). This is used for node names, element ids, etc.

## Function result values

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.

`EMSCRIPTEN_RESULT`

  This type is used to return the result of most functions in this API. Positive values denote success, while zero and negative values signal failure. Possible values are listed below.

  `EMSCRIPTEN_RESULT_SUCCESS`

    The operation succeeded.

  `EMSCRIPTEN_RESULT_DEFERRED`

    The requested operation cannot be completed now for web security reasons, and has been deferred for completion in the next event handler.

  `EMSCRIPTEN_RESULT_NOT_SUPPORTED`

    The given operation is not supported by this browser or the target element. This value will be returned at the time the callback is registered if the operation is not supported.

  `EMSCRIPTEN_RESULT_FAILED_NOT_DEFERRED`

    The requested operation could not be completed now for web security reasons. It failed because the user requested the operation not be deferred.

  `EMSCRIPTEN_RESULT_INVALID_TARGET`

    The operation failed because the specified target element is invalid.

  `EMSCRIPTEN_RESULT_UNKNOWN_TARGET`

    The operation failed because the specified target element was not found.

  `EMSCRIPTEN_RESULT_INVALID_PARAM`

    The operation failed because an invalid parameter was passed to the function.

  `EMSCRIPTEN_RESULT_FAILED`

    Generic failure result message, returned if no specific result is available.

  `EMSCRIPTEN_RESULT_NO_DATA`

    The operation failed because no data is currently available.

## Keys

### Defines

`EMSCRIPTEN_EVENT_KEYPRESS`
`EMSCRIPTEN_EVENT_KEYDOWN`
`EMSCRIPTEN_EVENT_KEYUP`

  Emscripten key events.

`DOM_KEY_LOCATION`

  The location of the key on the keyboard; one of the values below.

  `DOM_KEY_LOCATION_STANDARD`
  `DOM_KEY_LOCATION_LEFT`
  `DOM_KEY_LOCATION_RIGHT`
  `DOM_KEY_LOCATION_NUMPAD`

    Locations of the key on the keyboard.

### Struct

`EmscriptenKeyboardEvent`

  The event structure passed in keyboard events: `keypress`, `keydown` and `keyup`.

  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.

  EM_UTF8 `key`

    The printed representation of the pressed key.

    Maximum size 32 `char` (i.e. `EM_UTF8 key[32]`).

  EM_UTF8 `code`

    A string that identifies the physical key being pressed. The value is not affected by the current keyboard layout or modifier state, so a particular key will always return the same value.

    Maximum size 32 `char` (i.e. `EM_UTF8 code[32]`).

  unsigned long `location`

    Indicates the location of the key on the keyboard. One of the `DOM_KEY_LOCATION` values.

  EM_BOOL `ctrlKey`
  EM_BOOL `shiftKey`
  EM_BOOL `altKey`
  EM_BOOL `metaKey`

    Specifies which modifiers were active during the key event.

  EM_BOOL `repeat`

    Specifies if this keyboard event represents a repeated press.

  EM_UTF8 `locale`

    A locale string indicating the configured keyboard locale. This may be an empty string if the browser or device doesn’t know the keyboard’s locale.

    Maximum size 32 char (i.e. `EM_UTF8 locale[32]`).

  EM_UTF8 `charValue`

    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.

    Maximum size 32 `char` (i.e. `EM_UTF8 charValue[32]`).

    Warning

    This attribute has been dropped from DOM Level 3 events.

  unsigned long `charCode`

    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.

  unsigned long `keyCode`

    A system and implementation dependent numerical code identifying the unmodified value of the pressed key.

    Warning

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

  unsigned long `which`

    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.

### Callback functions

`em_key_callback_func`

  Function pointer for the `keypress callback functions`, defined as:

      typedef EM_BOOL (*em_key_callback_func)(int eventType, const EmscriptenKeyboardEvent *keyEvent, void *userData);

  Parameters: | eventType (int) – The type of `key event`. keyEvent (const EmscriptenKeyboardEvent*) – Information about the key event that occurred. userData (void*) – The `userData` originally passed to the registration function.
  Returns: | `true` (non zero) to indicate that the event was consumed by the callback handler.
  Return type: | `EM_BOOL`

### Functions

EMSCRIPTEN_RESULT `emscripten_set_keypress_callback`(const char *target, void *userData, EM_BOOL useCapture, em_key_callback_func callback)
EMSCRIPTEN_RESULT `emscripten_set_keydown_callback`(const char *target, void *userData, EM_BOOL useCapture, em_key_callback_func callback)
EMSCRIPTEN_RESULT `emscripten_set_keyup_callback`(const char *target, void *userData, EM_BOOL useCapture, em_key_callback_func callback)

  Registers a callback function for receiving browser-generated keyboard input events.

  Parameters: | target (const char*) – Target HTML element id. userData (void*) – User-defined data to be passed to the callback (opaque to the API). useCapture (EM_BOOL) – Set `true` to use capture. 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.
  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | `EMSCRIPTEN_RESULT`
  See also: | https://developer.mozilla.org/en/DOM/Event/UIEvent/KeyEvent http://www.javascriptkit.com/jsref/eventkeyboardmouse.shtml

## Mouse

### Defines

`EMSCRIPTEN_EVENT_CLICK`
`EMSCRIPTEN_EVENT_MOUSEDOWN`
`EMSCRIPTEN_EVENT_MOUSEUP`
`EMSCRIPTEN_EVENT_DBLCLICK`
`EMSCRIPTEN_EVENT_MOUSEMOVE`

  Emscripten mouse events.

### Struct

`EmscriptenMouseEvent`

  The event structure passed in mouse events: click, mousedown, mouseup, dblclick and mousemove.

  `double timestamp;`

    A timestamp of when this data was generated by the browser. This is an absolute wallclock time in milliseconds.

  long `screenX`
  long `screenY`

    The coordinates relative to the browser screen coordinate system.

  long `clientX`
  long `clientY`

    The coordinates relative to the viewport associated with the event.

  EM_BOOL `ctrlKey`
  EM_BOOL `shiftKey`
  EM_BOOL `altKey`
  EM_BOOL `metaKey`

    Specifies which modifiers were active during the mouse event.

  unsigned short `button`

    Identifies which pointer device button changed state (see MouseEvent.button):

    > - 0 : Left button
    > - 1 : Middle button (if present)
    > - 2 : Right button

  unsigned short `buttons`

    A bitmask that indicates which combinations of mouse buttons were being held down at the time of the event.

  long `movementX`
  `long movementY;`

    If pointer lock is active, these two extra fields give relative mouse movement since the last event.

  long `canvasX`
  long `canvasY`

    These fields give the mouse coordinates mapped to the Emscripten canvas client area (Emscripten-specific extension).

  long `padding`

    Internal, and can be ignored.

    Note

    Implementers only: pad this struct to multiple of 8 bytes to make `WheelEvent` unambiguously align to 8 bytes.

### Callback functions

`em_mouse_callback_func`

  Function pointer for the `mouse event callback functions`, defined as:

      typedef EM_BOOL (*em_mouse_callback_func)(int eventType, const EmscriptenMouseEvent *keyEvent, void *userData);

  Parameters: | eventType (int) – The type of `mouse event`. keyEvent (const EmscriptenMouseEvent*) – Information about the mouse event that occurred. userData (void*) – The `userData` originally passed to the registration function.
  Returns: | `true` (non zero) to indicate that the event was consumed by the callback handler.
  Return type: | `EM_BOOL`

### Functions

EMSCRIPTEN_RESULT `emscripten_set_click_callback`(const char *target, void *userData, EM_BOOL useCapture, em_mouse_callback_func callback)
EMSCRIPTEN_RESULT `emscripten_set_mousedown_callback`(const char *target, void *userData, EM_BOOL useCapture, em_mouse_callback_func callback)
EMSCRIPTEN_RESULT `emscripten_set_mouseup_callback`(const char *target, void *userData, EM_BOOL useCapture, em_mouse_callback_func callback)
EMSCRIPTEN_RESULT `emscripten_set_dblclick_callback`(const char *target, void *userData, EM_BOOL useCapture, em_mouse_callback_func callback)
EMSCRIPTEN_RESULT `emscripten_set_mousemove_callback`(const char *target, void *userData, EM_BOOL useCapture, em_mouse_callback_func callback)

  Registers a callback function for receiving browser-generated mouse input events.

  Parameters: | target (const char*) – Target HTML element id. userData (void*) – User-defined data to be passed to the callback (opaque to the API). useCapture (EM_BOOL) – Set `true` to use capture. 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.
  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | `EMSCRIPTEN_RESULT`

EMSCRIPTEN_RESULT `emscripten_get_mouse_status`(EmscriptenMouseEvent *mouseState)

  Returns the most recently received mouse event state.

  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.

  Parameters: | mouseState (EmscriptenMouseEvent*) – The most recently received mouse event state.
  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | `EMSCRIPTEN_RESULT`

## Wheel

### Defines

`EMSCRIPTEN_EVENT_WHEEL`

  Emscripten wheel event.

`DOM_DELTA_PIXEL`

  The units of measurement for the delta must be pixels (from spec).

`DOM_DELTA_LINE`

  The units of measurement for the delta must be individual lines of text (from spec).

`DOM_DELTA_PAGE`

  The units of measurement for the delta must be pages, either defined as a single screen or as a demarcated page (from spec).

### Struct

`EmscriptenWheelEvent`

  The event structure passed in mousewheel events.

  EmscriptenMouseEvent `mouse`

    Specifies general mouse information related to this event.

  double `deltaX`
  double `deltaY`
  double `deltaZ`

    Movement of the wheel on each of the axis.

  unsigned long `deltaMode`

    One of the `DOM_DELTA_` values that indicates the units of measurement for the delta values.

### Callback functions

`em_wheel_callback_func`

  Function pointer for the `wheel event callback functions`, defined as:

      typedef EM_BOOL (*em_wheel_callback_func)(int eventType, const EmscriptenWheelEvent *keyEvent, void *userData);

  Parameters: | eventType (int) – The type of wheel event (`EMSCRIPTEN_EVENT_WHEEL`). keyEvent (const EmscriptenWheelEvent*) – Information about the wheel event that occurred. userData (void*) – The `userData` originally passed to the registration function.
  Returns: | `true` (non zero) to indicate that the event was consumed by the callback handler.
  Return type: | `EM_BOOL`

### Functions

EMSCRIPTEN_RESULT EMSCRIPTEN_RESULT `emscripten_set_wheel_callback`(const char *target, void *userData, EM_BOOL useCapture, em_wheel_callback_func callback)

  Registers a callback function for receiving browser-generated mousewheel events.

  Parameters: | target (const char*) – Target HTML element id. userData (void*) – User-defined data to be passed to the callback (opaque to the API). useCapture (EM_BOOL) – Set `true` to use capture. 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.
  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | `EMSCRIPTEN_RESULT`

## UI

### Defines

`EMSCRIPTEN_EVENT_RESIZE`
`EMSCRIPTEN_EVENT_SCROLL`

  Emscripten UI events.

### Struct

`EmscriptenUiEvent`

  The event structure passed in DOM element UIEvent events: resize and scroll.

  long `detail`

    Specifies additional detail/information about this event.

  int `documentBodyClientWidth`
  int `documentBodyClientHeight`

    The clientWidth/clientHeight of the `document.body` element.

  int `windowInnerWidth`
  int `windowInnerHeight`

    The innerWidth/innerHeight of the browser window.

  int `windowOuterWidth`
  `int windowOuterHeight;`

    The outerWidth/outerHeight of the browser window.

  int `scrollTop`
  int `scrollLeft`

    The page scroll position.

### Callback functions

`em_ui_callback_func`

  Function pointer for the `UI event callback functions`, defined as:

      typedef EM_BOOL (*em_ui_callback_func)(int eventType, const EmscriptenUiEvent *keyEvent, void *userData);

  Parameters: | eventType (int) – The type of UI event (`EMSCRIPTEN_EVENT_RESIZE`). keyEvent (const EmscriptenUiEvent*) – Information about the UI event that occurred. userData (void*) – The `userData` originally passed to the registration function.
  Returns: | `true` (non zero) to indicate that the event was consumed by the callback handler.
  Return type: | `EM_BOOL`

### Functions

EMSCRIPTEN_RESULT `emscripten_set_resize_callback`(const char *target, void *userData, EM_BOOL useCapture, em_ui_callback_func callback)
EMSCRIPTEN_RESULT `emscripten_set_scroll_callback`(const char *target, void *userData, EM_BOOL useCapture, em_ui_callback_func callback)

  Registers a callback function for receiving DOM element resize and scroll events.

  Parameters: | target (const char*) – Target HTML element id. userData (void*) – User-defined data to be passed to the callback (opaque to the API). useCapture (EM_BOOL) – Set `true` to use capture. 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.
  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | `EMSCRIPTEN_RESULT`

## Focus

### Defines

`EMSCRIPTEN_EVENT_BLUR`
`EMSCRIPTEN_EVENT_FOCUS`
`EMSCRIPTEN_EVENT_FOCUSIN`
`EMSCRIPTEN_EVENT_FOCUSOUT`

  Emscripten focus events.

### Struct

`EmscriptenFocusEvent`

  The event structure passed in DOM element blur, focus, focusin and focusout events.

  EM_UTF8 `nodeName`

    The nodeName of the target HTML Element.

    Maximum size 128 `char` (i.e. `EM_UTF8 nodeName[128]`).

  EM_UTF8 `id`

    The ID of the target element.

    Maximum size 128 `char` (i.e. `EM_UTF8 id[128]`).

### Callback functions

`em_focus_callback_func`

  Function pointer for the `focus event callback functions`, defined as:

      typedef EM_BOOL (*em_focus_callback_func)(int eventType, const EmscriptenFocusEvent *keyEvent, void *userData);

  Parameters: | eventType (int) – The type of focus event (`EMSCRIPTEN_EVENT_BLUR`). keyEvent (const EmscriptenFocusEvent*) – Information about the focus event that occurred. userData (void*) – The `userData` originally passed to the registration function.
  Returns: | `true` (non zero) to indicate that the event was consumed by the callback handler.
  Return type: | `EM_BOOL`

### Functions

EMSCRIPTEN_RESULT `emscripten_set_blur_callback`(const char *target, void *userData, EM_BOOL useCapture, em_focus_callback_func callback)
EMSCRIPTEN_RESULT `emscripten_set_focus_callback`(const char *target, void *userData, EM_BOOL useCapture, em_focus_callback_func callback)
EMSCRIPTEN_RESULT `emscripten_set_focusin_callback`(const char *target, void *userData, EM_BOOL useCapture, em_focus_callback_func callback)
EMSCRIPTEN_RESULT `emscripten_set_focusout_callback`(const char *target, void *userData, EM_BOOL useCapture, em_focus_callback_func callback)

  Registers a callback function for receiving DOM element blur, focus, focusin and focusout events.

  Parameters: | target (const char*) – Target HTML element id. userData (void*) – User-defined data to be passed to the callback (opaque to the API). useCapture (EM_BOOL) – Set `true` to use capture. 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.
  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | `EMSCRIPTEN_RESULT`

## Device orientation

### Defines

`EMSCRIPTEN_EVENT_DEVICEORIENTATION`

  Emscripten `deviceorientation` events.

### Struct

`EmscriptenDeviceOrientationEvent`

  The event structure passed in the deviceorientation event.

  double `timestamp`

    Absolute wallclock time when the event occurred (in milliseconds).

  double `alpha`
  double `beta`
  double `gamma`

    The orientation of the device in terms of the transformation from a coordinate frame fixed on the Earth to a coordinate frame fixed in the device.

    The image (source: dev.opera.com) and definitions below illustrate the co-ordinate frame:

    > - `alpha`: the rotation of the device around the Z axis.
    > - `beta`: the rotation of the device around the X axis.
    > - `gamma`: the rotation of the device around the Y axis.

  EM_BOOL `absolute`

    If `false`, the orientation is only relative to some other base orientation, not to the fixed coordinate frame.

### Callback functions

`em_deviceorientation_callback_func`

  Function pointer for the `orientation event callback functions`, defined as:

      typedef EM_BOOL (*em_deviceorientation_callback_func)(int eventType, const EmscriptenDeviceOrientationEvent *keyEvent, void *userData);

  Parameters: | eventType (int) – The type of orientation event (`EMSCRIPTEN_EVENT_DEVICEORIENTATION`). keyEvent (const EmscriptenDeviceOrientationEvent*) – Information about the orientation event that occurred. userData (void*) – The `userData` originally passed to the registration function.
  Returns: | `true` (non zero) to indicate that the event was consumed by the callback handler.
  Return type: | `EM_BOOL`

### Functions

EMSCRIPTEN_RESULT `emscripten_set_deviceorientation_callback`(void *userData, EM_BOOL useCapture, em_deviceorientation_callback_func callback)

  Registers a callback function for receiving the deviceorientation event.

  Parameters: | userData (void*) – User-defined data to be passed to the callback (opaque to the API). useCapture (EM_BOOL) – Set `true` to use capture. 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.
  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | `EMSCRIPTEN_RESULT`

EMSCRIPTEN_RESULT `emscripten_get_deviceorientation_status`(EmscriptenDeviceOrientationEvent *orientationState)

  Returns the most recently received `deviceorientation` event state.

  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.

  Parameters: | orientationState (EmscriptenDeviceOrientationEvent*) – The most recently received `deviceorientation` event state.
  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | `EMSCRIPTEN_RESULT`

## Device motion

### Defines

`EMSCRIPTEN_EVENT_DEVICEMOTION`

  Emscripten devicemotion event.

### Struct

`EmscriptenDeviceMotionEvent`

  The event structure passed in the devicemotion event.

  double `timestamp`

    Absolute wallclock time when the event occurred (milliseconds).

  double `accelerationX`
  double `accelerationY`
  double `accelerationZ`

    Acceleration of the device excluding gravity.

  double `accelerationIncludingGravityX`
  double `accelerationIncludingGravityY`
  double `accelerationIncludingGravityZ`

    Acceleration of the device including gravity.

  double `rotationRateAlpha`
  double `rotationRateBeta`
  double `rotationRateGamma`

    The rotational delta of the device.

### Callback functions

`em_devicemotion_callback_func`

  Function pointer for the `devicemotion event callback functions`, defined as:

      typedef EM_BOOL (*em_devicemotion_callback_func)(int eventType, const EmscriptenDeviceMotionEvent *keyEvent, void *userData);

  Parameters: | eventType (int) – The type of devicemotion event (`EMSCRIPTEN_EVENT_DEVICEMOTION`). keyEvent (const EmscriptenDeviceMotionEvent*) – Information about the devicemotion event that occurred. userData (void*) – The `userData` originally passed to the registration function.
  Returns: | `true` (non zero) to indicate that the event was consumed by the callback handler.
  Return type: | `EM_BOOL`

### Functions

EMSCRIPTEN_RESULT `emscripten_set_devicemotion_callback`(void *userData, EM_BOOL useCapture, em_devicemotion_callback_func callback)

  Registers a callback function for receiving the devicemotion event.

  Parameters: | userData (void*) – User-defined data to be passed to the callback (opaque to the API). useCapture (EM_BOOL) – Set `true` to use 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.
  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | `EMSCRIPTEN_RESULT`

EMSCRIPTEN_RESULT `emscripten_get_devicemotion_status`(EmscriptenDeviceMotionEvent *motionState)

  Returns the most recently received devicemotion event state.

  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.

  Parameters: | motionState (EmscriptenDeviceMotionEvent*) – The most recently received `devicemotion` event state.
  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | `EMSCRIPTEN_RESULT`

## Orientation

### Defines

`EMSCRIPTEN_EVENT_ORIENTATIONCHANGE`

  Emscripten orientationchange event.

`EMSCRIPTEN_ORIENTATION_PORTRAIT_PRIMARY`

  Primary portrait mode orientation.

`EMSCRIPTEN_ORIENTATION_PORTRAIT_SECONDARY`

  Secondary portrait mode orientation.

`EMSCRIPTEN_ORIENTATION_LANDSCAPE_PRIMARY`

  Primary landscape mode orientation.

`EMSCRIPTEN_ORIENTATION_LANDSCAPE_SECONDARY`

  Secondary landscape mode orientation.

### Struct

`EmscriptenOrientationChangeEvent`

  The event structure passed in the orientationchange event.

  int `orientationIndex`

    One of the `EM_ORIENTATION_PORTRAIT_xxx` fields, or -1 if unknown.

  int `orientationAngle`

    Emscripten-specific extension: Some browsers refer to `window.orientation`, so report that as well.

    Orientation angle in degrees. 0: “default orientation”, i.e. default upright orientation to hold the mobile device in. Could be either landscape or portrait.

### Callback functions

`em_orientationchange_callback_func`

  Function pointer for the `orientationchange event callback functions`, defined as:

      typedef EM_BOOL (*em_orientationchange_callback_func)(int eventType, const EmscriptenOrientationChangeEvent *keyEvent, void *userData);

  Parameters: | eventType (int) – The type of orientationchange event (`EMSCRIPTEN_EVENT_ORIENTATIONCHANGE`). keyEvent (const EmscriptenOrientationChangeEvent*) – Information about the orientationchange event that occurred. userData (void*) – The `userData` originally passed to the registration function.
  Returns: | `true` (non zero) to indicate that the event was consumed by the callback handler.
  Return type: | `EM_BOOL`

### Functions

EMSCRIPTEN_RESULT `emscripten_set_orientationchange_callback`(void *userData, EM_BOOL useCapture, em_orientationchange_callback_func callback)

  Registers a callback function for receiving the orientationchange event.

  Parameters: | userData (void*) – User-defined data to be passed to the callback (opaque to the API). useCapture (EM_BOOL) – Set `true` to use 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.
  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | `EMSCRIPTEN_RESULT`

EMSCRIPTEN_RESULT `emscripten_get_orientation_status`(EmscriptenOrientationChangeEvent *orientationStatus)

  Returns the current device orientation state.

  Parameters: | orientationStatus (EmscriptenOrientationChangeEvent*) – The most recently received orientation state.
  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | `EMSCRIPTEN_RESULT`

EMSCRIPTEN_RESULT `emscripten_lock_orientation`(int allowedOrientations)

  Locks the screen orientation to the given set of `allowed orientations`.

  Parameters: | allowedOrientations (int) – A bitfield set of `EMSCRIPTEN_ORIENTATION_xxx` flags.
  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | `EMSCRIPTEN_RESULT`

EMSCRIPTEN_RESULT `emscripten_unlock_orientation`(void)

  Removes the orientation lock so the screen can turn to any orientation.

  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | `EMSCRIPTEN_RESULT`

## Fullscreen

### Defines

`EMSCRIPTEN_EVENT_FULLSCREENCHANGE`

  Emscripten fullscreenchange event.

### Struct

`EmscriptenFullscreenChangeEvent`

  The event structure passed in the fullscreenchange event.

  EM_BOOL `isFullscreen`

    Specifies whether an element on the browser page is currently fullscreen.

  EM_BOOL `fullscreenEnabled`

    Specifies if the current page has the ability to display elements fullscreen.

  EM_UTF8 `nodeName`

    The nodeName of the target HTML Element that is in full screen mode.

    Maximum size 128 `char` (i.e. `EM_UTF8 nodeName[128]`).

    If `isFullscreen` is `false`, then `nodeName`, `id` and `elementWidth` and `ElementHeight` specify information about the element that just exited fullscreen mode.

  EM_UTF8 `id`

    The ID of the target HTML element that is in full screen mode.

    Maximum size 128 `char` (i.e. `EM_UTF8 id[128]`).

  int `elementWidth`
  int `elementHeight`

    The new pixel size of the element that changed fullscreen status.

  int `screenWidth`
  int `screenHeight`

    The size of the whole screen, in pixels.

### Callback functions

`em_fullscreenchange_callback_func`

  Function pointer for the `fullscreen event callback functions`, defined as:

      typedef EM_BOOL (*em_fullscreenchange_callback_func)(int eventType, const EmscriptenFullscreenChangeEvent *keyEvent, void *userData);

  Parameters: | eventType (int) – The type of fullscreen event (`EMSCRIPTEN_EVENT_FULLSCREENCHANGE`). keyEvent (const EmscriptenFullscreenChangeEvent*) – Information about the fullscreen event that occurred. userData (void*) – The `userData` originally passed to the registration function.
  Returns: | `true` (non zero) to indicate that the event was consumed by the callback handler.
  Return type: | `EM_BOOL`

### Functions

EMSCRIPTEN_RESULT `emscripten_set_fullscreenchange_callback`(const char *target, void *userData, EM_BOOL useCapture, em_fullscreenchange_callback_func callback)

  Registers a callback function for receiving the fullscreenchange event.

  Parameters: | target (const char*) – Target HTML element id. userData (void*) – User-defined data to be passed to the callback (opaque to the API). useCapture (EM_BOOL) – Set `true` to use capture. 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.
  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | `EMSCRIPTEN_RESULT`

EMSCRIPTEN_RESULT `emscripten_get_fullscreen_status`(EmscriptenFullscreenChangeEvent *fullscreenStatus)

  Returns the current page fullscreen state.

  Parameters: | fullscreenStatus (EmscriptenFullscreenChangeEvent*) – The most recently received fullscreen state.
  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | `EMSCRIPTEN_RESULT`

EMSCRIPTEN_RESULT `emscripten_request_fullscreen`(const char *target, EM_BOOL deferUntilInEventHandler)

  Requests the given target element to transition to full screen mode.

  Note

  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.

  Parameters: | target (const char*) – Target HTML element id. 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.
  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | EMSCRIPTEN_RESULT

EMSCRIPTEN_RESULT `emscripten_exit_fullscreen`(void)

  Returns back to windowed browsing mode.

  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | `EMSCRIPTEN_RESULT`

## Pointerlock

### Defines

`EMSCRIPTEN_EVENT_POINTERLOCKCHANGE`

  Emscripten pointerlockchange events.

### Struct

`EmscriptenPointerlockChangeEvent`

  The event structure passed in the pointerlockchange event.

  EM_BOOL `isActive`

    Specifies whether an element on the browser page currently has pointer lock enabled.

  EM_UTF8 `nodeName`

    The nodeName of the target HTML Element that has the pointer lock active.

    Maximum size 128 `char` (i.e. `EM_UTF8 nodeName[128]`).

  EM_UTF8 `id`

    The ID of the target HTML element that has the pointer lock active.

    Maximum size 128 `char` (i.e. `EM_UTF8 id[128]`).

### Callback functions

`em_pointerlockchange_callback_func`

  Function pointer for the `pointerlockchange event callback functions`, defined as:

      typedef EM_BOOL (*em_pointerlockchange_callback_func)(int eventType, const EmscriptenPointerlockChangeEvent *keyEvent, void *userData);

  Parameters: | eventType (int) – The type of pointerlockchange event (`EMSCRIPTEN_EVENT_POINTERLOCKCHANGE`). keyEvent (const EmscriptenPointerlockChangeEvent*) – Information about the pointerlockchange event that occurred. userData (void*) – The `userData` originally passed to the registration function.
  Returns: | `true` (non zero) to indicate that the event was consumed by the callback handler.
  Return type: | `EM_BOOL`

### Functions

EMSCRIPTEN_RESULT `emscripten_set_pointerlockchange_callback`(const char *target, void *userData, EM_BOOL useCapture, em_pointerlockchange_callback_func callback)

  Registers a callback function for receiving the pointerlockchange event.

  Pointer lock hides the mouse cursor and exclusively gives the target element relative mouse movement events via the mousemove event.

  Parameters: | target (const char*) – Target HTML element id. userData (void*) – User-defined data to be passed to the callback (opaque to the API). useCapture (EM_BOOL) – Set `true` to use capture. 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.
  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | `EMSCRIPTEN_RESULT`

EMSCRIPTEN_RESULT `emscripten_get_pointerlock_status`(EmscriptenPointerlockChangeEvent *pointerlockStatus)

  Returns the current page pointerlock state.

  Parameters: | pointerlockStatus (EmscriptenPointerlockChangeEvent*) – The most recently received pointerlock state.
  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | `EMSCRIPTEN_RESULT`

EMSCRIPTEN_RESULT `emscripten_request_pointerlock`(const char *target, EM_BOOL deferUntilInEventHandler)

  Requests the given target element to grab pointerlock.

  Note

  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.

  Parameters: | target (const char*) – Target HTML element id. 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.
  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | `EMSCRIPTEN_RESULT`

EMSCRIPTEN_RESULT `emscripten_exit_pointerlock`(void)

  Exits pointer lock state and restores the mouse cursor to be visible again.

  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | `EMSCRIPTEN_RESULT`

## Visibility

### Defines

`EMSCRIPTEN_EVENT_VISIBILITYCHANGE`

  Emscripten visibilitychange event.

`EMSCRIPTEN_VISIBILITY_HIDDEN`

  The document is hidden (not visible).

`EMSCRIPTEN_VISIBILITY_VISIBLE`

  The document is at least partially visible.

`EMSCRIPTEN_VISIBILITY_PRERENDER`

  The document is loaded off screen and not visible (prerender).

`EMSCRIPTEN_VISIBILITY_UNLOADED`

  The document is to be unloaded.

### Struct

`EmscriptenVisibilityChangeEvent`

  The event structure passed in the visibilitychange event.

  EM_BOOL `hidden`

    If true, the current browser page is now hidden.

  int `visibilityState`

    Specifies a more fine-grained state of the current page visibility status. One of the `EMSCRIPTEN_VISIBILITY_` values.

### Callback functions

`em_visibilitychange_callback_func`

  Function pointer for the `visibilitychange event callback functions`, defined as:

      typedef EM_BOOL (*em_visibilitychange_callback_func)(int eventType, const EmscriptenVisibilityChangeEvent *keyEvent, void *userData);

  Parameters: | eventType (int) – The type of `visibilitychange` event (`EMSCRIPTEN_VISIBILITY_HIDDEN`). keyEvent (const EmscriptenVisibilityChangeEvent*) – Information about the `visibilitychange` event that occurred. userData (void*) – The `userData` originally passed to the registration function.
  Returns: | `true` (non zero) to indicate that the event was consumed by the callback handler.
  Return type: | `EM_BOOL`

### Functions

EMSCRIPTEN_RESULT `emscripten_set_visibilitychange_callback`(void *userData, EM_BOOL useCapture, em_visibilitychange_callback_func callback)

  Registers a callback function for receiving the visibilitychange event.

  Parameters: | userData (void*) – User-defined data to be passed to the callback (opaque to the API). useCapture (EM_BOOL) – Set `true` to use capture. 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.
  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | `EMSCRIPTEN_RESULT`

EMSCRIPTEN_RESULT `emscripten_get_visibility_status`(EmscriptenVisibilityChangeEvent *visibilityStatus)

  Returns the current page visibility state.

  Parameters: | visibilityStatus (EmscriptenVisibilityChangeEvent*) – The most recently received page visibility state.
  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | `EMSCRIPTEN_RESULT`

## Touch

### Defines

`EMSCRIPTEN_EVENT_TOUCHSTART`
`EMSCRIPTEN_EVENT_TOUCHEND`
`EMSCRIPTEN_EVENT_TOUCHMOVE`
`EMSCRIPTEN_EVENT_TOUCHCANCEL`

  Emscripten touch events.

### Struct

`EmscriptenTouchPoint`

  Specifies the status of a single touch point on the page.

  long `identifier`

    An identification number for each touch point.

  long `screenX`
  long `screenY`

    The touch coordinate relative to the whole screen origin, in pixels.

  long `clientX`
  long `clientY`

    The touch coordinate relative to the viewport, in pixels.

  long `pageX`
  long `pageY`

    The touch coordinate relative to the viewport, in pixels, and including any scroll offset.

  EM_BOOL `isChanged`

    Specifies whether the touch point changed during this event.

  EM_BOOL `onTarget`

    Specifies whether this touch point is still above the original target on which it was initially pressed.

  long `canvasX`
  long `canvasY`

    The touch coordinates mapped to the Emscripten canvas client area, in pixels.

`EmscriptenTouchEvent`

  Specifies the data of a single touchevent.

  int `numTouches`

    The number of valid elements in the touches array.

  EM_BOOL `ctrlKey`
  EM_BOOL `shiftKey`
  EM_BOOL `altKey`
  EM_BOOL `metaKey`

    Specifies which modifiers were active during the touch event.

  `EmscriptenTouchPoint touches[32]`

    An array of currently active touches, one for each finger.

### Callback functions

`em_touch_callback_func`

  Function pointer for the `touch event callback functions`, defined as:

      typedef EM_BOOL (*em_touch_callback_func)(int eventType, const EmscriptenTouchEvent *keyEvent, void *userData);

  Parameters: | eventType (int) – The type of touch event (`EMSCRIPTEN_EVENT_TOUCHSTART`). keyEvent (const EmscriptenTouchEvent*) – Information about the touch event that occurred. userData (void*) – The `userData` originally passed to the registration function.
  Returns: | `true` (non zero) to indicate that the event was consumed by the callback handler.
  Return type: | `EM_BOOL`

### Functions

EMSCRIPTEN_RESULT `emscripten_set_touchstart_callback`(const char *target, void *userData, EM_BOOL useCapture, em_touch_callback_func callback)
EMSCRIPTEN_RESULT `emscripten_set_touchend_callback`(const char *target, void *userData, EM_BOOL useCapture, em_touch_callback_func callback)
EMSCRIPTEN_RESULT `emscripten_set_touchmove_callback`(const char *target, void *userData, EM_BOOL useCapture, em_touch_callback_func callback)
EMSCRIPTEN_RESULT `emscripten_set_touchcancel_callback`(const char *target, void *userData, EM_BOOL useCapture, em_touch_callback_func callback)

  Registers a callback function for receiving touch events : touchstart, touchend, touchmove and touchcancel.

  Parameters: | target (const char*) – Target HTML element id. userData (void*) – User-defined data to be passed to the callback (opaque to the API). useCapture (EM_BOOL) – Set `true` to use capture. 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.
  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | `EMSCRIPTEN_RESULT`

## Gamepad

### Defines

`EMSCRIPTEN_EVENT_GAMEPADCONNECTED`
`EMSCRIPTEN_EVENT_GAMEPADDISCONNECTED`

  Emscripten gamepad events.

### Struct

`EmscriptenGamepadEvent`

  Represents the current snapshot state of a gamepad.

  double `timestamp`

    Absolute wallclock time when the data was recorded (milliseconds).

  int `numAxes`

    The number of valid axis entries in the `axis` array.

  int `numButtons`

    The number of valid button entries in the analogButton and digitalButton arrays.

  `double axis[64]`

    The analog state of the gamepad axes, in the range [-1, 1].

  `double analogButton[64]`

    The analog state of the gamepad buttons, in the range [0, 1].

  `EM_BOOL digitalButton[64]`

    The digital state of the gamepad buttons, either 0 or 1.

  EM_BOOL `connected`

    Specifies whether this gamepad is connected to the browser page.

  long `index`

    An ordinal associated with this gamepad, zero-based.

  EM_UTF8 `id`

    An ID for the brand or style of the connected gamepad device. Typically, this will include the USB vendor and a product ID.

    Maximum size 64 `char` (i.e. `EM_UTF8 id[128]`).

  EM_UTF8 `mapping`

    A string that identifies the layout or control mapping of this device.

    Maximum size 128 `char` (i.e. `EM_UTF8 mapping[128]`).

### Callback functions

`em_gamepad_callback_func`

  Function pointer for the `gamepad event callback functions`, defined as:

      typedef EM_BOOL (*em_gamepad_callback_func)(int eventType, const EmscriptenGamepadEvent *keyEvent, void *userData)

  Parameters: | eventType (int) – The type of gamepad event (`EMSCRIPTEN_EVENT_GAMEPADCONNECTED`). keyEvent (const EmscriptenGamepadEvent*) – Information about the gamepad event that occurred. userData (void*) – The `userData` originally passed to the registration function.
  Returns: | `true` (non zero) to indicate that the event was consumed by the callback handler.
  Return type: | `EM_BOOL`

### Functions

EMSCRIPTEN_RESULT `emscripten_set_gamepadconnected_callback`(void *userData, EM_BOOL useCapture, em_gamepad_callback_func callback)
EMSCRIPTEN_RESULT `emscripten_set_gamepaddisconnected_callback`(void *userData, EM_BOOL useCapture, em_gamepad_callback_func callback)

  Registers a callback function for receiving the gamepad events: gamepadconnected and gamepaddisconnected.

  Parameters: | userData (void*) – User-defined data to be passed to the callback (opaque to the API). useCapture (EM_BOOL) – Set `true` to use capture. 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.
  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | `EMSCRIPTEN_RESULT`

int `emscripten_get_num_gamepads`(void)

  Returns the number of gamepads connected to the system or `EMSCRIPTEN_RESULT_NOT_SUPPORTED` if the current browser does not support gamepads.

  Note

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

  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | int

EMSCRIPTEN_RESULT `emscripten_get_gamepad_status`(int index, EmscriptenGamepadEvent *gamepadState)

  Returns a snapshot of the current gamepad state.

  Parameters: | index (int) – The index of the gamepad to check (in the array of connected gamepads). gamepadState (EmscriptenGamepadEvent*) – The most recently received gamepad state.
  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | `EMSCRIPTEN_RESULT`

## Battery

### Defines

`EMSCRIPTEN_EVENT_BATTERYCHARGINGCHANGE`
`EMSCRIPTEN_EVENT_BATTERYLEVELCHANGE`

  Emscripten batterymanager events.

### Struct

`EmscriptenBatteryEvent`

  The event structure passed in the batterymanager events: `chargingchange` and `levelchange`.

  double `chargingTime`

    Time remaining until the battery is fully charged (seconds).

  double `dischargingTime`

    Time remaining until the battery is empty and the system will be suspended (seconds).

  double `level`

    Current battery level, on a scale of 0 to 1.0.

  `EM_BOOL charging;`

    `true` if the battery is charging, `false` otherwise.

### Callback functions

`em_battery_callback_func`

  Function pointer for the `batterymanager event callback functions`, defined as:

      typedef EM_BOOL (*em_battery_callback_func)(int eventType, const EmscriptenBatteryEvent *keyEvent, void *userData);

  Parameters: | eventType (int) – The type of `batterymanager` event (`EMSCRIPTEN_EVENT_BATTERYCHARGINGCHANGE`). keyEvent (const EmscriptenBatteryEvent*) – Information about the `batterymanager` event that occurred. userData (void*) – The `userData` originally passed to the registration function.
  Returns: | `true` (non zero) to indicate that the event was consumed by the callback handler.
  Return type: | `EM_BOOL`

### Functions

EMSCRIPTEN_RESULT `emscripten_set_batterychargingchange_callback`(void *userData, em_battery_callback_func callback)
EMSCRIPTEN_RESULT `emscripten_set_batterylevelchange_callback`(void *userData, em_battery_callback_func callback)

  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). useCapture (EM_BOOL) – Set `true` to use capture. 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.
  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | `EMSCRIPTEN_RESULT`

EMSCRIPTEN_RESULT `emscripten_get_battery_status`(EmscriptenBatteryEvent *batteryState)

  Returns the current battery status.

  Parameters: | batteryState (EmscriptenBatteryEvent*) – The most recently received battery state.
  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | `EMSCRIPTEN_RESULT`

## Vibration

### Functions

EMSCRIPTEN_RESULT `emscripten_vibrate`(int msecs)

  Produces a vibration for the specified time, in milliseconds.

  Parameters: | msecs (int) – The amount of time for which the vibration is required (milliseconds).
  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | `EMSCRIPTEN_RESULT`

EMSCRIPTEN_RESULT `emscripten_vibrate_pattern`(int *msecsArray, int numEntries)

  Produces a complex vibration feedback pattern.

  Parameters: | msecsArray (int*) – An array of timing entries [on, off, on, off, on, off, ...] where every second one specifies a duration of vibration, and every other one specifies a duration of silence. numEntries (int) – The number of integers in the array `msecsArray`.
  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | `EMSCRIPTEN_RESULT`

## Page unload

### Defines

`EMSCRIPTEN_EVENT_BEFOREUNLOAD`

  Emscripten beforeunload event.

### Callback functions

`em_beforeunload_callback`

  Function pointer for the `beforeunload event callback functions`, defined as:

      typedef const char *(*em_beforeunload_callback)(int eventType, const void *reserved, void *userData);

  Parameters: | eventType (int) – The type of `beforeunload` event (`EMSCRIPTEN_EVENT_BEFOREUNLOAD`). reserved (const void*) – Reserved for future use; pass in 0. userData (void*) – The `userData` originally passed to the registration function.
  Returns: | Return a string to be displayed to the user.
  Return type: | char*

### Functions

EMSCRIPTEN_RESULT `emscripten_set_beforeunload_callback`(void *userData, em_beforeunload_callback callback)

  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.
  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | `EMSCRIPTEN_RESULT`

## WebGL context

### Defines

`EMSCRIPTEN_EVENT_WEBGLCONTEXTLOST`
`EMSCRIPTEN_EVENT_WEBGLCONTEXTRESTORED`

  Emscripten WebGL context events.

### Callback functions

`em_webgl_context_callback`

  Function pointer for the `WebGL Context event callback functions`, defined as:

      typedef EM_BOOL (*em_webgl_context_callback)(int eventType, const void *reserved, void *userData);

  Parameters: | eventType (int) – The type of `WebGL context event`. reserved (const void*) – Reserved for future use; pass in 0. userData (void*) – The `userData` originally passed to the registration function.
  Returns: | `true` (non zero) to indicate that the event was consumed by the callback handler.
  Return type: | `EM_BOOL`

### Functions

EMSCRIPTEN_RESULT `emscripten_set_webglcontextlost_callback`(const char *target, void *userData, EM_BOOL useCapture, em_webgl_context_callback callback)
EMSCRIPTEN_RESULT `emscripten_set_webglcontextrestored_callback`(const char *target, void *userData, EM_BOOL useCapture, em_webgl_context_callback callback)

  Registers a callback function for the canvas WebGL context events: `webglcontextlost` and `webglcontextrestored`.

  Parameters: | target (const char*) – Target HTML element id. userData (void*) – User-defined data to be passed to the callback (opaque to the API). useCapture (EM_BOOL) – Set `true` to use capture. 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.
  Returns: | `EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values.
  Return type: | `EMSCRIPTEN_RESULT`

EM_BOOL `emscripten_is_webgl_context_lost`(const char *target)

  Queries the given canvas element for whether its WebGL context is in a lost state.

  Parameters: | target (const char*) – Reserved for future use, pass in 0.
  Returns: | `true` if the WebGL context is in a lost state.
  Return type: | `EM_BOOL`