Class ui.panel.ButtonBar

ButtonBar panel for displaying an interactive horizontal row of buttons.

This class creates a fixed-height panel (1 line of button content) that renders a set of labelled buttons side by side and tracks which one is currently focused. It is designed as the button row of a dialog: the parent panel owns the event loop and decides which keys navigate or confirm; the ButtonBar exposes navigation methods and get_selection().

To add blank rows above and/or below the buttons, pass a border with a blank format, e.g. border = { format = terminal.draw.box_fmt.blank }. The border is drawn by the Panel base class and the button content occupies only the inner area.

Typical use

Place a ButtonBar as the bottom child of a vertically-split panel whose top child holds the dialog prompt or message. In the parent's key handler, call select_next/select_prev for arrow keys, select_cancel for Escape, and get_selection() when the confirm key (e.g. Enter) is pressed.

Usage:

local ButtonBar = require("terminal.ui.panel.button_bar")

local bar = ButtonBar {
  items = {
    { id = "yes",    label = "Yes" },
    { id = "no",     label = "No" },
    { id = "cancel", label = "Cancel", cancel = true },
  },
  selected = "no",
  attr     = { fg = "white", bg = "blue" },
}

-- Inside the parent's key-dispatch loop:
if key == keys.left   then bar:select_prev() end
if key == keys.right  then bar:select_next() end
if key == keys.escape then bar:select_cancel() end
if key == keys.enter  then
  local id = bar:get_selection()
  -- act on id
end

Tables

Confirm.ids Response ID constants.
Confirm.sets Preset item sets.

Methods

ui.panel.buttonbar:get_selection () Get the id of the currently focused button.
ui.panel.buttonbar:init (opts) Create a new ButtonBar instance.
ui.panel.buttonbar:preferred_min_width () Returns the preferred minimum outer width.
ui.panel.buttonbar:select (id) Move focus to the button with the given id.
ui.panel.buttonbar:select_cancel () Move focus to the cancel-marked button.
ui.panel.buttonbar:select_next () Move focus to the next (right) button.
ui.panel.buttonbar:select_prev () Move focus to the previous (left) button.


Tables

Confirm.ids
Response ID constants. Plain strings used as value fields in the preset sets. Copy of cli.Confirm.ids.
Confirm.sets
Preset item sets. Each is an array, where the values are has tables; {label, value, cancel?}. These are ready to pass as opts.items, as the most common sets. Copy of cli.Confirm.sets.

Methods

ui.panel.buttonbar:get_selection ()
Get the id of the currently focused button.

Returns:

    any The focused button id.
ui.panel.buttonbar:init (opts)
Create a new ButtonBar instance. Do not call this method directly, call on the class instead. See example.

Parameters:

  • opts Configuration options (see Panel:init for inherited properties).
    • items table Array of button items. Each entry must have a label field (string) and may have an id field (any; defaults to the item's index) and a cancel field (boolean; marks this button as the cancel action). At most one item may carry cancel = true.
    • selected any Id of the button that receives initial focus. Defaults to the first item. (optional)
    • prefix string String prepended to every button label when rendered. Default "[". (optional)
    • postfix string String appended to every button label when rendered. Default "]". (optional)
    • padding number Number of spaces rendered between adjacent buttons. (default 1)
    • button_min_width number Minimum display-column width for each button cell (prefix + label + postfix combined). Cells are padded with spaces when the content is shorter. (optional)
    • button_max_width number Maximum display-column width for each button cell (prefix + label + postfix combined). Labels that exceed this are truncated with an ellipsis via text.width.truncate_ellipsis. (optional)
    • auto_render boolean When true, automatically re-renders the panel whenever the selection changes via select, select_next, select_prev, or select_cancel. (default false)
    • attr table Text attributes applied to the entire bar background, including the spaces between and around buttons (e.g. { fg = "white", bg = "blue" }). (optional)
    • button_attr table Text attributes applied to unselected buttons. When omitted and opts.attr is provided, derived automatically by inverting the reverse field of opts.attr. (optional)
    • selected_attr table Text attributes applied to the focused button. When omitted, derived automatically by inverting the reverse field of opts.button_attr. (optional)

Returns:

    ButtonBar A new ButtonBar instance.

Usage:

    local ButtonBar = require("terminal.ui.panel.button_bar")
local bar = ButtonBar {
  items = {
    { label = "OK" },
    { label = "Cancel", cancel = true },
  },
}
ui.panel.buttonbar:preferred_min_width ()
Returns the preferred minimum outer width. At this width all buttons render at their maximum display size with the least truncation. Includes any border width overhead. Can be used by parent dialogs to compute their own preferred width.

Returns:

    number The preferred minimum outer width in columns.
ui.panel.buttonbar:select (id)
Move focus to the button with the given id. Re-renders when auto_render is true and the selection changed.

Parameters:

  • id any The id of the button to focus.

Returns:

  1. any The id of the currently focused button after the operation.
  2. string An error message when the given id does not exist in the items.
ui.panel.buttonbar:select_cancel ()
Move focus to the cancel-marked button. Useful when the parent receives an Escape key press. Always returns the currently focused button id (first return is always truthy). The second return value signals whether the move was successful: it is nil on success and an error string when no cancel button is defined (in which case focus does not move). Re-renders when auto_render is true and the selection changed.

Returns:

  1. any The id of the currently focused button after the operation.
  2. string "no cancel button" when no item is marked with cancel = true.
ui.panel.buttonbar:select_next ()
Move focus to the next (right) button. Has no effect when the last button is already focused; does not wrap around. Re-renders when auto_render is true and the selection changed.

Returns:

    any The id of the currently focused button after the operation.
ui.panel.buttonbar:select_prev ()
Move focus to the previous (left) button. Has no effect when the first button is already focused; does not wrap around. Re-renders when auto_render is true and the selection changed.

Returns:

    any The id of the currently focused button after the operation.
generated by LDoc 1.5.0