# ribbon — `u_pbt_ribbon` #

← Riferimento dei componenti · Sommario della guida

> Barra multifunzione in stile Office: schede, gruppi, dodici tipi di controlli avanzati, menu applicativo, barra di accesso rapido, schede contestuali con banner e keytip.

> ▶ Vederlo dal vivo — Applicazione dimostrativa, riquadro Ribbon: l'anteprima, il codice che lo produce e questa pagina, affiancati.

## In breve #

Userobject | `u_pbt_ribbon`
Classi degli item | `n_pbt_ribbon_tab` (scheda), `n_pbt_ribbon_group` (gruppo), `n_pbt_ribbon_item` (controllo), `n_pbt_ribbon_menu_item` (voce di menu), `n_pbt_ribbon_ctx_group` (gruppo di schede contestuali)
Serve per | Sostituire una barra dei menu e le relative barre degli strumenti con un'interfaccia di comando moderna, leggibile e gerarchizzata
Altezza | Intrinseca: la barra multifunzione si allinea sempre al proprio contenuto, nulla da attivare — vedere Altezza automatica
Limite in modalità demo | 2 schede al massimo — vedere La modalità demo

### La regola d'oro: tutto passa dal percorso #

La barra multifunzione è una gerarchia a quattro livelli: scheda → gruppo → controllo → voce di menu. Non c'è alcun identificatore globale da gestire: ogni oggetto si raggiunge attraverso il percorso che vi conduce e ogni aggiunta avviene sull'handle del genitore.

    // Leggere o pilotare un controllo : sempre il percorso completo
    uo_ruban.of_tab("accueil").of_group("presse_papier").of_item("coller").ib_enabled = false

Due conseguenze pratiche e comode: due gruppi diversi possono usare lo stesso identificatore di controllo senza intralciarsi e gli event Le consegnano il percorso completo — sa sempre da dove proviene il clic.

## Avvio rapido #

    // event open della finestra
    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", "Appunti")
    lnv_groupe.of_add_big_button("coller", "Incolla", "mono:img\paste.svg")
    lnv_groupe.of_add_button("couper", "Taglia", "mono:img\cut.svg")
    lnv_groupe.of_add_button("copier", "Copia", "mono:img\copy.svg")

    uo_ruban.of_select_tab("accueil")

    // event ue_clicked di 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

## Proprietà #

Proprietà | Tipo | Predefinito | Ruolo
--- | --- | --- | ---
`is_app_button` | string | `""` | Etichetta del pulsante applicativo, in alto a sinistra, che apre il menu applicativo. Vuoto = etichetta `File`
`ib_minimized` | boolean | `false` | `true` riduce la barra multifunzione alle sole intestazioni delle schede; un clic su una scheda la espande temporaneamente (attiva `ue_minimized`)
`ib_veto_gallery` | boolean | `true` | Chiedere prima che una piastrella di galleria venga scelta (attiva `ue_gallery_selection_changing`, che può rifiutare). Attivo per impostazione predefinita: non scrivere nulla lascia sempre passare. Lo metta a `false` per togliere l'andata e ritorno verso PowerBuilder (~35 ms) dove si noterebbe
`is_theme_style` | string | `fluent` | Stile visivo del componente (costanti `THEME_STYLE_*`)
`is_theme_mode` | string | `light` | Variante chiara o scura (costanti `THEME_MODE_*`)
`il_theme_accent` | long | `-1` | Colore d'accento di questo componente (`-1` = accento del tema)
`is_tooltip` | string | `""` | Tooltip semplice mostrato al passaggio del mouse sul componente
`is_super_tooltip_title` | string | `""` | Titolo del tooltip avanzato (prevale su `is_tooltip`)
`is_super_tooltip_text` | string | `""` | Testo del tooltip avanzato (markup avanzato accettato)
`is_super_tooltip_image` | string | `""` | Immagine del tooltip avanzato

Costante — `ACCENT_LIGHT` (`-1`): da passare come colore di una scheda o di un gruppo contestuale affinché segua il colore d'accento del tema, schiarito, anziché un colore fisso.

