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 #

Avvio rapido #

// event open della finestra
// of_add_panel(chiave, testo, icona, allineamento, larghezza)
// la chiave ritrova il pannello in seguito ; larghezza 0 = adattata al testo, -1 = prende lo spazio libero
uo_status.of_add_panel(/*key*/ "state", /*text*/ "Ready",          /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ -1)
uo_status.of_add_panel(/*key*/ "pos",   /*text*/ "Line 12, Col 4", /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ 0)
uo_status.of_add_panel(/*key*/ "clock", /*text*/ "12:00",          /*icon_file*/ "", /*align*/ uo_status.ALIGN_END,   /*width*/ 140)

// Aggiornare un pannello in qualsiasi momento, tramite il suo identificatore
uo_status.of_panel(/*key*/ "state").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. Riceve comunque il clic destro (ue_panel_rclicked) : un menu contestuale « Copia » non è un'attivazione.
• 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. Conta comunque in of_count e nelle posizioni, e of_keys_at rende per lui una chiave vuota.
• Per rendere un pannello cliccabile, lo chieda: of_panel(/*key*/ "id").ib_clickable = true. Un pannello dotato di un elenco a discesa (of_add_menu_item) lo è d'ufficio.

// Il pannello mostra un nuovo testo
uo_status.of_panel(/*key*/ "state").is_text = "3 record modificati"

Vedere Base comune · Gli item.

Proprietà #

Metodi #

Gli argomenti di of_add_panel #

Su un pannello — n_pbt_statusbar_panel #

Su una voce di elenco — n_pbt_statusbar_menu_item #

