ribbon — u_pbt_ribbon #

← Component reference · Guide contents

Office-style ribbon: tabs, groups, twelve types of rich controls, application menu, quick access toolbar, banner-headed contextual tabs and keytips.

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

At a glance #

The golden rule: everything goes through the path #

The ribbon is a four-level hierarchy: tab → group → control → menu entry. There are no global identifiers for you to manage: every object is reached through the path that leads to it, and every addition is made on the parent handle.

// Read or drive a control : the full path, always
uo_ruban.of_tab("accueil").of_group("presse_papier").of_item("coller").ib_enabled = false

Two practical, comfortable consequences: two different groups can use the same control identifier without clashing, and events hand you the full path — you always know where the click came from.

Quick start #

// open event of the window
n_pbt_ribbon_tab   lnv_onglet
n_pbt_ribbon_group lnv_groupe

lnv_onglet = uo_ruban.of_add_tab("accueil", "Home")

lnv_groupe = lnv_onglet.of_add_group("presse_papier", "Clipboard")
lnv_groupe.of_add_big_button("coller", "Paste", "mono:img\paste.svg")
lnv_groupe.of_add_button("couper", "Cut", "mono:img\cut.svg")
lnv_groupe.of_add_button("copier", "Copy", "mono:img\copy.svg")

uo_ruban.of_select_tab("accueil")

// ue_clicked event of uo_ruban : (string as_tab, string as_group, string as_id)
choose case as_id
    case "coller" ; of_coller()
    case "couper" ; of_couper()
    case "copier" ; of_copier()
end choose

Properties #

Constant — ACCENT_LIGHT (-1): pass it as the color of a contextual tab or group so that it follows the theme accent, lightened, instead of a fixed color.

Properties of a tab — n_pbt_ribbon_tab #

Obtained through of_tab(id), they can be changed on the fly.

Properties of a group — n_pbt_ribbon_group #

Obtained through of_tab(id).of_group(id).

Color picker mode constants: COLORMODE_PALETTE (swatch palette, the default mode) and COLORMODE_OPEN (full palette with confirmation).

Properties of a control — n_pbt_ribbon_item #

Obtained through of_tab(id).of_group(id).of_item(id). They apply to every type of control; the properties that make no sense for a given type are simply ignored.

Properties of a menu entry — n_pbt_ribbon_menu_item #

Obtained through of_tab(id).of_group(id).of_item(id).of_menu_item(id).

The twelve types of controls #

They are all added on a group handle and return the handle of the control they create — so you can go straight on to filling a menu or a list.

of_add_colorpicker accepts a fifth argument as_mode: COLORMODE_PALETTE (swatch palette) or COLORMODE_OPEN (full palette with OK and Cancel buttons).

Methods #

Building the ribbon #

Filling menus and lists #

All these methods are called on a control handle.

Application menu and quick access toolbar #

Contextual tabs #

Shared #

Events #

Every control event carries the full path: you never need an identifier that is unique across the whole application.

Examples #

A complete ribbon, from the application menu to the groups #

// open event : the whole build is grouped into a single rendering
n_pbt_ribbon_tab   lnv_onglet
n_pbt_ribbon_group lnv_groupe
n_pbt_ribbon_item  lnv_item

uo_ruban.of_set_redraw(false)
uo_ruban.is_app_button = "File"

// Application menu, with a cascade under "Save as"
uo_ruban.of_add_app_menu_item(/*id*/ "nouveau", /*label*/ "New", /*image*/ "mono:img\new.svg")
uo_ruban.of_add_app_menu_item("ouvrir", "Open...", "mono:img\open.svg")
uo_ruban.of_add_app_menu_item("enr_sous", "Save as", "mono:img\saveas.svg")
uo_ruban.of_add_app_menu_item(/*parent*/ "enr_sous", /*id*/ "sous_pdf", "PDF document", "")
uo_ruban.of_add_app_menu_item(/*parent*/ "enr_sous", /*id*/ "sous_csv", "CSV file", "")
uo_ruban.of_add_app_menu_separator("sep1")
uo_ruban.of_add_app_menu_item("quitter", "Exit", "mono:img\exit.svg")

