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 #

Avvio rapido #

// event open della finestra
uo_etapes.of_add_step(/*key*/ "compte",  /*etichetta*/ "Account")
uo_etapes.of_add_step(/*key*/ "profil",  /*etichetta*/ "Profilo")
uo_etapes.of_add_step(/*key*/ "paiement", /*etichetta*/ "Pagamento")
uo_etapes.of_add_step(/*key*/ "fin",     /*etichetta*/ "Conferma")

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

// Pulsante Avanti della procedura guidata
uo_etapes.ii_current = uo_etapes.ii_current + 1

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:

Un quarto stato, error, non si ottiene mai automaticamente: lo forza Lei su un passaggio che non è riuscito (vedere più avanti).

Proprietà #

Proprietà di un passaggio — n_pbt_stepbar_step #

Ottenute tramite of_step(id):

Metodi #

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 #

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 che permette di scrivere «indietro sì, saltare avanti no» in una riga.

is_navigation_mode resta il filtro del clic: NAV_NONE non solleva più nulla, NAV_BACKWARD lascia cliccare soltanto i passi già percorsi.

Da tastiera #

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

Le frecce non selezionano, a differenza delle schede di un dockcontainer. Raggiungere un passaggio pone una domanda alla sua applicazione: percorrere una barra di otto passaggi ne invierebbe otto, e un rifiuto a metà strada lascerebbe il fuoco e il passaggio corrente disallineati.

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 #

uo_etapes.of_add_step(/*key*/ "compte",   /*etichetta*/ "Account")
uo_etapes.of_add_step(/*key*/ "profil",   /*etichetta*/ "Profilo")
uo_etapes.of_add_step(/*key*/ "paiement", /*etichetta*/ "Pagamento")
uo_etapes.of_add_step(/*key*/ "fin",      /*etichetta*/ "Conferma")

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

Segnalare un passaggio in errore #

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

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

Sequenza verticale #

// left / right : la sequenza si disegna verticalmente, ideale a lato di un modulo
uo_etapes.is_position = uo_etapes.POSITION_START

// Il TERZO argomento e l'icona : prende il posto del numero del passaggio
uo_etapes.of_add_step(/*key*/ "compte", /*etichetta*/ "Account", /*icona*/ "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_etapes.of_add_step("compte",   "[b]Account[/b][br][size=9](accesso)")
uo_etapes.of_add_step("profil",   "[b]Profilo[/b][br][size=9](i suoi dati)")
uo_etapes.of_add_step("paiement", "[b]Pagamento[/b][br][size=9](carta)")
uo_etapes.of_add_step("fin",      "[accent][b]Terminato[/b][/accent]")

uo_etapes.ii_current = 2

Navigazione al clic #

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

Passaggio condizionale #

// Un cliente gia noto non ha un passaggio "Profilo" da compilare
uo_etapes.of_step("profil").ib_visible = false

Buone pratiche #

• Date a ogni passo un identificatore funzionale stabile ("paiement"): è 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.

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