stepbar — u_pbt_stepbar #

← Komponentenreferenz · Inhalt des Handbuchs

Schrittleiste eines Assistenten: die bereits durchlaufenen Schritte, der aktuelle und die noch bevorstehenden, waagerecht oder senkrecht.

▶ Live ansehen — Demoanwendung, Kachel Stepbar: die Vorschau, der zugehörige Code und diese Seite, nebeneinander.

Auf einen Blick #

Schnellstart #

// open-Event des Fensters
uo_steps.of_add_step(/*key*/ "account",  /*label*/ "Konto")
uo_steps.of_add_step(/*key*/ "profile",  /*label*/ "Profil")
uo_steps.of_add_step(/*key*/ "payment", /*label*/ "Zahlung")
uo_steps.of_add_step(/*key*/ "done",     /*label*/ "Bestätigung")

// Aktueller Schritt (1 = der erste)
uo_steps.ii_current = 1

// Schaltflaeche Weiter des Assistenten : der naechste Schritt, ausgeblendete und deaktivierte werden uebersprungen
uo_steps.of_next()

// Schaltflaeche Zurueck
uo_steps.of_previous()

Das Modell: ein Schritt, drei automatische Zustände #

Ein Schritt hat keinen Zustand, den Sie von Hand verwalten müssten. Er ergibt sich aus seiner Position relativ zu ii_current:

Drei weitere Zustände werden nie automatisch erreicht: Sie erzwingen sie für einen Schritt — error, wenn er fehlgeschlagen ist, warning, wenn er durchlaufen ist, aber noch etwas zu prüfen bleibt, skipped, wenn er übersprungen wurde (siehe weiter unten).

Eigenschaften #

Eigenschaften eines Schritts — n_pbt_stepbar_step #

Erhältlich über of_step(id):

Methoden #

Das dritte Argument ist das Symbol, wie überall sonst in der Bibliothek (of_add_item der Listbar, of_add_panel der Statusleiste, of_add_tile der Tilesbox). Die zweite Zeile folgt danach.

Events #

Die Leiste navigiert NICHT von selbst. Ein Klick meldet (ue_step_clicked) und sonst nichts: Die Leiste bleibt, wo sie ist. Sie selbst verschieben sie, indem Sie ii_current setzen oder of_next / of_previous aufrufen — und diese Bewegungen melden sich über ue_step_changed.

Diese Aufteilung ist keine Einschränkung, sie ist der Sinn der Komponente: Eine Schrittleiste spiegelt einen Ablauf wider, den Ihre Anwendung steuert. Schritt 3 zu erreichen bedeutet in der Regel, dass ein Formular gültig war und ein Datensatz gespeichert wurde — das kann kein Klick für Sie entscheiden.

ue_step_clicked trägt den angezielten Schritt, ue_step_changed zusätzlich den verlassenen — mit fachlichem Bezeichner ebenso wie mit Rang. Mit diesem Paar protokollieren oder speichern Sie den verlassenen Schritt; die Regel „zurück ja, vorwärts springen nein" schreibt sich mit NAV_BACKWARD.

is_navigation_mode bleibt der Filter für den Klick: NAV_NONE löst überhaupt nichts mehr aus, NAV_BACKWARD lässt nur die bereits abgeschlossenen Schritte anklicken. NAV_VISITED geht weiter: Jeder bereits erreichte Schritt bleibt anklickbar, auch vor dem aktuellen — wer zu Schritt 2 zurückgegangen ist, um etwas zu korrigieren, kehrt mit einem Klick zu dem bereits erreichten Schritt 4 zurück, was NAV_BACKWARD nie erlaubt. Eine neue Schrittliste vergisst, was erreicht wurde, und ein eingefügter Schritt wurde nie erreicht.

Über die Tastatur #

Die Leiste ist ein einziger Tabulatorstopp: einmal erreicht, lässt sie sich vollständig über die Tastatur durchlaufen.

Die Pfeile wählen nicht aus, anders als die Registerkarten eines dockcontainer: sie verschieben den Fokus. Eingabe oder Leertaste auf einem Schritt meldet den Klick (ue_step_clicked), wie die Maus; Ihre Anwendung verschiebt die Leiste. Eine Leiste mit acht Schritten per Tastatur zu durchlaufen darf keine acht Klicks senden.