### Proprietà di una scheda — `n_pbt_ribbon_tab` #

Ottenute tramite `of_tab(id)`, si modificano a caldo.

Proprietà | Tipo | Predefinito | Ruolo
--- | --- | --- | ---
`ib_visible` | boolean | `true` | `false` nasconde la scheda senza eliminarla — è il meccanismo stesso delle schede contestuali
`is_keytip` | string | `""` | Lettera di accesso rapido visualizzata dopo la pressione di Alt (`"H"` per Home)

### Proprietà di un gruppo — `n_pbt_ribbon_group` #

Ottenute tramite `of_tab(id).of_group(id)`.

Proprietà | Tipo | Predefinito | Ruolo
--- | --- | --- | ---
`ib_visible` | boolean | `true` | `false` nasconde il gruppo e tutti i suoi controlli
`ib_launcher` | boolean | `false` | Mostra la piccola freccia in basso a destra nel gruppo — l'avvio della finestra di dialogo (attiva `ue_launcher`). La freccia vive nella barra del titolo del gruppo, e un gruppo che la barra multifunzione ha dovuto ridurre per mancanza di spazio la mantiene nello stesso posto — viaggia inoltre nel pannello aperto dal gruppo ridotto.

Costanti di modalità del selettore di colore: `COLORMODE_PALETTE` (tavolozza di campioni, modalità predefinita) e `COLORMODE_OPEN` (tavolozza completa con conferma).

### Proprietà di un controllo — `n_pbt_ribbon_item` #

Ottenute tramite `of_tab(id).of_group(id).of_item(id)`. Si applicano a tutti i tipi di controllo; le proprietà prive di senso per un dato tipo vengono semplicemente ignorate.

Proprietà | Tipo | Predefinito | Ruolo
--- | --- | --- | ---
`is_label` | string | `""` | Etichetta del controllo. Accetta il testo formattato con tag
`ib_enabled` | boolean | `true` | `false` disattiva il controllo e ne blocca l'attivazione
`ib_checked` | boolean | `false` | Stato premuto di un interruttore o selezionato di una casella di controllo
`ib_visible` | boolean | `true` | `false` nasconde il controllo; i vicini si compattano
`is_text` | string | `""` | Testo digitato o selezionato in una casella combinata
`id_value` | double | `0` | Valore numerico di un selettore numerico
`il_color` | long | `-1` | Colore corrente di un selettore di colore
`ii_visible_items` | integer | `3` | Solo raccolta: numero di riquadri che la striscia compressa mostra in una volta. Gli altri restano raggiungibili tramite le frecce, oppure nella griglia espansa
`is_keytip` | string | `""` | Lettera di accesso rapido del controllo, visualizzata dopo la pressione di Alt
`is_tooltip` | string | `""` | Tooltip semplice mostrato al passaggio del mouse sull'item
`is_super_tooltip_title` | string | `""` | Titolo del tooltip avanzato dell'item (prevale su `is_tooltip`)
`is_super_tooltip_text` | string | `""` | Testo del tooltip avanzato dell'item (markup avanzato accettato)
`is_super_tooltip_image` | string | `""` | Immagine del tooltip avanzato dell'item

### Proprietà di una voce di menu — `n_pbt_ribbon_menu_item` #

Ottenute tramite `of_tab(id).of_group(id).of_item(id).of_menu_item(id)`.

Proprietà | Tipo | Predefinito | Ruolo
--- | --- | --- | ---
`ib_enabled` | boolean | `true` | `false` disattiva la voce
`ib_checked` | boolean | `false` | Segno di spunta di una voce creata con `of_add_menu_check`

## I dodici tipi di controlli #

Si aggiungono tutti sull'handle di un gruppo e restituiscono l'handle del controllo creato — può quindi proseguire subito con il riempimento di un menu o di un elenco.

