stepbar — u_pbt_stepbar #

← Référence des composants · Sommaire du guide

Fil d'étapes d'un assistant : les étapes franchies, celle en cours et celles à venir, en horizontal ou en vertical.

▶ Le voir en vrai — Application de démonstration, tuile Stepbar : l'aperçu, le code qui le produit et cette page, côte à côte.

En bref #

Démarrage rapide #

// event open de la fenetre
uo_steps.of_add_step(/*key*/ "account",  /*label*/ "Compte")
uo_steps.of_add_step(/*key*/ "profile",  /*label*/ "Profil")
uo_steps.of_add_step(/*key*/ "payment", /*label*/ "Paiement")
uo_steps.of_add_step(/*key*/ "done",     /*label*/ "Confirmation")

// Etape en cours (1 = la premiere)
uo_steps.ii_current = 1

// Bouton Suivant de l'assistant : l'etape suivante, en sautant les masquees et les desactivees
uo_steps.of_next()

// Bouton Precedent
uo_steps.of_previous()

Le modèle : une étape, trois états automatiques #

Une étape n'a pas d'état à gérer à la main. Il se déduit de sa position par rapport à ii_current :

Trois autres états ne s'obtiennent jamais automatiquement : vous les forcez sur une étape — error quand elle a échoué, warning quand elle est franchie mais qu'un point reste à revoir, skipped quand elle a été ignorée (voir plus bas).

Propriétés #

Propriétés d'une étape — n_pbt_stepbar_step #

Obtenues par of_step(id) :

Méthodes #

Le troisième argument est l'icône, comme partout ailleurs dans la bibliothèque (of_add_item du listbar, of_add_panel de la statusbar, of_add_tile du tilesbox). La seconde ligne vient après elle.

Événements #

La barre ne navigue pas toute seule. Un clic rapporte (ue_step_clicked) et rien d'autre : la barre reste où elle est. C'est vous qui la déplacez, en posant ii_current ou en appelant of_next / of_previous — et ces déplacements-là s'annoncent par ue_step_changed.

Ce partage n'est pas une contrainte, c'est le sens du composant : une barre d'étapes reflète un parcours que votre application pilote. Atteindre l'étape 3 veut dire qu'un formulaire était valide et qu'un enregistrement est parti ; aucun clic ne peut en décider à votre place.

ue_step_clicked porte l'étape visée, ue_step_changed porte en plus l'étape quittée — par identifiant métier autant que par rang. Ce couple sert à journaliser ou à enregistrer l'étape que l'on quitte ; la règle « on peut revenir en arrière, mais pas sauter en avant » s'écrit, elle, avec NAV_BACKWARD.

is_navigation_mode reste le filtre du clic : NAV_NONE ne lève plus rien du tout, NAV_BACKWARD ne laisse cliquer que les étapes déjà franchies. NAV_VISITED va plus loin : toute étape déjà atteinte reste cliquable, même en avant de l'étape en cours — l'utilisateur revenu corriger l'étape 2 retourne d'un clic à l'étape 4 qu'il avait atteinte, ce que NAV_BACKWARD ne permet jamais. Une nouvelle liste d'étapes oublie ce qui a été atteint, et une étape insérée n'a jamais été atteinte.

Au clavier #

La barre est un seul arrêt de tabulation : une fois atteinte, elle se parcourt entièrement au clavier.

Les flèches ne sélectionnent pas, à la différence des onglets d'un dockcontainer : elles déplacent le focus. Entrée ou Espace sur une étape rapporte le clic (ue_step_clicked), comme la souris ; c'est votre application qui déplace la barre. Parcourir une barre de huit étapes au clavier ne doit pas envoyer huit clics.

Chaque étape est un vrai bouton : elle porte son libellé et son état dans son nom parlé (« Compte - terminée »), l'étape courante est marquée aria-current="step", et une étape désactivée est un bouton désactivé — pas seulement un texte grisé. La pastille numérotée n'est pas lue à voix haute : un rang n'apprend rien.

Exemples #

Avancer dans l'assistant #

// Les quatre etapes de l'assistant, dans l'ordre
uo_steps.of_add_step(/*key*/ "account",   /*label*/ "Compte")
uo_steps.of_add_step(/*key*/ "profile",   /*label*/ "Profil")
uo_steps.of_add_step(/*key*/ "payment", /*label*/ "Paiement")
uo_steps.of_add_step(/*key*/ "done",      /*label*/ "Confirmation")

