toolbar — `u_pbt_toolbar` #

← Component reference · Guide contents

Flat toolbar: several bars spread over bands, buttons, toggles, drop-down menus, input fields, automatic overflow and drag-by-handle repositioning.

▶ See it live — Demo application, Toolbar tile: the preview, the code behind it and this page, side by side.

At a glance #

Userobject	`u_pbt_toolbar`
Item classes	`n_pbt_toolbar_bar` (bar) → `n_pbt_toolbar_item` (tool)
Used for	Replacing a classic toolbar with a modern, themed one spread over several rearrangeable rows
Height	Intrinsic: the bar always fits itself to its rows, nothing to enable — see Automatic height

Quick start #

// open event of the window

// MAIN_BAR is the default bar, always present : the address starts from it


uo_toolbar.of_add_button(/*keys*/ uo_toolbar.MAIN_BAR + "/save", /*text*/ "", /*image*/ "mono:img\save.svg", /*tooltip*/ "Save")
uo_toolbar.of_add_button(/*keys*/ uo_toolbar.MAIN_BAR + "/find", /*text*/ "", /*image*/ "mono:img\find.svg", /*tooltip*/ "Find")
uo_toolbar.of_add_separator(/*keys*/ uo_toolbar.MAIN_BAR)
uo_toolbar.of_add_button(/*keys*/ uo_toolbar.MAIN_BAR + "/help", /*text*/ "Help",  /*image*/ "", /*tooltip*/ "About")

// ue_clicked event of uo_toolbar : (string as_keys)
choose case as_keys
    case "main/save" ; of_enregistrer()
    case "main/find" ; of_rechercher()
    case "main/help" ; of_aide()
end choose

The model: bars, bands, tools #

A toolbar contains one or more bars. Each bar sits on a band (a row) and occupies a position within that row: two bars on the same band share the row, two bars on different bands stack up — exactly like classic Office toolbars.

Tools (buttons, toggles, menus, fields) belong to a bar. Their identifier is only unique inside their own bar, so access always goes through the full path.

uo_toolbar.of_bar("main").of_item("save").ib_enabled = false

Additions live on the parent handle too: you add a tool to a bar, not to the toolbar. See Shared foundation · Items for the general principle.

Properties #