Metodo del gruppo | Controllo ottenuto | Event
--- | --- | ---
`of_add_big_button (id, label, image)` | Pulsante grande a tutta altezza, icona sopra l'etichetta | `ue_clicked`
`of_add_big_split (id, label, image)` | Pulsante grande diviso: la parte superiore agisce, la freccia apre il menu | `ue_clicked` · `ue_menu_selected`
`of_add_big_dropdown (id, label, image)` | Pulsante grande con menu a discesa | `ue_menu_selected`
`of_add_button (id, label, image)` | Pulsante piccolo (impilato in colonne da tre) | `ue_clicked`
`of_add_toggle (id, label, image)` | Piccolo interruttore che rimane premuto | `ue_toggled`
`of_add_dropdown (id, label, image)` | Pulsante piccolo con menu a discesa | `ue_menu_selected`
`of_add_checkbox (id, label)` | Casella di controllo | `ue_toggled`
`of_add_separator ( )` | Separatore verticale tra due blocchi di controlli | —
`of_add_combo (id, largeur_px, modifiable)` | Casella combinata, modificabile o meno | `ue_combo_changed`
`of_add_spinner (id, largeur_px, mini, maxi, pas, valeur)` | Selettore numerico con frecce | `ue_value_changed`
`of_add_colorpicker (id, label, image, couleur)` | Pulsante di colore diviso: il clic riapplica, la freccia apre la tavolozza di campioni | `ue_clicked` · `ue_color_changed`
`of_add_gallery (id, larghezza_px, larghezza_piastrella, altezza_piastrella)` | Striscia scorrevole di piastrelle illustrate | `ue_gallery_selection_changed`

`of_add_colorpicker` accetta un quinto argomento `as_mode`: `COLORMODE_PALETTE` (tavolozza di campioni) o `COLORMODE_OPEN` (tavolozza completa con i pulsanti OK e Annulla).

## Metodi #

### Costruire la barra multifunzione #

Metodo | Ruolo
--- | ---
`of_add_tab (string as_id, string as_title)` | Aggiunge una scheda e ne restituisce l'handle: vi concateni sopra i gruppi
`of_insert_tab (string as_id, string as_title, integer ai_index)` | Aggiunge una scheda nella posizione che sceglie lei (`0` = in testa) invece che in fondo, e ne restituisce l'handle come `of_add_tab`. Un id già assegnato viene rifiutato
`of_tab (string as_id)` | Handle di una scheda esistente (creata al primo accesso)
`of_add_group (string as_id, string as_title)` | Su un handle di scheda: aggiunge un gruppo intitolato e ne restituisce l'handle
`of_group (string as_id)` | Su un handle di scheda: handle di un gruppo esistente
`of_item (string as_id)` | Su un handle di gruppo: handle di un controllo esistente
`of_select_tab (string as_id)` | Attiva una scheda — rigorosamente equivalente a un clic dell'utente (attiva `ue_selection_changed`)
`of_selected_key ( )` | Identificatore della scheda attiva, `""` se nessuna. Tenuto aggiornato da `ue_selection_changed`, quindi corretto fin dall'avvio
`of_remove_group (string as_id)` | Su un handle di scheda: rimuove un gruppo e tutti i suoi controlli
`of_remove_item (string as_id)` | Su un handle di gruppo: rimuove un controllo
`of_remove_tab (string as_id)` | Rimuove una scheda e tutto il suo contenuto
`of_clear ( )` | Svuota completamente la barra multifunzione: schede, gruppi, controlli, barra di accesso rapido, menu applicativo

### Riempire i menu e gli elenchi #

Tutti questi metodi si richiamano sull'handle di un controllo.

