stepbar — `u_pbt_stepbar` #

← Riferimento dei componenti · Sommario della guida

Sequenza di passaggi di una procedura guidata: i passaggi già compiuti, quello in corso e quelli ancora da affrontare, in orizzontale o in verticale.

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

In breve #

Userobject	`u_pbt_stepbar`
Classe degli item	`n_pbt_stepbar_step` (un passaggio)
Serve per	Mostrare all'utente a che punto si trova in una procedura guidata, in un modulo su più pagine, in un processo di approvazione
Principio	Lei dichiara i passaggi, poi sposta `ii_current`: gli stati si calcolano da soli

Avvio rapido #

// event open della finestra
uo_steps.of_add_step(/*key*/ "account",  /*label*/ "Account")
uo_steps.of_add_step(/*key*/ "profile",  /*label*/ "Profilo")
uo_steps.of_add_step(/*key*/ "payment", /*label*/ "Pagamento")
uo_steps.of_add_step(/*key*/ "done",     /*label*/ "Conferma")

// Passaggio in corso (1 = il primo)
uo_steps.ii_current = 1

// Pulsante Avanti della procedura guidata : il passaggio successivo, saltando quelli nascosti e disattivati
uo_steps.of_next()

// Pulsante Indietro
uo_steps.of_previous()

Il modello: un passaggio, tre stati automatici #

Un passaggio non ha uno stato da gestire a mano. Esso si deduce dalla sua posizione rispetto a ii_current:

Posizione	Stato	Resa
Prima del passaggio corrente	`done` — terminato	Pastiglia spuntata
Il passaggio corrente	`current` — in corso	Pastiglia messa in evidenza
Dopo il passaggio corrente	`todo` — prossimo	Pastiglia numerata, tinta discreta

Altri tre stati non si ottengono mai automaticamente: li forza Lei su un passaggio — error quando non è riuscito, warning quando è percorso ma resta qualcosa da rivedere, skipped quando è stato saltato (vedere più avanti).

Proprietà #

