toolbar — `u_pbt_toolbar` #

← Riferimento dei componenti · Sommario della guida

Barra degli strumenti piatta: più barre distribuite su bande, pulsanti, interruttori, menu a discesa, campi di immissione, overflow automatico e spostamento tramite maniglia.

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

In breve #

Userobject	`u_pbt_toolbar`
Classi degli item	`n_pbt_toolbar_bar` (barra) → `n_pbt_toolbar_item` (strumento)
Serve per	Sostituire una barra degli strumenti classica con una barra moderna, a tema, distribuita su più righe riorganizzabili
Altezza	Intrinseca: la barra si allinea sempre alle proprie righe, nulla da attivare — vedere Altezza automatica

Avvio rapido #

// event open della finestra
n_pbt_toolbar_bar lnv_bar

// of_bar() restituisce la barra predefinita, sempre presente (id = MAIN_BAR)
lnv_bar = uo_toolbar.of_bar(uo_toolbar.MAIN_BAR)

lnv_bar.of_add_button(/*id*/ "save", /*text*/ "", /*image*/ "mono:img\save.svg", /*tooltip*/ "Salva")
lnv_bar.of_add_button(/*id*/ "find", /*text*/ "", /*image*/ "mono:img\find.svg", /*tooltip*/ "Cerca")
lnv_bar.of_add_separator()
lnv_bar.of_add_button(/*id*/ "help", /*text*/ "Guida",  /*image*/ "", /*tooltip*/ "Informazioni")

// event ue_clicked di uo_toolbar : (string as_bar, string as_id)
choose case as_bar + "/" + as_id
    case "main/save" ; of_enregistrer()
    case "main/find" ; of_rechercher()
    case "main/help" ; of_aide()
end choose

Il modello: barre, bande, strumenti #

Una barra degli strumenti contiene una o più barre. Ogni barra è collocata su una banda (una riga) e occupa una posizione all'interno di quella riga: due barre sulla stessa banda si dividono la riga, due barre su bande diverse si impilano — esattamente come le barre degli strumenti classiche di Office.

Gli strumenti (pulsanti, interruttori, menu, campi) appartengono a una barra. Il loro identificatore è univoco solo all'interno della propria barra: l'accesso passa quindi sempre dal percorso completo.

uo_toolbar.of_bar("main").of_item("save").ib_enabled = false

Anche le aggiunte avvengono sull'handle del genitore: si aggiunge uno strumento a una barra, non alla barra degli strumenti. Vedere Base comune · Gli item per il principio generale.

Proprietà #

