Module emscripten
emscripten API.
Description
The functions in this module broadly reflect emscripten’s API and obviously are only implemented for the emscripten platform.
See Emscripten’s API documentation for more information about these APIs.
The counterpart of functions defined in this module are two main Javascript functions that can be used to send messages to Erlang.
Module.cast('some_proc', 'message')
await Module.call('some_proc', 'message')
These respectively send the following messages to Erlang process registered as some_proc:
{emscripten, {cast, <<"message">>}}
{emscripten, {call, Promise, <<"message">>}}
Promise should be passed to promise_resolve/1,2 or promise_reject/1,2 as
documented below.
Data Types
focus_event()
focus_event() = #{node_name => unicode:unicode_binary(), id => unicode:unicode_binary()}
html5_target()
html5_target() = window | document | screen | iodata()
keyboard_event()
keyboard_event() = #{timestamp => float(), location => integer(), ctrl_key => boolean(), shift_key => boolean(), alt_key => boolean(), meta_key => boolean(), repeat => boolean(), char_code => integer(), key_code => integer(), which => integer(), key => unicode:unicode_binary(), code => unicode:unicode_binary(), char_value => unicode:unicode_binary(), locale => unicode:unicode_binary()}
listener_handle()
abstract datatype: listener_handle()
mouse_event()
mouse_event() = #{timestamp => float(), screen_x => integer(), screen_y => integer(), client_x => integer(), client_y => integer(), ctrl_key => boolean(), shift_key => boolean(), alt_key => boolean(), meta_key => boolean(), button => integer(), buttons => integer(), movement_x => integer(), movement_y => integer(), target_x => integer(), target_y => integer(), padding => integer()}
promise()
abstract datatype: promise()
register_error_reason()
register_error_reason() = not_supported | failed_not_deferred | invalid_target | unknown_target | failed | no_data | timed_out | integer()
register_option()
register_option() = {use_capture, boolean()} | {prevent_default, boolean()}
register_options()
register_options() = boolean() | [register_option()]
register_result()
register_result() = {ok, listener_handle()} | {ok, listener_handle(), deferred} | {error, register_error_reason()}
run_script_opt()
run_script_opt() = main_thread | async
touch_event()
touch_event() = #{timestamp => float(), ctrl_key => boolean(), shift_key => boolean(), alt_key => boolean(), meta_key => boolean(), touches => [touch_point()]}
touch_point()
touch_point() = #{identifier => integer(), screen_x => integer(), screen_y => integer(), client_x => integer(), client_y => integer(), page_x => integer(), page_y => integer(), is_changed => boolean(), on_target => boolean(), target_x => integer(), target_y => integer()}
ui_event()
ui_event() = #{detail => integer(), document_body_client_width => integer(), document_body_client_height => integer(), window_inner_width => integer(), window_inner_height => integer(), window_outer_width => integer(), window_outer_height => integer(), scroll_top => integer(), scroll_left => integer()}
wheel_event()
wheel_event() = #{timestamp => float(), screen_x => integer(), screen_y => integer(), client_x => integer(), client_y => integer(), ctrl_key => boolean(), shift_key => boolean(), alt_key => boolean(), meta_key => boolean(), button => integer(), buttons => integer(), movement_x => integer(), movement_y => integer(), target_x => integer(), target_y => integer(), padding => integer(), delta_x => integer(), delta_y => integer(), delta_z => integer(), delta_mode => integer()}
Function Index
Function Details
promise_reject/1
promise_reject(Promise::promise()) -> ok
Equivalent to promise_reject(_Promise, 0).
promise_reject/2
promise_reject(_Promise::promise(), _Value::integer() | iodata()) -> ok
_Promise: Opaque promise resource_Value: Value to send to Javascript, must be an integer or a string.
Reject a promise with a given result.
This is similar to promise_resolve except the promise is rejected.
promise_resolve/1
promise_resolve(Promise::promise()) -> ok
Equivalent to promise_resolve(_Promise, 0).
promise_resolve/2
promise_resolve(_Promise::promise(), _Value::integer() | iodata()) -> ok
_Promise: Opaque promise resource_Value: Value to send to Javascript, must be an integer or a string.
Successfully resolve a promise with a given result.
A promise is currently only obtained through synchronous calls using
Module.call() javascript function.
If Javascript calls:
await Module.call('some_proc', 'message')
and if an Erlang process is registered as some_proc, then the process
will receive a message:
{emscripten, {call, Promise, <<"message">>}}
and the Javascript caller will wait until promise_resolve or promise_reject
is called. If the process doesn’t exist, the promise will be rejected with
‘no_proc’. Likewise if the Promise is garbage collected by the Erlang VM.
register_blur_callback/1
register_blur_callback(Target::html5_target()) -> register_result()
Equivalent to register_blur_callback(_Target, []).
register_blur_callback/2
register_blur_callback(Target::html5_target(), Options::register_options()) -> register_result()
Register for blur events. Events are sent as:
{emscripten, {blur, focus_event()}}
See also: register_keypress_callback/2.
register_blur_callback/3
register_blur_callback(Target::html5_target(), Options::register_options(), UserData::any()) -> register_result()
Register for blur events. Events are sent as:
{emscripten, {blur, focus_event()}, UserData}
See also: register_keypress_callback/2.
register_click_callback/1
register_click_callback(Target::html5_target()) -> register_result()
Equivalent to register_click_callback(_Target, []).
register_click_callback/2
register_click_callback(Target::html5_target(), Options::register_options()) -> register_result()
Register for click events. Events are sent as:
{emscripten, {click, mouse_event()}}
See also: register_keypress_callback/2.
register_click_callback/3
register_click_callback(Target::html5_target(), Options::register_options(), UserData::any()) -> register_result()
Register for click events. Events are sent as:
{emscripten, {click, mouse_event()}, UserData}
See also: register_keypress_callback/2.
register_dblclick_callback/1
register_dblclick_callback(Target::html5_target()) -> register_result()
Equivalent to register_dblclick_callback(_Target, []).
register_dblclick_callback/2
register_dblclick_callback(Target::html5_target(), Options::register_options()) -> register_result()
Register for dblclick events.
See also: register_click_callback/2.
register_dblclick_callback/3
register_dblclick_callback(Target::html5_target(), Options::register_options(), UserData::any()) -> register_result()
Register for dblclick events.
See also: register_click_callback/2.
register_focus_callback/1
register_focus_callback(Target::html5_target()) -> register_result()
Equivalent to register_focus_callback(_Target, []).
register_focus_callback/2
register_focus_callback(Target::html5_target(), Options::register_options()) -> register_result()
Register for focus events.
See also: register_blur_callback/2.
register_focus_callback/3
register_focus_callback(Target::html5_target(), Options::register_options(), UserData::any()) -> register_result()
Register for focus events.
See also: register_blur_callback/2.
register_focusin_callback/1
register_focusin_callback(Target::html5_target()) -> register_result()
Equivalent to register_focusin_callback(_Target, []).
register_focusin_callback/2
register_focusin_callback(Target::html5_target(), Options::register_options()) -> register_result()
Register for focusin events.
See also: register_blur_callback/2.
register_focusin_callback/3
register_focusin_callback(Target::html5_target(), Options::register_options(), UserData::any()) -> register_result()
Register for focusin events.
See also: register_blur_callback/2.
register_focusout_callback/1
register_focusout_callback(Target::html5_target()) -> register_result()
Equivalent to register_focusout_callback(_Target, []).
register_focusout_callback/2
register_focusout_callback(Target::html5_target(), Options::register_options()) -> register_result()
Register for focusout events.
See also: register_blur_callback/2.
register_focusout_callback/3
register_focusout_callback(Target::html5_target(), Options::register_options(), UserData::any()) -> register_result()
Register for focusout events.
See also: register_blur_callback/2.
register_keydown_callback/1
register_keydown_callback(Target::html5_target()) -> register_result()
Equivalent to register_keydown_callback(_Target, []).
register_keydown_callback/2
register_keydown_callback(Target::html5_target(), Options::register_options()) -> register_result()
Register for keydown events.
See also: register_keypress_callback/2.
register_keydown_callback/3
register_keydown_callback(Target::html5_target(), Options::register_options(), UserData::any()) -> register_result()
Register for keydown events.
See also: register_keypress_callback/2.
register_keypress_callback/1
register_keypress_callback(Target::html5_target()) -> register_result()
Equivalent to register_keypress_callback(_Target, []).
register_keypress_callback/2
register_keypress_callback(Target::html5_target(), Options::register_options()) -> register_result()
Register for keypress events. This function registers with no user data and events are sent as:
{emscripten, {keypress, keyboard_event()}}
See also: register_keypress_callback/3.
register_keypress_callback/3
register_keypress_callback(_Target::html5_target(), _Options::register_options(), _UserData::any()) -> register_result()
_Target: target to register keypress on_Options: options for event handling_UserData: user data passed back
Register for keypress events.
This function registers keypress events on a given target.
Target can be specified as special atoms window for Javascript’s window,
document for window.document. screen is also supported, but it doesn’t
seem to work, see https://github.com/emscripten-core/emscripten/issues/19865
Second parameter specifies options which can be a boolean() to match
useCapture in Emscripten’s API. Alternatively, the option can be a proplist()
with use_capture and prevent_default keys. prevent_default determines
what the handler should return to Javascript, true meaning that the default
should be prevented.
Third parameter is user data that is passed back. Indeed, when an event occurs, the following message is sent to the process that registered the event:
{emscripten, {keypress, keyboard_event()}, UserData}
The function eventually returns a listener_handle() or an error. The
handler is an opaque resource that actually contains a copy of UserData.
Please note that if the calling process dies, the callback and any callback
for the same event on the same target are unregistered.
register_keyup_callback/1
register_keyup_callback(Target::html5_target()) -> register_result()
Equivalent to register_keyup_callback(_Target, []).
register_keyup_callback/2
register_keyup_callback(Target::html5_target(), Options::register_options()) -> register_result()
Register for keyup events.
See also: register_keypress_callback/2.
register_keyup_callback/3
register_keyup_callback(Target::html5_target(), Options::register_options(), UserData::any()) -> register_result()
Register for keyup events.
See also: register_keypress_callback/2.
register_mousedown_callback/1
register_mousedown_callback(Target::html5_target()) -> register_result()
Equivalent to register_mousedown_callback(_Target, []).
register_mousedown_callback/2
register_mousedown_callback(Target::html5_target(), Options::register_options()) -> register_result()
Register for mousedown events.
See also: register_click_callback/2.
register_mousedown_callback/3
register_mousedown_callback(Target::html5_target(), Options::register_options(), UserData::any()) -> register_result()
Register for mousedown events.
See also: register_click_callback/2.
register_mouseenter_callback/1
register_mouseenter_callback(Target::html5_target()) -> register_result()
Equivalent to register_mouseenter_callback(_Target, []).
register_mouseenter_callback/2
register_mouseenter_callback(Target::html5_target(), Options::register_options()) -> register_result()
Register for mouseenter events.
See also: register_click_callback/2.
register_mouseenter_callback/3
register_mouseenter_callback(Target::html5_target(), Options::register_options(), UserData::any()) -> register_result()
Register for mouseenter events.
See also: register_click_callback/2.
register_mouseleave_callback/1
register_mouseleave_callback(Target::html5_target()) -> register_result()
Equivalent to register_mouseleave_callback(_Target, []).
register_mouseleave_callback/2
register_mouseleave_callback(Target::html5_target(), Options::register_options()) -> register_result()
Register for mouseleave events.
See also: register_click_callback/2.
register_mouseleave_callback/3
register_mouseleave_callback(Target::html5_target(), Options::register_options(), UserData::any()) -> register_result()
Register for mouseleave events.
See also: register_click_callback/2.
register_mousemove_callback/1
register_mousemove_callback(Target::html5_target()) -> register_result()
Equivalent to register_mousemove_callback(_Target, []).
register_mousemove_callback/2
register_mousemove_callback(Target::html5_target(), Options::register_options()) -> register_result()
Register for mousemove events.
See also: register_click_callback/2.
register_mousemove_callback/3
register_mousemove_callback(Target::html5_target(), Options::register_options(), UserData::any()) -> register_result()
Register for mousemove events.
See also: register_click_callback/2.
register_mouseout_callback/1
register_mouseout_callback(Target::html5_target()) -> register_result()
Equivalent to register_mouseout_callback(_Target, []).
register_mouseout_callback/2
register_mouseout_callback(Target::html5_target(), Options::register_options()) -> register_result()
Register for mouseout events.
See also: register_click_callback/2.
register_mouseout_callback/3
register_mouseout_callback(Target::html5_target(), Options::register_options(), UserData::any()) -> register_result()
Register for mouseout events.
See also: register_click_callback/2.
register_mouseover_callback/1
register_mouseover_callback(Target::html5_target()) -> register_result()
Equivalent to register_mouseover_callback(_Target, []).
register_mouseover_callback/2
register_mouseover_callback(Target::html5_target(), Options::register_options()) -> register_result()
Register for mouseover events.
See also: register_click_callback/2.
register_mouseover_callback/3
register_mouseover_callback(Target::html5_target(), Options::register_options(), UserData::any()) -> register_result()
Register for mouseover events.
See also: register_click_callback/2.
register_mouseup_callback/1
register_mouseup_callback(Target::html5_target()) -> register_result()
Equivalent to register_mouseup_callback(_Target, []).
register_mouseup_callback/2
register_mouseup_callback(Target::html5_target(), Options::register_options()) -> register_result()
Register for mouseup events.
See also: register_click_callback/2.
register_mouseup_callback/3
register_mouseup_callback(Target::html5_target(), Options::register_options(), UserData::any()) -> register_result()
Register for mouseup events.
See also: register_click_callback/2.
register_resize_callback/1
register_resize_callback(Target::html5_target()) -> register_result()
Equivalent to register_resize_callback(_Target, []).
register_resize_callback/2
register_resize_callback(Target::html5_target(), Options::register_options()) -> register_result()
Register for resize events. Events are sent as:
{emscripten, {resize, ui_event()}}
See also: register_keypress_callback/2.
register_resize_callback/3
register_resize_callback(Target::html5_target(), Options::register_options(), UserData::any()) -> register_result()
Register for resize events. Events are sent as:
{emscripten, {resize, ui_event()}, UserData}
See also: register_keypress_callback/2.
register_scroll_callback/1
register_scroll_callback(Target::html5_target()) -> register_result()
Equivalent to register_scroll_callback(_Target, []).
register_scroll_callback/2
register_scroll_callback(Target::html5_target(), Options::register_options()) -> register_result()
Register for scroll events.
See also: register_resize_callback/2.
register_scroll_callback/3
register_scroll_callback(Target::html5_target(), Options::register_options(), UserData::any()) -> register_result()
Register for scroll events.
See also: register_resize_callback/2.
register_touchcancel_callback/1
register_touchcancel_callback(Target::html5_target()) -> register_result()
Equivalent to register_touchcancel_callback(_Target, []).
register_touchcancel_callback/2
register_touchcancel_callback(Target::html5_target(), Options::register_options()) -> register_result()
Register for touchcancel events.
See also: register_touchstart_callback/2.
register_touchcancel_callback/3
register_touchcancel_callback(Target::html5_target(), Options::register_options(), UserData::any()) -> register_result()
Register for touchcancel events.
See also: register_touchstart_callback/2.
register_touchend_callback/1
register_touchend_callback(Target::html5_target()) -> register_result()
Equivalent to register_touchend_callback(_Target, []).
register_touchend_callback/2
register_touchend_callback(Target::html5_target(), Options::register_options()) -> register_result()
Register for touchend events.
See also: register_touchstart_callback/2.
register_touchend_callback/3
register_touchend_callback(Target::html5_target(), Options::register_options(), UserData::any()) -> register_result()
Register for touchend events.
See also: register_touchstart_callback/2.
register_touchmove_callback/1
register_touchmove_callback(Target::html5_target()) -> register_result()
Equivalent to register_touchmove_callback(_Target, []).
register_touchmove_callback/2
register_touchmove_callback(Target::html5_target(), Options::register_options()) -> register_result()
Register for touchmove events.
See also: register_touchstart_callback/2.
register_touchmove_callback/3
register_touchmove_callback(Target::html5_target(), Options::register_options(), UserData::any()) -> register_result()
Register for touchmove events.
See also: register_touchstart_callback/2.
register_touchstart_callback/1
register_touchstart_callback(Target::html5_target()) -> register_result()
Equivalent to register_touchstart_callback(_Target, []).
register_touchstart_callback/2
register_touchstart_callback(Target::html5_target(), Options::register_options()) -> register_result()
Register for touchstart events. Events are sent as:
{emscripten, {touchstart, touch_event()}}
See also: register_keypress_callback/2.
register_touchstart_callback/3
register_touchstart_callback(Target::html5_target(), Options::register_options(), UserData::any()) -> register_result()
Register for touchstart events. Events are sent as:
{emscripten, {touchstart, touch_event()}, UserData}
See also: register_keypress_callback/2.
register_wheel_callback/1
register_wheel_callback(Target::html5_target()) -> register_result()
Equivalent to register_wheel_callback(_Target, []).
register_wheel_callback/2
register_wheel_callback(Target::html5_target(), Options::register_options()) -> register_result()
Register for wheel events. Events are sent as:
{emscripten, {wheel, wheel_event()}}
See also: register_keypress_callback/2.
register_wheel_callback/3
register_wheel_callback(Target::html5_target(), Options::register_options(), UserData::any()) -> register_result()
Register for wheel events. Events are sent as:
{emscripten, {wheel, mouse_event()}, UserData}
See also: register_keypress_callback/2.
run_script/1
run_script(Script::iodata()) -> ok
Equivalent to run_script(_Script, []).
run_script/2
run_script(_Script::iodata(), _Options::[run_script_opt()]) -> ok
_Script: Script to run_Options: List of options. If main_thread is specified, the script
is run on the main thread. If async, the script is run asynchronously, i.e.
the caller does not wait for completion. Only applies if main_thread is specified.
returns: ok
Run a script. By default, the script is run in the current worker thread, which arguably may not be very useful. Please note that exception handling is disabled, so the script should not throw and should compile, otherwise this will crash the VM.
unregister_blur_callback/1
unregister_blur_callback(TargetOrHandle::html5_target() | listener_handle()) -> ok | {error, register_error_reason()}
Unregister a blur event handler.
See also: unregister_keypress_callback/1.
unregister_click_callback/1
unregister_click_callback(TargetOrHandle::html5_target() | listener_handle()) -> ok | {error, register_error_reason()}
Unregister a click event handler.
See also: unregister_keypress_callback/1.
unregister_dblclick_callback/1
unregister_dblclick_callback(TargetOrHandle::html5_target() | listener_handle()) -> ok | {error, register_error_reason()}
Unregister a dblclick event handler.
See also: unregister_click_callback/1.
unregister_focus_callback/1
unregister_focus_callback(TargetOrHandle::html5_target() | listener_handle()) -> ok | {error, register_error_reason()}
Unregister a focus event handler.
See also: unregister_blur_callback/1.
unregister_focusin_callback/1
unregister_focusin_callback(TargetOrHandle::html5_target() | listener_handle()) -> ok | {error, register_error_reason()}
Unregister a focusin event handler.
See also: unregister_blur_callback/1.
unregister_focusout_callback/1
unregister_focusout_callback(TargetOrHandle::html5_target() | listener_handle()) -> ok | {error, register_error_reason()}
Unregister a focusout event handler.
See also: unregister_blur_callback/1.
unregister_keydown_callback/1
unregister_keydown_callback(TargetOrHandle::html5_target() | listener_handle()) -> ok | {error, register_error_reason()}
Unregister a keydown event handler.
See also: unregister_keypress_callback/1.
unregister_keypress_callback/1
unregister_keypress_callback(_TargetOrHandle::html5_target() | listener_handle()) -> ok | {error, register_error_reason()}
_TargetOrHandle: Target or handle
returns: ok or an error
Unregister a keypress listener.
To match Emscripten’s API, this function can take a target. This function unregisters every keypress listeners on the specified target.
Alternatively, this function can take a listener_handle() returned by
register_keypress_callback/1,2,3. This will still unregister every
keypress listeners on the same target.
Passing a listener_handle() is recommended to avoid surprises and for
memory efficiency. If a handle is passed, it can then be garbage collected.
If a handle is not passed, but the process dies, every keypress listener
on the same target will be unregistered, including listeners that were
later registered. This is a known limitation of the implementation that
favored avoiding memory leaks and crashes.
unregister_keyup_callback/1
unregister_keyup_callback(TargetOrHandle::html5_target() | listener_handle()) -> ok | {error, register_error_reason()}
Unregister a keyup event handler.
See also: unregister_keypress_callback/1.
unregister_mousedown_callback/1
unregister_mousedown_callback(TargetOrHandle::html5_target() | listener_handle()) -> ok | {error, register_error_reason()}
Unregister a mousedown event handler.
See also: unregister_click_callback/1.
unregister_mouseenter_callback/1
unregister_mouseenter_callback(TargetOrHandle::html5_target() | listener_handle()) -> ok | {error, register_error_reason()}
Unregister a mouseenter event handler.
See also: unregister_click_callback/1.
unregister_mouseleave_callback/1
unregister_mouseleave_callback(TargetOrHandle::html5_target() | listener_handle()) -> ok | {error, register_error_reason()}
Unregister a mouseleave event handler.
See also: unregister_click_callback/1.
unregister_mousemove_callback/1
unregister_mousemove_callback(TargetOrHandle::html5_target() | listener_handle()) -> ok | {error, register_error_reason()}
Unregister a mousemove event handler.
See also: unregister_click_callback/1.
unregister_mouseout_callback/1
unregister_mouseout_callback(TargetOrHandle::html5_target() | listener_handle()) -> ok | {error, register_error_reason()}
Unregister a mouseout event handler.
See also: unregister_click_callback/1.
unregister_mouseover_callback/1
unregister_mouseover_callback(TargetOrHandle::html5_target() | listener_handle()) -> ok | {error, register_error_reason()}
Unregister a mouseover event handler.
See also: unregister_click_callback/1.
unregister_mouseup_callback/1
unregister_mouseup_callback(TargetOrHandle::html5_target() | listener_handle()) -> ok | {error, register_error_reason()}
Unregister a mouseup event handler.
See also: unregister_click_callback/1.
unregister_resize_callback/1
unregister_resize_callback(TargetOrHandle::html5_target() | listener_handle()) -> ok | {error, register_error_reason()}
Unregister a resize event handler.
See also: unregister_keypress_callback/1.
unregister_scroll_callback/1
unregister_scroll_callback(TargetOrHandle::html5_target() | listener_handle()) -> ok | {error, register_error_reason()}
Unregister a scroll event handler.
See also: unregister_resize_callback/1.
unregister_touchcancel_callback/1
unregister_touchcancel_callback(TargetOrHandle::html5_target() | listener_handle()) -> ok | {error, register_error_reason()}
Unregister a touchcancel event handler.
See also: unregister_touchstart_callback/1.
unregister_touchend_callback/1
unregister_touchend_callback(TargetOrHandle::html5_target() | listener_handle()) -> ok | {error, register_error_reason()}
Unregister a touchend event handler.
See also: unregister_touchstart_callback/1.
unregister_touchmove_callback/1
unregister_touchmove_callback(TargetOrHandle::html5_target() | listener_handle()) -> ok | {error, register_error_reason()}
Unregister a touchmove event handler.
See also: unregister_touchstart_callback/1.
unregister_touchstart_callback/1
unregister_touchstart_callback(TargetOrHandle::html5_target() | listener_handle()) -> ok | {error, register_error_reason()}
Unregister a touchstart event handler.
See also: unregister_keypress_callback/1.
unregister_wheel_callback/1
unregister_wheel_callback(TargetOrHandle::html5_target() | listener_handle()) -> ok | {error, register_error_reason()}
Unregister a wheel event handler.
See also: unregister_keypress_callback/1.