Property	Type	Default	Purpose
`is_theme_style`	string	`fluent`	Visual style of the component (`THEME_STYLE_*` constants)
`is_theme_mode`	string	`light`	Light or dark variant (`THEME_MODE_*` constants)
`il_theme_accent`	long	`-1`	Accent color of this component (`-1` = the theme accent)
`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
`ib_reorderable`	boolean	`false`	Lets the user rearrange the bars with the mouse: the move grips appear and a bar can be dragged to another band. Off by default — a toolbar taken apart by accident is a support call. Your code rearranges them either way (`of_set_layout`, `of_add_bar`): the switch restrains the user, never the application

Constant #

Constant	Value	Purpose
`MAIN_BAR`	`"main"`	Identifier of the default bar, always available without having to create it

Methods #

Method	Purpose
`of_bar (string as_key)` → `n_pbt_toolbar_bar`	Returns the handle of a bar (created on first access)
`of_add_button (string as_keys, string as_text, string as_image, string as_tooltip)` → `long`	Action button at its address, `"main/save"`: the bar, then its own id. A click raises `ue_clicked`. Returns `0` once applied, `-5` on an invalid argument (empty key, wrong address), `-2` when the component is not created
`of_item (string as_keys)` → `n_pbt_toolbar_item`	Returns the handle of one tool, by its address
`of_add_bar (string as_key)` → `long`	Adds a bar and returns `0` (`-5` on an invalid argument, `-2` when the component is not created)
`of_add_bar (string as_key, integer ai_band, integer ai_index)` → `long`	Adds a bar at a specific band and position (both counted from 1). Returns `0` once applied, `-2` when the component is not created
`of_remove_bar (string as_key)`	Removes one bar and its tools. The others keep their live state, and the bands close ranks behind the one that leaves. This is not hiding it (`ib_visible` on its handle): hiding keeps it in the model, ready to come back exactly where it was; removing forgets it. Returns `0` once applied, `-5` on an invalid argument (empty key, wrong address), `-2` when the component is not created
`of_get_layout ()`	Reads the current arrangement back as JSON: which bar on which band, at which rank, and visible or not. Store it, then hand it back with `of_set_layout`
`of_set_layout (string as_layout_json)`	Restores a bar layout previously received through `ue_layout_changed`. Returns `0` once applied, `-5` on an invalid argument (empty key, wrong address), `-2` when the component is not created
`of_clear ( )`	Removes every bar and every tool. Returns `0` once applied, `-2` when the component is not created
`of_reset ( )`	Clears the content and restores the properties to their defaults. Returns `0` once applied, `-2` when the component is not created
`of_add_toggle (string as_keys, string as_text, string as_image, string as_tooltip)` → `long`	Two-state toggle; clicking it raises `ue_toggled`. Returns `0` once applied, `-5` on an invalid argument (empty key, wrong address), `-2` when the component is not created
`of_add_dropdown (string as_keys, string as_text, string as_image, string as_tooltip)` → `long`	Drop-down menu button; picking an entry raises `ue_menu_selected`. Returns `0` once applied, `-5` on an invalid argument (empty key, wrong address), `-2` when the component is not created
`of_add_label (string as_keys, string as_text)` → `long`	Informational label, not clickable. Returns `0` once applied, `-5` on an invalid argument (empty key, wrong address), `-2` when the component is not created
`of_add_textbox (string as_keys, string as_text, integer ai_width, string as_tooltip)` → `long`	Input field; Enter or loss of focus raises `ue_text_changed`. `ai_width` in pixels. Returns `0` once applied, `-5` on an invalid argument (empty key, wrong address), `-2` when the component is not created
`of_add_datepicker (string as_keys, string as_date, string as_tooltip)` → `long`	Date picker; picking a date raises `ue_date_changed`. Dates in `"yyyy-mm-dd"` format. Returns `0` once applied, `-5` on an invalid argument (empty key, wrong address), `-2` when the component is not created
`of_add_separator (string as_keys)`	Vertical separator rule. Returns `0` once applied, `-5` on an invalid argument (empty key, wrong address), `-2` when the component is not created
`of_insert_button (string as_keys, string as_text, string as_image, string as_tooltip, integer ai_index)` → `long`	Button added at the position you choose (first = 1) instead of at the end. Returns `0` once applied, `-5` on an invalid argument (empty key, wrong address), `-2` when the component is not created
`of_move_item (string as_keys, integer ai_index)`	Moves a tool to another position within this bar (first = 1). It keeps its kind, its menu and its live state: the tool changes place, it is not rebuilt. Works for every kind, so the `of_add_` without an `of_insert_` insert by adding then moving. Returns `0` once applied, `-5` on an invalid argument (empty key, wrong address), `-2` when the component is not created
`of_remove_item (string as_keys)`	Removes one tool from this bar. The bar stays, and so does everything else in it, live state included — only the named tool goes. To make it come and go instead, `ib_visible` on its handle keeps it in the model. Returns `0` once applied, `-5` on an invalid argument (empty key, wrong address), `-2` when the component is not created
`of_add_menu_item (string as_keys, string as_label, string as_image)`	Entry in the menu of a drop-down button ; Cascading entry, filed under an existing entry. Returns `0` once applied, `-5` on an invalid argument (empty key, wrong address), `-2` when the component is not created
`of_add_menu_separator (string as_keys)`	Separator rule inside the menu. Returns `0` once applied, `-5` on an invalid argument (empty key, wrong address), `-2` when the component is not created

On a bar — `n_pbt_toolbar_bar` #

Member	Type	Default	Purpose
`ii_band`	integer	`1`	Band (row) carrying the bar; `1` = first row
`ii_index`	integer	`1`	Position of the bar within its band; `1` = the first
`ib_visible`	boolean	`true`	Shows or hides one bar. A hidden bar keeps its band, its rank and its items: showing it again puts it back exactly where it was, with nothing to rebuild — that is the difference with `of_clear`, which would lose them

On a tool — `n_pbt_toolbar_item` #

Member	Type	Default	Purpose
`ib_visible`	boolean	`true`	Shows or hides one item. It keeps its rank in the bar: showing it again puts it back exactly where it was, not at the end. Not to be confused with `ib_enabled`, which leaves it in place, greyed — hide what does not apply, grey what is momentarily unavailable
`ib_enabled`	boolean	`true`	Tool active or grayed out
`ib_checked`	boolean	`false`	State of a toggle (no effect on the other types)
`is_text`	string	`""`	Label, rich markup accepted
`is_shortcut`	string	`""`	Keyboard shortcut (`"Ctrl+S"`), shown in the tooltip and active

Images accept every form the library recognizes: path, mono:, tint:, DLL resource.

Events #

Event	Raised when
`ue_clicked (string as_keys)`	A button is clicked (or triggered by its shortcut)
`ue_toggled (string as_keys, boolean ab_checked)`	A toggle changes state; `ab_checked` carries the new state
`ue_menu_selected (string as_keys)`	A drop-down menu entry is picked
`ue_text_changed (string as_keys, string as_text)`	An input field is validated (Enter or loss of focus)
`ue_date_changed (string as_keys, string as_date)`	A date is picked (`"yyyy-mm-dd"`)
`ue_bar_reordered (string as_key, integer ai_band, integer ai_index)`	The user dragged a bar by its grip to another band or another rank (needs `ib_reorderable`). Says which bar moved and where it landed, where `ue_layout_changed` carries the whole arrangement. Band and rank start at 1, like `ii_band` and `ii_index`
`ue_layout_changed (string as_layout_json)`	The arrangement changed — the user dragged a bar by its grip, or your own code moved or hid one. Carries the whole layout, not just what moved
`ue_auto_height (long al_height)`	The ideal height has changed and the bar has adjusted to it — always active: the number of rows dictates the height
`ue_ready ( )`	The component has finished loading; everything sent beforehand has been replayed
`ue_runtime_missing ( )`	The WebView2 runtime is missing: the component stays empty
`ue_bg_color (long al_color)`	The component has computed its theme background color; the userobject has already adopted it (`backcolor`)

Examples #

Pre-checked toggles and a grayed-out tool #



uo_toolbar.of_add_toggle(/*keys*/ uo_toolbar.MAIN_BAR + "/bold",   /*text*/ "", /*image*/ "mono:img\bold.svg",   /*tooltip*/ "Bold")
uo_toolbar.of_add_toggle(/*keys*/ uo_toolbar.MAIN_BAR + "/italic", /*text*/ "", /*image*/ "mono:img\italic.svg", /*tooltip*/ "Italic")
uo_toolbar.of_add_separator(/*keys*/ uo_toolbar.MAIN_BAR)
uo_toolbar.of_add_button(/*keys*/ uo_toolbar.MAIN_BAR + "/undo",   /*text*/ "", /*image*/ "mono:img\undo.svg",   /*tooltip*/ "Undo")

// Every tool is driven through its handle, obtained from ITS bar
uo_toolbar.of_item(/*keys*/ uo_toolbar.MAIN_BAR + "/bold").ib_checked = true    // toggle checked up front
uo_toolbar.of_item(/*keys*/ uo_toolbar.MAIN_BAR + "/undo").ib_enabled = false   // nothing to undo yet

// ue_toggled event of uo_toolbar
if as_key = "bold" then of_appliquer_gras(ab_checked)


// The menu is filled from the component : three levels, bar/dropdown/entry
uo_toolbar.of_add_dropdown(/*keys*/ uo_toolbar.MAIN_BAR + "/export", /*text*/ "Export", &
                                   /*image*/ "mono:img\save.svg", /*tooltip*/ "Export the file")
uo_toolbar.of_add_menu_item(/*keys*/ uo_toolbar.MAIN_BAR + "/export/exp_pdf", /*label*/ "PDF",  /*image*/ "")
uo_toolbar.of_add_menu_item(/*keys*/ uo_toolbar.MAIN_BAR + "/export/exp_csv", /*label*/ "CSV",  /*image*/ "")
uo_toolbar.of_add_menu_separator(/*keys*/ uo_toolbar.MAIN_BAR + "/export")

// Submenu : a FOURTH level, the entry it nests under
uo_toolbar.of_add_menu_item(/*keys*/ uo_toolbar.MAIN_BAR + "/export/exp_img", /*label*/ "Image...", /*image*/ "")
uo_toolbar.of_add_menu_item(/*keys*/ uo_toolbar.MAIN_BAR + "/export/exp_img/exp_png", /*label*/ "PNG", /*image*/ "")
uo_toolbar.of_add_menu_item(/*keys*/ uo_toolbar.MAIN_BAR + "/export/exp_img/exp_jpg", /*label*/ "JPEG", /*image*/ "")

// ue_menu_selected event of uo_toolbar : (as_keys)
n_pbt_utils lnv_utils   // autoinstantiate : nothing to create, nothing to destroy
string ls_ids[]

if lnv_utils.of_split_path(as_keys, ls_ids) = 3 then
	if ls_ids[2] = "export" then of_exporter(ls_ids[3])
end if

Search field and date picker #



uo_toolbar.of_add_button(/*keys*/ uo_toolbar.MAIN_BAR + "/save", /*text*/ "", /*image*/ "mono:img\save.svg", /*tooltip*/ "Save")
uo_toolbar.of_item(/*keys*/ uo_toolbar.MAIN_BAR + "/save").is_shortcut = "Ctrl+S"    // shortcut active and displayed
uo_toolbar.of_add_separator(/*keys*/ uo_toolbar.MAIN_BAR)

// 160 px wide ; the text is reported on validation
uo_toolbar.of_add_textbox(/*keys*/ uo_toolbar.MAIN_BAR + "/search", /*text*/ "", /*width*/ 160, /*tooltip*/ "Find (Enter to validate)")

uo_toolbar.of_add_label(/*keys*/ uo_toolbar.MAIN_BAR + "/lbl_due", /*text*/ "Due date:")
uo_toolbar.of_add_datepicker(/*keys*/ uo_toolbar.MAIN_BAR + "/due", /*date*/ "2026-07-11", /*tooltip*/ "Due date")

// ue_text_changed event of uo_toolbar
if as_key = "search" then of_filtrer(as_text)

// ue_date_changed event of uo_toolbar : as_date in "yyyy-mm-dd" format
if as_key = "due" then id_echeance = Date(as_date)

Two bars and a remembered layout #

The user can grab a bar by its handle (to the left of the bar) and move it to another band or another position. Keep the layout when the window closes, and restore it when it opens.



uo_toolbar.of_add_button(/*keys*/ uo_toolbar.MAIN_BAR + "/new",  /*text*/ "New", /*image*/ "", /*tooltip*/ "")
uo_toolbar.of_add_button(/*keys*/ uo_toolbar.MAIN_BAR + "/open", /*text*/ "Open",  /*image*/ "", /*tooltip*/ "")

// Second bar, placed on band 2 (second row), in first position

uo_toolbar.of_add_bar(/*key*/ "format", /*band*/ 2, /*index*/ 1)
uo_toolbar.of_add_toggle(/*keys*/ "format/bold", /*text*/ "B", /*image*/ "", /*tooltip*/ "Bold")

// A bar can also be moved at any time through its properties
uo_toolbar.of_bar(/*key*/ "format").ii_band  = 1
uo_toolbar.of_bar(/*key*/ "format").ii_index = 2    // second bar of the first row

// ue_layout_changed event of uo_toolbar : keep the chosen layout
is_disposition = as_layout_json

// Next time the window opens : restore what the user had arranged
if is_disposition <> "" then uo_toolbar.of_set_layout(is_disposition)

Overflow: "More tools" #

When the width is no longer enough, the tools that do not fit are folded into a More tools menu marked by a chevron at the end of the bar. This is automatic and requires no code: the folded tools stay clickable and raise the same events. A folded field — text box or date picker — stays a real field: you type in it, you pick a date in it, and the event is raised exactly as if the tool had stayed in the bar.

Automatic height #

Nothing to enable: the number of rows (of_set_layout) dictates the height, the bar adjusts to it on its own and notifies you.

// ue_auto_height event of uo_toolbar
uo_contenu.y      = uo_toolbar.y + al_height
uo_contenu.height = parent.workspaceheight() - uo_contenu.y

See Shared foundation.

Best practices #

Use MAIN_BAR for as long as a single bar is enough: it already exists, there is no need to add it.
Always reach a tool through its path — of_bar(...).of_item(...) — never through its identifier alone: that is what makes identifiers reusable from one bar to the next.
Group related tools with of_add_separator() rather than with extra bars.
On icon-only buttons, always fill in the tooltip: it is the only label the user has.
If you let users rearrange the bars, remember ue_layout_changed and replay of_set_layout at startup, otherwise their effort is lost every time the application launches.
Call of_reset() before rebuilding the toolbar from scratch for another context.
When the commands become too numerous for a bar, move up to the ribbon, organized into tabs and groups.

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

Two helpers are not inherited: of_icon and of_escape_markup live on n_pbt_utils. Declare one — n_pbt_utils lnv_utils, nothing to create — and call them on it.