# ZButton

- Button with text “Button”

- in focused state

- in disabled state

- 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.

## Example

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

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

## Keyboard Usage

Key | Result
--- | ---
`Enter` | Activate the button
`Space` | 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.

## Behavior

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

Palette Color | Usage
--- | ---
`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.

## ZButton

class Tui::ZButton : public Tui::ZWidget

  A button widget.

  Constructors

  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`.

  Functions

  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.

  Signals

  void clicked()

    This signal is emitted when the button is activated.

  Slots

  void click()

    Focus and activate the button.