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_etapes.of_add_step(/*key*/ "compte",  /*libelle*/ "Compte")
uo_etapes.of_add_step(/*key*/ "profil",  /*libelle*/ "Profil")
uo_etapes.of_add_step(/*key*/ "paiement", /*libelle*/ "Paiement")
uo_etapes.of_add_step(/*key*/ "fin",     /*libelle*/ "Confirmation")

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

// Bouton Suivant de l'assistant
uo_etapes.ii_current = uo_etapes.ii_current + 1

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 :

Un quatrième état, error, ne s'obtient jamais automatiquement : vous le forcez sur une étape qui a échoué (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. C'est ce couple qui permet d'écrire « on peut revenir en arrière, mais pas sauter en avant » en une ligne.

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.

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. Atteindre une étape pose une question à votre application : parcourir une barre de huit étapes en enverrait huit, et un refus en cours de route laisserait le focus et l'étape courante désynchronisés.

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 #

uo_etapes.of_add_step(/*key*/ "compte",   /*libelle*/ "Compte")
uo_etapes.of_add_step(/*key*/ "profil",   /*libelle*/ "Profil")
uo_etapes.of_add_step(/*key*/ "paiement", /*libelle*/ "Paiement")
uo_etapes.of_add_step(/*key*/ "fin",      /*libelle*/ "Confirmation")

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

Signaler une étape en erreur #

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

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

Fil vertical #

// left / right : le fil se dessine verticalement, ideal en marge d'un formulaire
uo_etapes.is_position = uo_etapes.POSITION_START

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

Libellés enrichis sur deux lignes #

// Le libelle d'une etape accepte le balisage riche
uo_etapes.of_add_step("compte",   "[b]Compte[/b][br][size=9](connexion)")
uo_etapes.of_add_step("profil",   "[b]Profil[/b][br][size=9](vos informations)")
uo_etapes.of_add_step("paiement", "[b]Paiement[/b][br][size=9](carte)")
uo_etapes.of_add_step("fin",      "[accent][b]Termine[/b][/accent]")

uo_etapes.ii_current = 2

Navigation au clic #

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

Étape conditionnelle #

// Un client deja connu n'a pas d'etape "Profil" a remplir
uo_etapes.of_step("profil").ib_visible = false

Bonnes pratiques #

• Donnez à chaque étape un identifiant métier stable ("paiement") : 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