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_item("accueil/presse_papier/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

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

uo_ruban.of_add_group("accueil/presse_papier", "Appunti")
uo_ruban.of_add_big_button("accueil/presse_papier/coller", "Incolla", "mono:img\paste.svg")
uo_ruban.of_add_button("accueil/presse_papier/couper", "Taglia", "mono:img\cut.svg")
uo_ruban.of_add_button("accueil/presse_papier/copier", "Copia", "mono:img\copy.svg")

uo_ruban.of_select_tab("accueil")

// event ue_clicked di uo_ruban : (string as_keys)
choose case as_key
    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("tab"), 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_title`	string	`""`	Titolo della scheda. Posto da `of_add_tab`; scriverlo qui lo cambia, leggerlo dice cosa mostra
`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_group("tab/group").

Proprietà	Tipo	Predefinito	Ruolo
`ib_visible`	boolean	`true`	`false` nasconde il gruppo e tutti i suoi controlli
`is_title`	string	`""`	Dicitura sotto il gruppo. Posta da `of_add_group`; scriverla qui la cambia
`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_item("tab/group/control"). 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_menu_item("tab/group/control/entry").

Proprietà	Tipo	Predefinito	Ruolo
`is_image`	string	`""`	Immagine della voce di menu. Una stringa vuota la toglie
`of_is_separator ( )` → `boolean`	—	—	La voce è una linea di separazione? Sola lettura: cosa una voce è è stato deciso all'aggiunta
`of_is_header ( )` → `boolean`	—	—	La voce è un titolo non cliccabile? Sola lettura, stessa ragione
`of_is_checkable ( )` → `boolean`	—	—	La voce porta un segno di spunta? Sola lettura; `ib_checked` dice se è messo
`ib_enabled`	boolean	`true`	`false` disattiva la voce
`ib_visible`	boolean	`true`	`false` toglie la voce dal menu alla sua prossima apertura — cascata compresa — senza rimuoverla
`ib_checked`	boolean	`false`	Segno di spunta di una voce creata con `of_add_menu_check`

I dodici tipi di controlli #

Si aggiungono tutti all'indirizzo di un gruppo — "home/clipboard" — e restituiscono 0 (-5 per un argomento non valido, -2 se il componente non è creato); un menu o un elenco si riempie poi all'indirizzo del controllo.

Metodo del gruppo	Controllo ottenuto	Event
`of_add_big_button (string as_keys, string as_label, string as_image)` → `long`	Pulsante grande a tutta altezza, icona sopra l'etichetta. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato	`ue_clicked`
`of_add_big_split (string as_keys, string as_label, string as_image)` → `long`	Pulsante grande diviso: la parte superiore agisce, la freccia apre il menu. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato	`ue_clicked` · `ue_menu_selected`
`of_add_big_dropdown (string as_keys, string as_label, string as_image)` → `long`	Pulsante grande con menu a discesa. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato	`ue_menu_selected`
`of_add_button (string as_keys, string as_label, string as_image)` → `long`	Pulsante piccolo (impilato in colonne da tre). Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato	`ue_clicked`
`of_add_toggle (string as_keys, string as_label, string as_image)` → `long`	Piccolo interruttore che rimane premuto. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato	`ue_toggled`
`of_add_dropdown (string as_keys, string as_label, string as_image)` → `long`	Pulsante piccolo con menu a discesa. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato	`ue_menu_selected`
`of_add_checkbox (string as_keys, string as_label)` → `long`	Casella di controllo. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato	`ue_toggled`
`of_add_separator (string as_keys)` → `long`	Separatore verticale tra due blocchi di controlli. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato	—
`of_add_combo (string as_keys, integer ai_width_px, boolean ab_editable)` → `long`	Casella combinata, modificabile o meno. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato	`ue_combo_changed`
`of_add_spinner (string as_keys, integer ai_width_px, double ad_min, double ad_max, double ad_step, double ad_value)` → `long`	Selettore numerico con frecce. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato	`ue_value_changed`
`of_add_colorpicker (string as_keys, string as_label, string as_image, long al_color)` → `long`	Pulsante di colore diviso: il clic riapplica, la freccia apre la tavolozza di campioni. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato	`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_key, string as_title)`	Aggiunge una scheda e restituisce `0` (`-5` per un argomento non valido, `-2` se il componente non è creato): i gruppi si aggiungono poi al suo indirizzo
`of_insert_tab (string as_key, string as_title, integer ai_index)`	Aggiunge una scheda nella posizione che sceglie lei (`1` = in testa) invece che in fondo, e restituisce `0` (`-5` per un argomento non valido, `-2` se il componente non è creato) come `of_add_tab`. Un id già assegnato viene rifiutato
`of_tab (string as_key)`	Handle di una scheda esistente (creata al primo accesso)
`of_add_group (string as_keys, string as_title)`	Aggiunge un gruppo intitolato a una scheda — `"home/clipboard"` — e restituisce `0` (`-5` per un argomento non valido, `-2` se il componente non è creato)
`of_group (string as_keys)`	Handle di un gruppo esistente, tramite il suo indirizzo
`of_item (string as_keys)`	Handle di un controllo esistente, tramite il suo indirizzo — `"home/clipboard/paste"`
`of_select_tab (string as_key)`	Attiva una scheda — rigorosamente equivalente a un clic dell'utente (attiva `ue_selection_changed`). Restituisce `0` una volta applicato, `-2` se il componente non è creato
`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_keys)`	Rimuove un gruppo e tutti i suoi controlli, tramite il suo indirizzo. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_remove_item (string as_keys)`	Rimuove un controllo, tramite il suo indirizzo. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_remove_tab (string as_key)`	Rimuove una scheda e tutto il suo contenuto. Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_clear ( )`	Svuota completamente la barra multifunzione: schede, gruppi, controlli, barra di accesso rapido, menu applicativo. Restituisce `0` una volta applicato, `-2` se il componente non è creato

