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

### Menu a discesa a cascata #

    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.

← Riferimento dei componenti · Sommario della guida