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) · `n_pbt_statusbar_menu_item` (voce di elenco)
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(/*key*/ "etat",  /*text*/ "Pronto",           /*icon_file*/ "", /*align*/ uo_statut.ALIGN_START,  /*width*/ 0)
uo_statut.of_add_panel(/*key*/ "",      /*text*/ "Riga 12, Col 4", /*icon_file*/ "", /*align*/ uo_statut.ALIGN_START,  /*width*/ 0)
uo_statut.of_add_panel(/*key*/ "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_panel("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_panel("id").ib_clickable = true. Un pannello dotato di un elenco a discesa (of_add_menu_item) lo è d'ufficio.

uo_statut.of_panel("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_key, string as_text, string as_icon_file, string as_align, integer ai_width)`	Aggiunge un pannello in fondo alla barra. Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_add_sep ( )`	Aggiunge una linea verticale di separazione tra due gruppi di pannelli. Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_insert_panel (as_keys, as_text, as_icon_file, as_align, ai_width, ai_index)`	Inserisce un pannello in una posizione precisa (contata a partire da 1). Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_move_panel (string as_key, integer ai_index)`	Sposta un pannello esistente in un'altra posizione. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_remove_panel (string as_key)`	Elimina un solo pannello; gli altri conservano il proprio stato. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_panel (string as_key)` → `n_pbt_statusbar_panel`	Restituisce l'handle di un pannello (creato al primo accesso)
`of_flash_panel (string as_key, string as_text, long al_ms)`	Mostra un messaggio per `al_ms` millisecondi, poi rimette il testo precedente (`al_ms` ≤ 0 = 2 secondi). 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)` · `(as_keys, as_label, as_image)`	Aggiunge una voce all'elenco a discesa di un pannello: `as_keys` ha due livelli, il pannello poi la voce (`"enc/utf8"`). Dalla prima voce il pannello è un selettore: il clic apre l'elenco, e la scelta torna con `ue_panel_menu_clicked` con lo stesso indirizzo. Un'etichetta vuota riprende la chiave. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_insert_menu_item (string as_keys, string as_label, integer ai_index)` · `(as_keys, as_label, as_image, ai_index)`	Inserisce una voce in una posizione precisa (contata da 1). 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_key)`	Riga di separazione nell'elenco del pannello `as_key`. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_remove_menu_item (string as_keys)`	Toglie una sola voce; tolta l'ultima, il pannello ritrova il comportamento che gli dà `ib_clickable`. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_move_menu_item (string as_keys, integer ai_index)`	Sposta una voce in un'altra posizione del suo elenco. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_menu_item (string as_keys)` → `n_pbt_statusbar_menu_item`	Restituisce l'handle di una voce (creato al primo accesso), per disattivarla, spuntarla o rinominarla
`of_clear_menu (string as_key)`	Toglie tutto l'elenco a discesa; il pannello ritrova il comportamento che gli dà `ib_clickable`. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_clear ( )`	Svuota la barra: tutti i pannelli e tutti i separatori. Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_reset ( )`	Svuota la barra e riporta le proprietà ai valori predefiniti. Restituisce `0` una volta applicato, `-2` se il componente non è creato

Gli argomenti di `of_add_panel` #

Argomento	Valori	Effetto
`as_keys`	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

Su una voce di elenco — `n_pbt_statusbar_menu_item` #

Ottenuta con of_menu_item("enc/utf8"): l'indirizzo ha due livelli, il pannello poi la voce. L'elenco è un menu nativo: una proprietà cambiata mentre è aperto si vede all'apertura successiva.

Membro	Tipo	Predefinito	Ruolo
`is_label`	string	`""`	Testo della voce
`is_image`	string	`""`	Immagine prima del testo, modificabile in ogni momento
`ib_enabled`	boolean	`true`	Voce disattivata: mostrata, ma impossibile da scegliere
`ib_checked`	boolean	`false`	Spunta davanti alla voce, per il valore in uso
`ib_visible`	boolean	`true`	Voce tolta dall'elenco senza essere rimossa: rimostrarla non richiede altro

uo_statut.of_add_menu_item("enc/utf8", "UTF-8")
uo_statut.of_add_menu_item("enc/ansi", "ANSI")
uo_statut.of_menu_item("enc/utf8").ib_checked = true     // la valeur en cours
uo_statut.of_menu_item("enc/ansi").ib_enabled = false    // pas disponible ici

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:

uo_statut.of_panel("etat").is_state = n_pbt_statusbar_panel.STATE_WARNING

Event #

Event	Attivato quando
`ue_panel_clicked (string as_key)`	Viene cliccato un pannello il cui identificatore è valorizzato
`ue_panel_double_clicked (string as_key)`	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_key, 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_keys)`	Una voce di un elenco a discesa di pannello è stata scelta (vedere `of_add_menu_item`). `as_keys` porta i due livelli: il pannello, poi la voce — `"clock/utc"`
`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(/*key*/ "", /*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(/*key*/ "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(/*key*/ "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(/*key*/ "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(/*key*/ "conn", /*text*/ "Connesso",   /*icon_file*/ "mono:img\plug.svg", /*align*/ uo_statut.ALIGN_START, /*width*/ 0)
uo_statut.of_add_panel(/*key*/ "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_keys
    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(/*key*/ "", /*text*/ "Benvenuto [b]in[/b] [accent]PBToolboxAI[/accent]", &
                       /*icon_file*/ "", /*align*/ uo_statut.ALIGN_START, /*width*/ 0)

uo_statut.of_add_panel(/*key*/ "", /*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_panel("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(/*key*/ "import", /*text*/ "Importazione", /*icon_file*/ "", /*align*/ uo_statut.ALIGN_START, /*width*/ 220)
lnv_avance = uo_statut.of_panel("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_panel("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_panel("user").ib_visible = ib_utilisateur_identifie

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

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

// Rimuovere un pannello diventato inutile
uo_statut.of_remove_panel(/*key*/ "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.

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.