buttonbar — u_pbt_buttonbar #
← Component reference · Guide contents
buttonbar lays out a row of command buttons — icon, label, or both — in one component. A click reports the button id (
ue_clicked); each button is driven by a handle (of_button) to disable, colour or hide it. It is the component to prefer as soon as there are several buttons: one WebView2 for the whole bar, where N separatebuttonwould cost N.
▶ See it live — Demo application, Button bar tile, with the code and this page side by side.
Quick start #
// A command bar in three lines
uo_bar.of_add_button(/*key*/ "save", /*image_file*/ "mono:img\packimages.dll:svg/samples/save", /*text*/ "Save")
uo_bar.of_add_button(/*key*/ "find", /*image_file*/ "mono:img\packimages.dll:svg/samples/find", /*text*/ "Find")
uo_bar.of_add_button(/*key*/ "copy", /*image_file*/ "", /*text*/ "Copy") // no icon
// Grey out a button
uo_bar.of_button(/*key*/ "copy").ib_enabled = false
// React : ue_clicked carries the button key
// (in the ue_clicked event of the component)
CHOOSE CASE as_key
CASE "save" ; wf_save()
CASE "find" ; wf_find()
END CHOOSEProperties #
| Property | Type | Default | Description |
|---|---|---|---|
ii_padding_x | integer | 12 | Left/right inset of the bar, in pixels: the space before the first button and after the last one. 0 presses the buttons to the edges; -1 = the theme's |
ii_padding_y | integer | 12 | Top/bottom inset of the bar, in pixels. A button FILLS the bar's height, so this inset decides how tall the buttons are (a taller bar, or a smaller inset, gives taller buttons). 12 by default; -1 = the theme's |
ii_gap | integer | -1 | Space BETWEEN two buttons, in pixels. -1 (default) = the theme's. 0 joins the buttons, with a separator line between them when the theme has one |
is_align | string | end | Aligns the row: start (left), center, end (right, default, like a dialog) or justify (equal-width buttons across the full width). Logical (RTL-aware) values — ALIGN_* constants |
is_default | string | "" | Key of the default button — the primary action, painted with the accent, that Enter fires (like a dialog's OK). When a button of the bar has the keyboard focus, Enter fires THAT button, which then wears the default look (the Windows convention); is_default still reads back the key you set. A greyed or hidden default does not take Enter: the key stays with the window. When two bars of the same window have a default button (two MDI sheets, two panels), Enter goes to the one on the side of the focus. The role leaves with its button: removing it, or clearing the bar, empties is_default. Empty = none; only one default button at a time |
is_cancel | string | "" | Key of the cancel button — the one Escape fires (like a dialog's Cancel). Greyed or hidden, it does not take Escape. The role leaves with its button: removing it, or clearing the bar, empties is_cancel. Empty = none; only one cancel button at a time |
is_theme_style | string | "" | Visual style of the component (THEME_STYLE_* constants); empty = the application's, followed at every change |
is_theme_mode | string | "" | Light or dark variant (THEME_MODE_* constants); empty = the application's, followed at every change |
il_theme_accent | long | -1 | Accent colour of this component (-1 = the application accent, or the theme's) |
is_tooltip | string | "" | Simple tooltip shown when hovering the component |
is_super_tooltip_title | string | "" | Title of the rich tooltip (takes precedence over is_tooltip) |
is_super_tooltip_text | string | "" | Text of the rich tooltip (rich markup accepted) |
is_super_tooltip_image | string | "" | Image of the rich tooltip |
Methods #
| Method | Role |
|---|---|
of_add_button (string as_key, string as_image_file, string as_text) → long | Adds a command button (id, image file, label) at the end of the bar. mono: on the image recolours it to the theme; an empty label makes an icon-only button. Returns 0, -5 on an empty key, a key holding / or a vertical bar, a key already in the bar, or a button with neither image nor text |
of_insert_button (string as_key, integer ai_index, string as_image_file, string as_text) → long | Inserts a command button at position ai_index (1 based), shifting the rest right. Returns 0, -5 on an empty key, a key holding / or a vertical bar, a key already in the bar, or a button with neither image nor text |
of_remove_button (string as_key) → long | Removes one button by its key; the others keep their live state. Its Alt+letter, the shortcuts the application gave it, its default / cancel role, colours and tooltip leave with it. Returns 0, -5 on an empty key or a key that names no button |
of_move_button (string as_key, integer ai_index) → long | Moves one button to position ai_index (1 based) without losing its live state. Returns 0, -5 on an empty key or a key that names no button |
of_clear_buttons ( ) → long | Removes every button from the bar, with their Alt+letters, the shortcuts the application gave them, the default / cancel roles, colours and tooltips. Returns 0, -2 when not created |
of_focus_button (string as_key) → long | Puts the keyboard focus on ONE button — No rather than Yes in a destructive question, so that Enter answers No. Returns 0, -5 on an empty key or a key that names no button, -4 when the button cannot take it (greyed, hidden, or not drawn in demo mode), -2 when not created |
of_register_shortcut (string as_chord, string as_key) → long | Gives ONE button a keyboard shortcut (Ctrl+S, F5…): pressed anywhere in the window, it fires the button (ue_clicked), even when the focus is elsewhere. It is independent of the button's Alt+letter: greying the button, changing its letter or re-enabling it never touches it. An empty chord removes it. On a bar a shortcut always names a button: the one-argument form, or a key that names no button, returns -5. Returns 0, -2 when not created |
of_button (string as_key) → n_pbt_buttonbar_button | Returns a button's handle (by id) to read or change its properties (see below) |
Events #
| Event | When |
|---|---|
ue_clicked (string as_key) | A button was used: a click, Enter (the default button, or the focused one), Escape (the cancel button), its Alt+letter or a shortcut registered on it. Its key is passed: an application that wires Cancel must expect it from Escape too. A disabled button emits nothing |
A button's properties (of_button) #
| Property | Type | Default | Description |
|---|---|---|---|
ib_enabled | boolean | true | Enables or disables a button; disabled, it cannot be clicked, nor fired by Enter, Escape or its shortcut |
ib_visible | boolean | true | Shows or hides a button; hidden, it keeps its place and comes back where it was |
is_text | string | "" | The button label; change it after adding. A button keeps a label or an icon: emptying the label of a button without an icon is refused, and the label reads back unchanged |
is_image | string | "" | The button icon (image file; mono: follows the theme); change it after adding. Emptying the icon of a button without a label is refused. An icon-only button is announced to a screen reader by its tooltip (is_tooltip), else by its key |
il_badge | long | 0 | A small count badge in the button corner (0 = none) |
is_shortcut | string | "" | Mnemonic for this button: Alt+the letter fires it, from anywhere in the window, and the letter is underlined in its label. One letter (the first is used); empty = none. A shortcut registered explicitly for the same key (of_register_shortcut) wins over the letter; a PB menu using the same letter loses it while the button can fire. While the button is greyed, hidden or not drawn in demo mode, its letter is left to the window |
il_back_color | long | -1 | Background of THIS button (-1 = the component's, which follows the theme) |
il_text_color | long | -1 | Text colour of THIS button (-1 = the component's) |
il_back_color_hover | long | -1 | Background of THIS button on hover (-1 = the component's) |
il_text_color_hover | long | -1 | Text colour of THIS button on hover (-1 = the component's) |
il_accent | long | -1 | Accent of THIS button (-1 = the component's accent) |
Inherited from the common base #
These members exist on every visual component — they are not specific to this one. They are detailed once, in the transverse chapters; this table only says where to read them.
| Members | Role | Detailed in |
|---|---|---|
of_count · of_keys_at · of_has | Walk what the component holds | 3.2 Items |
of_reset | Put the component back to zero | 3.6 Resetting a component: of_reset() |
of_register_shortcut · of_clear_shortcuts | The component's keyboard chords | 3.5 Keyboard shortcuts |
of_is_created · of_is_ready · of_get_last_error | Whether it was born, whether it is ready, what failed | 3.7 Diagnostics |
of_save_as_png · of_save_as_jpg | Export the rendering as an image | 3.8 Exporting the rendering as an image |
of_set_redraw | Group changes into a single repaint | 3.10 Best practices |
of_preload_icons | Icons shown with no delay | Instant display: of_icon |
of_set_translation | Translate one of the component's labels | 5.2 Adapting a label: of_set_translation |
of_focus_webview | Give the component the focus | 6.4 Keyboard and focus |
of_print · of_print_to_pdf | Print, or write a PDF | 6.9 Printing |
of_set_property · of_get_property · of_component_name | Driving a property by its name | 3.1 The property engine |