Toolbar — version history

u_pbt_toolbar · Introduced in 1.0

A flat, themed toolbar: several bars spread over rows, buttons, toggles, drop-down menus, input fields, automatic overflow and drag-to-reorder by the grip. Introduced in 1.0.

4.0 — October 2026 #

New #

• Every drop-down menu entry has its own handle: of_menu_item("bar/tool/entry") returns an n_pbt_toolbar_menu_item (ib_enabled, ib_visible, ib_checked, is_text, is_shortcut, is_image), addressed by its full path; its item colors are drawn in the menu.
• Menus are managed entry by entry: of_remove_item removes an entry, of_clear_menu empties a drop-down, of_add_menu_separator accepts an entry address (the line goes into its cascade), and cascades accept any depth.
• of_add_split_button: a split button (the main part raises ue_clicked, the arrow opens its menu and raises ue_menu_selected).
• is_group on a toggle: exclusive toggles (left / center / right) — checking one unchecks the others.
• is_image on a tool and on a menu entry: the icon can be changed on the fly ("" removes it).
• is_date on a date picker: the date can be read and written ("yyyy-mm-dd", "" clears the field); the calendar works from the keyboard (arrows, Page Up/Down, Home/End, Enter, Esc), and Enter, Space, F4 or Down arrow open it from the field.
• ue_item_rclicked(as_keys): a right-click on a tool; a right-click outside any tool raises ue_rclicked, never both. ue_mouse_enter and ue_mouse_leave, already documented, are now raised.
• The shortcut of an input field puts the caret in it (Ctrl+F on a search box); the shortcut of a date picker opens its calendar.
• From the keyboard, each bar is a single tab stop (the arrows move from tool to tool); toggles, drop-downs and disabled tools are announced as such to screen readers.
• [symbol=name] tag in rich text: eighteen monochrome glyphs that follow the text colour (clock, location, person, calendar, phone, mail, warning…); an unknown name stays as text.
• Every native menu of the component (like every native menu of the library) lets the user type the first letters of an entry to jump to it, read through the keyboard layout; a menu with more than 500 entries only draws what is visible.
• of_add_combo: a drop-down list in the bar — a field and its arrow, editable or not (ib_editable on its handle), filled with of_add_combo_item and emptied with of_clear_combo or of_remove_combo_item; a choice raises ue_combo_changed(as_keys, as_text), the ribbon's event. Folded into the chevron it stays a working list; in demo mode the list shows 6 choices.

Fixed #

