statusbar — `u_pbt_statusbar` #

← Component reference · Guide contents

Status bar made of panels: rich text, icons, fixed or automatic widths, alignment to the left or to the right, clickable panels, a mini progress bar and colored states.

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

At a glance #

Userobject	`u_pbt_statusbar`
Item class	`n_pbt_statusbar_panel` (panel) · `n_pbt_statusbar_menu_item` (drop-down entry)
Used for	Showing the state of the application at the bottom of the window: context, progress, discreet alerts
Opt-in options	—

Quick start #

// window open event
// of_add_panel(id, text, icon, alignment, width)
// the key finds the panel later ; width 0 = fitted to the text
uo_status.of_add_panel(/*key*/ "state",  /*text*/ "Ready",           /*icon_file*/ "", /*align*/ uo_status.ALIGN_START,  /*width*/ 0)
uo_status.of_add_panel(/*key*/ "pos",   /*text*/ "Line 12, Col 4", /*icon_file*/ "", /*align*/ uo_status.ALIGN_START,  /*width*/ 0)
uo_status.of_add_panel(/*key*/ "clock", /*text*/ "12:00",          /*icon_file*/ "", /*align*/ uo_status.ALIGN_END, /*width*/ 140)

// Update a panel at any time, through its identifier
uo_status.of_panel(/*key*/ "state").is_text = "Saving..."

The model: panels with keys #

The bar is a sequence of panels, added in order. A panel is given an identifier when it is created: that is how you find it later to change its text, its icon or its state.

The identifier is an addressing key, not an interactivity switch:

Identifier supplied: the panel can be found again — you change its content, you give it a tooltip. It stays inert: a status bar shows things above all, and a panel like Line 12, Col 4 must not look pressable. It still receives the right click (ue_panel_rclicked) : a « Copy » context menu is not an activation.
Empty identifier: the panel is purely decorative. It cannot be found, cannot be clicked, and no tooltip can be attached to it. Give every panel an identifier: it costs nothing and keeps the door open. It still counts in of_count and in positions, and of_keys_at gives an empty key for it.
To make a panel clickable, ask for it: of_panel(/*key*/ "id").ib_clickable = true. A panel carrying a drop-down list (of_add_menu_item) already is.

// The panel shows a new text
uo_status.of_panel(/*key*/ "state").is_text = "3 records changed"

See Shared foundation · Items.

Properties #

