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_etapes.of_add_step(/*key*/ "compte",  /*bezeichnung*/ "Konto")
uo_etapes.of_add_step(/*key*/ "profil",  /*bezeichnung*/ "Profil")
uo_etapes.of_add_step(/*key*/ "paiement", /*bezeichnung*/ "Zahlung")
uo_etapes.of_add_step(/*key*/ "fin",     /*bezeichnung*/ "Bestätigung")

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

// Schaltflaeche Weiter des Assistenten
uo_etapes.ii_current = uo_etapes.ii_current + 1

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:

Ein vierter Zustand, error, wird nie automatisch erreicht: Sie erzwingen ihn für einen Schritt, der fehlgeschlagen ist (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. Genau dieses Paar erlaubt es, „zurück ja, vorwärts springen nein" in einer Zeile zu schreiben.

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.

Ü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. Einen Schritt zu erreichen stellt Ihrer Anwendung eine Frage: eine Leiste mit acht Schritten zu durchlaufen würde acht davon senden, und eine Ablehnung auf halbem Weg würde Fokus und aktuellen Schritt auseinanderlaufen lassen.

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 #

uo_etapes.of_add_step(/*key*/ "compte",   /*bezeichnung*/ "Konto")
uo_etapes.of_add_step(/*key*/ "profil",   /*bezeichnung*/ "Profil")
uo_etapes.of_add_step(/*key*/ "paiement", /*bezeichnung*/ "Zahlung")
uo_etapes.of_add_step(/*key*/ "fin",      /*bezeichnung*/ "Bestätigung")

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

Einen Schritt als fehlerhaft kennzeichnen #

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

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

Senkrechte Leiste #

// left / right : die Leiste wird senkrecht gezeichnet, ideal am Rand eines Formulars
uo_etapes.is_position = uo_etapes.POSITION_START

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

Erweiterte Bezeichnungen auf zwei Zeilen #

// Die Bezeichnung eines Schritts nimmt Rich-Text-Auszeichnung an
uo_etapes.of_add_step("compte",   "[b]Konto[/b][br][size=9](Anmeldung)")
uo_etapes.of_add_step("profil",   "[b]Profil[/b][br][size=9](Ihre Angaben)")
uo_etapes.of_add_step("paiement", "[b]Zahlung[/b][br][size=9](Karte)")
uo_etapes.of_add_step("fin",      "[accent][b]Fertig[/b][/accent]")

uo_etapes.ii_current = 2

Navigation per Klick #

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

Bedingter Schritt #

// Ein bereits bekannter Kunde hat keinen Schritt "Profil" auszufuellen
uo_etapes.of_step("profil").ib_visible = false

Best Practices #

• Geben Sie jedem Schritt einen stabilen fachlichen Bezeichner ("paiement"): 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