Proprietà	Tipo	Predefinito	Ruolo
`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
`ib_reorderable`	boolean	`false`	Consente all'utente di riorganizzare le barre con il mouse: le maniglie di spostamento compaiono e una barra può essere trascinata su un'altra banda. Disattivato per impostazione predefinita — una barra degli strumenti smontata per errore è una chiamata all'assistenza. Il suo codice le riorganizza comunque (`of_set_layout`, `of_add_bar`): l'autorizzazione riguarda l'utente, mai l'applicazione

Costante #

Costante	Valore	Ruolo
`MAIN_BAR`	`"main"`	Identificatore della barra predefinita, sempre disponibile senza doverla creare

Metodi #

Metodo	Ruolo
`of_bar (string as_id)` → `n_pbt_toolbar_bar`	Restituisce l'handle di una barra (creata al primo accesso)
`of_add_bar (string as_bar)` → `n_pbt_toolbar_bar`	Aggiunge una barra e ne restituisce l'handle
`of_add_bar (string as_bar, integer ai_band, integer ai_index)` → `n_pbt_toolbar_bar`	Aggiunge una barra su una banda e in una posizione precise (entrambe contate a partire da 0)
`of_remove_bar (string as_id)`	Rimuove una barra e i suoi strumenti. Le altre mantengono il loro stato attivo, e le bande si compattano dietro quella che se ne va. Non è la stessa cosa che nasconderla (`ib_visible` sul suo handle): nascondere la mantiene nel modello, pronta a tornare esattamente dov'era; rimuovere la dimentica
`of_get_layout ()`	Rilegge la disposizione corrente in JSON: quale barra su quale banda, a quale rango, e visibile o no. Da memorizzare, poi da restituire con `of_set_layout`
`of_set_layout (string as_layout_json)`	Ripristina una disposizione di barre ricevuta in precedenza tramite `ue_layout_changed`
`of_clear ( )`	Elimina tutte le barre e tutti gli strumenti
`of_reset ( )`	Svuota il contenuto e riporta le proprietà ai valori predefiniti

Su una barra — `n_pbt_toolbar_bar` #

Membro	Tipo	Predefinito	Ruolo
`ii_band`	integer	`0`	Banda (riga) che ospita la barra; `0` = prima riga
`ii_index`	integer	`0`	Posizione della barra all'interno della propria banda
`ib_visible`	boolean	`true`	Mostra o nasconde una barra. Una barra nascosta conserva la sua banda, il suo rango e le sue voci: rimostrarla la rimette esattamente dov'era, senza ricostruire nulla — è la differenza con `of_clear`, che le perderebbe
`of_item (string as_id)` → `n_pbt_toolbar_item`			Restituisce l'handle di uno strumento di questa barra
`of_add_button (as_id, as_text, as_image, as_tooltip)` → `n_pbt_toolbar_item`			Pulsante di azione; il clic attiva `ue_clicked`
`of_add_toggle (as_id, as_text, as_image, as_tooltip)` → `n_pbt_toolbar_item`			Interruttore a due stati; il clic attiva `ue_toggled`
`of_add_dropdown (as_id, as_text, as_image, as_tooltip)` → `n_pbt_toolbar_item`			Pulsante con menu a discesa; una scelta attiva `ue_menu_selected`
`of_add_label (as_id, as_text)` → `n_pbt_toolbar_item`			Etichetta informativa, non cliccabile
`of_add_textbox (as_id, as_text, ai_width, as_tooltip)` → `n_pbt_toolbar_item`			Campo di immissione; Invio o perdita del focus attiva `ue_text_changed`. `ai_width` in pixel
`of_add_datepicker (as_id, as_date, as_tooltip)` → `n_pbt_toolbar_item`			Selettore di data; una scelta attiva `ue_date_changed`. Date nel formato `"aaaa-mm-gg"`
`of_add_separator ( )`			Tratto verticale di separazione
`of_insert_button (as_id, as_text, as_image, as_tooltip, ai_index)` → `n_pbt_toolbar_item`			Pulsante aggiunto nella posizione scelta (primo = 0) invece che in fondo
`of_move_item (string as_id, integer ai_index)`			Sposta uno strumento in un'altra posizione in questa barra (primo = 0). Conserva il suo tipo, il suo menu e il suo stato vivo: lo strumento cambia posto, non viene ricostruito. Vale per ogni tipo, quindi gli `of_add_` senza `of_insert_` inseriscono aggiungendo e poi spostando
`of_remove_item (string as_id)`			Rimuove uno strumento da questa barra. La barra resta, e con lei tutto il resto, stato attivo compreso — se ne va solo lo strumento indicato. Per farlo andare e venire, `ib_visible` sul suo handle lo mantiene nel modello

Su uno strumento — `n_pbt_toolbar_item` #

Membro	Tipo	Predefinito	Ruolo
`ib_visible`	boolean	`true`	Mostra o nasconde una voce. Conserva il suo rango nella barra: rimostrarla la rimette esattamente dov'era, non in fondo. Da non confondere con `ib_enabled`, che la lascia al suo posto, in grigio — nascondete cio che non si applica, ingrigite cio che è momentaneamente non disponibile
`ib_enabled`	boolean	`true`	Strumento attivo o disattivato
`ib_checked`	boolean	`false`	Stato di un interruttore (senza effetto sugli altri tipi)
`is_text`	string	`""`	Etichetta, testo formattato con tag accettato
`is_shortcut`	string	`""`	Scorciatoia da tastiera (`"Ctrl+S"`), mostrata nel tooltip e attiva
`of_add_menu_item (as_id, as_label, as_image)`			Voce del menu di un pulsante a discesa
`of_add_menu_item (as_parent, as_id, as_label, as_image)`			Voce a cascata, collocata sotto una voce esistente
`of_add_menu_separator (as_id)`			Tratto di separazione nel menu

Le immagini accettano tutte le forme riconosciute dalla libreria: percorso, mono:, tint:, risorsa di una DLL.

Event #

Event	Attivato quando
`ue_clicked (string as_bar, string as_id)`	Un pulsante viene cliccato (o attivato dalla propria scorciatoia)
`ue_toggled (string as_bar, string as_id, boolean ab_checked)`	Un interruttore cambia stato; `ab_checked` riporta il nuovo stato
`ue_menu_selected (string as_bar, string as_dropdown, string as_id)`	Viene scelta una voce di un menu a discesa
`ue_text_changed (string as_bar, string as_id, string as_text)`	Un campo di immissione viene confermato (Invio o perdita del focus)
`ue_date_changed (string as_bar, string as_id, string as_date)`	Viene scelta una data (`"aaaa-mm-gg"`)
`ue_bar_reordered (string as_id, integer ai_band, integer ai_index)`	L'utente ha trascinato una barra dalla maniglia su un'altra banda o un altro rango (richiede `ib_reorderable`). Dice quale barra si è spostata e dove è arrivata, mentre `ue_layout_changed` porta l'intera disposizione. Banda e rango partono da 1
`ue_layout_changed (string as_layout_json)`	La disposizione è cambiata — l'utente ha trascinato una barra dalla maniglia, o il vostro codice ne ha spostata o nascosta una. Porta la disposizione intera, non solo ciò che si è mosso
`ue_auto_height (long al_height)`	L'altezza ideale è cambiata e la barra vi si è adattata — sempre attivo: è il numero di righe a dettare l'altezza
`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 #

