Event reference
Every host-dispatched event is represented by an event class. Simple
delegates remain available for compact handlers, while typed
On…Event properties and the matching element helpers receive
the full event object with its target, coordinates, value or key data.
OnClick, OnInput,
OnScroll and OnKeyDown keep their simple
signatures. When a typed handler and a simple handler are both set for the
same event, the typed handler wins.
The event object
Event is the base class for every dispatched event. It carries
the data every handler can rely on, and concrete subclasses add payload
specific to the event family.
| Member | Meaning |
|---|---|
Type | The normalised event name, for example click or pointerdown. |
Target | The deepest element involved in the interaction. |
CurrentTarget | The element whose handler is running. It may be an ancestor when the event bubbles to the nearest handler. |
DefaultPrevented | Set when the handler calls PreventDefault(). |
PreventDefault() | Marks the event as handled. Hosts with no built-in default action treat this as advisory. |
StopPropagation() | Records that the handler does not want the event to travel further. Donkeh already invokes only the nearest handler. |
| Event class | Extends | Adds |
|---|---|---|
Event | — | Type, target, current target and default handling. |
MouseEvent | Event | ClientX, ClientY, LocalX, LocalY, Button, Modifiers. |
ClickEvent, MouseDownEvent, MouseUpEvent, MouseOverEvent, MouseOutEvent | MouseEvent | Event-specific classes for the mouse family. |
PointerEvent | MouseEvent | The same position data, typed separately so pointer fields can grow. |
PointerDownEvent, PointerMoveEvent, PointerUpEvent | PointerEvent | Concrete pointer phases. |
ScrollEvent | Event | DeltaX, DeltaY and Modifiers. |
InputEvent, ChangeEvent | Event | Value, the current or committed control text. |
PasteEvent | Event | Text, the pasted text. |
SubmitEvent | Event | No extra fields yet. |
KeyDownEvent | Event | Key, Modifiers and the formatted Chord. |
FocusEvent, BlurEvent | Event | No extra fields yet. |
MediaEvent | Event | Time, the playback position in seconds. |
PlayEvent, PauseEvent, EndedEvent, TimeUpdateEvent | MediaEvent | Concrete playback phases. |
ContextMenuEvent | MouseEvent | X, Y, WindowX, WindowY and the clicked Target. |
DragEvent | MouseEvent | Data, Source and Cancel. |
Registering handlers
There are four equivalent entry points. Typed properties and element helpers
let the compiler infer the event class; On and Attr.On
accept any delegate shape.
using static Donkeh.UILab._;
using static Donkeh.UILab.HtmlHelper;
// Typed property: the lambda receives a ClickEvent.
Button(new Props
{
OnClickEvent = click => Console.WriteLine($"click at {click.LocalX}, {click.LocalY}")
}, Text("Save"));
// Typed element helper.
H("button", Text("Cancel"))
.OnClick(click => Console.WriteLine(click.Type));
// Simple handler for handlers that need no payload.
H("button", Text("Close")).OnClick(() => Close());
// Arbitrary event name. The delegate can be any shape the host dispatches.
H("div").On("click", new Action<ClickEvent>(
click => Console.WriteLine(click.Target?.Key)));
Event names are normalised: onClick, onclick and
click all address the same event. Each element stores one
handler per event name, so registering the same name again replaces the
previous delegate rather than adding a second listener.
All dispatched events
The table below is the complete set of events Donkeh dispatches into the
tree. An event that is not listed can still be registered with
On; it simply has no host dispatcher unless a custom host
raises it.
| Event | Typed handler | Simple handler | Event class | Payload |
|---|---|---|---|---|
click | OnClickEvent | OnClick | ClickEvent | Pointer position, button and modifiers. |
mousedown | OnMouseDownEvent | OnMouseDown | MouseDownEvent | Pointer position, button and modifiers. |
mouseup | OnMouseUpEvent | OnMouseUp | MouseUpEvent | Pointer position, button and modifiers. |
mouseover | OnMouseOverEvent | OnMouseOver | MouseOverEvent | Pointer position and modifiers. |
mouseout | OnMouseOutEvent | OnMouseOut | MouseOutEvent | Pointer position and modifiers. |
pointerdown | OnPointerDownEvent | OnPointerDown | PointerDownEvent | Window and element-local coordinates. |
pointermove | OnPointerMoveEvent | OnPointerMove | PointerMoveEvent | Window and element-local coordinates. |
pointerup | OnPointerUpEvent | OnPointerUp | PointerUpEvent | Window and element-local coordinates. |
scroll | OnScrollEvent | OnScroll | ScrollEvent | Applied DeltaX and DeltaY in CSS pixels. |
contextmenu | OnContextMenu | — | ContextMenuEvent | Clicked target, handling target, local and window coordinates. |
dragstart | OnDragStart | — | DragEvent | Shared DataTransfer, source, coordinates and Cancel. |
drag | OnDrag | — | DragEvent | Shared DataTransfer, source and coordinates. |
dragenter | OnDragEnter | — | DragEvent | Shared DataTransfer, source and coordinates. |
dragover | OnDragOver | — | DragEvent | Shared DataTransfer, source and coordinates. |
dragleave | OnDragLeave | — | DragEvent | Shared DataTransfer, source and coordinates. |
drop | OnDrop | — | DragEvent | Shared DataTransfer, source and coordinates. |
dragend | OnDragEnd | — | DragEvent | Shared DataTransfer, source and coordinates. |
keydown | OnKeyDownEvent | OnKeyDown | KeyDownEvent | Key name, modifier flags and formatted chord. |
input | OnInputEvent | OnInput | InputEvent | Current control text. |
change | OnChangeEvent | OnChange | ChangeEvent | Committed control value. |
submit | OnSubmitEvent | OnSubmit | SubmitEvent | No extra fields. Browser host only. |
paste | OnPasteEvent | OnPaste | PasteEvent | Pasted text. |
focus | OnFocusEvent | OnFocus | FocusEvent | No extra fields. |
blur | OnBlurEvent | OnBlur | BlurEvent | No extra fields. |
play | OnPlayEvent | OnPlay | PlayEvent | Playback position in Time. |
pause | OnPauseEvent | OnPause | PauseEvent | Playback position in Time. |
ended | OnEndedEvent | OnEnded | EndedEvent | Playback position in Time. |
timeupdate | OnTimeUpdateEvent | OnTimeUpdate | TimeUpdateEvent | Current playback position in seconds. |
Mouse and pointer events
Mouse handlers receive window coordinates in ClientX and
ClientY, and coordinates relative to the handling element in
LocalX and LocalY. The legacy
OnPointerDown, OnPointerMove and
OnPointerUp delegates receive the local pair directly.
A click is raised when a primary-button press and release land
on the same element without crossing the drag threshold. Disabled elements
do not raise it. mousedown is raised when the press starts;
mouseup is raised on release, including when the pointer moved
away. mouseover and mouseout track hover changes
for the whole ancestor chain.
Pointer events follow the pressed pointer. pointermove and
pointerup are delivered to the element that captured the
pointer, which keeps drags stable when the pointer leaves the element.
Touch input is translated into the same pointer events by the desktop and
Android hosts. The browser bridge raises pointerup for a
cancelled pointer. When a pointerdown handler captures the
pointer, the mouse press and release are not also dispatched for that
gesture, so choose one family per interaction.
var surface = H("div", new Props
{
ClassName = "surface",
OnPointerDownEvent = down =>
{
Console.WriteLine($"pressed at {down.LocalX}, {down.LocalY}");
},
OnPointerMoveEvent = move =>
{
Console.WriteLine($"moved by {move.ClientX}, {move.ClientY}");
},
OnPointerUpEvent = up =>
{
Console.WriteLine($"released at {up.LocalX}, {up.LocalY}");
}
});
Context menu
contextmenu is the one mouse-family event whose simple
signature is already an event object. Attach
OnContextMenu to a container to treat its children as one
menu area.
Div(new Props
{
ClassName = "file-list",
OnContextMenu = menu =>
{
OpenMenu(menu.Target?.Key, menu.WindowX, menu.WindowY);
menu.PreventDefault();
}
}, rows);
Keyboard, focus and text events
keydown is delivered to the focused element. The simple
handler receives the formatted chord, while KeyDownEvent
exposes the key on its own and the modifier flags separately.
H("input", new Props
{
ClassName = "search",
OnKeyDownEvent = key =>
{
if (key.Key == "Escape")
{
ClearSearch();
}
else if (key.Modifiers == KeyModifiers.Control && key.Key == "K")
{
OpenCommandPalette();
}
}
});
input fires while a text control changes and carries the
current text. change fires when the value is committed: on
Enter or blur for text controls, when a checkbox, radio, range or select
value is finalised. paste carries the pasted text. On the
desktop and Android hosts, a paste handler owns the edit and the host does
not also insert the text; the browser bridge prevents the native paste for
the same reason.
focus is delivered to the element that gained focus.
blur is delivered when focus moves away. The browser bridge
listens to focusin and focusout internally and
maps them to these two names, so application code uses one set of events on
every host.
submit events. The desktop
and Android hosts do not perform native form submission, so call the same
function from a submit button's click handler or from
keydown when a text field receives Enter.
Scroll events
scroll reports the distance in CSS pixels that was actually
applied, positive when scrolling right or down. The event targets the
element under the pointer when a wheel scroll is applied and bubbles to the
nearest ancestor with a handler. On the desktop host, Ctrl+wheel is
forwarded with the raw wheel direction so an application can implement
zoom or brush size instead of scrolling the document.
H("div", new Props
{
ClassName = "scroller",
OnScrollEvent = scroll =>
{
Console.WriteLine($"moved {scroll.DeltaX}px across and {scroll.DeltaY}px down");
}
});
Drag and drop
A drag starts on the nearest ancestor with
Draggable = true after the pointer moves past a small
threshold. Every event in one drag shares the same
DataTransfer. Write a payload in dragstart and
read it in drop.
| Event | When it fires |
|---|---|
dragstart | The pointer moves past the drag threshold on a draggable source. Set Cancel to abandon the drag. |
drag | The pointer moves during an active drag, on the source. |
dragenter | The pointer first enters a potential drop target. |
dragover | The pointer moves within a potential drop target. Set Data.DropEffect to none to show refusal. |
dragleave | The pointer leaves a potential drop target. |
drop | The pointer is released over a target that handles the drag. |
dragend | The drag finishes, whether or not a drop was accepted. |
H("li", new Props
{
Key = file.Id,
Draggable = true,
OnDragStart = drag =>
{
drag.Data.SetData("application/x-file-id", file.Id);
drag.Data.EffectAllowed = "move";
}
}, Text(file.Name));
H("div", new Props
{
ClassName = "drop-zone",
OnDragOver = drag =>
{
drag.Data.DropEffect = drag.Data.HasData("application/x-file-id")
? "move"
: "none";
},
OnDrop = drop =>
{
var id = drop.Data.GetData("application/x-file-id");
if (id is not null)
{
MoveFile(id, drop.LocalX, drop.LocalY);
}
}
});
DragEvent.Data is a mutable DataTransfer shared by
the whole interaction. Formats are arbitrary strings; use a reverse-DNS
media type for private data and text/plain for a readable
fallback. EffectAllowed and DropEffect are
descriptive on the native hosts.
Media events
audio and video elements raise
play, pause, ended and
timeupdate. The media event classes expose the playback
position in seconds. OnAudioReady and
OnVideoReady are lifecycle callbacks, not DOM events: they run
once when the window-side player has been created.
Video(new Props
{
Src = "media/intro.mp4",
Controls = true,
OnPlayEvent = play => Console.WriteLine($"playing from {play.Time}s"),
OnTimeUpdateEvent = update => SeekBar.Value = update.Time,
OnEndedEvent = ended => ShowReplayButton()
});
Host support
The virtual event surface is the same on every host. A few families are produced by different platform mechanisms, and one is browser-only.
| Family | Desktop and Android | Browser |
|---|---|---|
click, mousedown, mouseup, mouseover, mouseout | Yes, from the native pointer pipeline. | Yes, delegated from DOM mouse events. |
pointerdown, pointermove, pointerup | Yes; touch is translated into pointer events. | Yes; pointercancel is reported as pointerup. |
scroll | Yes, from wheel and scrollbar drags. | Yes, from the element's scroll offset delta. |
contextmenu | Yes, from a right-button press. | Yes, from the DOM context-menu event. |
| Drag family | Yes, with dragstart from a draggable ancestor. | Not forwarded by the bridge yet. |
keydown, input, change, paste | Yes, from the focused control. | Yes, delegated from DOM events. |
focus, blur | Yes, from the window focus model. | Yes, mapped from focusin and focusout. |
submit | No native form submission. | Yes, from the DOM submit event. |
play, pause, ended, timeupdate | Yes, from the window media players. | Yes, from native media elements. |
Events that are not exposed
These browser events have no Donkeh dispatcher. Registering a handler for one is still legal, but no built-in host will raise it.
| Event | Use instead |
|---|---|
mousemove | pointermove |
keyup, keypress | keydown |
dblclick | Track click timing in a click handler. |
wheel | scroll; Ctrl+wheel is forwarded as a scroll with the raw direction. |
touchstart, touchmove, touchend | Pointer and mouse events; touch is translated by the native hosts. |
focusin, focusout | focus and blur. |
pointercancel | pointerup on the browser host. |
beforeinput, select | input and change. |
load, error, resize | Host lifecycle and media player callbacks. |
Dispatch and bubbling
Event dispatch walks from the hit element up through its ancestors and
invokes only the first matching handler. There is no capture phase and no
listener list, so an event never fires twice for one element. Registering a
handler for a container therefore acts as a delegating handler for its
children, and Target identifies which child was involved.
Handler exceptions are contained. A throwing application handler cannot tear down the frame loop, which also means a mistake in a handler is silent rather than fatal.