• _images/button.tpi.e18d26542f.png

    Button with text “Button”

  • _images/button-focus.tpi.ad26ece997.png

    in focused state

  • _images/button-disabled.tpi.2ad2a8dc0a.png

    in disabled state

  • _images/button-default.tpi.98261ea264.png

    as dialog default

A button allows users to trigger actions in the application and is a commonly used widget in dialog boxes. A button can be activated by focusing it and pressing Enter or if set by using a keyboard mnemonic.

In a dialog one button can be setup as default button that can also be activated by pressing Enter in another widget in the same dialog if that widget does not itself use the Enter key.

The key to activate the button is usually shown highlighted when set using markup to set its text.


Tui::ZButton *button = new Tui::ZButton(Tui::withMarkup, "B<m>u</m>tton", dialog);

QObject::connect(button, &Tui::ZButton::clicked, [] { /* ... */ });

Keyboard Usage




Activate the button


Activate the button

Alt + (setup mnemonic)

Activate the button

(setup shortcut)

Activate the button

Also Enter can be used from anywhere in a dialog if the button is a default button and the focused widget does not suppress the usage of Enter to activate the default widget.


Buttons by default accept focus, are one cell high and have a fixed vertical layout policy. The size request of a button is the length of the text plus 6 cells plus the contents margins.

When a button has focus the default widget the dialog can not be activated using Enter.


Palette Color


button.fg, button.bg

Body of the button (active, unfocused, not default button)

button.default.fg, button.default.bg

Body of the button (active, unfocused, default button)

button.focused.fg, button.focused.bg

Body of the button (active, focused)

button.disabled.fg, button.disabled.bg

Body of the button (disabled)

button.shortcut.fg, button.shortcut.bg

Shortcut character in button text.

control.fg, control.bg

Focus markers left and right of the button body.


class Tui::ZButton : public Tui::ZWidget

A button widget.


explicit ZButton(const QString &text, Tui::ZWidget *parent = nullptr)
explicit ZButton(WithMarkupTag, const QString &markup, Tui::ZWidget *parent = nullptr)

Create the button with the given text or markup.


QString text() const
void setText(const QString &t)

Get or set the plain text content of the button.

When set the shortcut is also reset.

When the content of the button was most recently set using setMarkup() the returned text is empty.

QString markup() const
void setMarkup(const QString &m)

Get or set the text content of the button using markup.

When set the shortcut is also reset, if the markup contains a mnemonic it is setup as new shortcut.

When the content of the button was most recently set using setText() the returned markup is empty.

void setShortcut(const Tui::ZKeySequence &key)

Set the given key as shortcut for the button.

void setDefault(bool d)
bool isDefault() const

If the button is the dialog default button is can be activated by Enter even if another widget is focused.

This is only available if the button is used in a dialog (or another widget that exposes the Tui::ZDefaultWidgetManager facet.


void clicked()

This signal is emitted when the button is activated.


void click()

Focus and activate the button.