Interruttori già selezionati e strumento disattivato #

n_pbt_toolbar_bar lnv_bar
lnv_bar = uo_toolbar.of_bar(uo_toolbar.MAIN_BAR)

lnv_bar.of_add_toggle(/*id*/ "bold",   /*text*/ "", /*image*/ "mono:img\bold.svg",   /*tooltip*/ "Grassetto")
lnv_bar.of_add_toggle(/*id*/ "italic", /*text*/ "", /*image*/ "mono:img\italic.svg", /*tooltip*/ "Corsivo")
lnv_bar.of_add_separator()
lnv_bar.of_add_button(/*id*/ "undo",   /*text*/ "", /*image*/ "mono:img\undo.svg",   /*tooltip*/ "Annulla")

// Ogni strumento si pilota tramite il proprio handle, ottenuto dalla SUA barra
lnv_bar.of_item("bold").ib_checked = true    // interruttore gia selezionato
lnv_bar.of_item("undo").ib_enabled = false   // per ora non c'e nulla da annullare

// event ue_toggled di uo_toolbar
if as_id = "bold" then of_appliquer_gras(ab_checked)

n_pbt_toolbar_bar  lnv_bar
n_pbt_toolbar_item lnv_menu

lnv_bar = uo_toolbar.of_bar(uo_toolbar.MAIN_BAR)

// Il menu si riempie tramite l'handle restituito da of_add_dropdown
lnv_menu = lnv_bar.of_add_dropdown(/*id*/ "export", /*text*/ "Esporta", &
                                   /*image*/ "mono:img\save.svg", /*tooltip*/ "Esporta la pratica")
lnv_menu.of_add_menu_item(/*id*/ "exp_pdf", /*label*/ "PDF",  /*image*/ "")
lnv_menu.of_add_menu_item(/*id*/ "exp_csv", /*label*/ "CSV",  /*image*/ "")
lnv_menu.of_add_menu_separator(/*id*/ "sep1")

// Sottomenu : si indica la voce padre come primo argomento
lnv_menu.of_add_menu_item(/*id*/ "exp_img", /*label*/ "Immagine...", /*image*/ "")
lnv_menu.of_add_menu_item(/*parent*/ "exp_img", /*id*/ "exp_png", /*label*/ "PNG", /*image*/ "")
lnv_menu.of_add_menu_item(/*parent*/ "exp_img", /*id*/ "exp_jpg", /*label*/ "JPEG", /*image*/ "")

// event ue_menu_selected di uo_toolbar : (as_bar, as_dropdown, as_id)
if as_dropdown = "export" then of_exporter(as_id)

Campo di ricerca e selettore di data #

n_pbt_toolbar_bar lnv_bar
lnv_bar = uo_toolbar.of_bar(uo_toolbar.MAIN_BAR)

