Events: what the host tells your application¶
Everything the user does in a NativeHTMLKit window is handled by the native host first; the host then reports what happened to the backend as notifications. This page lists every notification and event type that Core 1.0.3 sends, with their fields. It is written for both audiences:
- App developers receive these events through an SDK's event registration API (see the
Python or
PowerShell SDK reference for the exact
calls). The
typenames and fields below are what the SDK hands you. - Client authors receive them as raw wire-v1 frames (protocol reference §8).
Sources: the host's dispatch code and the renderer's event serializer in this repository, plus frames captured from a headless 1.0.3 host. Events that need real input (pointer, keyboard, IME, native drops) cannot be produced in headless mode and were not captured there; their field lists come from the source.
Notifications at a glance¶
| Method | Params | Sent when |
|---|---|---|
document.event |
{window_id, document_id, event} |
a DOM event fired in a document (user input, or a command such as focus, request_submit, show_dialog) |
document.error |
{window_id, document_id, message, fatal?} |
a document-level problem the backend should know about (an event too large for one frame, a failed native drop, a renderer failure — fatal: true means the document was removed) |
window.event |
{window_id, type, data} |
native window changes (below) |
app.shutdown |
{deadline_ms} |
the application is ending; exit before the deadline |
app.activated |
{args, cwd, activation_token} |
the user launched a single-instance app again; args is the second launch's command line |
desktop.preferences_changed |
preferences snapshot | the desktop colour scheme, reduced-motion or high-contrast setting changed |
request.cancelled |
{id, reason} |
a pending host decision (window.before_close) was superseded, e.g. by an app-wide quit |
Two host requests also need an answer ({"allow": true|false}): window.before_close
{window_id, reason} and app.before_quit {reason}. SDKs expose them as close/quit handlers.
Clients must ignore notification types and members they do not know: new ones may be added within v1.
document.event¶
Common members¶
Every DOM event object carries:
| Member | Meaning |
|---|---|
type |
Event type (tables below). |
element |
id of the nearest element with an id on the event path (the target itself if it has one); "" if none. |
path |
Ids of the identified elements on the propagation path, innermost first (only the first one for events that do not bubble, such as focus). |
node |
Generation-checked node reference of the actual target (usable with node-addressed ops). |
detail |
Click count for click/dblclick, else 0. |
cancelable |
Whether the event has a default action. |
default_prevented |
Present when cancelable: whether a set_default_action rule prevented it. |
shift, ctrl, alt, meta |
Modifier state. |
Match targets on element or path. If a click lands on <span id="icon"> inside
<button id="save">, element is "icon" and path is ["icon", "save", …].
Members whose names start with _ (for example _target, _element) are internal bookkeeping:
ignore them; they are not part of the contract.
Depending on the target and type, these members are added:
| Member | When |
|---|---|
value |
target is a form control (text of input/textarea, value of select) |
checked |
target is a checkbox or radio |
selection {start, end, direction} |
target is a text control with a selection |
files |
target is an <input type=file> with chosen files |
related_element, related_node |
focus and mouse over/out/enter/leave events |
key, code, repeat, is_composing |
keyboard events |
data, input_type |
beforeinput, input, composition events |
x, y, button, buttons |
pointer, mouse and wheel events (viewport CSS px) |
pointer_id, pointer_type, is_primary, pressure |
pointer events |
delta_x, delta_y |
wheel |
old_state, new_state |
toggle, beforetoggle ("open"/"closed") |
submitter |
submit |
validity |
invalid (same shape as get_validity) |
return_value |
close of a <dialog> |
property_name, pseudo_element, elapsed_time |
transition events |
animation_name, pseudo_element, elapsed_time |
animation events |
DOM event types¶
| Group | Types |
|---|---|
| Pointer and mouse | click, dblclick, auxclick, contextmenu, mousedown, mouseup, mousemove, mouseover, mouseout, mouseenter, mouseleave, pointerdown, pointerup, pointermove, pointercancel, gotpointercapture, lostpointercapture, wheel |
| Scrolling | scroll |
| Keyboard and text editing | keydown, keyup, beforeinput, input, change, select, selectionchange, copy, cut, paste |
| IME composition | compositionstart, compositionupdate, compositionend |
| Focus | focus, blur, focusin, focusout |
| Forms | submit, reset, invalid |
Dialogs, popovers, <details> |
toggle, beforetoggle, cancel (Escape on a modal dialog), close |
| CSS transitions | transitionrun, transitionstart, transitionend, transitioncancel |
| CSS animations | animationstart, animationiteration, animationend, animationcancel |
Host-generated event types¶
These are not DOM events; they have their own members:
| Type | Members | Meaning |
|---|---|---|
link_activated |
element, href, url (resolved, or null), node |
the user activated an <a href>. The host never navigates; open it yourself (for example desktop.open_external) if you want to. |
dragstart |
element (source id), source, x, y |
in-page drag of an element with draggable="true" began (after 4 CSS px of movement) |
dragover |
element (target id), source, x, y |
the element under the pointer changed during the drag |
drop |
element (target), source |
released over a target |
dragend |
element, source, dropped, target |
always last; Escape or focus loss cancels |
drag_feedback |
phase, accepted, kind (files/text), element, node, x, y, external: true |
a drag from another application entered, moved over a new target or left (transitions only) |
drop (external) |
element, node, x, y, paths or text, external: true |
files (≤1024 local paths) or text dropped from another application onto an element that opted in with data-nativehtmlkit-drop="files text" |
environment_changed |
environment (as get_environment) |
the desktop preferences changed what the document's media queries see |
Default actions¶
Events reach the backend after the host has already acted on the input, so a handler cannot
cancel anything. To stop a default action (a shortcut key, form submission, the context menu, a
dialog's Escape cancel, a popover toggle), register a rule beforehand with the
set_default_action op; the SDKs wrap it. The event then arrives
with default_prevented: true. Example, captured from a headless host:
→ document.command {op: "set_default_action", element: "f", event: "submit"} ← {updated: true}
→ document.command {op: "request_submit", element: "f"}
← document.event {type: "submit", element: "f", path: ["f"], cancelable: true, default_prevented: true, …}
← {submitted: true, default_prevented: true}
What a command emits¶
Commands that behave like user actions emit the matching events before their response; plain state setters do not. Captured from Core 1.0.3:
| Command | Events (in order) |
|---|---|
focus {element: "i"} |
focus, focusin (and blur, focusout on the previously focused element) |
request_submit on a valid form |
submit |
request_submit with an empty required field |
invalid (with validity), then focus, focusin on that control |
reset_form |
reset |
check_validity with failures |
invalid per failing control |
show_dialog {modal: true} |
beforetoggle, focus changes, toggle |
close_dialog {return_value: "ok"} |
beforetoggle, close (with return_value), toggle |
show_popover / hide_popover / toggle_popover |
beforetoggle, toggle |
set_attribute {name: "open"} on <details> |
toggle |
scroll_to that moves |
scroll |
set_control_selection |
select, selectionchange |
replace_control_range |
beforeinput, input, selectionchange |
edit_command {command: "copy"} |
copy |
select_text / clear_selection |
selectionchange |
set_value, set_checked, set_selected_values, set_text, set_environment |
none |
A typical captured frame:
{"jsonrpc":"2.0","method":"document.event","params":{"window_id":"w1","document_id":"d1",
"event":{"type":"invalid","element":"note","path":["note"],"node":"node:1:13:1","detail":0,
"cancelable":true,"default_prevented":false,"value":"","shift":false,"ctrl":false,"alt":false,
"meta":false,"validity":{"valid":false,"flags":{"valueMissing":true,…},"message":"…"}}}}
Delivery guarantees¶
- Events of a document are delivered in order. Events of a document that has since been replaced or
unloaded are dropped, so
document_idin an event always names the document that produced it. - A document queues at most 1024 undelivered events; an event that would not fit in one 2 MiB frame
is replaced by a
document.error. - If the backend stops reading, the host drops
document.eventandwindow.eventnotifications (never responses or host requests) and counts them inhost.diagnostics.dropped_notifications. Keep reading while you work, or move slow work off the reading thread.
window.event¶
{window_id, type, data}. Types sent by Core 1.0.3:
type |
data |
When |
|---|---|---|
close_requested |
{reason} |
a close was requested (title-bar button, OS, or window.request_close with reason: "backend_request"); a window.before_close decision follows after app.ready |
closed |
{} |
the window was destroyed (not sent for the last window when its close starts shutdown) |
focused |
{focused} |
the native window gained or lost keyboard focus |
resized |
{physical_width, physical_height, scale_factor} |
the surface size changed |
scale_changed |
{scale_factor} |
the display scale changed (moved to another monitor, settings) |
key |
{key, state: "pressed"/"released", repeat, physical_key} |
raw native key event (DOM keyboard events are sent as well when a document is loaded) |
dropped_files / dropped_text / text |
{paths} / {text} / {text, cursor, anchor} |
only for the built-in probe surface of a window without a document |
None of these are produced in headless mode except close_requested and closed (from
window.request_close).
Application lifecycle¶
backend host
host.hello ────────────────────────────▶
window.create / document.load ─────────▶
app.ready ─────────────────────────────▶ phase: running
◀──────────────────────────── document.event / window.event …
app.request_quit ──────────────────────▶ (or the user closes the last window)
◀──────────────────────────── app.before_quit {reason} (request)
{"allow": true} ───────────────────────▶
◀──────────────────────────── app.shutdown {deadline_ms}
exit before deadline_ms
app.before_quitreasons:backend_request(fromapp.request_quit) andlast_window(the user closed the last window). Answer{"allow": false}to keep running, e.g. to ask about unsaved work.window.before_closereasons:backend_request(window.request_close) andnative_close(the title-bar button or another OS close request).- There is no host-side deadline for these answers; always answer promptly.
app.shutdownmakes every window and document handle stale. It is also sent when startup is cancelled (the user closed the window beforeapp.ready).app.force_quitfrom the backend, or Ctrl+Shift+Q pressed by the user in a document window, ends the session without asking; the backend is killed and the host exits with status 1.- A second launch of a
single-instance app arrives asapp.activated; the first instance's window is focused where the OS allows it.
Source: nativehtmlkit-core/docs/guides/events.md · edit the page there.