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 #

Quick start #

// window open event
// of_add_panel(id, text, icon, alignment, width)
// empty id = purely informative panel ; width 0 = fitted to the text
uo_statut.of_add_panel(/*key*/ "etat",  /*text*/ "Ready",           /*icon_file*/ "", /*align*/ uo_statut.ALIGN_START,  /*width*/ 0)
uo_statut.of_add_panel(/*key*/ "",      /*text*/ "Line 12, Col 4", /*icon_file*/ "", /*align*/ uo_statut.ALIGN_START,  /*width*/ 0)
uo_statut.of_add_panel(/*key*/ "heure", /*text*/ "12:00",          /*icon_file*/ "", /*align*/ uo_statut.ALIGN_END, /*width*/ 140)

// Update a panel at any time, through its identifier
uo_statut.of_panel("etat").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.
• 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.
• To make a panel clickable, ask for it: of_panel("id").ib_clickable = true. A panel carrying a drop-down list (of_add_menu_item) already is.

uo_statut.of_panel("etat").is_text = "3 records changed"

See Shared foundation · Items.

Properties #

Methods #

The arguments of of_add_panel #

On a panel — n_pbt_statusbar_panel #

On a drop-down entry — n_pbt_statusbar_menu_item #

Obtained through of_menu_item("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.

uo_statut.of_add_menu_item("enc/utf8", "UTF-8")
uo_statut.of_add_menu_item("enc/ansi", "ANSI")
uo_statut.of_menu_item("enc/utf8").ib_checked = true     // la valeur en cours
uo_statut.of_menu_item("enc/ansi").ib_enabled = false    // pas disponible ici

State constants #

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

uo_statut.of_panel("etat").is_state = n_pbt_statusbar_panel.STATE_WARNING

Events #

Keyboard #

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

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_statut.of_add_panel(/*key*/ "", /*text*/ "Panel fitted to its content", /*icon_file*/ "", /*align*/ uo_statut.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_statut.of_add_panel(/*key*/ "pos", /*text*/ "Line 1, Col 1", /*icon_file*/ "", /*align*/ uo_statut.ALIGN_START, /*width*/ 150)

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

Icons and clickable panels #

// A non-empty identifier makes the panel clickable
uo_statut.of_add_panel(/*key*/ "save", /*text*/ "Saved", /*icon_file*/ "mono:img\save.svg", /*align*/ uo_statut.ALIGN_START, /*width*/ 0)
uo_statut.of_add_sep()   // separator line between two groups of panels
uo_statut.of_add_panel(/*key*/ "conn", /*text*/ "Connected",   /*icon_file*/ "mono:img\plug.svg", /*align*/ uo_statut.ALIGN_START, /*width*/ 0)
uo_statut.of_add_panel(/*key*/ "user", /*text*/ "Guillaume",  /*icon_file*/ "mono:img\user.svg", /*align*/ uo_statut.ALIGN_END, /*width*/ 160)

// ue_panel_clicked event of uo_statut
choose case as_keys
    case "conn" ; open(w_parametres_connexion)
    case "user" ; open(w_profil)
end choose

Rich text in a panel #

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

uo_statut.of_add_panel(/*key*/ "", /*text*/ "Welcome [b]to[/b] [accent]PBToolboxAI[/accent]", &
                       /*icon_file*/ "", /*align*/ uo_statut.ALIGN_START, /*width*/ 0)

uo_statut.of_add_panel(/*key*/ "", /*text*/ "[green]Online[/green] [picture=mono:img\plug.svg,14,14]", &
                       /*icon_file*/ "", /*align*/ uo_statut.ALIGN_END, /*width*/ 0)

// Rich text works for updates too
uo_statut.of_panel("etat").is_text = "[b]" + String(ll_modifies) + "[/b] records changed"

Following a long operation #

n_pbt_statusbar_panel lnv_avance

uo_statut.of_add_panel(/*key*/ "import", /*text*/ "Import", /*icon_file*/ "", /*align*/ uo_statut.ALIGN_START, /*width*/ 220)
lnv_avance = uo_statut.of_panel("import")

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

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

Raising a discreet alert #

n_pbt_statusbar_panel lnv_panneau
lnv_panneau = uo_statut.of_panel("conn")

if not ib_connecte then
    lnv_panneau.is_text  = "Offline"
    lnv_panneau.is_state = lnv_panneau.STATE_ERROR
else
    lnv_panneau.is_text  = "Connected"
    lnv_panneau.is_state = lnv_panneau.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_statut.of_panel("user").ib_visible = ib_utilisateur_identifie

// Gray it out when the matching action makes no sense
uo_statut.of_panel("save").ib_enabled = ib_document_ouvert

// Reorder : move the status panel to the front (positions counted from 0)
uo_statut.of_move_panel(/*key*/ "etat", /*index*/ 0)

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

The resize grip #

// On a resizable window, the corner grip is a familiar landmark
uo_statut.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.
• Leave the identifier empty for a purely informative panel: that avoids a click that does nothing.
• Save the right-hand side for stable information (time, user, connection) and the left-hand side for the current context.
• 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.

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.

← Component reference · Guide contents