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 key (
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 : key, label, icon
// ("&Save" underlines the S : Alt+S fires the button from anywhere in the window)
uo_bar.of_add_button(/*key*/ "save", /*text*/ "&Save", /*image*/ "mono:img\packimages.dll:svg/samples/save")
uo_bar.of_add_button(/*key*/ "find", /*text*/ "&Find", /*image*/ "mono:img\packimages.dll:svg/samples/find")
uo_bar.of_add_button(/*key*/ "copy", /*text*/ "&Copy")
// A chord : Ctrl+S fires Save, whatever control has the focus
uo_bar.of_button(/*key*/ "save").is_shortcut = "Ctrl+S"
// 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 |
|---|---|---|---|
ib_enabled | boolean | true | The whole bar enabled or greyed. Greyed, no button answers — no click, Enter, Escape, Alt+letter or shortcut: those keys stay with the window — and the bar leaves the Tab order. Each button keeps its own ib_enabled |
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 |
ii_image_size | integer | 0 | Size of the button icons, in pixels; 0 = the theme's (18) |
ii_badge_size | integer | 0 | Height of the badges, in pixels — their text follows; 0 = the theme's (16) |
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. With no default set, the focused button keeps its focus ring only. A greyed or hidden default does not take Enter: the key stays with the window — it never goes to the default button of ANOTHER bar, even when that one is alone. 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_text {, string as_image}) → long | Adds a command button at the end of the bar: its key, its label and, optionally, its icon (image file; mono: recolours it to the theme). The label accepts rich markup; &Save underlines the S and makes Alt+S fire the button, && is a literal &. 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, string as_text, string as_image, integer ai_index) → long | Inserts a command button at position ai_index (1 based), shifting the rest; beyond the last it goes at the end, at 0 or less in first place. 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; beyond the last = at the end, 0 or less = first) 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_clear_shortcuts ( ) → long | Drops the shortcut of EVERY button: it no longer answers, no longer shows in the tooltip, and is_shortcut reads back empty. The Alt+letters stay. 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, in a greyed bar, 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…), the same as its is_shortcut: pressed anywhere in the window, it fires the button (ue_clicked), even when the focus is elsewhere, and it joins its tooltip. It is independent of the button's Alt+letter. While the button cannot fire (greyed, hidden, not drawn), the key stays with the window. 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; a chord the window can never fire (a letter alone, Ctrl+Shift) returns -5 and keeps the shortcut in place. Returns 0, -2 when not created |
of_button (string as_key) → n_pbt_buttonbar_button | Returns a button's handle (by its key) to read or change its properties (see below). A key that names no button gets one shared neutral handle: what it is given goes nowhere. of_count, of_keys_at and of_has count the hidden buttons too |
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 |
ue_button_rclicked (string as_key, long al_x, long al_y) | A right click on ONE button, or the Menu key on the focused one, with its key: the place to open that button's menu. A greyed button answers nothing. It is the only event of that right click: ue_rclicked is not raised on top of it; al_x, al_y: where to open the menu, in screen pixels — the pointer, or the bottom-left corner of the button from the keyboard (Menu key, Shift+F10); a contextmenu opens there as they are (uo_menu.of_show(al_x, al_y)) |
ue_rclicked ( ) | A right click on the bar OUTSIDE any button. A right click on a button raises ue_button_rclicked alone: a menu scripted in both never opens twice |
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, its Alt+letter or its shortcut — those keys stay with the window; the arrow keys skip it |
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, rich markup accepted; change it after adding. &Save underlines the S and makes Alt+S fire the button from anywhere in the window, like a PowerBuilder CommandButton; && is a literal &. 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 |
is_style | string | standard | The look of the button: standard, primary (the accent block), flat (no frame at rest) or danger (a destructive action, in the theme's danger colour) — STYLE_* constants; an unknown value reads back standard. A greyed button loses its fill |
is_badge | string | "" | A small badge in the button corner: a count (3; beyond 99 it reads 99+) or a short word (New, !). "" or 0 = none. A screen reader hears it with the button's name |
il_badge | long | 0 | The same badge, as a number (0 = none); a word badge reads back 0 here |
il_badge_color | long | -1 | Colour of THIS button's badge; -1 = the theme's, 0 is black. The text on it is picked so it stays readable |
is_mnemonic | string | "" | The Alt+letter of the button when it is not the & of its label — it wins over it: one letter or digit, the first of its kind in the label is underlined. Empty = the & of the label. While the button cannot fire, its letter stays with the window |
is_shortcut | string | "" | A keyboard CHORD for this button — Ctrl+S, F5, Ctrl+Shift+P: pressed anywhere in the window, it fires the button, and it joins its tooltip (Save (Ctrl+S)). It reads back in its canonical form (ctrl+s); a chord the window can never fire is refused and reads back empty. The same as of_register_shortcut(chord, key). The Alt+letter is the & of the label, or is_mnemonic |
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: it paints its badge and, when it is the default button (or in the primary style), its fill (-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 |
is_accessible_name · is_accessible_description | The name and description a screen reader says | 3.4 Optional properties and events |