// Quick access toolbar, above the tabs
uo_ruban.of_add_qat(/*id*/ "qat_enr", /*image*/ "mono:img\save.svg", /*tooltip*/ "Save")
uo_ruban.of_add_qat("qat_annuler", "mono:img\undo.svg", "Undo")

// Home tab
lnv_onglet = uo_ruban.of_add_tab("accueil", "Home")
lnv_onglet.is_keytip = "H"

lnv_groupe = lnv_onglet.of_add_group("presse_papier", "Clipboard")
lnv_item = lnv_groupe.of_add_big_split("coller", "Paste", "mono:img\paste.svg")
lnv_item.of_add_menu_item("coller_texte", "Paste without formatting", "")
lnv_item.of_add_menu_item("coller_lien", "Paste as link", "")
lnv_groupe.of_add_button("couper", "Cut", "mono:img\cut.svg")
lnv_groupe.of_add_button("copier", "Copy", "mono:img\copy.svg")
lnv_groupe.ib_launcher = true       // options arrow at the bottom right

uo_ruban.of_set_redraw(true)
uo_ruban.of_select_tab("accueil")

A single click router #

// ue_clicked event of uo_ruban : (string as_tab, string as_group, string as_id)
// The full path arrives with the event : a single router is enough,
// and two groups can reuse the same identifier without getting in the way.
choose case as_group + "/" + as_id
    case "presse_papier/couper" ; of_couper()
    case "presse_papier/copier" ; of_copier()
    case "presse_papier/coller" ; of_coller()
    case "police/gras"          ; of_basculer_gras()
end choose

Driving the state of controls according to permissions #

// Always through the path : tab > group > control
uo_ruban.of_tab("accueil").of_group("presse_papier").of_item("coller").ib_enabled = of_presse_papier_non_vide()
uo_ruban.of_tab("accueil").of_group("outils").of_item("pinceau").ib_checked = true
uo_ruban.of_tab("admin").ib_visible = gb_administrateur

// Gray out an entry INSIDE a drop-down menu (level 4)
uo_ruban.of_tab("accueil").of_group("presse_papier").of_item("coller") &
        .of_menu_item("coller_lien").ib_enabled = false

Banner-headed contextual tabs #

The Office principle: tabs that appear only when the selection warrants them, topped by a colored titled banner.

// open event : we prepare the contextual group, hidden by default
n_pbt_ribbon_ctx_group lnv_ctx
n_pbt_ribbon_tab       lnv_onglet
n_pbt_ribbon_group     lnv_groupe

// Without a color, the banner follows the theme accent ; RGB(...) to force it
lnv_ctx = uo_ruban.of_add_contextual_group(/*id*/ "img", /*title*/ "Picture Tools", &
                                           /*color*/ RGB(224, 32, 96))
lnv_onglet = lnv_ctx.of_add_tab("format", "Format")
lnv_groupe = lnv_onglet.of_add_group("ajuster", "Adjust")
lnv_groupe.of_add_big_button("rogner", "Crop", "mono:img\crop.svg")
lnv_groupe.of_add_button("pivoter", "Rotate", "mono:img\rotate.svg")

// When a picture is selected : we reveal the tab and activate it
uo_ruban.of_tab("format").ib_visible = true
uo_ruban.of_select_tab("format")

// When it is deselected : we hide it, the banner goes away with it
uo_ruban.of_tab("format").ib_visible = false

Drop-down, spinner, color picker and gallery #

n_pbt_ribbon_group lnv_groupe
n_pbt_ribbon_item  lnv_item

lnv_groupe = uo_ruban.of_tab("accueil").of_add_group("police", "Font")

