Event objects¶
Callbacks registered with Document.on receive one dict per event. The host
creates it after native dispatch; the SDK adds window_id and document_id.
Common members¶
| Member | Type | Meaning |
|---|---|---|
type |
str |
Event type, e.g. "click". |
element |
str |
id of the nearest element with an id, starting at the target ("" if none). |
path |
list[str] |
Ids of the identified elements on the bubbling route, innermost first. For non-bubbling events only the target's entry. |
node |
str |
Node reference of the actual target, usable with document.node(reference=...). |
window_id, document_id |
str |
Where the event happened. |
detail |
int |
Click count for pointer events, else 0. |
cancelable |
bool |
Whether the event has a cancelable default action. |
default_prevented |
bool |
Present when cancelable: whether a prevent_default rule cancelled it. |
shift, ctrl, alt, meta |
bool |
Modifier state. |
Members beginning with _ are internal and may change.
Control state (when the target is a form control)¶
| Member | Meaning |
|---|---|
value |
Current value of an input, textarea or select |
checked |
Checkbox/radio state |
selection |
{"start", "end", "direction"} for text controls (UTF-16 offsets) |
files |
Selected files of an <input type="file"> |
Type-specific members (present when they apply)¶
| Member | Events |
|---|---|
key, code, repeat, is_composing |
keydown, keyup: key is the logical key: the character for printable keys ("a", "A"), otherwise a key name such as "Enter", "Escape", "Tab", "ArrowDown", "Space"; code names the physical key ("KeyA", "Enter") |
data, input_type |
beforeinput, input, composition events |
x, y, button, buttons |
pointer, mouse and wheel events (x/y in CSS pixels) |
delta_x, delta_y |
wheel |
pointer_id, pointer_type, is_primary, pressure |
pointer events |
related_node, related_element |
mouseover/mouseout/focusin/focusout and similar |
submitter |
submit: id of the button that submitted (if it has one) |
validity |
invalid: {"valid", "message", "flags"} as from Document.validity |
old_state, new_state |
beforetoggle, toggle ("open"/"closed") |
return_value |
close of a <dialog> |
property_name, elapsed_time, pseudo_element |
transition* |
animation_name, elapsed_time, pseudo_element |
animation* |
Event types¶
The host listens for these types on every document and forwards each one; subscribe to the ones you need:
| Group | Types |
|---|---|
| Pointer and mouse | click, dblclick, auxclick, contextmenu, mousedown, mouseup, mousemove, mouseover, mouseout, mouseenter, mouseleave, pointerdown, pointerup, pointermove, pointercancel, gotpointercapture, lostpointercapture, wheel |
| Keyboard and text | keydown, keyup, beforeinput, input, compositionstart, compositionupdate, compositionend |
| Focus | focus, blur, focusin, focusout |
| Forms | change, submit, reset, invalid, select |
| Selection and clipboard | selectionchange, copy, cut, paste |
| Dialogs and popovers | toggle, beforetoggle, cancel, close |
| Scrolling | scroll |
| Transitions and animations | transitionrun, transitionstart, transitionend, transitioncancel, animationstart, animationiteration, animationend, animationcancel |
Two further types come from the host rather than the DOM:
| Type | Members | When |
|---|---|---|
link_activated |
element, href, url (resolved, or None), node |
A link (<a href>) was activated. Documents never navigate; handle this event, e.g. with Application.open_external. |
environment_changed |
environment |
The desktop preferences changed the document's media environment. |
And the SDK's own error type: {"type": "error", "message", "fatal"} for document.error
notifications (see Document errors).
Programmatic changes do not fire events¶
set_value, set_checked, set_text and the other mutation methods change the DOM without
firing input, change or similar events; they model a script assignment, not user input.
request_submit, reset_form, show_dialog/close_dialog and the popover methods do fire their
events (submit/invalid, reset, beforetoggle/toggle/close). If your handler must also
run after a programmatic change, call it yourself.
Delegation example¶
# <ul id="todos"><li id="todo-3"><input id="todo-3-done" type="checkbox"> ...
# <button id="todo-3-delete">Delete</button></li></ul>
def on_click(event):
# A click on the Delete button: element == "todo-3-delete",
# path == ["todo-3-delete", "todo-3", "todos", ...]
if event["element"].endswith("-delete"):
delete(int(event["element"].split("-")[1]))
def on_change(event):
if event["element"].endswith("-done"):
set_done(int(event["element"].split("-")[1]), event["checked"])
document.on("click", on_click, element="todos")
document.on("change", on_change, element="todos")
See events and callbacks for threading and ordering.
Source: nativehtmlkit-python/docs/reference/events.md ยท edit the page there.