Tutti questi metodi si richiamano sul componente, con l'indirizzo del controllo (scheda/gruppo/controllo) — la voce, la scelta o il riquadro come quarto livello.

Metodo	Ruolo
`of_add_menu_item (string as_keys, string as_label, string as_image)`	Voce radice del menu di un pulsante a discesa o diviso. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_add_menu_check (string as_keys, string as_label)` · `(id, label, image)`	Voce selezionabile: il clic ne inverte lo stato e lo riporta in `ue_menu_selected`. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_add_menu_header (string as_keys, string as_label)`	Riga di titolo non cliccabile, per suddividere un menu lungo. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_add_menu_separator (string as_keys)`	Riga di separazione nel menu. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_menu_item (string as_keys)`	Handle di una voce di menu, per disattivarla o selezionarla a caldo
`of_add_combo_item (string as_keys, string as_label)`	Aggiunge una scelta all'elenco di una casella combinata. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_add_gallery_item (string as_keys, string as_image, string as_label)`	Aggiunge un riquadro a una raccolta. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_select_gallery_item (string as_keys)`	Seleziona un riquadro di una raccolta da programma, tramite il suo indirizzo a quattro livelli (senza attivare alcun event). Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_open (string as_keys)`	Apre da programma il menu, l'elenco o la tavolozza di campioni del controllo a quell'indirizzo; un pulsante della barra di accesso rapido si indirizza con la sola chiave. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato

Metodo	Ruolo
`of_add_app_menu_item (string as_keys, string as_label, string as_image)`	Voce radice del menu applicativo (quello che apre il pulsante `is_app_button`). Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_add_app_menu_separator (string as_keys)`	Riga di separazione nel menu applicativo. Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_add_qat (string as_key, string as_image, string as_tooltip)`	Pulsante della barra di accesso rapido, sopra le schede, e restituisce `0` (`-5` per un argomento non valido, `-2` se il componente non è creato)
`of_qat_item (string as_key)`	Handle di un pulsante di accesso rapido, per disattivarlo o nasconderlo a caldo

Schede contestuali #