Jeder Schritt ist eine echte Schaltfläche: sie trägt ihre Beschriftung und ihren Zustand in ihrem gesprochenen Namen („Konto - abgeschlossen"), der aktuelle Schritt ist mit aria-current="step" markiert, und ein deaktivierter Schritt ist eine deaktivierte Schaltfläche — nicht bloß ausgegrauter Text. Der nummerierte Punkt wird nicht vorgelesen: ein Rang lehrt nichts.

Beispiele #

Im Assistenten weitergehen #

// Die vier Schritte des Assistenten, der Reihe nach
uo_steps.of_add_step(/*key*/ "account",   /*label*/ "Konto")
uo_steps.of_add_step(/*key*/ "profile",   /*label*/ "Profil")
uo_steps.of_add_step(/*key*/ "payment", /*label*/ "Zahlung")
uo_steps.of_add_step(/*key*/ "done",      /*label*/ "Bestätigung")

// Die Schritte 1 und 2 wechseln automatisch auf "abgeschlossen" (Haken)
uo_steps.ii_current = 3

Einen Schritt als fehlerhaft kennzeichnen #

// Der Zustand eines Schritts wird ueber sein Handle erzwungen
uo_steps.of_step(/*key*/ "profile").is_state = n_pbt_stepbar_step.STATE_ERROR

// Sobald das Problem behoben ist, uebergibt man wieder an die automatische Berechnung
uo_steps.of_step(/*key*/ "profile").is_state = n_pbt_stepbar_step.STATE_AUTO

Übersprungener Schritt, zu prüfender Schritt, wieder vorwärts #

// Die vier Schritte der Bestellung
uo_steps.of_add_step(/*key*/ "cart",    /*label*/ "Warenkorb")
uo_steps.of_add_step(/*key*/ "coupon",    /*label*/ "Gutschein")
uo_steps.of_add_step(/*key*/ "delivery", /*label*/ "Lieferung")
uo_steps.of_add_step(/*key*/ "payment",  /*label*/ "Zahlung")

// Der Kunde hat keinen Gutscheincode : der Schritt wird uebersprungen, weder erledigt noch offen
uo_steps.of_step(/*key*/ "coupon").is_state = n_pbt_stepbar_step.STATE_SKIPPED

// Adresse nicht geprueft : der Schritt ist durchlaufen, aber zu pruefen
uo_steps.of_step(/*key*/ "delivery").is_state = n_pbt_stepbar_step.STATE_WARNING

// Jeder bereits erreichte Schritt bleibt anklickbar, auch vor dem aktuellen
uo_steps.is_navigation_mode = u_pbt_stepbar.NAV_VISITED

// Der Assistent hat Schritt 4 erreicht und geht zum Warenkorb zurueck : Schritte 2 bis 4 bleiben einen Klick entfernt
uo_steps.ii_current = 4
uo_steps.ii_current = 1

Senkrechte Leiste #

// POSITION_START / POSITION_END : die Leiste wird senkrecht gezeichnet, ideal am Rand eines Formulars
uo_steps.is_position = uo_steps.POSITION_START

// Das DRITTE Argument ist das Symbol : es tritt an die Stelle der Schrittnummer
uo_steps.of_add_step(/*key*/ "account", /*label*/ "Konto", /*icon_file*/ "mono:img\packimages.dll:svg/samples/folder-open")

Erweiterte Bezeichnungen auf zwei Zeilen #

// Die Bezeichnung eines Schritts nimmt Rich-Text-Auszeichnung an
uo_steps.of_add_step(/*key*/ "account",   /*label*/ "[b]Konto[/b][br][size=9](Anmeldung)")
uo_steps.of_add_step(/*key*/ "profile",   /*label*/ "[b]Profil[/b][br][size=9](Ihre Angaben)")
uo_steps.of_add_step(/*key*/ "payment", /*label*/ "[b]Zahlung[/b][br][size=9](Karte)")
uo_steps.of_add_step(/*key*/ "done",      /*label*/ "[accent][b]Fertig[/b][/accent]")

// Der Benutzer ist bei Schritt 2 : Schritt 1 erscheint als abgeschlossen
uo_steps.ii_current = 2

Navigation per Klick #

// event ue_step_clicked de uo_steps : (integer ai_index, string as_key)
// Die Leiste hat sich NICHT bewegt : hier wird entschieden.
if ai_index > uo_steps.ii_current then
    MessageBox("Assistent", "Schliessen Sie den aktuellen Schritt zuerst ab.")
    return
end if
uo_steps.ii_current = ai_index

Bedingter Schritt #

// Ein bereits bekannter Kunde hat keinen Schritt "Profil" auszufuellen
uo_steps.of_step(/*key*/ "profile").ib_visible = false

Best Practices #

• Geben Sie jedem Schritt einen stabilen fachlichen Bezeichner ("payment"): Genau diesen erhalten Sie in ue_step_clicked und ue_step_changed, nicht eine Nummer, die sich bei der geringsten Einfügung verschiebt.
• Lassen Sie die Komponente die Zustände berechnen; erzwingen Sie is_state nur für den Fehlerfall.
• Der Klick auf einen Schritt ist nur ein Signal: Sie entscheiden, ob Sie den Sprung erlauben oder nicht, insbesondere zu einem noch nicht erreichten Schritt.
• Klammern Sie die Deklaration der Schritte mit of_set_redraw(false) / of_set_redraw(true) ein, wenn es viele sind.
• Rufen Sie of_reset() auf, bevor Sie dieselbe Leiste für einen anderen Assistenten wiederverwenden.

Vom gemeinsamen Sockel geerbt #

Diese Mitglieder gibt es bei jeder visuellen Komponente — sie sind nicht dieser eigen. Sie werden einmal in den übergreifenden Kapiteln beschrieben; diese Tabelle sagt nur, wo man sie liest.

Zwei Helfer werden nicht geerbt: of_icon und of_escape_markup liegen auf n_pbt_utils. Deklarieren Sie eines — n_pbt_utils lnv_utils, nichts zu erzeugen — und rufen Sie sie darauf auf.

← Komponentenreferenz · Inhalt des Handbuchs