Button

Wire name button

A push button. It takes focus, activates from pointer or keyboard, and either raises an event, dispatches a command, or both.

new button caption="Save" action=file.save

---

Properties

Property	Type	Default	Meaning
action	action	—	Optional command dispatched on click.
caption	string	—	Display text.
default	flag	false	Default-button styling and Enter behavior.

Plus the common properties.

The caption is painted verbatim. There is no & mnemonic markup here — that belongs to MenuBar, which strips it; a button captioned "&Save" shows the ampersand.

Events

click — The button was activated, by pointer or by keyboard.

Field	Type	Meaning
trinket	uint	The button's object ID.

command — The command named by action= was activated. Raised only when action= is set, and before the click event, so a client may act on either. Carries the command rather than the trinket, because a command is what an application binds to and the same one may be reachable from several places.

Field	Type	Meaning
action	word	The command ID from action=.

command appears only when action= is set, and arrives before click. Both describe the same activation, so subscribe to whichever suits: click tells you this button, command tells you what was asked for — and the same command may be reachable from a menu item and a keyboard shortcut as well.

new button caption="Save" action=file.save

conn.OnCommand("file.save", func() { … })   // however it was reached
ui.Button("save").OnClick(func() { … })     // this button specifically

Keys

Key	Does
Space, Return	Activate.
Esc	Activate, only on a button marked as the cancel button. Otherwise unhandled, and the window sees it.

Keyboard activation shows a 250 ms press animation and fires the click when it finishes, so the button is visibly pressed rather than silently firing. The click callback runs on the platform's main thread — which matters because a handler may close a window, and on macOS SDL window teardown is only legal there.

A default button is drawn as the default and is what Return reaches when focus is elsewhere in the window.

Mouse

Gesture	Does
Press	Take focus, show pressed.
Drag off while held	Drop the pressed look — the click is cancelled.
Drag back on	Pressed again.
Release on the button	Activate.
Release off it	Nothing.

Hover lights the button on a graphical surface.

Behavior

Focus. A button takes focus by Tab and by click.

Disabled. !enabled refuses pointer and keyboard both, and the state is reported to assistive technology rather than only drawn.

Accessibility. Role Button. The caption becomes the accessible name, so acc_name is only needed where the caption is not descriptive — an icon button, or a bare ×.

See also

CheckBox · RadioButton · Common Properties · Events