Metodo	Ruolo
`of_add_contextual_tab (string as_key, 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. Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_add_contextual_group (string as_key, string as_title)` · `(id, title, al_color)`	Gruppo di schede contestuali: un banner intitolato e colorato sovrasta le sue schede. Restituisce `0` (`-5` per un argomento non valido, `-2` se il componente non è creato)
`of_ctx_group (string as_key)`	Recupera l'handle di un gruppo contestuale già creato, tramite la sua chiave — è su di esso che si impostano le sue proprietà
`of_add_contextual_tab (string as_key, string as_title, string as_group_key)`	Aggiunge una scheda sotto un gruppo contestuale: creata nascosta, coronata dalla fascia colorata del gruppo. È l'unico modo — l'handle di gruppo non aggiunge più nulla. Restituisce `0` una volta applicato, `-2` se il componente non è creato
`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. Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_set_redraw (boolean)`	Raggruppa una raffica di modifiche in un unico rendering. Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_preload_icons (string as_icons[])`	Preriscalda un lotto di icone all'avvio: una scheda aperta più tardi mostra le proprie istantaneamente. Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_save_as_png (string)` · `of_save_as_jpg (string)`	Esporta il rendering come immagine. Restituisce `0` una volta scritta l'immagine, `-4` se la scrittura fallisce, `-2` se il componente non è creato

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_keys)`	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_keys, boolean ab_checked)`	Un interruttore o una casella di controllo cambia stato; `ab_checked` porta il nuovo stato
`ue_menu_selected (string as_keys, boolean ab_checked)`	Viene scelta una voce di un menu a discesa. `as_keys` porta quattro livelli : scheda, gruppo, controllo contenitore, poi la voce scelta, `ab_checked` = lo stato di una voce selezionabile
`ue_combo_changed (string as_keys, string as_text)`	Una casella combinata cambia valore, per selezione o per digitazione
`ue_value_changed (string as_keys, double ad_value)`	Un selettore numerico cambia valore
`ue_color_changed (string as_keys, long al_color)`	Viene scelto un colore in un selettore di colore
`ue_gallery_selection_changed (string as_from_keys, string as_keys)`	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_keys` è la piastrella lasciata
`ue_gallery_selection_changing (string as_from_keys, string as_keys)` → boolean	Annullabile, posto prima che la piastrella venga scelta. Sollevato per impostazione predefinita; `ib_veto_gallery = false` lo elimina. `as_from_keys` è la piastrella corrente. Restituisca `false` per conservarla (uno stile che il documento non può ancora assumere)
`ue_launcher (string as_keys)`	Si fa clic sulla freccia di avvio di un gruppo — apra la Sua finestra delle opzioni
`ue_selection_changed (string as_keys)`	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_keys)`	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 #

// event open : si raggruppa tutta la costruzione in un unico rendering

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(/*key*/ "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", /*key*/ "sous_pdf", "Documento PDF", "")
uo_ruban.of_add_app_menu_item(/*parent*/ "enr_sous", /*key*/ "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(/*key*/ "qat_enr", /*immagine*/ "mono:img\save.svg", /*tooltip*/ "Salva")
uo_ruban.of_add_qat("qat_annuler", "mono:img\undo.svg", "Annulla")

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

uo_ruban.of_add_group("accueil/presse_papier", "Appunti")
uo_ruban.of_add_big_split("accueil/presse_papier/coller", "Incolla", "mono:img\paste.svg")
uo_ruban.of_add_menu_item("accueil/presse_papier/coller/coller_texte", "Incolla senza formattazione", "")
uo_ruban.of_add_menu_item("accueil/presse_papier/coller/coller_lien", "Incolla come collegamento", "")
uo_ruban.of_add_button("accueil/presse_papier/couper", "Taglia", "mono:img\cut.svg")
uo_ruban.of_add_button("accueil/presse_papier/copier", "Copia", "mono:img\copy.svg")
uo_ruban.of_group("accueil/presse_papier").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_keys)
// Il percorso completo arriva con l'event : basta un solo smistamento,
// e due gruppi possono riutilizzare lo stesso identificatore senza disturbarsi.
choose case as_keys
    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_item("accueil/presse_papier/coller").ib_enabled = of_presse_papier_non_vide()