Metodo | Ruolo
--- | ---
`of_add_menu_item (string as_id, string as_label, string as_image)` | Voce radice del menu di un pulsante a discesa o diviso
`of_add_menu_item (string as_parent, string as_id, string as_label, string as_image)` | Voce a cascata: `as_parent` indica una voce esistente di questo menu
`of_add_menu_check (string as_id, string as_label)` · `(id, label, image)` | Voce selezionabile: il clic ne inverte lo stato e lo riporta in `ue_menu_selected`
`of_add_menu_header (string as_label)` | Riga di titolo non cliccabile, per suddividere un menu lungo
`of_add_menu_separator ( )` | Riga di separazione nel menu
`of_menu_item (string as_id)` | Handle di una voce di menu, per disattivarla o selezionarla a caldo
`of_add_combo_item (string as_label)` | Aggiunge una scelta all'elenco di una casella combinata
`of_add_gallery_item (string as_id, string as_image, string as_label)` | Aggiunge un riquadro a una raccolta
`of_select_item (string as_id)` | Seleziona un riquadro di una raccolta da programma (senza attivare alcun event)
`of_open ( )` | Apre da programma il menu, l'elenco o la tavolozza di campioni del controllo

### Menu applicativo e barra di accesso rapido #

Metodo | Ruolo
--- | ---
`of_add_app_menu_item (string as_id, string as_label, string as_image)` | Voce radice del menu applicativo (quello che apre il pulsante `is_app_button`)
`of_add_app_menu_item (string as_parent, string as_id, string as_label, string as_image)` | Voce a cascata del menu applicativo
`of_add_app_menu_separator (string as_id)` | Riga di separazione nel menu applicativo
`of_add_qat (string as_id, string as_image, string as_tooltip)` | Pulsante della barra di accesso rapido, sopra le schede, e ne restituisce l'handle
`of_qat_item (string as_id)` | Handle di un pulsante di accesso rapido, per disattivarlo o nasconderlo a caldo

### Schede contestuali #