// Editable drop-down : we fill it through its handle
lnv_item = lnv_groupe.of_add_combo(/*id*/ "nom_police", /*width_px*/ 140, /*editable*/ true)
lnv_item.of_add_combo_item("Segoe UI")
lnv_item.of_add_combo_item("Arial")
lnv_item.of_add_combo_item("Calibri")
lnv_item.is_text = "Segoe UI"

// Numeric spinner : min, max, step, initial value
lnv_groupe.of_add_spinner(/*id*/ "taille", /*width_px*/ 70, /*min*/ 6, /*max*/ 96, &
                          /*step*/ 1, /*value*/ 11)

// Color picker in full palette mode (with OK / Cancel)
lnv_groupe.of_add_colorpicker(/*id*/ "couleur", /*label*/ "Color", &
                              /*image*/ "mono:img\font-color.svg", &
                              /*color*/ RGB(0, 0, 0), &
                              /*mode*/ lnv_groupe.COLORMODE_OPEN)

// Style gallery : scrolling illustrated tiles
lnv_item = lnv_groupe.of_add_gallery(/*id*/ "styles", /*width_px*/ 220, &
                                     /*tile_width*/ 64, /*tile_height*/ 48)
lnv_item.of_add_gallery_item("st_normal", "img\style-normal.png", "Normal")
lnv_item.of_add_gallery_item("st_titre",  "img\style-titre.png",  "Title")
lnv_item.of_add_gallery_item("st_note",   "img\style-note.png",   "Note")
lnv_item.of_add_gallery_item("st_code",   "img\style-code.png",   "Code")

// The collapsed strip shows 4 thumbnails at a time ; the others stay
// reachable through the arrows, or in the expanded grid.
lnv_item.ii_visible_items = 4

lnv_item.of_select_item("st_normal")

// ue_value_changed event of uo_ruban : (string as_tab, string as_group, string as_id, double ad_value)
if as_id = "taille" then of_appliquer_taille(ad_value)

// ue_color_changed event of uo_ruban : (string as_tab, string as_group, string as_id, long al_color)
if as_id = "couleur" then of_appliquer_couleur(al_color)

Refusing the choice of a gallery thumbnail #

// The question is asked by DEFAULT: nothing to enable. This line does the
// opposite, removing it where arbitration is useless.
uo_ruban.ib_veto_gallery = false

// ue_gallery_selection_changing event of uo_ruban :
//   (string as_tab, string as_group, string as_id, string as_from_item, string as_item)
// Returning FALSE keeps the current thumbnail (as_from_item).
if as_item = "st_code" and not of_document_supporte_code() then
    MessageBox("Style", "This document cannot take the Code style.")
    return false
end if
return true

The dialog launcher #

// The small arrow at the bottom right of the group
uo_ruban.of_tab("accueil").of_group("police").ib_launcher = true

// ue_launcher event of uo_ruban : (string as_tab, string as_group)
// The path identifies the group : we open the matching options window.
choose case as_group
    case "police"        ; open(w_options_police)
    case "presse_papier" ; open(w_options_collage)
end choose

Keytips: driving the ribbon from the keyboard #

// Alt displays the letters ; Alt then H then C triggers "copier"
uo_ruban.of_tab("accueil").is_keytip = "H"
uo_ruban.of_tab("accueil").of_group("presse_papier").of_item("copier").is_keytip = "C"
uo_ruban.of_tab("accueil").of_group("presse_papier").of_item("couper").is_keytip = "X"

Pressing Alt wherever the focus sits in the window hands over to the ribbon: it takes the keyboard focus and raises its letters. You have nothing to wire — it is enough that at least one keytip is declared. Escape, a second Alt or picking a command return the focus to the control the user had left.

ue_keytips warns you at every state change, and gives you the current level:

// ue_keytips event of uo_ruban : (boolean ab_on, integer ai_level)
// The keyboard is driving the ribbon: clear the status bar hint, which talks
// about the mouse, and put it back when the letters drop.
if ab_on then
    uo_statut.of_item("main").is_text = "Type a letter (level " + String(ai_level) + ")"