uo_ruban.of_item("accueil/outils/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_item("accueil/presse_papier/coller") &
        .of_menu_item("coller_lien").ib_enabled = false

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

// Senza colore, il banner segue il colore d'accento del tema ; RGB(...) per imporlo
uo_ruban.of_add_contextual_group(/*key*/ "img", /*titolo*/ "Strumenti immagine", &
                                           /*colore*/ RGB(224, 32, 96))
uo_ruban.of_add_contextual_tab("format", "Formato", "img")
uo_ruban.of_add_group("format/ajuster", "Regola")
uo_ruban.of_add_big_button("format/ajuster/rogner", "Ritaglia", "mono:img\crop.svg")
uo_ruban.of_add_button("format/ajuster/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 #


uo_ruban.of_add_group("accueil/police", "Carattere")

// Casella combinata modificabile : la si riempie tramite il suo handle
uo_ruban.of_add_combo("accueil/police/nom_police", /*larghezza_px*/ 140, /*modificabile*/ true)
uo_ruban.of_add_combo_item("accueil/police/nom_police", "Segoe UI")
uo_ruban.of_add_combo_item("accueil/police/nom_police", "Arial")
uo_ruban.of_add_combo_item("accueil/police/nom_police", "Calibri")
uo_ruban.of_item("accueil/police/nom_police").is_text = "Segoe UI"

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

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

// Raccolta di stili : riquadri illustrati scorrevoli
uo_ruban.of_add_gallery("accueil/police/styles", /*larghezza_px*/ 220, &
                                     /*larghezza_riquadro*/ 64, /*altezza_riquadro*/ 48)
uo_ruban.of_add_gallery_item("accueil/police/styles/st_normal", "img\style-normal.png", "Normale")
uo_ruban.of_add_gallery_item("accueil/police/styles/st_titre",  "img\style-titre.png",  "Titolo")
uo_ruban.of_add_gallery_item("accueil/police/styles/st_note",   "img\style-note.png",   "Nota")
uo_ruban.of_add_gallery_item("accueil/police/styles/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.
uo_ruban.of_item("accueil/police/styles").ii_visible_items = 4

uo_ruban.of_select_gallery_item("accueil/police/styles/st_normal")

// event ue_value_changed di uo_ruban : (string as_keys, double ad_value)
n_pbt_utils lnv_utils   // autoinstantiate : niente da creare, niente da distruggere
if lnv_utils.of_leaf(as_keys) = "taille" then of_appliquer_taille(ad_value)

// event ue_color_changed di uo_ruban : (string as_keys, long al_color)
n_pbt_utils lnv_utils   // autoinstantiate : niente da creare, niente da distruggere
if lnv_utils.of_leaf(as_keys) = "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_from_keys, string as_keys)
// Restituire FALSE conserva il riquadro corrente (as_from_keys).
n_pbt_utils lnv_utils   // autoinstantiate : niente da creare, niente da distruggere
if lnv_utils.of_leaf(as_keys) = "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_group("accueil/police").ib_launcher = true

// event ue_launcher di uo_ruban : (string as_keys)
// Il percorso identifica il gruppo : si apre la finestra delle opzioni corrispondente.
n_pbt_utils lnv_utils   // autoinstantiate : niente da creare, niente da distruggere
choose case lnv_utils.of_leaf(as_keys)
    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_item("accueil/presse_papier/copier").is_keytip = "C"
uo_ruban.of_item("accueil/presse_papier/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


lnv_item = uo_ruban.of_item("accueil/presse_papier/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")

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.

Ereditato dalla base comune #

Questi membri esistono su tutti i componenti visivi — non sono propri di questo. Sono descritti una sola volta, nei capitoli trasversali; questa tabella dice solo dove leggerli.

Membri	Ruolo	Descritto in
`of_count` · `of_keys_at` · `of_has`	Percorrere ciò che il componente contiene	3.2 Gli item
`of_reset`	Riportare il componente a zero	3.6 Riportare un componente a zero: `of_reset()`
`of_register_shortcut` · `of_clear_shortcuts`	Scorciatoie da tastiera del componente	3.5 Le scorciatoie da tastiera
`of_is_created` · `of_is_ready` · `of_get_last_error`	Se è nato, se è pronto, cosa è fallito	3.7 Diagnostica
`of_save_as_png` · `of_save_as_jpg`	Esportare il rendering in immagine	3.8 Esportare il rendering come immagine
`of_set_redraw`	Raggruppare le modifiche in un solo ridisegno	3.10 Buone pratiche
`of_preload_icons`	Icone mostrate senza ritardo	Visualizzazione istantanea: `of_icon`
`of_set_translation`	Tradurre una dicitura del componente	5.2 Adattare un'etichetta: `of_set_translation`
`of_focus_webview`	Dare il focus al componente	6.4 Tastiera e focus
`of_print` · `of_print_to_pdf`	Stampare, o scrivere un PDF	6.9 Stampare
`of_set_property` · `of_get_property` · `of_component_name`	Pilotare una proprietà per nome	3.1 Il motore delle proprietà

Due aiuti non sono ereditati: of_icon e of_escape_markup vivono su n_pbt_utils. Ne dichiari uno — n_pbt_utils lnv_utils, niente da creare — e li chiami su di esso.

← Riferimento dei componenti · Sommario della guida

ribbon — `u_pbt_ribbon` #

In breve #

La regola d'oro: tutto passa dal percorso #

Avvio rapido #

Proprietà #

Proprietà di una scheda — `n_pbt_ribbon_tab` #

Proprietà di un gruppo — `n_pbt_ribbon_group` #

Proprietà di un controllo — `n_pbt_ribbon_item` #

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

I dodici tipi di controlli #

Metodi #

Costruire la barra multifunzione #

Riempire i menu e gli elenchi #

Menu applicativo e barra di accesso rapido #

Schede contestuali #

Comuni #

Event #

Esempi #

Una barra multifunzione completa, dal menu applicativo ai gruppi #

Un unico smistamento dei clic #

Pilotare lo stato dei controlli in base ai diritti #

Schede contestuali con banner #

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

Rifiutare la scelta di un riquadro di raccolta #

L'avvio della finestra di dialogo #

Keytip: guidare la barra multifunzione da tastiera #

Tooltip avanzati su un controllo #

Altezza automatica #

Ridurre la barra multifunzione per guadagnare spazio #

Ripartire da una barra multifunzione vuota #

Da un menu PowerBuilder esistente #

Buone pratiche #

Ereditato dalla base comune #

ribbon — u_pbt_ribbon #

In breve #

La regola d'oro: tutto passa dal percorso #

Avvio rapido #

Proprietà #

Proprietà di una scheda — n_pbt_ribbon_tab #

Proprietà di un gruppo — n_pbt_ribbon_group #

Proprietà di un controllo — n_pbt_ribbon_item #

Proprietà di una voce di menu — n_pbt_ribbon_menu_item #

I dodici tipi di controlli #

Metodi #

Costruire la barra multifunzione #

Riempire i menu e gli elenchi #

Menu applicativo e barra di accesso rapido #

Schede contestuali #

Comuni #

Event #

Esempi #

Una barra multifunzione completa, dal menu applicativo ai gruppi #

Un unico smistamento dei clic #

Pilotare lo stato dei controlli in base ai diritti #

Schede contestuali con banner #

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

Rifiutare la scelta di un riquadro di raccolta #

L'avvio della finestra di dialogo #

Keytip: guidare la barra multifunzione da tastiera #

Tooltip avanzati su un controllo #

Altezza automatica #

Ridurre la barra multifunzione per guadagnare spazio #

Ripartire da una barra multifunzione vuota #

Da un menu PowerBuilder esistente #

Buone pratiche #

Ereditato dalla base comune #

ribbon — `u_pbt_ribbon` #

Proprietà di una scheda — `n_pbt_ribbon_tab` #

Proprietà di un gruppo — `n_pbt_ribbon_group` #

Proprietà di un controllo — `n_pbt_ribbon_item` #

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