Property	Type	Default	Purpose
`ib_show_resize_grip`	boolean	`false`	Shows the resize grip in the corner at the end of the bar; dragging it resizes the window (from the bottom-left corner in a right-to-left layout). It is drawn only while the window can be resized that way: maximized or without a sizing border, it disappears and the property stays set
`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	Purpose
`of_add_panel (string as_key, string as_text, string as_icon_file, string as_align, integer ai_width)`	Adds a panel at the end of the bar. Returns `0` once applied, `-5` when the key is already taken or contains `/` or `	`(an empty key adds a decorative panel),` -2` when the component is not created
`of_add_sep ( )`	Adds a group break at the current position. Panels already separate themselves with a thin line : this one is wider, so the panels before and after it read as two groups. Call it between two `of_add_panel` ; it opens the group of the panel after it (on the side of the one before when it comes last). A separator is not a panel : it counts neither for `of_count` / `of_keys_at` nor in positions. Returns `0` once applied, `-2` when the component is not created
`of_insert_panel (string as_key, string as_text, string as_icon_file, string as_align, integer ai_width, integer ai_index)`	Inserts a panel at a given position, counted in panels from 1 (`0` or less = first, past the last = at the end). Same refusals as `of_add_panel`. Returns `0` once applied, `-5` when the key is already taken or contains `/` or `	`,` -2` when the component is not created
`of_move_panel (string as_key, integer ai_index)`	Moves an existing panel to another position, counted in panels from 1. Returns `0` once applied, `-5` on an empty key or one the bar was never given, `-2` when the component is not created
`of_remove_panel (string as_key)`	Removes a single panel, with its dropdown ; the others keep their state. Returns `0` once applied, `-5` on an empty key or one the bar was never given, `-2` when the component is not created
`of_panel (string as_key)` → `n_pbt_statusbar_panel`	Returns the handle to a panel (created on first access). An empty key (a decorative panel), an address or a list designates nothing: its handle writes nowhere and reads back empty
`of_flash_panel (string as_key, string as_text, long al_ms)`	Shows a message for `al_ms` milliseconds, then shows the panel's text again (`al_ms` ≤ 0 = 2 seconds). The message is shown OVER the text: `is_text` always reads back as the panel's text, never as the message. Returns `0` once applied, `-5` on an empty key, an address or a key the bar was never given, `-2` when the component is not created
`of_add_menu_item (string as_keys, string as_label)` · `(as_keys, as_label, as_image)`	Adds an entry to the dropdown of a panel : `as_keys` has two levels, the panel then the entry (`"enc/utf8"`). From the first entry on, the panel becomes a chooser : a click opens the list, and the pick comes back through `ue_panel_menu_clicked` with the same address. An empty label falls back to the key. Returns `0` once applied, `-5` on an address that does not have two levels, a panel the bar was never given or an entry already taken, `-2` when the component is not created
`of_insert_menu_item (string as_keys, string as_label, integer ai_index)` · `(as_keys, as_label, as_image, ai_index)`	Inserts an entry at a given position (counted from 1). 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_key)`	Separator line in the list of panel `as_key`. A separator has no address: only `of_clear_menu` removes it, and a list made of separators alone is no list (no chevron, no click). Returns `0` once applied, `-5` on an empty key or a panel the bar was never given, `-2` when the component is not created
`of_remove_menu_item (string as_keys)`	Removes a single entry; the last one gone, the panel goes back to the behaviour `ib_clickable` gives it. Returns `0` once applied, `-5` on an invalid argument (empty key, wrong address), `-2` when the component is not created
`of_move_menu_item (string as_keys, integer ai_index)`	Moves an entry to another position in its list. Returns `0` once applied, `-5` on an invalid argument (empty key, wrong address), `-2` when the component is not created
`of_menu_item (string as_keys)` → `n_pbt_statusbar_menu_item`	Returns the handle to an entry (created on first access), to grey it, tick it or rename it. An address without two levels designates nothing : its handle writes nowhere and reads empty
`of_clear_menu (string as_key)`	Removes the whole drop-down list; the panel goes back to the behaviour `ib_clickable` gives it. Returns `0` once applied, `-5` on an invalid argument (empty key, wrong address), `-2` when the component is not created
`of_clear ( )`	Empties the bar: every panel and every separator. Returns `0` once applied, `-2` when the component is not created
`of_reset ( )`	Empties the bar and resets every property to its default. Returns `0` once applied, `-2` when the component is not created

The arguments of `of_add_panel` #

Argument	Values	Effect
`as_keys`	free, or `""`	Key of the panel, the one you find it by later. Empty = a decorative panel, neither addressable nor clickable
`as_text`	text	Content of the panel. Rich text markup is accepted
`as_icon_file`	image path, or `""`	Icon displayed before the text (accepted forms)
`as_align`	`ALIGN_START` (default) or `ALIGN_END`	Side the panel is pushed toward. Logical values: `START` = start of the reading direction (left in left-to-right writing). The physical aliases `"left"` / `"right"` are still accepted
`ai_width`	pixels, or `0`	Fixed width. `0` = the panel fits its content

On a panel — `n_pbt_statusbar_panel` #

Member	Type	Default	Purpose
`is_text`	string	`""`	Text of the panel, rich text markup accepted
`is_image`	string	`""`	Icon of the panel, which can be changed at any time
`ib_enabled`	boolean	`true`	Panel grayed out and not clickable
`ib_visible`	boolean	`true`	Panel hidden, without being removed from the bar
`ii_progress`	integer	—	Mini progress bar inside the panel, beside the text, from `0` to `100` (above 100 the bar is full and reads back `100`); a negative value makes it disappear. Reads back `-1` when the panel has no bar (and `0` for a bar at 0 %)
`is_state`	string	`""`	Semantic state of the panel, which colors its text and marks its leading edge: see the constants below. Any other value means no state and reads back empty; a disabled panel is greyed, state mark included
`ib_indeterminate`	boolean	`false`	Bar animated without a value, for a task whose duration is unknown. Independent of `ii_progress`, which stays the exact percentage
`ib_clickable`	boolean	`false`	Does the panel answer the click. Opt-in: a panel stays inert until you ask, while keeping its key — it is driven and carries a tooltip. A panel with a drop-down list is clickable already

