# statusbar — `u_pbt_statusbar` #

← Riferimento dei componenti · Sommario della guida

> Barra di stato a pannelli: testo formattato, icone, larghezze fisse o automatiche, allineamento a sinistra o a destra, pannelli cliccabili, mini barra di avanzamento e stati colorati.

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

## In breve #

Userobject | `u_pbt_statusbar`
Classe degli item | `n_pbt_statusbar_panel` (pannello)
Serve per | Mostrare in fondo alla finestra lo stato dell'applicazione: contesto, avanzamento, avvisi discreti
Opzioni opt-in | —

## Avvio rapido #

    // event open della finestra
    // of_add_panel(id, testo, icona, allineamento, larghezza)
    // id vuoto = pannello puramente informativo ; larghezza 0 = adattata al testo
    uo_statut.of_add_panel(/*id*/ "etat",  /*text*/ "Pronto",           /*icon_file*/ "", /*align*/ uo_statut.ALIGN_START,  /*width*/ 0)
    uo_statut.of_add_panel(/*id*/ "",      /*text*/ "Riga 12, Col 4", /*icon_file*/ "", /*align*/ uo_statut.ALIGN_START,  /*width*/ 0)
    uo_statut.of_add_panel(/*id*/ "heure", /*text*/ "12:00",          /*icon_file*/ "", /*align*/ uo_statut.ALIGN_END, /*width*/ 140)

    // Aggiornare un pannello in qualsiasi momento, tramite il suo identificatore
    uo_statut.of_item("etat").is_text = "Salvataggio in corso..."

## Il modello: pannelli con chiave #

La barra è una sequenza di pannelli, aggiunti nell'ordine. Alla creazione un pannello riceve un identificatore: è tramite questo che lo si ritrova in seguito per cambiarne il testo, l'icona o lo stato.

L'identificatore è una chiave di indirizzamento, non un interruttore di interattività:

- Identificatore indicato: il pannello è ritrovabile — se ne cambia il contenuto, gli si mette un suggerimento. Resta inerte: una barra di stato mostra prima di tutto, e un pannello come `Riga 12, Col 4` non deve sembrare premibile.
- Identificatore vuoto: il pannello è puramente decorativo. Non è né ritrovabile né cliccabile, e nessun suggerimento può essergli attaccato. Dia un identificatore a tutti i suoi pannelli: non costa nulla e lascia la porta aperta.
- Per rendere un pannello cliccabile, lo chieda: `of_item("id").ib_clickable = true`. Un pannello dotato di un elenco a discesa (`of_set_panel_menu`) lo è d'ufficio.

    uo_statut.of_item("etat").is_text = "3 record modificati"

Vedere Base comune · Gli item.

## Proprietà #

