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 #

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à #

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à di un gruppo — n_pbt_ribbon_group #

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

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à 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).

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.

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 #

Riempire i menu e gli elenchi #

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

Menu applicativo e barra di accesso rapido #

Schede contestuali #

Comuni #

Event #

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

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