Metodo | Ruolo
--- | ---
`of_add_contextual_tab (string as_id, string as_title, long al_color)` | Scheda contestuale isolata: creata nascosta, contrassegnata da un bordo colorato. Passi `ACCENT_LIGHT` per seguire il colore d'accento del tema
`of_add_contextual_group (string as_id, string as_title)` · `(id, title, al_color)` | Gruppo di schede contestuali: un banner intitolato e colorato sovrasta le sue schede. Ne restituisce l'handle
`of_ctx_group (string as_id)` | Recupera l'handle di un gruppo contestuale già creato — utile quando non ha conservato quello restituito alla creazione
`of_add_tab (string as_id, string as_title)` | Su un handle di gruppo contestuale: aggiunge una scheda sovrastata dal banner, creata nascosta
`of_tab (string as_id)` | Su un handle di gruppo contestuale: handle di una delle sue schede
`il_color` (proprietà) | Su un handle di gruppo contestuale: ricolora il banner a caldo (`ACCENT_LIGHT` per tornare al colore d'accento)

### Comuni #

Metodo | Ruolo
--- | ---
`of_reset ( )` | Svuota la barra multifunzione e la riporta allo stato iniziale, proprietà comprese
`of_set_redraw (boolean)` | Raggruppa una raffica di modifiche in un unico rendering
`of_preload_icons (string as_icons[])` | Preriscalda un lotto di icone all'avvio: una scheda aperta più tardi mostra le proprie istantaneamente
`of_save_as_png (string)` · `of_save_as_jpg (string)` | Esporta il rendering come immagine

## Event #

Tutti gli event dei controlli portano con sé il percorso completo: non ha mai bisogno di un identificatore univoco in tutta l'applicazione.

Event | Attivato quando
--- | ---
`ue_clicked (string as_tab, string as_group, string as_id)` | Si fa clic su un pulsante, un pulsante grande, la parte principale di un pulsante diviso o di un selettore di colore
`ue_toggled (string as_tab, string as_group, string as_id, boolean ab_checked)` | Un interruttore o una casella di controllo cambia stato; `ab_checked` porta il nuovo stato
`ue_menu_selected (string as_tab, string as_group, string as_dropdown, string as_id, boolean ab_checked)` | Viene scelta una voce di un menu a discesa. `as_dropdown` = il controllo che lo contiene, `as_id` = la voce, `ab_checked` = lo stato di una voce selezionabile
`ue_combo_changed (string as_tab, string as_group, string as_id, string as_text)` | Una casella combinata cambia valore, per selezione o per digitazione
`ue_value_changed (string as_tab, string as_group, string as_id, double ad_value)` | Un selettore numerico cambia valore
`ue_color_changed (string as_tab, string as_group, string as_id, long al_color)` | Viene scelto un colore in un selettore di colore
`ue_gallery_selection_changed (string as_tab, string as_group, string as_id, string as_from_item, string as_item)` | Una piastrella di galleria è stata scelta. Stessi argomenti di `ue_gallery_selection_changing`: la domanda e il suo esito si leggono allo stesso modo, e `as_from_item` è la piastrella lasciata
`ue_gallery_selection_changing (string as_tab, string as_group, string as_id, string as_from_item, string as_item)` → boolean | Annullabile, posto prima che la piastrella venga scelta. Sollevato per impostazione predefinita; `ib_veto_gallery = false` lo elimina. `as_from_item` è la piastrella corrente. Restituisca `false` per conservarla (uno stile che il documento non può ancora assumere)
`ue_launcher (string as_tab, string as_group)` | Si fa clic sulla freccia di avvio di un gruppo — apra la Sua finestra delle opzioni
`ue_selection_changed (string as_id)` | Una scheda diventa attiva, per clic oppure tramite `of_select_tab`
`ue_app_button ( )` | Si fa clic sul pulsante applicativo
`ue_app_menu_selected (string as_id)` | Viene scelta una voce del menu applicativo
`ue_minimized (boolean ab_minimized)` | La barra multifunzione viene ridotta o espansa dall'utente
`ue_size_changed (long al_height, boolean ab_minimized)` | L'altezza della barra multifunzione è cambiata da sola: ridotta, espansa, una scheda contestuale mostrata, una finestra più stretta che perde una riga. A differenza di `ue_auto_height` — che parla solo quando il componente si ridimensiona da sé — questo si attiva sia che l'altezza automatica sia attiva o no: è pura informazione, per ricollocare ciò che sta sotto
`ue_keytips (boolean ab_on, integer ai_level)` | I keytip compaiono (`true`) o scompaiono (`false`). `ai_level` indica a che punto è la navigazione: `1` = le schede sono lettrate, `2` = lo sono i comandi della scheda corrente, `0` = nessun keytip
`ue_auto_height (long al_height)` | La barra multifunzione comunica la propria altezza ideale e vi si è appena adattata — sempre attivo: l'altezza di una barra multifunzione è intrinseca
`ue_ready ( )` | Il componente ha terminato il caricamento; tutto ciò che è stato inviato prima è stato riprodotto
`ue_runtime_missing ( )` | Il runtime WebView2 è assente: il componente resta vuoto
`ue_bg_color (long al_color)` | Il componente ha calcolato il colore di sfondo del proprio tema; l'userobject lo ha già adottato (`backcolor`)

## Esempi #

### Una barra multifunzione completa, dal menu applicativo ai gruppi #

    // event open : si raggruppa tutta la costruzione in un unico 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"

    // Menu applicativo, con una cascata sotto "Salva con nome"
    uo_ruban.of_add_app_menu_item(/*id*/ "nouveau", /*etichetta*/ "Nuovo", /*immagine*/ "mono:img\new.svg")
    uo_ruban.of_add_app_menu_item("ouvrir", "Apri...", "mono:img\open.svg")
    uo_ruban.of_add_app_menu_item("enr_sous", "Salva con nome", "mono:img\saveas.svg")
    uo_ruban.of_add_app_menu_item(/*parent*/ "enr_sous", /*id*/ "sous_pdf", "Documento PDF", "")
    uo_ruban.of_add_app_menu_item(/*parent*/ "enr_sous", /*id*/ "sous_csv", "File CSV", "")
    uo_ruban.of_add_app_menu_separator("sep1")
    uo_ruban.of_add_app_menu_item("quitter", "Esci", "mono:img\exit.svg")

    // Barra di accesso rapido, sopra le schede
    uo_ruban.of_add_qat(/*id*/ "qat_enr", /*immagine*/ "mono:img\save.svg", /*tooltip*/ "Salva")
    uo_ruban.of_add_qat("qat_annuler", "mono:img\undo.svg", "Annulla")

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

    lnv_groupe = lnv_onglet.of_add_group("presse_papier", "Appunti")
    lnv_item = lnv_groupe.of_add_big_split("coller", "Incolla", "mono:img\paste.svg")
    lnv_item.of_add_menu_item("coller_texte", "Incolla senza formattazione", "")
    lnv_item.of_add_menu_item("coller_lien", "Incolla come collegamento", "")
    lnv_groupe.of_add_button("couper", "Taglia", "mono:img\cut.svg")
    lnv_groupe.of_add_button("copier", "Copia", "mono:img\copy.svg")
    lnv_groupe.ib_launcher = true       // freccia delle opzioni in basso a destra

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

### Un unico smistamento dei clic #

    // event ue_clicked di uo_ruban : (string as_tab, string as_group, string as_id)
    // Il percorso completo arriva con l'event : basta un solo smistamento,
    // e due gruppi possono riutilizzare lo stesso identificatore senza disturbarsi.
    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

### Pilotare lo stato dei controlli in base ai diritti #

    // Sempre attraverso il percorso : scheda > gruppo > controllo
    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

    // Disattivare una voce DENTRO un menu a discesa (livello 4)
    uo_ruban.of_tab("accueil").of_group("presse_papier").of_item("coller") &
            .of_menu_item("coller_lien").ib_enabled = false

### Schede contestuali con banner #

Il principio di Office: schede che compaiono solo quando la selezione le giustifica, sovrastate da un banner intitolato e colorato.

    // event open : si prepara il gruppo contestuale, nascosto per impostazione predefinita
    n_pbt_ribbon_ctx_group lnv_ctx
    n_pbt_ribbon_tab       lnv_onglet
    n_pbt_ribbon_group     lnv_groupe

    // Senza colore, il banner segue il colore d'accento del tema ; RGB(...) per imporlo
    lnv_ctx = uo_ruban.of_add_contextual_group(/*id*/ "img", /*titolo*/ "Strumenti immagine", &
                                               /*colore*/ RGB(224, 32, 96))
    lnv_onglet = lnv_ctx.of_add_tab("format", "Formato")
    lnv_groupe = lnv_onglet.of_add_group("ajuster", "Regola")
    lnv_groupe.of_add_big_button("rogner", "Ritaglia", "mono:img\crop.svg")
    lnv_groupe.of_add_button("pivoter", "Ruota", "mono:img\rotate.svg")

    // Alla selezione di un'immagine : si rivela la scheda e la si attiva
    uo_ruban.of_tab("format").ib_visible = true
    uo_ruban.of_select_tab("format")

    // Alla deselezione : la si nasconde, il banner sparisce con lei
    uo_ruban.of_tab("format").ib_visible = false

### Casella combinata, selettore numerico, selettore di colore e raccolta #

    n_pbt_ribbon_group lnv_groupe
    n_pbt_ribbon_item  lnv_item

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

    // Casella combinata modificabile : la si riempie tramite il suo handle
    lnv_item = lnv_groupe.of_add_combo(/*id*/ "nom_police", /*larghezza_px*/ 140, /*modificabile*/ 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"

    // Selettore numerico : minimo, massimo, passo, valore iniziale
    lnv_groupe.of_add_spinner(/*id*/ "taille", /*larghezza_px*/ 70, /*minimo*/ 6, /*massimo*/ 96, &
                              /*passo*/ 1, /*valore*/ 11)

    // Selettore di colore in modalita tavolozza completa (con OK / Annulla)
    lnv_groupe.of_add_colorpicker(/*id*/ "couleur", /*etichetta*/ "Colore", &
                                  /*immagine*/ "mono:img\font-color.svg", &
                                  /*colore*/ RGB(0, 0, 0), &
                                  /*modalita*/ lnv_groupe.COLORMODE_OPEN)

    // Raccolta di stili : riquadri illustrati scorrevoli
    lnv_item = lnv_groupe.of_add_gallery(/*id*/ "styles", /*larghezza_px*/ 220, &
                                         /*larghezza_riquadro*/ 64, /*altezza_riquadro*/ 48)
    lnv_item.of_add_gallery_item("st_normal", "img\style-normal.png", "Normale")
    lnv_item.of_add_gallery_item("st_titre",  "img\style-titre.png",  "Titolo")
    lnv_item.of_add_gallery_item("st_note",   "img\style-note.png",   "Nota")
    lnv_item.of_add_gallery_item("st_code",   "img\style-code.png",   "Codice")

    // La striscia compressa mostra 4 riquadri alla volta ; gli altri restano
    // raggiungibili tramite le frecce, oppure nella griglia espansa.
    lnv_item.ii_visible_items = 4

    lnv_item.of_select_item("st_normal")

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

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

### Rifiutare la scelta di un riquadro di raccolta #

    // La domanda e posta per IMPOSTAZIONE PREDEFINITA: niente da attivare. Questa
    // riga fa il contrario, la toglie dove arbitrare non serve.
    uo_ruban.ib_veto_gallery = false

    // event ue_gallery_selection_changing di uo_ruban :
    //   (string as_tab, string as_group, string as_id, string as_from_item, string as_item)
    // Restituire FALSE conserva il riquadro corrente (as_from_item).
    if as_item = "st_code" and not of_document_supporte_code() then
        MessageBox("Stile", "Questo documento non può assumere lo stile Codice.")
        return false
    end if
    return true

### L'avvio della finestra di dialogo #

    // La piccola freccia in basso a destra nel gruppo
    uo_ruban.of_tab("accueil").of_group("police").ib_launcher = true

    // event ue_launcher di uo_ruban : (string as_tab, string as_group)
    // Il percorso identifica il gruppo : si apre la finestra delle opzioni corrispondente.
    choose case as_group
        case "police"        ; open(w_options_police)
        case "presse_papier" ; open(w_options_collage)
    end choose

### Keytip: guidare la barra multifunzione da tastiera #

    // Alt mostra le lettere ; Alt poi H poi C attiva "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"

Una pressione di Alt ovunque si trovi il focus nella finestra passa la mano alla barra multifunzione: prende il focus da tastiera e mostra le proprie lettere. Non c'è nulla da collegare: basta che sia dichiarato almeno un keytip. Esc, un secondo Alt o la scelta di un comando restituiscono il focus al controllo che l'utente aveva abbandonato.

`ue_keytips` la avvisa a ogni cambiamento di stato e le comunica il livello corrente:

    // event ue_keytips di uo_ruban : (boolean ab_on, integer ai_level)
    // La tastiera pilota la barra multifunzione: cancellare il suggerimento della
    // barra di stato, che parla del mouse, e ripristinarlo quando le lettere spariscono.
    if ab_on then
        uo_statut.of_item("main").is_text = "Digiti una lettera (livello " + String(ai_level) + ")"
    else
        uo_statut.of_item("main").is_text = ""
    end if

### Tooltip avanzati su un controllo #

    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 = "Incolla (Ctrl+V)"
    lnv_item.is_super_tooltip_text  = "Inserisce il contenuto degli appunti." &
                                    + "[br][br][size-=15]Usi la freccia per incollare senza formattazione.[/size-=15]"
    lnv_item.is_super_tooltip_image = "img\paste.png"

Queste quattro proprietà sono esattamente le stesse di qualsiasi altro item della libreria. Per un tooltip su una sola riga basta `is_tooltip`.

### Altezza automatica #

La barra multifunzione si dimensiona da sola: non c'è nulla da attivare. La avvisa a ogni cambiamento di altezza (compressione, scheda contestuale, cambio di tema) affinché Lei possa riposizionare ciò che si trova al di sotto.

    // event ue_auto_height di uo_ruban : (long al_height)
    // La barra multifunzione si e gia ridimensionata : si riposiziona cio che sta sotto.
    uo_contenu.y      = uo_ruban.y + uo_ruban.height
    uo_contenu.height = this.height - uo_contenu.y

### Ridurre la barra multifunzione per guadagnare spazio #

    uo_ruban.ib_minimized = true

    // event ue_minimized di uo_ruban : (boolean ab_minimized)
    // Si memorizza la preferenza dell'utente per la prossima apertura.
    of_enregistrer_preference("ruban_replie", ab_minimized)

### Ripartire da una barra multifunzione vuota #

    // of_reset svuota schede, gruppi, controlli, barra di accesso rapido e menu
    uo_ruban.of_reset()
    uo_ruban.of_add_tab("accueil", "Home")

## Da un menu PowerBuilder esistente #

Un'applicazione PowerBuilder ha già descritto i suoi comandi una volta: nel suo menu. Etichette, scorciatoie, immagini, separatori, sottomenu, suggerimenti — c'è tutto. `n_pbt_menu2ribbon` rilegge quel menu tramite RTTI e scrive il PowerScript che costruisce la barra multifunzione corrispondente.

    // Una sola volta, a mano : il generatore SCRIVE del codice, non viene eseguito
    // in produzione. Incollate il risultato nell'open della vostra finestra.
    n_pbt_menu2ribbon lnv_gen
    string ls_code

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

    ClipBoard(ls_code)

La conversione è deterministica: nessuna IA, nessuna chiamata di rete, niente che esca dalla postazione. E gli identificatori generati conservano il percorso del menu (`m_principal.m_fichier.m_ouvrir`), così il `choose case` delle vostre azioni esistenti funziona tale e quale da `ue_clicked`.

Il codice prodotto è un punto di partenza da rileggere, non un risultato finito: un menu è un elenco, una barra multifunzione è un'impaginazione. Raggruppate, scegliete i pulsanti grandi, togliete ciò che non merita di stare sempre in vista. L'esempio 9 della pagina barra multifunzione dell'applicazione dimostrativa mostra un risultato completo.

## Buone pratiche #

- Racchiuda tutta la costruzione tra `of_set_redraw(false)` e `of_set_redraw(true)`: una barra multifunzione completa viene così disegnata in una sola volta, senza sfarfallio.
- Conservi gli handle restituiti (`n_pbt_ribbon_tab`, `n_pbt_ribbon_group`, `n_pbt_ribbon_item`) in variabili locali per il tempo della costruzione: il codice resta breve e leggibile. Per pilotare un controllo più tardi, ripassi semplicemente dal percorso.
- Richiami `of_preload_icons` all'avvio: senza di esso, la prima visualizzazione di una scheda mai aperta mostra un breve ritardo prima delle sue icone.
- Un identificatore deve essere univoco solo all'interno del proprio gruppo. Ne approfitti per dare ai controlli nomi semplici (`copier`, `coller`) anziché ricorrere ai prefissi.
- Riservi le schede contestuali ai comandi che non hanno alcun senso fuori contesto: una scheda permanente disattivata è più riposante di una scheda che compare e scompare.
- La domanda è posta per impostazione predefinita: un `ue_gallery_selection_changing` lasciato vuoto autorizza sempre la scelta, non deve fare nulla. La disattivi con `ib_veto_gallery = false` se arbitrare non le serve, perché ogni domanda costa un andata e ritorno verso PowerBuilder.
- Un solo avvio di finestra di dialogo per gruppo, e soltanto se il gruppo ha davvero opzioni avanzate da offrire.
- Per ricostruire un'intera barra multifunzione, preferisca `of_clear()` (o `of_reset()`) a una serie di `of_remove_tab`: senza di ciò, il riutilizzo di un identificatore di scheda non riesce.
- Per una barra dei comandi più leggera, senza schede né gruppi, veda toolbar; per una navigazione laterale, listbar.

← Riferimento dei componenti · Sommario della guida