Proprietà | Tipo | Predefinito | Ruolo
--- | --- | --- | ---
`ib_show_resize_grip` | boolean | `false` | Mostra la maniglia di ridimensionamento nell'angolo di fine barra
`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

## Metodi #

Metodo | Ruolo
--- | ---
`of_add_panel (string as_id, string as_text, string as_icon_file, string as_align, integer ai_width)` | Aggiunge un pannello in fondo alla barra
`of_add_sep ( )` | Aggiunge una linea verticale di separazione tra due gruppi di pannelli
`of_insert_panel (as_id, as_text, as_icon_file, as_align, ai_width, ai_index)` | Inserisce un pannello in una posizione precisa (contata a partire da 0)
`of_move_panel (string as_id, integer ai_index)` | Sposta un pannello esistente in un'altra posizione
`of_remove_panel (string as_id)` | Elimina un solo pannello; gli altri conservano il proprio stato
`of_item (string as_id)` → `n_pbt_statusbar_panel` | Restituisce l'handle di un pannello (creato al primo accesso)
`of_flash_panel (string as_id, string as_text, long al_ms)` | Mostra un messaggio per `al_ms` millisecondi, poi rimette il testo precedente (`al_ms` ≤ 0 = 2 secondi)
`of_set_panel_menu (string as_id, string as_item_ids[], string as_labels[])` | Trasforma il pannello in un selettore: il clic apre un elenco a discesa e la scelta torna con `ue_panel_menu_clicked`. Un identificatore `-` inserisce un separatore; un'etichetta vuota riprende l'identificatore
`of_clear_panel_menu (string as_id)` | Toglie l'elenco a discesa; il pannello ritrova il comportamento che gli dà `ib_clickable`
`of_clear ( )` | Svuota la barra: tutti i pannelli e tutti i separatori
`of_reset ( )` | Svuota la barra e riporta le proprietà ai valori predefiniti

### Gli argomenti di `of_add_panel` #

Argomento | Valori | Effetto
--- | --- | ---
`as_id` | libero, o `""` | Chiave del pannello, quella con cui lo si ritrova in seguito. Vuoto = pannello decorativo, né indirizzabile né cliccabile
`as_text` | testo | Contenuto del pannello. Il testo formattato con tag è accettato
`as_icon_file` | percorso di immagine, oppure `""` | Icona mostrata prima del testo (forme accettate)
`as_align` | `ALIGN_START` (predefinito) oppure `ALIGN_END` | Lato verso cui il pannello viene spinto. Valori logici: `START` = inizio della lettura (a sinistra nella scrittura da sinistra a destra). Gli alias fisici `"left"` / `"right"` restano accettati
`ai_width` | pixel, oppure `0` | Larghezza fissa. `0` = il pannello si adatta al proprio contenuto

### Su un pannello — `n_pbt_statusbar_panel` #

Membro | Tipo | Predefinito | Ruolo
--- | --- | --- | ---
`is_text` | string | `""` | Testo del pannello, testo formattato con tag accettato
`is_image` | string | `""` | Icona del pannello, modificabile in qualsiasi momento
`ib_enabled` | boolean | `true` | Pannello disattivato e non cliccabile
`ib_visible` | boolean | `true` | Pannello nascosto, senza essere rimosso dalla barra
`ii_progress` | integer | — | Mini barra di avanzamento nel pannello, da `0` a `100`; un valore negativo la fa scomparire
`is_state` | string | `""` | Stato semantico del pannello, che lo colora: vedere le costanti qui sotto
`ib_indeterminate` | boolean | `false` | Barra animata senza valore, per un'elaborazione di durata sconosciuta. Indipendente da `ii_progress`, che resta la percentuale esatta
`ib_clickable` | boolean | `false` | Il pannello reagisce al clic. Opt-in: un pannello resta inerte finché non lo si chiede, pur conservando la sua chiave — è pilotato e porta un suggerimento. Un pannello con elenco a discesa è cliccabile d'ufficio

### Costanti di stato #

Costante | Valore | Uso
--- | --- | ---
`STATE_NONE` | `""` | Nessuno stato: aspetto normale
`STATE_INFO` | `"info"` | Informazione
`STATE_WARNING` | `"warning"` | Avvertimento
`STATE_ERROR` | `"error"` | Errore
`STATE_SUCCESS` | `"success"` | Successo

Come per ogni proprietà a valori predefiniti, utilizzi la costante anziché la stringa:

    n_pbt_statusbar_panel lnv_panneau
    lnv_panneau = uo_statut.of_item("etat")
    lnv_panneau.is_state = lnv_panneau.STATE_WARNING

## Event #

Event | Attivato quando
--- | ---
`ue_panel_clicked (string as_id)` | Viene cliccato un pannello il cui identificatore è valorizzato
`ue_panel_double_clicked (string as_id)` | Un pannello cliccabile riceve un doppio clic — la scorciatoia classica dietro `Riga 12, Col 4` che apre un "Vai alla riga"
`ue_panel_rclicked (string as_id, long al_x, long al_y)` | Un pannello riceve un clic destro. `al_x` e `al_y` sono pixel schermo: da passare tali e quali per aprire un menu contestuale dove l'utente ha mirato
`ue_panel_menu_clicked (string as_id, string as_item_id)` | Una voce di un elenco a discesa di pannello è stata scelta (vedere `of_set_panel_menu`)
`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`)

## Da tastiera #

La barra è un solo arresto di tabulazione: vi entrano soltanto i pannelli fatti per essere cliccati, e le frecce li percorrono.

Tasto | Effetto
--- | ---
Frecce | Passano al pannello interattivo precedente / successivo, ciclando; i pannelli di sola visualizzazione e quelli disattivati vengono saltati
Inizio / Fine | Primo / ultimo pannello interattivo
Invio o Spazio | Attiva il pannello — vale a dire `ue_panel_clicked`, oppure l'apertura del suo elenco a discesa se ne ha uno

Un pannello che si limita a visualizzare non è un controllo: non è né focalizzabile né annunciato come tale. Un pannello cliccabile ma disattivato resta invece annunciato come non disponibile, anziché passare per testo. Una barra di avanzamento annuncia il proprio valore, e una indeterminata non ne annuncia alcuno — quell'assenza è il senso della parola.

Il fuoco sopravvive alla ricostruzione della barra: essa viene ridisegnata a ogni cambio di testo, e senza questo il fuoco cadrebbe ogni secondo su una barra che mostra un orologio.

## Esempi #

### Larghezze fisse e larghezze automatiche #

    // Larghezza 0 : il pannello occupa esattamente lo spazio del suo testo
    uo_statut.of_add_panel(/*id*/ "", /*text*/ "Pannello adattato al contenuto", /*icon_file*/ "", /*align*/ uo_statut.ALIGN_START, /*width*/ 0)

    // Larghezza fissa in pixel : utile quando il testo cambia spesso,
    // affinche i pannelli vicini non si spostino a ogni aggiornamento
    uo_statut.of_add_panel(/*id*/ "pos", /*text*/ "Riga 1, Col 1", /*icon_file*/ "", /*align*/ uo_statut.ALIGN_START, /*width*/ 150)

    // Un pannello spinto all'estremita opposta
    uo_statut.of_add_panel(/*id*/ "heure", /*text*/ "12:00", /*icon_file*/ "", /*align*/ uo_statut.ALIGN_END, /*width*/ 140)

### Icone e pannelli cliccabili #

    // Un identificatore non vuoto rende il pannello cliccabile
    uo_statut.of_add_panel(/*id*/ "save", /*text*/ "Salvato", /*icon_file*/ "mono:img\save.svg", /*align*/ uo_statut.ALIGN_START, /*width*/ 0)
    uo_statut.of_add_sep()   // linea di separazione tra due gruppi di pannelli
    uo_statut.of_add_panel(/*id*/ "conn", /*text*/ "Connesso",   /*icon_file*/ "mono:img\plug.svg", /*align*/ uo_statut.ALIGN_START, /*width*/ 0)
    uo_statut.of_add_panel(/*id*/ "user", /*text*/ "Guillaume",  /*icon_file*/ "mono:img\user.svg", /*align*/ uo_statut.ALIGN_END, /*width*/ 160)

    // event ue_panel_clicked di uo_statut
    choose case as_id
        case "conn" ; open(w_parametres_connexion)
        case "user" ; open(w_profil)
    end choose

### Testo formattato in un pannello #

I pannelli accettano il testo formattato con tag: stili, colori e piccole immagini direttamente nel testo.

    uo_statut.of_add_panel(/*id*/ "", /*text*/ "Benvenuto [b]in[/b] [accent]PBToolboxAI[/accent]", &
                           /*icon_file*/ "", /*align*/ uo_statut.ALIGN_START, /*width*/ 0)

    uo_statut.of_add_panel(/*id*/ "", /*text*/ "[green]In linea[/green] [picture=mono:img\plug.svg,14,14]", &
                           /*icon_file*/ "", /*align*/ uo_statut.ALIGN_END, /*width*/ 0)

    // Il testo formattato vale anche per gli aggiornamenti
    uo_statut.of_item("etat").is_text = "[b]" + String(ll_modifies) + "[/b] record modificati"

### Seguire un'elaborazione lunga #

    n_pbt_statusbar_panel lnv_avance

    uo_statut.of_add_panel(/*id*/ "import", /*text*/ "Importazione", /*icon_file*/ "", /*align*/ uo_statut.ALIGN_START, /*width*/ 220)
    lnv_avance = uo_statut.of_item("import")

    // Nel ciclo di elaborazione : la mini barra segue l'avanzamento
    lnv_avance.ii_progress = ll_pourcentage
    lnv_avance.is_text     = "Importazione " + String(ll_pourcentage) + " %"

    // Alla fine : nascondere la mini barra e segnalare il risultato
    lnv_avance.ii_progress = -1                       // valore negativo = barra nascosta
    lnv_avance.is_text     = "Importazione completata"
    lnv_avance.is_state    = lnv_avance.STATE_SUCCESS

### Segnalare un avviso discreto #

    n_pbt_statusbar_panel lnv_panneau
    lnv_panneau = uo_statut.of_item("conn")

    if not ib_connecte then
        lnv_panneau.is_text  = "Non in linea"
        lnv_panneau.is_state = lnv_panneau.STATE_ERROR
    else
        lnv_panneau.is_text  = "Connesso"
        lnv_panneau.is_state = lnv_panneau.STATE_NONE   // ritorno all'aspetto normale
    end if

### Adattare la barra al contesto #

    // Nascondere un pannello senza eliminarlo : ritrovera il suo posto piu tardi
    uo_statut.of_item("user").ib_visible = ib_utilisateur_identifie

    // Disattivarlo quando l'azione corrispondente non ha senso
    uo_statut.of_item("save").ib_enabled = ib_document_ouvert

    // Riorganizzare : mettere il pannello di stato in testa (posizioni contate a partire da 0)
    uo_statut.of_move_panel(/*id*/ "etat", /*index*/ 0)

    // Rimuovere un pannello diventato inutile
    uo_statut.of_remove_panel(/*id*/ "import")

### La maniglia di ridimensionamento #

    // Su una finestra ridimensionabile, la maniglia d'angolo e un riferimento familiare
    uo_statut.ib_show_resize_grip = true

## Buone pratiche #

- Assegni una larghezza fissa ai pannelli il cui testo cambia spesso (posizione del cursore, contatori): i pannelli vicini smetteranno di saltare a ogni aggiornamento.
- Lasci vuoto l'identificatore per un pannello puramente informativo: si evita così un clic senza effetto.
- Riservi il lato destro alle informazioni stabili (ora, utente, connessione) e il lato sinistro al contesto corrente.
- Utilizzi `is_state` anziché colori nel testo: lo stato segue sia il tema chiaro sia quello scuro.
- Si ricordi di riportare `is_state` a `STATE_NONE` e `ii_progress` a un valore negativo non appena l'avviso o l'elaborazione è terminata.
- Una barra di stato non è un registro: oltre cinque o sei pannelli, è preferibile una notifica toaster.
- Se l'avanzamento merita più di una mini barra di pannello, passi alla progressbar.

← Riferimento dei componenti · Sommario della guida