// Les etapes 1 et 2 passent automatiquement en "terminee" (coche)
uo_steps.ii_current = 3

Signaler une étape en erreur #

// L'etat d'une etape se force par son handle
uo_steps.of_step(/*key*/ "profile").is_state = n_pbt_stepbar_step.STATE_ERROR

// Une fois le probleme corrige, on rend la main au calcul automatique
uo_steps.of_step(/*key*/ "profile").is_state = n_pbt_stepbar_step.STATE_AUTO

Étape ignorée, étape à revoir, retour en avant #

// Les quatre etapes de la commande
uo_steps.of_add_step(/*key*/ "cart",    /*label*/ "Panier")
uo_steps.of_add_step(/*key*/ "coupon",    /*label*/ "Code promo")
uo_steps.of_add_step(/*key*/ "delivery", /*label*/ "Livraison")
uo_steps.of_add_step(/*key*/ "payment",  /*label*/ "Paiement")

// Le client n'a pas de code promo : l'etape est ignoree, ni faite ni a faire
uo_steps.of_step(/*key*/ "coupon").is_state = n_pbt_stepbar_step.STATE_SKIPPED

// Adresse non verifiee : l'etape est franchie, mais elle est a revoir
uo_steps.of_step(/*key*/ "delivery").is_state = n_pbt_stepbar_step.STATE_WARNING

// Toute etape deja atteinte reste cliquable, meme en avant de l'etape en cours
uo_steps.is_navigation_mode = u_pbt_stepbar.NAV_VISITED

// L'assistant a atteint l'etape 4 puis revient au panier : les etapes 2 a 4 restent a un clic
uo_steps.ii_current = 4
uo_steps.ii_current = 1

Fil vertical #

// POSITION_START / POSITION_END : le fil se dessine verticalement, ideal en marge d'un formulaire
uo_steps.is_position = uo_steps.POSITION_START

// Le TROISIEME argument est l'icone : elle prend la place du rang de l'etape
uo_steps.of_add_step(/*key*/ "account", /*label*/ "Compte", /*icon_file*/ "mono:img\packimages.dll:svg/samples/folder-open")

Libellés enrichis sur deux lignes #

// Le libelle d'une etape accepte le balisage riche
uo_steps.of_add_step(/*key*/ "account",   /*label*/ "[b]Compte[/b][br][size=9](connexion)")
uo_steps.of_add_step(/*key*/ "profile",   /*label*/ "[b]Profil[/b][br][size=9](vos informations)")
uo_steps.of_add_step(/*key*/ "payment", /*label*/ "[b]Paiement[/b][br][size=9](carte)")
uo_steps.of_add_step(/*key*/ "done",      /*label*/ "[accent][b]Termine[/b][/accent]")

// L'utilisateur est a l'etape 2 : l'etape 1 s'affiche terminee
uo_steps.ii_current = 2

Navigation au clic #

// event ue_step_clicked de uo_steps : (integer ai_index, string as_key)
// La barre n'a PAS bouge : c'est ici qu'on decide.
if ai_index > uo_steps.ii_current then
    MessageBox("Assistant", "Terminez l'etape en cours avant de continuer.")
    return
end if
uo_steps.ii_current = ai_index

Étape conditionnelle #

// Un client deja connu n'a pas d'etape "Profil" a remplir
uo_steps.of_step(/*key*/ "profile").ib_visible = false

Bonnes pratiques #

• Donnez à chaque étape un identifiant métier stable ("payment") : c'est lui que vous recevez dans ue_step_clicked, pas un numéro qui bouge à la moindre insertion.
• Laissez le composant calculer les états ; ne forcez is_state que pour l'erreur.
• Le clic sur une étape est un simple signal : c'est à vous d'autoriser (ou non) le saut, en particulier vers une étape non encore atteinte.
• Encadrez la déclaration des étapes par of_set_redraw(false) / of_set_redraw(true) quand elles sont nombreuses.
• Appelez of_reset() avant de réutiliser le même fil pour un autre assistant.

Hérité du socle commun #

Ces membres existent sur tous les composants visuels — ils ne sont pas propres à celui-ci. Ils sont détaillés une seule fois, dans les chapitres transverses ; cette table dit seulement où les lire.

Deux aides ne sont pas héritées : of_icon et of_escape_markup vivent sur n_pbt_utils. Déclarez-en une — n_pbt_utils lnv_utils, rien à créer — et appelez-les dessus.

← Référence des composants · Sommaire du guide