lnv_bar.of_add_button(/*id*/ "save", /*text*/ "", /*image*/ "mono:img\save.svg", /*tooltip*/ "Salva")
lnv_bar.of_item("save").is_shortcut = "Ctrl+S"    // scorciatoia attiva e visualizzata
lnv_bar.of_add_separator()

// 160 px di larghezza ; il testo viene riportato alla conferma
lnv_bar.of_add_textbox(/*id*/ "search", /*text*/ "", /*width*/ 160, /*tooltip*/ "Cerca (Invio per confermare)")

lnv_bar.of_add_label(/*id*/ "lbl_due", /*text*/ "Scadenza:")
lnv_bar.of_add_datepicker(/*id*/ "due", /*date*/ "2026-07-11", /*tooltip*/ "Data di scadenza")

// event ue_text_changed di uo_toolbar
if as_id = "search" then of_filtrer(as_text)

// event ue_date_changed di uo_toolbar : as_date nel formato "aaaa-mm-gg"
if as_id = "due" then id_echeance = Date(as_date)

Due barre e disposizione memorizzata #

L'utente può afferrare una barra dalla sua maniglia (a sinistra della barra) e spostarla su un'altra banda o in un'altra posizione. Conservi la disposizione alla chiusura e la ripristini all'apertura.

n_pbt_toolbar_bar lnv_std, lnv_fmt

lnv_std = uo_toolbar.of_bar(uo_toolbar.MAIN_BAR)
lnv_std.of_add_button(/*id*/ "new",  /*text*/ "Nuovo", /*image*/ "", /*tooltip*/ "")
lnv_std.of_add_button(/*id*/ "open", /*text*/ "Apri",  /*image*/ "", /*tooltip*/ "")

// Seconda barra, collocata sulla banda 1 (seconda riga), in prima posizione
lnv_fmt = uo_toolbar.of_add_bar(/*bar*/ "format", /*band*/ 1, /*index*/ 0)
lnv_fmt.of_add_toggle(/*id*/ "bold", /*text*/ "G", /*image*/ "", /*tooltip*/ "Grassetto")

// Una barra si puo anche ricollocare in qualsiasi momento tramite le sue proprieta
uo_toolbar.of_bar("format").ii_band  = 0
uo_toolbar.of_bar("format").ii_index = 1    // seconda barra della prima riga

// event ue_layout_changed di uo_toolbar : conservare la disposizione scelta
is_disposition = as_layout_json

// Alla successiva apertura : ripristinare cio che l'utente aveva sistemato
if is_disposition <> "" then uo_toolbar.of_set_layout(is_disposition)

Overflow: «Altri strumenti» #

Quando la larghezza non basta più, gli strumenti che non entrano vengono raccolti in un menu Altri strumenti segnalato da un chevron alla fine della barra. È automatico, non c'è nulla da programmare: gli strumenti raccolti restano cliccabili e attivano gli stessi event. Un campo raccolto — casella di testo o selettore di data — resta un campo vero: ci si scrive, ci si sceglie una data, e l'event parte esattamente come se lo strumento fosse rimasto nella barra.

Altezza automatica #

Nulla da attivare: è il numero di righe (of_set_layout) a dettare l'altezza, la barra vi si adatta da sola e La avvisa.

// event ue_auto_height di uo_toolbar
uo_contenu.y      = uo_toolbar.y + al_height
uo_contenu.height = parent.workspaceheight() - uo_contenu.y

Vedere Base comune.

Buone pratiche #

Si serva di MAIN_BAR finché una sola barra è sufficiente: esiste già, non serve aggiungerla.
Raggiunga sempre uno strumento tramite il suo percorso — of_bar(...).of_item(...) — e non tramite il solo identificatore: è ciò che rende gli identificatori riutilizzabili da una barra all'altra.
Raggruppi gli strumenti affini con of_add_separator() piuttosto che con barre aggiuntive.
Sui pulsanti con la sola icona, compili sempre il tooltip: è l'unica etichetta di cui dispone l'utente.
Se lascia che l'utente riorganizzi le barre, memorizzi ue_layout_changed e riproponga of_set_layout all'apertura, altrimenti il lavoro va perso a ogni avvio.
Chiami of_reset() prima di ricostruire interamente la barra degli strumenti per un altro contesto.
Quando i comandi diventano troppo numerosi per una barra, passi alla barra multifunzione, organizzata per schede e gruppi.