• An entry chosen in a drop-down folded into the overflow (chevron) panel returns its full address in ue_menu_selected (it arrived without the parent of its cascade, under another drop-down, or empty); the shortcut of a folded drop-down opens its menu under the chevron instead of the top-left corner of the screen; rich-text labels are rendered in that panel instead of showing their tags.
• An update to another tool (a status label refreshed by a timer) no longer wipes the text being typed in a field, nor the keyboard focus.
• is_text set by the application on a field the user has just validated is applied, including is_text = "" in ue_text_changed (the old text came back with a second event).
• Enter in an input field validates it without also pressing the window's default button; Esc restores its last validated text.
• A menu choice made while a date picker's calendar was open can no longer arrive as a ue_date_changed.
• An entry disabled, hidden or removed while its menu is open no longer raises anything; a drop-down or cascade whose entries are all hidden is drawn disabled; separators no longer dangle at the start, at the end or doubled.
• ii_index now moves a bar to the right; of_add_bar(key, band, index) on an occupied index inserts the bar before the occupant and the bands close up; dragging a bar below the last row creates a new row.
• The arrow keys no longer get stuck behind a field folded into the chevron panel.
• Colors and tooltip set on a bar (of_bar) apply to the bar, not to a tool of the same name; il_text_color works on a label, and item colors paint the input itself.
• The tooltip given when adding a tool (of_add_button(…, tooltip)) is a single themed bubble, in rich text, with the shortcut appended; is_tooltip replaces it and reads back.
• Holding a shortcut key down no longer repeats the action (a toggle used to flicker); the shortcut of a hidden tool passes the key on to the next tool bearing the same chord; Ctrl+-, Ctrl++, Ctrl+, work on an AZERTY keyboard.
• In right-to-left layouts, the Left / Right arrows follow the screen direction.
• ue_layout_changed is raised when adding a bar moves another one, and no longer when re-showing a bar that is already visible.
• In right-to-left reading, native menus hang from the right edge of their title and cascades open to the left (Left opens, Right closes).
• Rich text: a closing tag closes its own tag only ([b]A[i]B[/b]C leaves C in italics only), a ] escaped by of_escape_markup right after a tag no longer breaks the formatting around it, and [picture=…] accepts a data URI and a file name containing a comma.
• Reading back il_back_color_hover or il_text_color_hover of an item never coloured returns -1 (the theme's colour), like the other item colours (it returned 0, black).
• A decimal property (id_…) is written and read back correctly whatever the machine's decimal separator.
• Enter or Esc pressed in the component, when it does not use them, goes back to the window: the PowerBuilder Default or Cancel CommandButton fires (the key was lost).
• A disabled component (ib_enabled = false) leaves the Tab order; enabled again (or after of_reset), it takes its place back.
• With no language chosen by the application, the component announces English to screen readers (it announced French).
• is_theme_style, is_theme_mode and il_theme_accent read back the style and mode shown and the component's own accent (-1 when it has none); an unknown or badly written value is ignored instead of leaving the component without a theme, and an axis left empty follows the application's theme.
• The application accent (PBT_SetDefaultThemeAccent) survives a change of theme, is followed as long as the component has no accent of its own, and repaints everything derived from it (hover, pressed, selections); Windows high contrast is supported.
• Typing a character with AltGr in a PowerBuilder field (the euro of a French keyboard, AltGr+E) no longer fires a Ctrl+Alt shortcut of that key.

Behavior changes #

• Adds, of_add_separator, of_move_item and removals return -5 for a key already taken, a key containing / or |, a bar that was never added or an unknown address (a typo in a bar name used to create a ghost bar); only MAIN_BAR needs no of_add_bar, and of_add_bar(MAIN_BAR, …) must come before its first tool (-5 afterwards). of_set_layout with text that is not JSON returns -5.
• of_clear, of_remove_bar and of_remove_item release the handles of what goes (IsValid() returns false), disarm its shortcuts and forget its colors and tooltips: ask for a handle again after a removal.
• of_item with a three-level address no longer designates anything (it acted on the bar's tool of the same name): an entry is driven through of_menu_item.
• of_count and of_keys_at on a bar, and the index of of_move_item, no longer count separators; of_count returns a long.
• is_shortcut reads back as written (Ctrl+S); ii_band and ii_index of an unknown bar return 0.
• A single key (Delete) is no longer a tool shortcut: it needs Ctrl or Alt, or a key from F1 to F24. of_register_shortcut(chord, address) takes the address of a tool or an entry ("main/save"), -5 otherwise.
• band and index in the layout (of_get_layout, of_set_layout, ue_layout_changed) count from 1, like ii_band, ii_index and ue_bar_reordered: a layout saved by 3.0 must be shifted by one.
• Rich text: a markup image on a network share ([picture=\\server\share\x.png]) is no longer shown: go through of_icon(), which embeds it.
• of_set_layout raises ue_layout_changed, as the dockcontainer and the datagrid do: every change of the layout is announced, whether it comes from the user or from your code.
• Details and how to adapt: Migrating from 3.0 to 4.0, sections 11.3, 11.6, 11.17 and 11.48.

3.0 — September 2026 #

New #

• of_set_property, of_get_property and of_component_name: drive a property by its name (settings screen, saved configuration).

Fixed #

• of_add_menu_item accepts the four-level address ("bar/dropdown/entry/subentry") the documentation showed: it was refused with -5.
• The shortcut of a hidden tool no longer triggers it (Ctrl+S used to fire a hidden Save button).
• The text of a hovered tool is readable in the Office 2007 dark theme.
• A color read back (il_text_color, il_accent…) returns the color that was set, and -1 when it is the theme's (it returned 0).
• Rich text: a [word] that is not a tag is shown as typed (report[final].pdf) instead of disappearing with the rest of the text.

Behavior changes #

• Every position passed to a method counts from 1: of_add_bar(key, band, index), of_move_item, of_insert_button, ii_band, ii_index — as ue_bar_reordered already did.
• ue_menu_selected returns the full address of a cascaded entry ("file/saveas/fmt_other/png8" instead of "file/saveas/png8").
• See Migrating from 2.0 to 3.0.

2.0 — September 2026 #

New #

• of_count, of_keys_at and of_has on the component and at every level (bar, drop-down): what the toolbar holds can be asked.
• A tool's properties read back live: a getter tells what is on screen.
• Every method returning a long documents what its return value means (0 applied, -5 invalid argument, -2 component not created).
• ue_script_error: a script error in the page reaches PowerBuilder with its message instead of being lost.

Fixed #

• A disabled tool is readable in every theme (higher contrast for disabled text).
• A Windows path, or a text containing a quote, received in an event arrives intact (backslashes are no longer doubled, the text is no longer cut at the quote).

Behavior changes #

• The API is reshaped: a tool is reached by its address ("main/save", "main/export/pdf" for a drop-down entry), everything is added from the component (uo_toolbar.of_add_button("main/save", …)), adds return a code instead of a handle, and bar and tool handles only carry properties (of_bar, of_item).
• Events receive the address as a single argument: ue_clicked(as_keys), ue_toggled(as_keys, ab_checked), ue_menu_selected(as_keys), ue_text_changed(as_keys, as_text), ue_date_changed(as_keys, as_date).
• Every changed signature: Migrating from 1.0 to 2.0.

1.0 — August 2026 #

New #

• Several bars spread over bands (rows), like classic Office toolbars; a default bar, MAIN_BAR, always present.
• Tools: buttons, toggles, drop-down menus with cascades, labels, input fields, date pickers and separators; insert at a chosen index, move and remove a tool or a bar.
• Automatic overflow: what does not fit goes into a panel opened by a chevron, where a folded field stays a working field.
• User reordering by the grip (ib_reorderable, ue_bar_reordered) and a savable layout (of_get_layout, of_set_layout, ue_layout_changed).
• ib_visible on a bar and on a tool: hidden, they keep their place and come back at the same index.
• Per-tool keyboard shortcuts (is_shortcut), shown in the tooltip and active wherever the focus is.
• Intrinsic height: the toolbar fits its rows and announces it (ue_auto_height); rich-text labels, themes, per-tool colors and tooltips.