D Donkeh docs
GitHub

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.

Event classes are additive Existing handlers such as 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.

MemberMeaning
TypeThe normalised event name, for example click or pointerdown.
TargetThe deepest element involved in the interaction.
CurrentTargetThe element whose handler is running. It may be an ancestor when the event bubbles to the nearest handler.
DefaultPreventedSet 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 classExtendsAdds
Event—Type, target, current target and default handling.
MouseEventEventClientX, ClientY, LocalX, LocalY, Button, Modifiers.
ClickEvent, MouseDownEvent, MouseUpEvent, MouseOverEvent, MouseOutEventMouseEventEvent-specific classes for the mouse family.
PointerEventMouseEventThe same position data, typed separately so pointer fields can grow.
PointerDownEvent, PointerMoveEvent, PointerUpEventPointerEventConcrete pointer phases.
ScrollEventEventDeltaX, DeltaY and Modifiers.
InputEvent, ChangeEventEventValue, the current or committed control text.
PasteEventEventText, the pasted text.
SubmitEventEventNo extra fields yet.
KeyDownEventEventKey, Modifiers and the formatted Chord.
FocusEvent, BlurEventEventNo extra fields yet.
MediaEventEventTime, the playback position in seconds.
PlayEvent, PauseEvent, EndedEvent, TimeUpdateEventMediaEventConcrete playback phases.
ContextMenuEventMouseEventX, Y, WindowX, WindowY and the clicked Target.
DragEventMouseEventData, 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.

EventTyped handlerSimple handlerEvent classPayload
clickOnClickEventOnClickClickEventPointer position, button and modifiers.
mousedownOnMouseDownEventOnMouseDownMouseDownEventPointer position, button and modifiers.
mouseupOnMouseUpEventOnMouseUpMouseUpEventPointer position, button and modifiers.
mouseoverOnMouseOverEventOnMouseOverMouseOverEventPointer position and modifiers.
mouseoutOnMouseOutEventOnMouseOutMouseOutEventPointer position and modifiers.
pointerdownOnPointerDownEventOnPointerDownPointerDownEventWindow and element-local coordinates.
pointermoveOnPointerMoveEventOnPointerMovePointerMoveEventWindow and element-local coordinates.
pointerupOnPointerUpEventOnPointerUpPointerUpEventWindow and element-local coordinates.
scrollOnScrollEventOnScrollScrollEventApplied DeltaX and DeltaY in CSS pixels.
contextmenuOnContextMenu—ContextMenuEventClicked target, handling target, local and window coordinates.
dragstartOnDragStart—DragEventShared DataTransfer, source, coordinates and Cancel.
dragOnDrag—DragEventShared DataTransfer, source and coordinates.
dragenterOnDragEnter—DragEventShared DataTransfer, source and coordinates.
dragoverOnDragOver—DragEventShared DataTransfer, source and coordinates.
dragleaveOnDragLeave—DragEventShared DataTransfer, source and coordinates.
dropOnDrop—DragEventShared DataTransfer, source and coordinates.
dragendOnDragEnd—DragEventShared DataTransfer, source and coordinates.
keydownOnKeyDownEventOnKeyDownKeyDownEventKey name, modifier flags and formatted chord.
inputOnInputEventOnInputInputEventCurrent control text.
changeOnChangeEventOnChangeChangeEventCommitted control value.
submitOnSubmitEventOnSubmitSubmitEventNo extra fields. Browser host only.
pasteOnPasteEventOnPastePasteEventPasted text.
focusOnFocusEventOnFocusFocusEventNo extra fields.
blurOnBlurEventOnBlurBlurEventNo extra fields.
playOnPlayEventOnPlayPlayEventPlayback position in Time.
pauseOnPauseEventOnPausePauseEventPlayback position in Time.
endedOnEndedEventOnEndedEndedEventPlayback position in Time.
timeupdateOnTimeUpdateEventOnTimeUpdateTimeUpdateEventCurrent 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 is a browser event The browser host forwards native 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.

EventWhen it fires
dragstartThe pointer moves past the drag threshold on a draggable source. Set Cancel to abandon the drag.
dragThe pointer moves during an active drag, on the source.
dragenterThe pointer first enters a potential drop target.
dragoverThe pointer moves within a potential drop target. Set Data.DropEffect to none to show refusal.
dragleaveThe pointer leaves a potential drop target.
dropThe pointer is released over a target that handles the drag.
dragendThe 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.

FamilyDesktop and AndroidBrowser
click, mousedown, mouseup, mouseover, mouseoutYes, from the native pointer pipeline.Yes, delegated from DOM mouse events.
pointerdown, pointermove, pointerupYes; touch is translated into pointer events.Yes; pointercancel is reported as pointerup.
scrollYes, from wheel and scrollbar drags.Yes, from the element's scroll offset delta.
contextmenuYes, from a right-button press.Yes, from the DOM context-menu event.
Drag familyYes, with dragstart from a draggable ancestor.Not forwarded by the bridge yet.
keydown, input, change, pasteYes, from the focused control.Yes, delegated from DOM events.
focus, blurYes, from the window focus model.Yes, mapped from focusin and focusout.
submitNo native form submission.Yes, from the DOM submit event.
play, pause, ended, timeupdateYes, 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.

EventUse instead
mousemovepointermove
keyup, keypresskeydown
dblclickTrack click timing in a click handler.
wheelscroll; Ctrl+wheel is forwarded as a scroll with the raw direction.
touchstart, touchmove, touchendPointer and mouse events; touch is translated by the native hosts.
focusin, focusoutfocus and blur.
pointercancelpointerup on the browser host.
beforeinput, selectinput and change.
load, error, resizeHost 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.