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

// MAIN_BAR e la barra predefinita, sempre presente : l indirizzo parte da essa


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

// event ue_clicked di uo_toolbar : (string as_keys)
choose case as_keys
    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_key)` → `n_pbt_toolbar_bar`	Restituisce l'handle di una barra (creata al primo accesso)
`of_add_button (string as_keys, string as_text, string as_image, string as_tooltip)` → `long`	Pulsante d'azione al suo indirizzo, `"main/save"`: la barra, poi il proprio identificatore. Il clic solleva `ue_clicked`. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_item (string as_keys)` → `n_pbt_toolbar_item`	Restituisce l'handle di uno strumento, tramite il suo indirizzo
`of_add_bar (string as_key)` → `long`	Aggiunge una barra e restituisce `0` (`-5` per un argomento non valido, `-2` se il componente non è creato)
`of_add_bar (string as_key, integer ai_band, integer ai_index)` → `long`	Aggiunge una barra su una banda e in una posizione precise (entrambe contate a partire da 0). Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_remove_bar (string as_key)`	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. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`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`. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_clear ( )`	Elimina tutte le barre e tutti gli strumenti. Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_reset ( )`	Svuota il contenuto e riporta le proprietà ai valori predefiniti. Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_add_toggle (string as_keys, string as_text, string as_image, string as_tooltip)` → `long`	Interruttore a due stati; il clic attiva `ue_toggled`. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_add_dropdown (string as_keys, string as_text, string as_image, string as_tooltip)` → `long`	Pulsante con menu a discesa; una scelta attiva `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_label (string as_keys, string as_text)` → `long`	Etichetta informativa, non cliccabile. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_add_textbox (string as_keys, string as_text, integer ai_width, string as_tooltip)` → `long`	Campo di immissione; Invio o perdita del focus attiva `ue_text_changed`. `ai_width` in pixel. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_add_datepicker (string as_keys, string as_date, string as_tooltip)` → `long`	Selettore di data; una scelta attiva `ue_date_changed`. Date nel formato `"aaaa-mm-gg"`. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_add_separator (string as_keys)`	Tratto verticale di separazione. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_insert_button (string as_keys, string as_text, string as_image, string as_tooltip, integer ai_index)` → `long`	Pulsante aggiunto nella posizione scelta (primo = 0) invece che in fondo. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_move_item (string as_keys, 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. 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 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. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_add_menu_item (string as_keys, string as_label, string as_image)`	Voce del menu di un pulsante a discesa ; voce a cascata, collocata sotto una voce esistente. 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)`	Tratto 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

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

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

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

Event #

Event	Attivato quando
`ue_clicked (string as_keys)`	Un pulsante viene cliccato (o attivato dalla propria scorciatoia)
`ue_toggled (string as_keys, boolean ab_checked)`	Un interruttore cambia stato; `ab_checked` riporta il nuovo stato
`ue_menu_selected (string as_keys)`	Viene scelta una voce di un menu a discesa
`ue_text_changed (string as_keys, string as_text)`	Un campo di immissione viene confermato (Invio o perdita del focus)
`ue_date_changed (string as_keys, string as_date)`	Viene scelta una data (`"aaaa-mm-gg"`)
`ue_bar_reordered (string as_key, 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 #



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

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

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


// Il menu si riempie dal componente : tre livelli, barra/menu a discesa/voce
uo_toolbar.of_add_dropdown(/*keys*/ uo_toolbar.MAIN_BAR + "/export", /*text*/ "Esporta", &
                                   /*image*/ "mono:img\save.svg", /*tooltip*/ "Esporta la pratica")
uo_toolbar.of_add_menu_item(/*keys*/ uo_toolbar.MAIN_BAR + "/export/exp_pdf", /*label*/ "PDF",  /*image*/ "")
uo_toolbar.of_add_menu_item(/*keys*/ uo_toolbar.MAIN_BAR + "/export/exp_csv", /*label*/ "CSV",  /*image*/ "")
uo_toolbar.of_add_menu_separator(/*keys*/ uo_toolbar.MAIN_BAR + "/export")

// Sottomenu : un QUARTO livello, la voce sotto cui si annida
uo_toolbar.of_add_menu_item(/*keys*/ uo_toolbar.MAIN_BAR + "/export/exp_img", /*label*/ "Immagine...", /*image*/ "")
uo_toolbar.of_add_menu_item(/*keys*/ uo_toolbar.MAIN_BAR + "/export/exp_img/exp_png", /*label*/ "PNG", /*image*/ "")
uo_toolbar.of_add_menu_item(/*keys*/ uo_toolbar.MAIN_BAR + "/export/exp_img/exp_jpg", /*label*/ "JPEG", /*image*/ "")

// event ue_menu_selected di uo_toolbar : (as_keys)
n_pbt_utils lnv_utils   // autoinstantiate : niente da creare, niente da distruggere
string ls_ids[]

if lnv_utils.of_split_path(as_keys, ls_ids) = 3 then
	if ls_ids[2] = "export" then of_exporter(ls_ids[3])
end if

Campo di ricerca e selettore di data #



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

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

uo_toolbar.of_add_label(/*keys*/ uo_toolbar.MAIN_BAR + "/lbl_due", /*text*/ "Scadenza:")
uo_toolbar.of_add_datepicker(/*keys*/ uo_toolbar.MAIN_BAR + "/due", /*date*/ "2026-07-11", /*tooltip*/ "Data di scadenza")

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

// event ue_date_changed di uo_toolbar : as_date nel formato "aaaa-mm-gg"
if as_key = "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.



uo_toolbar.of_add_button(/*keys*/ uo_toolbar.MAIN_BAR + "/new",  /*text*/ "Nuovo", /*image*/ "", /*tooltip*/ "")
uo_toolbar.of_add_button(/*keys*/ uo_toolbar.MAIN_BAR + "/open", /*text*/ "Apri",  /*image*/ "", /*tooltip*/ "")

// Seconda barra, collocata sulla banda 1 (seconda riga), in prima posizione

uo_toolbar.of_add_toggle(/*keys*/ /*bar*/ "format", /*band*/ 1, /*index*/ 0 + "/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.

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

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.