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) → `n_pbt_toolbar_menu_item` (voce di menu)
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_save()
    case "main/find" ; of_find()
    case "main/help" ; of_help()
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.

// Gray out a tool, or one entry of its menu
uo_toolbar.of_item(/*keys*/ "main/save").ib_enabled = false
uo_toolbar.of_menu_item(/*keys*/ "main/export/pdf").ib_enabled = false

Tutto si fa dal componente, per indirizzi: uno strumento si aggiunge al proprio (of_add_button("main/save", …)), una voce di menu al proprio ("main/export/pdf", un livello in più per cascata), e ogni livello ha il suo getter — of_bar, of_item, of_menu_item. Vedere Base comune · Gli item per il principio generale.

Elenchi a discesa #

Un elenco a discesa (of_add_combo) è un campo e la sua freccia, come la combo della barra multifunzione. Non modificabile, l'utente sceglie nell'elenco (un clic sul campo, Invio, F4 o Alt+Giù lo aprono); modificabile, può anche digitare un valore proprio. Ogni scelta ritorna in ue_combo_changed; ripiegato nel chevron di una barra troppo stretta, l'elenco resta funzionante.

// A font the user only chooses, a size he may also type
uo_toolbar.of_add_combo(/*keys*/ "main/font", /*width*/ 130, /*editable*/ false, /*tooltip*/ "Font")
uo_toolbar.of_add_combo_item(/*keys*/ "main/font", /*label*/ "Segoe UI")
uo_toolbar.of_add_combo_item(/*keys*/ "main/font", /*label*/ "Arial")
uo_toolbar.of_item(/*keys*/ "main/font").is_text = "Segoe UI"
uo_toolbar.of_add_combo(/*keys*/ "main/size", /*width*/ 60, /*editable*/ true, /*tooltip*/ "Size")
uo_toolbar.of_add_combo_item(/*keys*/ "main/size", /*label*/ "10")
uo_toolbar.of_add_combo_item(/*keys*/ "main/size", /*label*/ "12")

// ue_combo_changed (string as_keys, string as_text) of uo_toolbar
st_status.Text = as_keys + " = " + as_text

Proprietà #

Proprietà	Tipo	Predefinito	Ruolo
`is_theme_style`	string	`""`	Stile visivo del componente (costanti `THEME_STYLE_*`); vuoto = quello dell'applicazione, seguito a ogni cambio
`is_theme_mode`	string	`""`	Variante chiara o scura (costanti `THEME_MODE_*`); vuoto = quella dell'applicazione, seguita a ogni cambio
`il_theme_accent`	long	`-1`	Colore d'accento di questo componente (`-1` = accento dell'applicazione, o quello 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, che si indirizza senza averla creata: nasce con il suo primo strumento. Per posizionarla, aggiungetela per prima — `of_add_bar(MAIN_BAR, 1, 1)`

Metodi #