Ottenuta con of_menu_item(/*keys*/ "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.

Le proprietà che ogni handle di item eredita — is_tooltip, is_super_tooltip_title, is_super_tooltip_text, is_super_tooltip_image, il_accent, il_back_color, il_text_color, il_back_color_hover, il_text_color_hover — sono senza effetto su una voce: la lista è un menu nativo, che non mostra né tooltip né colori di una voce. Sono ignorate e si rileggono vuote (-1 per un colore). Una posizione in una lista conta voci: un separatore non lo è, e of_count("enc"), of_keys_at("enc", n), of_has("enc/utf8") percorrono le voci di un pannello. Una chiave che comincia con __ è riservata al componente.

// The menu of the encoding panel, entry by entry
uo_status.of_add_menu_item(/*keys*/ "enc/utf8", /*label*/ "UTF-8")
uo_status.of_add_menu_item(/*keys*/ "enc/ansi", /*label*/ "ANSI")
uo_status.of_menu_item(/*keys*/ "enc/utf8").ib_checked = true     // the current value
uo_status.of_menu_item(/*keys*/ "enc/ansi").ib_enabled = false    // not available here

Costanti di stato #

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

// The panel takes the colors of a warning
uo_status.of_panel(/*key*/ "state").is_state = n_pbt_statusbar_panel.STATE_WARNING

Event #

Da tastiera #

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

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. Un pannello cliccabile disattivato mostra sempre il suo tooltip — quello che dice perché è disattivato — e un pannello con lista dice se la sua lista è aperta.

Un lettore di schermo sente i messaggi di of_flash_panel senza che il focus si sposti: è il ruolo di una barra di stato (una regione live cortese). Gli altri cambiamenti — un nuovo testo, un nuovo stato — sono letti solo con ib_announce = true; altrimenti un orologio al secondo parlerebbe tutto il giorno.

Il focus sopravvive alla ricostruzione della barra: un pannello aggiunto, rimosso, nascosto o disattivato la ricostruisce, e il focus torna sullo stesso pannello (sul successivo quando non può più prenderlo). Un testo, uno stato o un avanzamento cambiano sul posto, senza ricostruire nulla — un orologio al secondo non ruba mai il focus.

Esempi #

Larghezze fisse e larghezze automatiche #

// Larghezza 0 : il pannello occupa esattamente lo spazio del suo testo
uo_status.of_add_panel(/*key*/ "", /*text*/ "Pannello adattato al contenuto", /*icon_file*/ "", /*align*/ uo_status.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_status.of_add_panel(/*key*/ "pos", /*text*/ "Riga 1, Col 1", /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ 150)

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

Icone e pannelli cliccabili #

// Una chiave rende il pannello indirizzabile ; ib_clickable lo rende cliccabile
uo_status.of_add_panel(/*key*/ "save", /*text*/ "Salvato", /*icon_file*/ "mono:img\save.svg", /*align*/ uo_status.ALIGN_START, /*width*/ 0)
uo_status.of_add_sep()   // linea di separazione tra due gruppi di pannelli
uo_status.of_add_panel(/*key*/ "conn", /*text*/ "Connesso",   /*icon_file*/ "mono:img\plug.svg", /*align*/ uo_status.ALIGN_START, /*width*/ 0)
uo_status.of_add_panel(/*key*/ "user", /*text*/ "Alex Martin",  /*icon_file*/ "mono:img\user.svg", /*align*/ uo_status.ALIGN_END, /*width*/ 160)

// Solo questi due rispondono al clic (ue_panel_clicked)
uo_status.of_panel(/*key*/ "conn").ib_clickable = true
uo_status.of_panel(/*key*/ "user").ib_clickable = true

// event ue_panel_clicked di uo_status
choose case as_key
    case "conn" ; open(w_connection_settings)
    case "user" ; open(w_profile)
end choose

Testo formattato in un pannello #

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

// Un benvenuto a sinistra
uo_status.of_add_panel(/*key*/ "", /*text*/ "Benvenuto [b]in[/b] [accent]PBToolboxAI[/accent]", &
                       /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ 0)

// Lo stato della connessione a destra
uo_status.of_add_panel(/*key*/ "", /*text*/ "[green]In linea[/green] [picture=mono:img\plug.svg,14,14]", &
                       /*icon_file*/ "", /*align*/ uo_status.ALIGN_END, /*width*/ 0)

// Variabili locali
long ll_changed

// Il testo formattato vale anche per gli aggiornamenti
ll_changed = dw_list.ModifiedCount()
uo_status.of_panel(/*key*/ "state").is_text = "[b]" + String(ll_changed) + "[/b] records changed"

Seguire un'elaborazione lunga #

// Local variables
n_pbt_statusbar_panel lnv_import

// Il pannello di importazione, poi il suo handle per seguirlo
uo_status.of_add_panel(/*key*/ "import", /*text*/ "Importazione", /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ 220)
lnv_import = uo_status.of_panel(/*key*/ "import")

// Variabili locali
long ll_percent

// Nel ciclo di elaborazione : la mini barra segue l'avanzamento
for ll_percent = 0 to 100 step 25
    lnv_import.ii_progress = ll_percent
    lnv_import.is_text     = "Import " + String(ll_percent) + " %"
next

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

Segnalare un avviso discreto #

// Local variables
n_pbt_statusbar_panel lnv_panel

// Il pannello della connessione
lnv_panel = uo_status.of_panel(/*key*/ "conn")

// Non in linea : il pannello segnala un errore ; connesso : torna normale
if not ib_connected then
    lnv_panel.is_text  = "Non in linea"
    lnv_panel.is_state = lnv_panel.STATE_ERROR
else
    lnv_panel.is_text  = "Connesso"
    lnv_panel.is_state = lnv_panel.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_status.of_panel(/*key*/ "user").ib_visible = ib_user_signed_in

// Disattivarlo quando l'azione corrispondente non ha senso
uo_status.of_panel(/*key*/ "save").ib_enabled = ib_document_open

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

// Rimuovere un pannello diventato inutile
uo_status.of_remove_panel(/*key*/ "import")

La maniglia di ridimensionamento #

// Trascinare la maniglia d'angolo ridimensiona la finestra che porta la barra (nascosta quando e ingrandita)
uo_status.ib_show_resize_grip = true

Un pannello che prende lo spazio libero #

Come il pannello « Pronto » di ogni barra di stato Windows: cresce con la finestra, spinge i pannelli di fine in fondo, ed è il suo testo il primo a essere troncato quando manca spazio.

// Una larghezza di -1 : il pannello prende tutto lo spazio libero
uo_status.of_add_panel(/*key*/ "state", /*text*/ "Ready", /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ -1)
uo_status.of_add_panel(/*key*/ "clock", /*text*/ "12:00", /*icon_file*/ "", /*align*/ uo_status.ALIGN_END, /*width*/ 140)

// La stessa cosa su un pannello che esiste gia
uo_status.of_panel(/*key*/ "state").ib_spring = true

Posizionare la barra in fondo alla finestra #

of_dock_bottom la posa lungo il bordo inferiore di ciò che la porta, su tutta la larghezza: basta una chiamata nell'evento resize. In una cornice MDI, i fogli si dividono ciò che resta sopra.

// evento resize della finestra : la barra segue il bordo inferiore
uo_status.of_dock_bottom()

// evento resize di una cornice MDI : la barra in basso, i fogli sopra
uo_status.of_dock_bottom()
mdi_1.Resize(WorkSpaceWidth(), WorkSpaceHeight() - uo_status.Height)

Riprendere la MicroHelp #

In una cornice MDI con MicroHelp, PowerBuilder scrive l'aiuto della voce di menu sotto il puntatore, e SetMicroHelp scrive il vostro. La barra riprende questo ruolo: nominate una volta il pannello che mostra l'aiuto (is_help_panel), poi scrivete is_help dove chiamavate SetMicroHelp. L'aiuto appare sopra il testo del pannello, e "" gli restituisce il testo.

// Una volta : il pannello che mostra l'aiuto (di solito il primo)
uo_status.is_help_panel = "state"

// Dove chiamavate SetMicroHelp : l'aiuto appare sopra Ready
uo_status.is_help = "Saving the order..."

// "" restituisce al pannello il suo testo
uo_status.is_help = ""

// evento ue_item_hover di una menubar (uo_menu) : l'aiuto della voce sotto il puntatore
uo_status.is_help = this.of_item(/*keys*/ as_keys).is_tooltip

// evento getfocus di un campo (sle_name) : il suo Tag e il suo aiuto
uo_status.is_help = sle_name.Tag

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.
• Fate del primo pannello una molla (ib_spring, o una larghezza di -1): prende lo spazio libero, ed è il suo testo il primo a essere troncato.
• Un pannello è inerte per impostazione predefinita: chieda il clic con ib_clickable, e lasci senza reazione i pannelli che si limitano a mostrare.
• Riservi la fine della barra (ALIGN_END) alle informazioni stabili (ora, utente, connessione) e l'inizio (ALIGN_START) al contesto corrente; nella lettura da destra a sinistra i due lati si invertono da soli.
• 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.

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.

← Riferimento dei componenti · Sommario della guida