Proprietà	Tipo	Predefinito	Ruolo
`ii_current`	integer	`1`	Passaggio in corso, numerato a partire da 1 (numero di passaggi + 1 = tutto completato). Impostarlo solleva `ue_step_changed` quando la barra si sposta. Il passaggio in corso è seguito per identità: aggiungere, togliere o spostare un passaggio prima di esso non cambia il passaggio in corso. Impostato prima dei passaggi, il valore viene conservato e applicato non appena il passaggio esiste. Un passaggio in corso nascosto non lascia alcun passaggio «in corso» a video. «Tutto terminato» è ancorato all'ultimo passaggio di quel momento: un passaggio aggiunto dopo di esso diventa il passaggio in corso (e solleva `ue_step_changed`); uno inserito prima non cambia nulla
`is_position`	string	`"top"`	Orientamento: `top` / `bottom` (sequenza orizzontale) oppure `start` / `end` (sequenza verticale) — costanti `POSITION_TOP`, `POSITION_BOTTOM`, `POSITION_START`, `POSITION_END`. `START`/`END` sono logiche e seguono il senso di scrittura
`is_navigation_mode`	string	`"free"`	Ciò che un clic può raggiungere: `NAV_FREE` (qualunque passaggio, l'impostazione predefinita), `NAV_BACKWARD` (solo i passaggi già percorsi — tornare indietro, mai saltare avanti), `NAV_VISITED` (ogni passaggio già raggiunto, tranne quello in corso — dopo un ritorno indietro, i passaggi raggiunti più avanti restano a un clic) oppure `NAV_NONE` (nulla: un semplice indicatore di avanzamento, guidato dal suo codice soltanto). Ciò che resta cliccabile solleva `ue_step_clicked`; la barra, invece, non si sposta mai su un clic
`is_overflow_mode`	string	`"auto"`	Troppi passaggi per la larghezza: `OVERFLOW_AUTO` compatta la barra sotto una soglia leggibile per passaggio (ogni passaggio diventa un punto, solo quello corrente conserva l'etichetta, e tutti restano cliccabili), `OVERFLOW_SCROLL` conserva le etichette e fa scorrere, tenendo in vista il passaggio corrente, `OVERFLOW_SHRINK` le comprime fino ai puntini di sospensione. Una sequenza verticale non compatta mai
`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

Proprietà di un passaggio — `n_pbt_stepbar_step` #

Ottenute tramite of_step(id):

Proprietà	Tipo	Predefinito	Ruolo
`is_state`	string	`STATE_TODO`	Forza lo stato del passaggio: `STATE_TODO`, `STATE_CURRENT`, `STATE_DONE`, `STATE_ERROR`, `STATE_WARNING` (percorso, ma con qualcosa da rivedere: indicatore ambra con un «!», etichetta ambra), `STATE_SKIPPED` (saltato, né fatto né da fare: indicatore vuoto ad anello tratteggiato con un «–», etichetta in corsivo). I lettori di schermo li annunciano «con un avviso» e «saltato»; dopo l'uno o l'altro la linea è percorsa, come dopo un passaggio fatto. `STATE_AUTO` = ritorno al calcolo automatico; la rilettura restituisce lo stato effettivo del passaggio, non il forzamento. Impostato su una chiave che non designa alcun passaggio, viene ignorato
`is_text`	string	—	Cambia l'etichetta del passaggio, testo formattato con tag accettato
`is_description`	string	`""`	Seconda riga del passaggio — « Facoltativo », una data, un importo. Testo formattato con tag accettato. Annunciata a un lettore di schermo come descrizione del passaggio, dopo il suo nome. Una stringa vuota la toglie; una barra compattata la abbandona per restare su una riga
`is_image`	string	`""`	Icona mostrata al posto del numero del passaggio (forme accettate)
`ib_enabled`	boolean	`true`	Passaggio attivo; un passaggio disattivato non reagisce più al clic
`ib_visible`	boolean	`true`	Nasconde il passaggio senza toglierlo dal modello

Metodi #

Metodo	Ruolo
`of_add_step (string as_key, string as_label)`	Aggiunge un passaggio in fondo alla sequenza. Restituisce `0` una volta applicato, `-5` per una chiave vuota, contenente `/` o `	`, o già presente nella barra,` -2` se il componente non è creato
`of_add_step (string as_key, string as_label, string as_icon_file)`	Lo stesso, con l'icona al posto del numero del passaggio. Restituisce `0` una volta applicato, `-5` per una chiave vuota, contenente `/` o `	`, o già presente nella barra,` -2` se il componente non è creato
`of_add_step (string as_key, string as_label, string as_icon_file, string as_desc)`	Lo stesso, con l'icona e la seconda riga. Restituisce `0` una volta applicato, `-5` per una chiave vuota, contenente `/` o `	`, o già presente nella barra,` -2` se il componente non è creato
`of_insert_step (string as_key, string as_label, integer ai_index)`	Inserisce un passaggio nella posizione indicata (contata a partire da 1; `0` o meno = in testa, oltre la fine = in fondo). Restituisce `0` una volta applicato, `-5` per una chiave vuota, contenente `/` o `	`, o già presente nella barra,` -2` se il componente non è creato
`of_insert_step (string as_key, string as_label, string as_icon_file, integer ai_index)`	Lo stesso, con l'icona. Restituisce `0` una volta applicato, `-5` per una chiave vuota, contenente `/` o `	`, o già presente nella barra,` -2` se il componente non è creato
`of_insert_step (string as_key, string as_label, string as_icon_file, string as_desc, integer ai_index)`	Lo stesso, con l'icona e la seconda riga. Restituisce `0` una volta applicato, `-5` per una chiave vuota, contenente `/` o `	`, o già presente nella barra,` -2` se il componente non è creato
`of_move_step (string as_key, integer ai_index)`	Sposta un passaggio esistente; il passaggio in corso resta tale. Restituisce `0` una volta applicato, `-5` per una chiave vuota o che non designa alcun passaggio, `-2` se il componente non è creato
`of_next ( )`	Passa al passaggio successivo, saltando quelli nascosti e disattivati — proprio quelli su cui `ii_current + 1` atterrerebbe. Si ferma sull'ultimo raggiungibile. Il modo di navigazione non viene consultato: limita l'utente, non il suo codice. Nessuna domanda viene posta, ma `ue_step_changed` viene sollevato. Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_previous ( )`	Torna al passaggio precedente, stesse regole. Dalla posizione « tutto terminato » torna sull'ultimo passaggio. Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_remove_step (string as_key)`	Toglie un passaggio; gli altri conservano il proprio stato. Togliere il passaggio in corso porta al successivo raggiungibile (o a «tutto completato») e solleva `ue_step_changed`. Restituisce `0` una volta applicato, `-5` per una chiave vuota o che non designa alcun passaggio, `-2` se il componente non è creato
`of_clear_steps ( )`	Svuota la sequenza. La barra riparte dal primo passaggio: i passaggi aggiunti dopo formano un nuovo percorso. Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_step (string as_key)` → `n_pbt_stepbar_step`	Handle di un passaggio, per impostarne le proprietà
`of_reset ( )`	Svuota i passaggi e riporta tutte le proprietà ai valori predefiniti. Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_set_redraw (boolean)`	Raggruppa una raffica di modifiche in un solo rendering. Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_save_as_png (string)` · `of_save_as_jpg (string)`	Esporta il rendering come immagine. Restituisce `0` una volta scritta l'immagine, `-4` se la scrittura fallisce, `-2` se il componente non è creato

Il terzo argomento è l'icona, come ovunque nella libreria (of_add_item della listbar, of_add_panel della statusbar, of_add_tile della tilesbox). La seconda riga viene dopo.

Event #

Event	Attivato quando
`ue_step_clicked (integer ai_index, string as_key)`	L'utente ha cliccato un passo. La barra non si sposta: scrivete questo evento, fate i vostri controlli, poi impostate `ii_current` se accettate
`ue_step_changed (integer ai_from_index, string as_from_key, integer ai_index, string as_key)`	La barra si è spostata: `ii_current` è stato impostato su un altro passo, `of_next` / `of_previous` chiamato, il passo in corso tolto, oppure un passo aggiunto dopo «tutto terminato». Un clic non arriva mai qui
`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`)

La barra NON naviga da sola. Un clic riferisce (ue_step_clicked) e nient'altro: la barra resta dov'è. Siete voi a spostarla, impostando ii_current o chiamando of_next / of_previous — e quegli spostamenti si annunciano con ue_step_changed.

Questa divisione non è un vincolo, è il senso del componente: una barra di passi rispecchia un percorso che la vostra applicazione guida. Raggiungere il passo 3 di solito significa che un modulo era valido e che un record è stato salvato; nessun clic può deciderlo al vostro posto.

ue_step_clicked porta il passo mirato, ue_step_changed porta in più il passo lasciato — per identificatore funzionale quanto per rango. Questa coppia serve a registrare o salvare il passo che si lascia; la regola «indietro sì, saltare avanti no» si scrive con NAV_BACKWARD.

is_navigation_mode resta il filtro del clic: NAV_NONE non solleva più nulla, NAV_BACKWARD lascia cliccare soltanto i passi già percorsi. NAV_VISITED va oltre: ogni passaggio già raggiunto resta cliccabile, anche più avanti di quello in corso — l'utente tornato a correggere il passaggio 2 ritorna con un clic al passaggio 4 che aveva raggiunto, cosa che NAV_BACKWARD non permette mai. Un nuovo elenco di passaggi dimentica ciò che era stato raggiunto, e un passaggio inserito non è mai stato raggiunto.

Da tastiera #

La barra è un solo arresto di tabulazione: una volta raggiunta, si percorre interamente da tastiera.

Tasto	Effetto
Frecce	Spostano il fuoco da un passaggio all'altro, ciclando; i passaggi nascosti, disattivati o fuori portata (vedere `is_navigation_mode`) vengono saltati
Inizio / Fine	Primo / ultimo passaggio raggiungibile
Invio o Spazio	Riferisce un clic sul passaggio con il fuoco (`ue_step_clicked`) — la barra non si sposta per questo

Le frecce non selezionano, a differenza delle schede di un dockcontainer: spostano il fuoco. Invio o Spazio su un passaggio riferisce il clic (ue_step_clicked), come il mouse; è la sua applicazione a spostare la barra. Percorrere una barra di otto passaggi con la tastiera non deve inviare otto clic.

Ogni passaggio è un vero pulsante: porta la propria etichetta e il proprio stato nel nome pronunciato ("Account - completato"), il passaggio corrente è contrassegnato con aria-current="step", e un passaggio disattivato è un pulsante disattivato — non soltanto un testo in grigio. Il pallino numerato non viene letto ad alta voce: un numero d'ordine non insegna nulla.

Esempi #

Avanzare nella procedura guidata #

// I quattro passi della procedura guidata, in ordine
uo_steps.of_add_step(/*key*/ "account",   /*label*/ "Account")
uo_steps.of_add_step(/*key*/ "profile",   /*label*/ "Profilo")
uo_steps.of_add_step(/*key*/ "payment", /*label*/ "Pagamento")
uo_steps.of_add_step(/*key*/ "done",      /*label*/ "Conferma")

// I passaggi 1 e 2 passano automaticamente a "terminato" (spunta)
uo_steps.ii_current = 3

Segnalare un passaggio in errore #

// Lo stato di un passaggio si forza tramite il suo handle
uo_steps.of_step(/*key*/ "profile").is_state = n_pbt_stepbar_step.STATE_ERROR

// Una volta corretto il problema, si restituisce la mano al calcolo automatico
uo_steps.of_step(/*key*/ "profile").is_state = n_pbt_stepbar_step.STATE_AUTO

Passaggio saltato, passaggio da rivedere, tornare avanti #

// I quattro passi dell'ordine
uo_steps.of_add_step(/*key*/ "cart",    /*label*/ "Carrello")
uo_steps.of_add_step(/*key*/ "coupon",    /*label*/ "Coupon")
uo_steps.of_add_step(/*key*/ "delivery", /*label*/ "Consegna")
uo_steps.of_add_step(/*key*/ "payment",  /*label*/ "Pagamento")

// Il cliente non ha un codice promozionale : il passaggio e saltato, ne fatto ne da fare
uo_steps.of_step(/*key*/ "coupon").is_state = n_pbt_stepbar_step.STATE_SKIPPED

// Indirizzo non verificato : il passaggio e percorso, ma va rivisto
uo_steps.of_step(/*key*/ "delivery").is_state = n_pbt_stepbar_step.STATE_WARNING

// Ogni passaggio gia raggiunto resta cliccabile, anche piu avanti di quello in corso
uo_steps.is_navigation_mode = u_pbt_stepbar.NAV_VISITED

// La procedura ha raggiunto il passaggio 4, poi torna al carrello : i passaggi da 2 a 4 restano a un clic
uo_steps.ii_current = 4
uo_steps.ii_current = 1

Sequenza verticale #

// POSITION_START / POSITION_END : la sequenza si disegna verticalmente, ideale a lato di un modulo
uo_steps.is_position = uo_steps.POSITION_START

// Il TERZO argomento e l'icona : prende il posto del numero del passaggio
uo_steps.of_add_step(/*key*/ "account", /*label*/ "Account", /*icon_file*/ "mono:img\packimages.dll:svg/samples/folder-open")

Etichette arricchite su due righe #

// L'etichetta di un passaggio accetta il testo formattato con tag
uo_steps.of_add_step(/*key*/ "account",   /*label*/ "[b]Account[/b][br][size=9](accesso)")
uo_steps.of_add_step(/*key*/ "profile",   /*label*/ "[b]Profilo[/b][br][size=9](i suoi dati)")
uo_steps.of_add_step(/*key*/ "payment", /*label*/ "[b]Pagamento[/b][br][size=9](carta)")
uo_steps.of_add_step(/*key*/ "done",      /*label*/ "[accent][b]Terminato[/b][/accent]")

// L'utente e al passo 2 : il passo 1 appare completato
uo_steps.ii_current = 2

Navigazione al clic #

// event ue_step_clicked de uo_steps : (integer ai_index, string as_key)
// La barra NON si e spostata : qui si decide.
if ai_index > uo_steps.ii_current then
    MessageBox("Procedura guidata", "Completate il passo corrente prima di proseguire.")
    return
end if
uo_steps.ii_current = ai_index

Passaggio condizionale #

// Un cliente gia noto non ha un passaggio "Profilo" da compilare
uo_steps.of_step(/*key*/ "profile").ib_visible = false

Buone pratiche #

Date a ogni passo un identificatore funzionale stabile ("payment"): è quello che ricevete in ue_step_clicked e ue_step_changed, non un numero che si sposta al minimo inserimento.
Lasci che sia il componente a calcolare gli stati; forzi is_state solo per l'errore.
Il clic su un passaggio è un semplice segnale: sta a Lei autorizzare (o no) il salto, in particolare verso un passaggio non ancora raggiunto.
Racchiuda la dichiarazione dei passaggi tra of_set_redraw(false) / of_set_redraw(true) quando sono numerosi.
Chiami of_reset() prima di riutilizzare la stessa sequenza per un'altra procedura guidata.

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.