On a drop-down entry — `n_pbt_statusbar_menu_item` #

Obtained through of_menu_item(/*keys*/ "enc/utf8"): the address has two levels, the panel then the entry. The list is a native menu: a property changed while it is open shows at the next opening.

Member	Type	Default	Purpose
`is_label`	string	`""`	Text of the entry
`is_image`	string	`""`	Image before the text, which can be changed at any time
`ib_enabled`	boolean	`true`	Entry greyed out: shown, but impossible to pick
`ib_checked`	boolean	`false`	Check mark before the entry, for the value in use
`ib_visible`	boolean	`true`	Entry left out of the list without being removed: showing it again needs nothing more

// The menu of the encoding panel, entry by entry
uo_status.of_add_menu_item(/*keys*/ "enc/utf8", /*label*/ "UTF-8")
uo_status.of_add_menu_item(/*keys*/ "enc/ansi", /*label*/ "ANSI")
uo_status.of_menu_item(/*keys*/ "enc/utf8").ib_checked = true     // the current value
uo_status.of_menu_item(/*keys*/ "enc/ansi").ib_enabled = false    // not available here

State constants #

Constant	Value	Use
`STATE_NONE`	`""`	No state: normal appearance
`STATE_INFO`	`"info"`	Information
`STATE_WARNING`	`"warning"`	Warning
`STATE_ERROR`	`"error"`	Error
`STATE_SUCCESS`	`"success"`	Success

As with every property that takes predefined values, use the constant rather than the string:

// The panel takes the colors of a warning
uo_status.of_panel(/*key*/ "state").is_state = n_pbt_statusbar_panel.STATE_WARNING

Events #

Event	Raised when
`ue_panel_clicked (string as_key)`	A clickable panel (`ib_clickable`) is clicked
`ue_panel_double_clicked (string as_key)`	A clickable panel was double-clicked — the classic shortcut behind `Line 12, Col 4` that opens a "Go to line". Never on a panel carrying a drop-down list: its first click opened the list
`ue_panel_rclicked (string as_key, long al_x, long al_y)`	A panel with a key received a right click — clickable or not (a context menu is not an activation), never when it is disabled. One event per right click. `al_x` and `al_y` are screen pixels ; for a PowerBuilder menu, `PopMenu(PointerX(), PointerY())` of your window
`ue_panel_menu_clicked (string as_keys)`	An entry of a panel drop-down list was picked (see `of_add_menu_item`). `as_keys` carries both levels: the panel, then the entry — `"enc/utf8"`. From the keyboard, Enter, Space, Up or Down arrow open the list. A panel removed, disabled or hidden while its list is open closes it, and nothing is raised
`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`)

Keyboard #

The bar is a single tab stop: only the panels meant to be clicked enter it, and the arrows walk them.

Key	Effect
Arrows	Move to the previous / next interactive panel, wrapping around; display panels and disabled panels are skipped
Home / End	First / last interactive panel
Enter or Space	Triggers the panel — that is, `ue_panel_clicked`, or the opening of its dropdown if it has one

A panel that merely displays is not a control: it is neither focusable nor announced as one. A clickable but disabled panel, on the other hand, stays announced as unavailable rather than passing for text. A progress bar announces its value, and an indeterminate one announces none — that absence is the meaning of the word.

The focus survives the rebuild of the bar: it is redrawn on every text change, and without this the focus would drop every second on a bar showing a clock.

Examples #

Fixed widths and automatic widths #

// Width 0 : the panel takes exactly the room its text needs
uo_status.of_add_panel(/*key*/ "", /*text*/ "Panel fitted to its content", /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ 0)

// Fixed width in pixels : useful when the text changes often,
// so that the neighboring panels do not move on every update
uo_status.of_add_panel(/*key*/ "pos", /*text*/ "Line 1, Col 1", /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ 150)

// A panel pushed to the opposite end
uo_status.of_add_panel(/*key*/ "clock", /*text*/ "12:00", /*icon_file*/ "", /*align*/ uo_status.ALIGN_END, /*width*/ 140)

Icons and clickable panels #