else
    uo_statut.of_item("main").is_text = ""
end if

Rich tooltips on a control #

n_pbt_ribbon_item lnv_item

lnv_item = uo_ruban.of_tab("accueil").of_group("presse_papier").of_item("coller")
lnv_item.is_super_tooltip_title = "Paste (Ctrl+V)"
lnv_item.is_super_tooltip_text  = "Inserts the contents of the clipboard." &
                                + "[br][br][size-=15]Use the arrow to paste without formatting.[/size-=15]"
lnv_item.is_super_tooltip_image = "img\paste.png"

These four properties are exactly the same as on any other item of the library. For a one-line tooltip, is_tooltip alone is enough.

Automatic height #

The ribbon sizes itself: there is nothing to enable. It notifies you on every height change (collapsing, contextual tab, theme change) so that you can reposition whatever sits below.

// ue_auto_height event of uo_ruban : (long al_height)
// The ribbon has already resized itself : we reposition what sits below.
uo_contenu.y      = uo_ruban.y + uo_ruban.height
uo_contenu.height = this.height - uo_contenu.y

Collapsing the ribbon to save space #

uo_ruban.ib_minimized = true

// ue_minimized event of uo_ruban : (boolean ab_minimized)
// We remember the user preference for the next time the window opens.
of_enregistrer_preference("ruban_replie", ab_minimized)

Starting over from an empty ribbon #

// of_reset empties tabs, groups, controls, quick access toolbar and menu
uo_ruban.of_reset()
uo_ruban.of_add_tab("accueil", "Home")

From an existing PowerBuilder menu #

A PowerBuilder application has already described its commands once: in its menu. Labels, shortcuts, images, separators, sub-menus, tooltips — it is all there. n_pbt_menu2ribbon reads that menu back through RTTI and writes the PowerScript that builds the matching ribbon.

// Once, by hand : the generator WRITES code, it does not run in production.
// Paste its result into the open event of your window.
n_pbt_menu2ribbon lnv_gen
string ls_code

lnv_gen = create n_pbt_menu2ribbon
ls_code = lnv_gen.of_generate(/*menu*/ m_principal, /*variable*/ "uo_ruban")
destroy lnv_gen

ClipBoard(ls_code)

The conversion is deterministic: no AI, no network call, nothing that leaves the machine. And the generated identifiers keep the menu path (m_principal.m_fichier.m_ouvrir), so the choose case of your existing actions works as it is from ue_clicked.

The generated code is a starting point to review, not a deliverable: a menu is a list, a ribbon is a layout. Group things, choose your big buttons, drop what does not deserve to be permanently on show. Sample 9 of the ribbon page in the demo application shows a complete result.

Best practices #

• Wrap the whole build in of_set_redraw(false) / of_set_redraw(true): a complete ribbon is then drawn in one go, without flickering.
• Keep the returned handles (n_pbt_ribbon_tab, n_pbt_ribbon_group, n_pbt_ribbon_item) in local variables for the duration of the build: the code stays short and readable. To drive a control later on, simply go back through the path.
• Call of_preload_icons at startup: without it, the first display of a tab that has never been opened shows a brief delay before its icons appear.
• An identifier only needs to be unique within its group. Take advantage of that to name your controls simply (copier, coller) rather than with prefixes.
• Reserve contextual tabs for commands that make no sense out of context: a grayed-out permanent tab is more restful than a tab that appears and disappears.
• The question is asked by default: a ue_gallery_selection_changing left empty always allows the pick, you have nothing to do. Switch it off with ib_veto_gallery = false if arbitration is useless to you, since every question costs a round trip to PowerBuilder.
• One dialog launcher per group at most, and only if the group really has advanced options to offer.
• To rebuild an entire ribbon, prefer of_clear() (or of_reset()) over a series of of_remove_tab calls: without that, reusing a tab identifier fails.
• For a lighter command bar, without tabs or groups, see toolbar; for side navigation, listbar.

← Component reference · Guide contents