Skip to content

action_handlers

Jump to bottom
Jan Boon edited this page Jul 24, 2026 · 3 revisions

title: Action Handlers and Procedures description: Event wiring, the built-in handler catalog, client conventions and sequences published: true editor: markdown

An action handler ("AH") is a named command. Widgets name them in event attributes, menus and procedures sequence them, links trigger them, Lua calls them. The library ships the widget-support set; applications register their own for everything else.

Wiring and params

onclick_l="set" params_l="dblink=UI:TEMP:X|value=1"
onclick_l="proc:proc_toggle|help"                      <!-- combined "ah:params" form -->

Every event slot is an attribute pair: the handler name and a params string. Params follow the name=value|name=value convention: split on |, first = per segment, keys case-insensitive, whitespace trimmed, no escaping (values cannot contain |). A missing param reads as empty. Some handlers instead treat the whole string as one value (proc, lua, copy_to_clipboard, tree_reset). Handler names must be lower-case.

A handler receives the caller control, so relative targets ("my enclosing window") work; handlers run from Lua or links have a nil/synthetic caller.

Library-provided handlers

Generic:

handler params effect
set value=<expr> + dblink= / target_property= / target=<expr> evaluate an expression, write a database leaf or a reflected property
copy dbsrc=, dbdst= copy a database leaf or whole branch
resize_w elt=, value=, limit= grow/shrink an element's width toward a limit
copy_to_clipboard raw text system clipboard
unlock_all_container — unlock every window
set_transparent / set_alpha container id / target=,alpha= window background alpha
choose_ui_alpha (+cancel, use_global_alpha_settings, lock_unlock) — the per-window transparency editor; requires the define_ui_transparency modal to exist in your XML

Widget-internal (wired automatically; you rarely write these): tab_select, the container buttons ic_open/ic_close/ic_deactive/ic_popup/ic_popin/ic_lock/ic_help, scroll-text repeat buttons gst_add/gst_sub, combo internals combo_box_select_start/combo_box_select_end, spinner sn_up/sn_down, tree_reset.

Client-convention handlers

These names are used by interface data and even referenced by the library itself, but their implementations live in the game client. A standalone application must register equivalents; the widget sample does, and Embedding lists the minimal set with code:

name contract
proc run a procedure; see below for the exact list contract
lua execute the params string as Lua. The library calls this name for setOnDraw scripts, addOnDbChange links and lua_class associations, so without it those features are dead
enter_modal / push_modal / leave_modal group=<id> modal management (there is no pop_modal; leave_modal pops)
active_menu menu=<id>: open a menu at the cursor (right-click context menus)
browse / browse_undo / browse_redo drive an HTML group; links emit browse with name=<html group id>|url=<href>
set_keyboard_focus / reset_keyboard_focus focus an edit box (target=, select_all=)
submit_quick_help every AH invocation is forwarded here (the client's tutorial system listens); unregistered, it warns on every click, so register a no-op
launch_help url=: invoked by the container help button

Procedures

A <proc> is a named sequence of handler calls with argument substitution: the interface's macro facility.

<proc id="proc_toggle">
	<action handler="set" params="target_property=ui:sample:@0:active|value=not(getprop('ui:sample:@0:active'))" />
</proc>

<ctrl ... onclick_l="proc" params_l="proc_toggle|help" />
  • Called via the proc handler with |-separated arguments (no escaping).
  • @0, @1, … substitute the call arguments into each action's params and cond; multi-digit indexes work; a missing argument substitutes empty.
  • cond="expr" on an action skips it when the expression is false (evaluation failure runs the action).
  • Procs nest (handler="proc" inside a proc), and <instance>/<vector> are allowed inside <proc> to stamp action lists from templates.

The @0 contract. The procedure runner receives the whole split parameter list with the procedure name still at index 0, and maps @0 to entry 1. If you are implementing the proc handler yourself, pass the list through unmodified. An implementation that helpfully strips the name shifts every substitution by one and silently breaks every procedure call: the target of proc_toggle|window becomes ui:sample::active and nothing runs. {.is-warning}

Debugging

  • A misspelled handler logs not found action handler : <name>; watch the log, the UI stays silent.
  • The submit_quick_help forwarding means one warning per click until a sink is registered (see above).
  • From the Lua console you can probe interactively: runAH(nil, 'set', 'target_property=...|value=...') bisects between a raw handler call, a direct proc call and the surrounding wiring.

Clone this wiki locally