// A key makes the panel addressable ; ib_clickable makes it clickable
uo_status.of_add_panel(/*key*/ "save", /*text*/ "Saved", /*icon_file*/ "mono:img\save.svg", /*align*/ uo_status.ALIGN_START, /*width*/ 0)
uo_status.of_add_sep()   // separator line between two groups of panels
uo_status.of_add_panel(/*key*/ "conn", /*text*/ "Connected",   /*icon_file*/ "mono:img\plug.svg", /*align*/ uo_status.ALIGN_START, /*width*/ 0)
uo_status.of_add_panel(/*key*/ "user", /*text*/ "Alex Martin",  /*icon_file*/ "mono:img\user.svg", /*align*/ uo_status.ALIGN_END, /*width*/ 160)

// Only these two answer a click (ue_panel_clicked)
uo_status.of_panel(/*key*/ "conn").ib_clickable = true
uo_status.of_panel(/*key*/ "user").ib_clickable = true

// ue_panel_clicked event of uo_status
choose case as_key
    case "conn" ; open(w_connection_settings)
    case "user" ; open(w_profile)
end choose

Rich text in a panel #

Panels accept rich text markup: styles, colors and small images right inside the text.

// A welcome on the left
uo_status.of_add_panel(/*key*/ "", /*text*/ "Welcome [b]to[/b] [accent]PBToolboxAI[/accent]", &
                       /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ 0)

// The connection state on the right
uo_status.of_add_panel(/*key*/ "", /*text*/ "[green]Online[/green] [picture=mono:img\plug.svg,14,14]", &
                       /*icon_file*/ "", /*align*/ uo_status.ALIGN_END, /*width*/ 0)

// Rich text works for updates too
uo_status.of_panel(/*key*/ "state").is_text = "[b]" + String(ll_changed) + "[/b] records changed"

Following a long operation #

// Local variables
n_pbt_statusbar_panel lnv_import

// The import panel, then its handle to follow it
uo_status.of_add_panel(/*key*/ "import", /*text*/ "Import", /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ 220)
lnv_import = uo_status.of_panel(/*key*/ "import")

// Inside the processing loop : the mini bar follows the progress
lnv_import.ii_progress = ll_percent
lnv_import.is_text     = "Import " + String(ll_percent) + " %"

// At the end : hide the mini bar and report the result
lnv_import.ii_progress = -1                       // negative value = bar hidden
lnv_import.is_text     = "Import complete"
lnv_import.is_state    = lnv_import.STATE_SUCCESS

Raising a discreet alert #

// Local variables
n_pbt_statusbar_panel lnv_panel

// The connection panel
lnv_panel = uo_status.of_panel(/*key*/ "conn")

// Offline : the panel shows an error ; connected : it looks normal again
if not ib_connected then
    lnv_panel.is_text  = "Offline"
    lnv_panel.is_state = lnv_panel.STATE_ERROR
else
    lnv_panel.is_text  = "Connected"
    lnv_panel.is_state = lnv_panel.STATE_NONE   // back to the normal appearance
end if

Adapting the bar to the context #

// Hide a panel without deleting it : it will find its place again later
uo_status.of_panel(/*key*/ "user").ib_visible = ib_user_signed_in

// Gray it out when the matching action makes no sense
uo_status.of_panel(/*key*/ "save").ib_enabled = ib_document_open

// Reorder : move the status panel to the front (positions counted from 1)
uo_status.of_move_panel(/*key*/ "state", /*index*/ 1)

// Remove a panel that is no longer needed
uo_status.of_remove_panel(/*key*/ "import")

The resize grip #

// Dragging the corner grip resizes the window (hidden while it is maximized)
uo_status.ib_show_resize_grip = true

Best practices #

Give a fixed width to panels whose text changes often (cursor position, counters): the neighboring panels will stop jumping on every refresh.
A panel is inert by default: ask for the click with ib_clickable, and leave the panels that only display without one.
Keep the end of the bar (ALIGN_END) for stable information (time, user, connection) and the start (ALIGN_START) for the current context; in a right-to-left layout both sides swap on their own.
Use is_state rather than colors in the text: the state follows both the light and the dark theme.
Remember to set is_state back to STATE_NONE and ii_progress back to a negative value as soon as the alert or the operation is over.
A status bar is not a log: beyond five or six panels, prefer a toaster notification.
If the progress deserves more than a panel-sized mini bar, move up to the progressbar.

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.