Metodo	Ruolo
`of_bar (string as_key)` → `n_pbt_toolbar_bar`	Restituisce l'handle di una barra (creata al primo accesso): `ii_band`, `ii_index`, `ib_visible`
`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 suo identificatore. Il clic scatena `ue_clicked`. Restituisce `0` una volta aggiunto, `-5` se l'indirizzo è rifiutato (non `barra/strumento`, una barra mai aggiunta — tranne `main` —, un indirizzo già occupato), `-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 `barra/strumento`. Un indirizzo di un'altra profondità non designa alcuno strumento: una barra è `of_bar`, una voce di menu `of_menu_item`
`of_menu_item (string as_keys)` → `n_pbt_toolbar_menu_item`	Restituisce l'handle di una voce di un menu a discesa, tramite il suo indirizzo `barra/menu/voce` — un livello in più per cascata. Due cascate possono avere ciascuna il proprio `pdf`: l'indirizzo ne designa uno, mai entrambi
`of_add_bar (string as_key)` → `long`	Aggiunge una barra, su una banda propria dopo le altre. Restituisce `0` una volta aggiunta, `-5` se la chiave è rifiutata (vuota, con `/` o `	`, che inizia con` __ `o già occupata),` -2 `se il componente non è creato. La barra predefinita` main `nasce con il suo primo strumento: per posizionarla, aggiungetela prima di qualsiasi strumento (`of_add_bar(MAIN_BAR, 1, 1)`); dopo è occupata (`-5`) e si sposta tramite` of_bar(MAIN_BAR)`
`of_add_bar (string as_key, integer ai_band, integer ai_index)` → `long`	Aggiunge una barra a una banda e a una posizione precise (entrambe contate da 1); la barra che occupava quel rango si sposta di un passo a destra. Stessi codici di sopra
`of_remove_bar (string as_key)` → `long`	Rimuove una barra e i suoi strumenti, con i loro handle e le loro scorciatoie. Le altre mantengono il loro stato vivo, e le bande si ricompattano dietro quella che se ne va. Non è nasconderla (`ib_visible` sul suo handle): nasconderla la mantiene nel modello, pronta a tornare esattamente dov'era; rimuoverla la dimentica. Restituisce `0` una volta rimossa, `-5` per una barra che non esiste, `-2` se il componente non è creato
`of_get_layout ()` → `string`	Rilegge la disposizione corrente in JSON: quale barra su quale banda, a quale rango, e visibile o no. Bande e ranghi contati da 1, come `ii_band` / `ii_index`: da memorizzare così com'è e da restituire a `of_set_layout` — un andata e ritorno rende la stessa stringa
`of_set_layout (string as_layout_json)` → `long`	Ripristina una disposizione letta con `of_get_layout` o ricevuta tramite `ue_layout_changed`, restituita così com'era. Una barra che non nomina resta dov'è. Viene sollevato `ue_layout_changed`, come per ogni cambiamento della disposizione. Restituisce `0` una volta applicato, `-5` su una stringa vuota, `-2` se il componente non è creato. Anche un testo che non è JSON restituisce `-5`
`of_clear ( )` → `long`	Elimina tutte le barre, tutti gli strumenti e tutti i menu, con gli handle distribuiti e le scorciatoie degli strumenti e delle voci; ogni indirizzo può essere aggiunto di nuovo. 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 scatena `ue_toggled`. Restituisce `0` una volta aggiunto, `-5` se l'indirizzo è rifiutato (non `barra/strumento`, una barra mai aggiunta — tranne `main` —, un indirizzo già occupato), `-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, riempito con `of_add_menu_item`; una scelta scatena `ue_menu_selected`. Restituisce `0` una volta aggiunto, `-5` se l'indirizzo è rifiutato (non `barra/strumento`, una barra mai aggiunta — tranne `main` —, un indirizzo già occupato), `-2` se il componente non è creato. Un menu a discesa senza alcuna voce visibile viene disegnato in grigio
`of_add_split_button (string as_keys, string as_text, string as_image, string as_tooltip)` → `long`	Pulsante diviso: la sua parte principale è un pulsante (`ue_clicked`), la sua freccia apre un menu riempito con `of_add_menu_item` come quello di un menu a discesa (`ue_menu_selected`). La sua scorciatoia scatena la parte principale; ripiegato nel chevron, apre un elenco la cui prima riga è la sua azione. Restituisce `0` una volta aggiunto, `-5` se l'indirizzo è rifiutato (non `barra/strumento`, una barra mai aggiunta — tranne `main` —, un indirizzo già occupato), `-2` se il componente non è creato
`of_add_label (string as_keys, string as_text)` → `long`	Etichetta informativa, non cliccabile. Restituisce `0` una volta aggiunto, `-5` se l'indirizzo è rifiutato (non `barra/strumento`, una barra mai aggiunta — tranne `main` —, un indirizzo già occupato), `-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 la perdita del focus scatena `ue_text_changed`, Esc ripristina il testo convalidato. `ai_width` in pixel. Restituisce `0` una volta aggiunto, `-5` se l'indirizzo è rifiutato (non `barra/strumento`, una barra mai aggiunta — tranne `main` —, un indirizzo già occupato), `-2` se il componente non è creato
`of_add_combo (string as_keys, integer ai_width, boolean ab_editable, string as_tooltip)` → `long`	Elenco a discesa (combo): un campo e la sua freccia, la combo della barra multifunzione. `ab_editable = false`, l'utente sceglie solo nell'elenco; `true`, può anche digitare un valore proprio, convalidato da Invio o dall'uscita dal campo. L'elenco si riempie con `of_add_combo_item`, una scelta scatena `ue_combo_changed`, `is_text` imposta e rilegge il valore. `ai_width` in pixel (0 = larghezza predefinita). Ripiegato nel chevron, resta un elenco funzionante. Restituisce `0` una volta aggiunto, `-5` se l'indirizzo è rifiutato (non `barra/strumento`, una barra mai aggiunta — tranne `main` —, un indirizzo già occupato), `-2` se il componente non è creato
`of_add_combo_item (string as_keys, string as_label)` → `long`	Aggiunge una scelta all'elenco di un elenco a discesa: `as_keys` nomina l'elenco (`"main/zoom"`). Una scelta ha come chiave la sua etichetta, quindi il suo indirizzo è `"main/zoom/150%"` (`of_remove_combo_item`, `of_has`); `of_count` e `of_keys_at` sull'elenco ne percorrono le scelte. In modalità demo l'elenco mostra 6 scelte. Restituisce `0` una volta aggiunta, `-5` se `as_keys` non è un elenco a discesa, o se l'etichetta è vuota, contiene `/` o `	`, o è già nell'elenco,` -2` se il componente non è creato
`of_add_datepicker (string as_keys, string as_date, string as_tooltip)` → `long`	Selettore di data; una scelta scatena `ue_date_changed`, `is_date` legge e imposta la data. Date nel formato `"aaaa-mm-gg"`. Restituisce `0` una volta aggiunto, `-5` se l'indirizzo è rifiutato (non `barra/strumento`, una barra mai aggiunta — tranne `main` —, un indirizzo già occupato), `-2` se il componente non è creato
`of_add_separator (string as_keys)` → `long`	Linea verticale di separazione in una barra (`as_keys` la nomina). Un separatore non ha né chiave né rango. Restituisce `0` una volta aggiunto, `-5` per una barra mai aggiunta (tranne `main`), `-2` se il componente non è creato. Un separatore che strumenti nascosti lascerebbero in testa, in coda o doppio non viene disegnato
`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 = 1) anziché alla fine. Restituisce `0` una volta aggiunto, `-5` se l'indirizzo è rifiutato (non `barra/strumento`, una barra mai aggiunta — tranne `main` —, un indirizzo già occupato), `-2` se il componente non è creato
`of_move_item (string as_keys, integer ai_index)` → `long`	Sposta uno strumento in un'altra posizione nella sua barra (primo = 1; il rango conta gli strumenti, un separatore non ne occupa). Mantiene tipo, menu e stato vivo: lo strumento cambia posto, non viene ricostruito. Restituisce `0` una volta applicato, `-5` se nessuno strumento vive a quell'indirizzo, `-2` se il componente non è creato
`of_remove_item (string as_keys)` → `long`	Rimuove uno strumento (`"main/save"`) o una voce di menu (`"main/export/pdf"`, con la sua cascata), con i suoi handle e la sua scorciatoia. Tutto il resto rimane, stato vivo compreso. Per far andare e venire uno strumento, `ib_visible` sul suo handle lo mantiene nel modello. Restituisce `0` una volta rimosso, `-5` se nulla vive a quell'indirizzo, `-2` se il componente non è creato
`of_remove_combo_item (string as_keys)` → `long`	Rimuove una scelta di un elenco a discesa, nominata dal suo indirizzo `"main/zoom/150%"`; il valore mostrato resta. `of_remove_item` fa lo stesso. Restituisce `0` una volta rimossa, `-5` se quell'elenco non ha tale scelta, `-2` se il componente non è creato
`of_add_menu_item (string as_keys, string as_label, string as_image)` → `long`	Voce del menu di un pulsante a discesa, al suo indirizzo `barra/menu/voce`; ogni livello in più la colloca in cascata sotto la voce precedente, a qualunque profondità. Un'etichetta vuota mostra la chiave. Restituisce `0` una volta aggiunta, `-5` se l'indirizzo è rifiutato (livello vuoto o con `	`, menu o voce padre mai aggiunti, indirizzo già occupato),` -2 `se il componente non è creato. Vale anche per il menu di un pulsante diviso (`of_add_split_button`)
`of_add_menu_separator (string as_keys)` → `long`	Linea di separazione alla fine del menu di un pulsante a discesa (`"main/export"`), o della cascata di una voce (`"main/export/img"`). Restituisce `0` una volta aggiunta, `-5` se l'indirizzo non nomina né l'uno né l'altra, `-2` se il componente non è creato. Vale anche per il menu di un pulsante diviso (`of_add_split_button`)
`of_clear_menu (string as_keys)` → `long`	Svuota il menu di un pulsante a discesa (`"main/recent"`) e mantiene il pulsante: il modo per ricostruire un elenco di file recenti. Gli handle e le scorciatoie delle sue voci se ne vanno con esse. Restituisce `0` una volta applicato, `-5` se l'indirizzo non nomina alcun menu a discesa, `-2` se il componente non è creato. Vale anche per il menu di un pulsante diviso (`of_add_split_button`)
`of_clear_combo (string as_keys)` → `long`	Svuota l'elenco di un elenco a discesa (`"main/zoom"`); il valore mostrato resta. Il modo di ricostruire un elenco che segue il documento. Restituisce `0` una volta applicato, `-5` se `as_keys` non è un elenco a discesa, `-2` se il componente non è creato
`of_register_shortcut (string as_chord, string as_keys)` → `long`	Su una toolbar la scorciatoia prende l'indirizzo di ciò che scatena: uno strumento (`barra/strumento` — come `is_shortcut` sul suo handle) o una voce di menu (`barra/menu/voce`). Risponde ovunque sia il focus nella finestra e compare nel tooltip o a destra della voce; `""` la rimuove. Una barra degli strumenti non ha nulla da scatenare per sé stessa: la forma a un argomento restituisce `-5`. Restituisce `0` una volta applicato, `-5` se l'indirizzo non nomina né uno strumento né una voce, o nomina un'etichetta, `-2` se il componente non è creato
`of_clear_shortcuts ( )` → `long`	Rimuove tutte le scorciatoie della barra degli strumenti — quelle dei suoi strumenti e delle sue voci di menu: non rispondono più, non si mostrano più, e `is_shortcut` rilegge `""`. Restituisce `0` una volta applicato, `-2` se il componente non è creato

Su una barra — `n_pbt_toolbar_bar` #

Membro	Tipo	Predefinito	Ruolo
`ii_band`	integer	`1`	Banda (riga) che ospita la barra; `1` = prima riga
`ii_index`	integer	`1`	Posizione della barra all'interno della propria banda; `1` = la prima
`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; riletta così come è scritta. Uno strumento nascosto, disattivato o oltre il limite della demo non risponde. Serve Ctrl o Alt (Maiusc si aggiunge), oppure è da F1 a F24: un tasto da solo — una lettera, Canc, Invio — è digitazione, mai una scorciatoia. Un pulsante o un interruttore si attiva; un campo di immissione riceve il cursore, con il testo selezionato; un selettore di data apre il suo calendario; un'etichetta non ne accetta
`is_date`	string	`""`	Data di un selettore di data, `"aaaa-mm-gg"` (`""` svuota il campo). Rilegge la data visualizzata — quella scelta dall'utente come quella impostata qui. Una data malformata viene ignorata; gli altri tipi di strumento non hanno data e rileggono `""`
`is_image`	string	`""`	Icona dello strumento (stesse forme dell'aggiunta: percorso, `mono:`, `tint:`…); `""` la rimuove. Un interruttore Riproduci che diventa Pausa, un pulsante che diventa un'icona di errore — senza rimuovere e riaggiungere lo strumento
`is_group`	string	`""`	Gruppo di un interruttore: gli interruttori di una stessa barra che condividono un gruppo sono esclusivi, come i pulsanti di allineamento di un editor — premerne uno rilascia gli altri, premere quello già premuto lo lascia premuto. Solo l'interruttore premuto scatena `ue_toggled`. `ib_checked = true` impostato dal vostro codice rilascia anch'esso gli altri, senza evento. `""` (predefinito): nessun gruppo
`ib_editable`	boolean	`false`	Un elenco a discesa (`of_add_combo`): `true`, l'utente può digitare un valore proprio oltre alle scelte dell'elenco; `false`, sceglie soltanto. Ogni altro strumento legge `false` e lo ignora

Su una voce di menu — `n_pbt_toolbar_menu_item` #

Membro	Tipo	Predefinito	Ruolo
`ib_enabled`	boolean	`true`	Disattivata, la voce resta nel menu e non può più essere scelta — né con il mouse, né con la tastiera, né con la sua scorciatoia
`ib_visible`	boolean	`true`	Nascosta, la voce lascia il menu (con la sua cascata); mantiene posto e stato, e torna dov'era
`ib_checked`	boolean	`false`	Un segno di spunta davanti alla voce. È l'applicazione a deciderlo: scegliere la voce non lo inverte
`is_text`	string	`""`	Etichetta della voce, testo formattato con tag accettato; rilegge la chiave se la voce è stata aggiunta senza etichetta
`is_shortcut`	string	`""`	Scorciatoia mostrata a destra della voce e attiva: la sceglie ovunque sia il focus e solleva `ue_menu_selected` come un clic — non se la voce, un livello sopra o il suo menu a discesa è disattivato o nascosto. Riletta così come è scritta; `""` la rimuove. Stessa regola di uno strumento: Ctrl o Alt, oppure da F1 a F24
`is_image`	string	`""`	Icona della voce, mostrata alla prossima apertura del menu; `""` la rimuove

Le immagini accettano tutte le forme riconosciute dalla libreria: percorso, mono:, tint:, risorsa di una DLL. Una voce di menu accetta i cinque colori di elemento (il_back_color, il_text_color, le loro varianti al passaggio del mouse, il_accent), disegnati nel menu; non mostra alcun tooltip — un menu nativo non ne ha.

Event #

Event	Attivato quando
`ue_clicked (string as_keys)`	Un pulsante — o la parte principale di un pulsante diviso — viene attivato: con un clic, con la sua scorciatoia, o dal pannello del chevron quando è ripiegato. `as_keys` è il suo indirizzo, `"main/save"`
`ue_toggled (string as_keys, boolean ab_checked)`	Un interruttore cambia stato; `ab_checked` riporta il nuovo stato. Scatenato solo da un gesto dell'utente: impostare `ib_checked` non lo scatena. In un gruppo (`is_group`), solo l'interruttore premuto lo scatena
`ue_menu_selected (string as_keys)`	Viene scelta una voce di menu a discesa — con il mouse, la tastiera o la sua scorciatoia, nella barra come nel pannello della freccia. `as_keys` è il suo indirizzo completo, `"main/export/img/png"`. Vale per il menu di un pulsante diviso come per quello di un menu a discesa; la voce stessa è l'ultimo livello dell'indirizzo
`ue_text_changed (string as_keys, string as_text)`	Un campo di immissione viene convalidato (Invio o perdita del focus); Invio si ferma al campo e non aziona il pulsante predefinito della finestra. Esc restituisce al campo il suo testo senza scatenarlo, e impostare `is_text` non lo scatena
`ue_date_changed (string as_keys, string as_date)`	Viene scelta una data (`"aaaa-mm-gg"`). Scatenato solo da una scelta dell'utente nel calendario; impostare `is_date` non lo scatena
`ue_combo_changed (string as_keys, string as_text)`	L'utente ha scelto un valore nell'elenco di un elenco a discesa, o ne ha digitato uno in un elenco modificabile e l'ha convalidato (Invio, o uscendo dal campo) — nella barra o nel pannello del chevron. `as_text` è il valore, `as_keys` = `barra/strumento`. Un valore digitato lo scatena solo se è cambiato; Esc ripristina il valore senza scatenarlo; `is_text` impostato dal vostro codice non scatena nulla. L'evento della barra multifunzione: stesso nome, stesso significato
`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, come `ii_band` e `ii_index`
`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, o ha ripristinato una disposizione con `of_set_layout`. Porta la disposizione intera, non solo ciò che si è mosso, bande e ranghi contati da 1: da memorizzare così com'è e da restituire a `of_set_layout`. Anche l'aggiunta di una barra che ne sposta un'altra lo scatena; nulla viene scatenato quando nulla si è mosso (mostrare una barra già visibile)
`ue_item_rclicked (string as_keys)`	Clic destro su uno strumento (uno in grigio non dice nulla); `as_keys` è il suo indirizzo. Aprite qui il vostro menu contestuale. Un clic destro fuori da ogni strumento scatena invece `ue_rclicked` — mai entrambi
`ue_rclicked ( )`	Clic destro sulla barra fuori da ogni strumento (un clic destro su uno strumento solleva solo `ue_item_rclicked`)
`ue_mouse_enter ( )`	Il mouse entra nella barra
`ue_mouse_leave ( )`	Il mouse esce dalla barra
`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 #

// Due interruttori, un separatore e un pulsante
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_keys = "main/bold" then of_apply_bold(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*/ "")

// Una voce si pilota con il SUO handle, al suo indirizzo
uo_toolbar.of_menu_item(/*keys*/ uo_toolbar.MAIN_BAR + "/export/exp_csv").ib_enabled = false

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

// Una voce del menu Export : la sua foglia indica il formato
if lnv_utils.of_split_path(/*keys*/ as_keys, /*out*/ ls_ids) >= 3 then
	if ls_ids[2] = "export" then of_export(ls_ids[UpperBound(ls_ids)])
end if

Campo di ricerca e selettore di data #

// Un pulsante con la sua scorciatoia, poi un separatore
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)")

// Un'etichetta davanti a un selettore di data
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_keys = "main/search" then of_filter(as_text)

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

Due barre e disposizione memorizzata #

Con ib_reorderable = true, 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.

// Senza questa riga nessuna maniglia : l utente non puo spostare nulla
uo_toolbar.ib_reorderable = true

// La barra principale e i suoi due pulsanti
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 2 (seconda riga), in prima posizione
uo_toolbar.of_add_bar(/*key*/ "format", /*band*/ 2, /*index*/ 1)
uo_toolbar.of_add_toggle(/*keys*/ "format/bold", /*text*/ "G", /*image*/ "", /*tooltip*/ "Grassetto")

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

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

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

Pulsante diviso e interruttori esclusivi #

// Incolla : la parte principale incolla subito, la freccia propone gli altri modi
uo_toolbar.of_add_split_button(/*keys*/ "edit/paste", /*text*/ "", /*image*/ "mono:img\paste.svg", /*tooltip*/ "Paste")
uo_toolbar.of_add_menu_item(/*keys*/ "edit/paste/plain", /*label*/ "Plain text", /*image*/ "")
uo_toolbar.of_add_menu_item(/*keys*/ "edit/paste/special", /*label*/ "Paste special...", /*image*/ "")

// Gli interruttori di allineamento condividono un gruppo : uno solo premuto alla volta
uo_toolbar.of_add_toggle(/*keys*/ "edit/left", /*text*/ "", /*image*/ "mono:img\left.svg", /*tooltip*/ "Left")
uo_toolbar.of_add_toggle(/*keys*/ "edit/center", /*text*/ "", /*image*/ "mono:img\center.svg", /*tooltip*/ "Center")
uo_toolbar.of_add_toggle(/*keys*/ "edit/right", /*text*/ "", /*image*/ "mono:img\right.svg", /*tooltip*/ "Right")
uo_toolbar.of_item(/*keys*/ "edit/left").is_group = "align"
uo_toolbar.of_item(/*keys*/ "edit/center").is_group = "align"
uo_toolbar.of_item(/*keys*/ "edit/right").is_group = "align"
uo_toolbar.of_item(/*keys*/ "edit/left").ib_checked = true

// event ue_clicked di uo_toolbar : la parte principale del pulsante diviso
if as_keys = "edit/paste" then of_paste()

// event ue_toggled di uo_toolbar : solo l interruttore premuto lo scatena
if ab_checked and Left(as_keys, 5) = "edit/" then of_align(Mid(as_keys, 6))

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_content.y      = uo_toolbar.y + al_height
uo_content.height = parent.workspaceheight() - uo_content.y

Vedere Base comune.

Buone pratiche #

Usate MAIN_BAR finché basta una sola barra: nasce con il suo primo strumento, non serve aggiungerla. Per posizionarla altrove che dopo le altre barre, aggiungetela prima di qualsiasi strumento — of_add_bar(MAIN_BAR, 1, 1); una volta nata, of_add_bar(MAIN_BAR) restituisce -5 e si sposta tramite of_bar(MAIN_BAR).ii_band.
Su una toolbar, of_register_shortcut prende l'indirizzo dello strumento o della voce che scatena. Una scorciatoia richiede Ctrl o Alt, oppure un tasto da F1 a F24: un tasto da solo resta alla digitazione.
Raggiunga sempre uno strumento tramite il suo percorso — of_item("main/save") — 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("main") 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
`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.