listbar — `u_pbt_listbar` #

← Komponentenreferenz · Inhalt des Handbuchs

Seitliche Navigationsleiste: einklappbare Abschnitte im Akkordeon-Stil, die Einträge mit Symbol enthalten, mit einem Akzentband auf dem aktuellen Eintrag und dem Einklappen zu einer Symbolleiste.

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

Auf einen Blick #

Userobject	`u_pbt_listbar`
Item-Klassen	`n_pbt_listbar_section` (Abschnitt) → `n_pbt_listbar_item` (Eintrag)
Wofür	Ein aus Schaltflächen zusammengebasteltes Seitenmenü durch eine strukturierte, gestaltete und einklappbare Navigation ersetzen
Opt-in-Optionen	`ib_auto_width`, `ib_reorderable`

Dies ist die einzige Komponente der Bibliothek, die ib_auto_width veröffentlicht: Ihre natürliche Breite hat tatsächlich eine Bedeutung, da die eingeklappte Leiste deutlich schmaler ist als die ausgeklappte Leiste. Der übliche Fall ist im Übrigen bereits abgedeckt, ohne dass etwas zu aktivieren wäre — ib_collapsed = true verkleinert die Leiste auf die Symbolleiste und gibt ihr die Breite beim Ausklappen zurück.

Schnellstart #

// open-Ereignis des Fensters

// Ein Abschnitt, dann seine Eintraege : jeder Eintrag wird ueber Abschnitt/Eintrag adressiert
uo_nav.of_add_section(/*key*/ "nav", /*text*/ "Navigation")
uo_nav.of_add_item(/*keys*/ "nav/home",   /*text*/ "Home",      /*image*/ "mono:img\home.svg")
uo_nav.of_add_item(/*keys*/ "nav/docs",   /*text*/ "Documents", /*image*/ "mono:img\doc.svg")
uo_nav.of_add_item(/*keys*/ "nav/search", /*text*/ "Search",    /*image*/ "mono:img\find.svg")

// Ein zweiter Abschnitt mit einem einzigen Eintrag
uo_nav.of_add_section(/*key*/ "settings", /*text*/ "Settings")
uo_nav.of_add_item(/*keys*/ "settings/prefs", /*text*/ "Preferences", /*image*/ "mono:img\gear.svg")

// Die Auswahl liegt auf dem EINTRAG, ueber seine Adresse : Abschnitt, dann Eintrag
uo_nav.of_select_item(/*keys*/ "nav/home")

// of_select_item loest ue_selection_changed aus, wie ein Klick : die erste Seite oeffnet sich dort

// Ereignis ue_selection_changed von uo_nav : (string as_from_keys, string as_keys)
choose case as_keys
    case "nav/home"       ; of_open_home()
    case "nav/docs"       ; of_open_documents()
    case "settings/prefs" ; of_open_preferences()
end choose

Zwei Ebenen, eine Adresse #

Ein Eintragsbezeichner ist nur innerhalb seines Abschnitts eindeutig: Ein Eintrag wird daher über seine Adresse benannt, Abschnitt und Eintrag durch / verbunden — "nav/docs". Die Komponente nimmt sie entgegen (of_item, of_select_item, of_remove_item…); ein Abschnitt wird allein über seinen Schlüssel benannt (of_section("nav")). Siehe Hierarchien.

// Ein Abschnitt ueber seinen Schluessel, ein Eintrag ueber seine Adresse
uo_nav.of_section(/*key*/ "nav").is_title = "Navigation"
uo_nav.of_item(/*keys*/ "nav/docs").is_text = "Documents"

Auch die Events tragen den vollständigen Pfad, und den verlassenen Eintrag dazu: ue_selection_changed(as_from_keys, as_keys).

Eigenschaften #

Eigenschaft	Typ	Standard	Zweck
`ib_collapsed`	boolean	`false`	`true` klappt die Leiste zu einer Symbolleiste ein: Abschnittstitel und Beschriftungen weichen einer dünnen Linie zwischen den Abschnitten, und alle Einträge bleiben sichtbar, auch die eines eingeklappten Abschnitts (das Einklappen kehrt beim Verlassen zurück). Ein Eintrag ohne Symbol zeigt seinen Anfangsbuchstaben, und jeder Eintrag nennt beim Überfahren seine Beschriftung
`ib_auto_width`	boolean	`false`	Opt-in: dasselbe für die Breite, auch im ausgeklappten Zustand (die Leiste richtet sich nach der längsten Beschriftung). Das Einklappen zur Symbolleiste schrumpft dagegen bereits von selbst; `ue_auto_width` folgt in beiden Fällen
`ib_reorderable`	boolean	`false`	Opt-in: Der Benutzer kann einen Eintrag mit der Maus verschieben. Die Bewegung bleibt innerhalb seines Abschnitts — eine Eintrags-Kennung ist nur dort eindeutig, ein Wechsel brächte also das Risiko zweier gleicher Schlüssel (löst `ue_item_reordered` aus)
`ib_veto_selection`	boolean	`false`	Opt-in: nachfragen, bevor sich die Auswahl verschiebt — eine Geste des Benutzers und `of_select_item` / `of_clear_selection` (löst `ue_selection_changing` aus, das ablehnen kann; ein abgelehnter Befehl liefert `-4`). Standardmäßig aus, wie jedes abbrechbare Ereignis der Bibliothek: Setzen Sie `true`, wenn Sie einen Wechsel ablehnen können müssen (nicht gespeicherte Eingaben). Jede Frage einer Geste kostet einen Hin- und Rückweg zu PowerBuilder (~35 ms)
`is_theme_style`	string	`""`	Visueller Stil der Komponente (Konstanten `THEME_STYLE_*`); leer = der der Anwendung, bei jeder Änderung übernommen
`is_theme_mode`	string	`""`	Helle oder dunkle Variante (Konstanten `THEME_MODE_*`); leer = die der Anwendung, bei jeder Änderung übernommen
`il_theme_accent`	long	`-1`	Akzentfarbe dieser Komponente (`-1` = Akzent der Anwendung, sonst der des Designs)
`is_tooltip`	string	`""`	Einfacher Tooltip beim Überfahren der Komponente
`is_super_tooltip_title`	string	`""`	Titel des erweiterten Tooltips (hat Vorrang vor `is_tooltip`)
`is_super_tooltip_text`	string	`""`	Text des erweiterten Tooltips (Rich-Markup zulässig)
`is_super_tooltip_image`	string	`""`	Bild des erweiterten Tooltips

Eigenschaften eines Abschnitts — `n_pbt_listbar_section` #

Eigenschaft	Typ	Standard	Zweck
`is_title`	string	`""`	Titel des Abschnitts. Akzeptiert die Rich-Text-Auszeichnung. Ein leerer Titel zeigt gar keine Kopfzeile an: Der Abschnitt wird zu einer einfachen, unsichtbaren Gruppierung; ein Abstand trennt ihn vom darüberliegenden Abschnitt (in der schmalen Leiste ein feiner Strich), und er lässt sich nicht mehr einklappen — niemand könnte ihn wieder öffnen
`ib_collapsed`	boolean	`false`	Akkordeon: `true` klappt die Einträge dieses Abschnitts ein. Die Kopfzeile bleibt sichtbar, ihr Chevron dreht sich; `ue_section_toggled` folgt, wie bei einem Klick auf die Kopfzeile
`ib_pinned`	boolean	`false`	`true` heftet den Abschnitt unten an die Leiste (Einstellungen, Hilfe): eine Fußzeile, die sichtbar bleibt, während der Rest der Leiste scrollt, bei genügend Platz ganz nach unten geschoben, und auch in der schmalen Leiste unten. Mehrere angeheftete Abschnitte stapeln sich in ihrer Reihenfolge. Nur die Darstellung ändert sich: Das Layout (`of_get_layout`) behält die Reihenfolge der Abschnitte, und die Pfeiltaste Unten führt vom letzten Eintrag oben zum ersten der Fußzeile
`is_image`	string	`""`	Symbol vor dem Abschnittstitel (akzeptierte Formen: Pfad, `mono:`, `tint:`, DLL-Ressource). Eine leere Zeichenkette entfernt es
`il_accent`	long	`-1`	Akzent dieses Abschnitts, also seines Titels und von nichts anderem: seine Einträge behalten ihren eigenen (`-1` = der der Komponente)
`il_back_color`	long	`-1`	Hintergrund des Abschnittstitels, als `RGB(r,g,b)` (`-1` = der der Komponente)
`il_text_color`	long	`-1`	Textfarbe des Abschnittstitels (`-1` = die der Komponente)
`il_back_color_hover`	long	`-1`	Hintergrund des Titels unter dem Zeiger (`-1` = der der Komponente)
`il_text_color_hover`	long	`-1`	Textfarbe des Titels unter dem Zeiger (`-1` = die der Komponente)

Eigenschaften eines Eintrags — `n_pbt_listbar_item` #

Eigenschaft	Typ	Standard	Zweck
`is_text`	string	`""`	Beschriftung des Eintrags, im laufenden Betrieb änderbar, ohne die Leiste neu aufzubauen. Akzeptiert die Rich-Text-Auszeichnung
`is_image`	string	`""`	Symbol, im laufenden Betrieb änderbar (akzeptierte Formen: Pfad, `mono:`, `tint:`, DLL-Ressource)
`ib_enabled`	boolean	`true`	`false` graut den Eintrag aus: Er bleibt an seinem Platz und reagiert auf nichts mehr — kein Klick, keine Eingabetaste, kein Rechtsklick, und die Pfeiltasten überspringen ihn
`ib_visible`	boolean	`true`	`false` blendet den Eintrag aus, ohne ihn aus der Leiste zu entfernen. Ein ausgeblendeter Eintrag kann nicht zur Auswahl werden (`of_select_item` liefert `-5`); den ausgewählten Eintrag auszublenden, lässt ihn ausgewählt, und beim erneuten Einblenden ist er wieder wie zuvor
`is_badge`	string	`""`	Zähler-Plakette am Ende des Eintrags (`"12"` ungelesen), in den Plakettenfarben des Themes; in der schmalen Leiste auf der Ecke des Symbols. Jeder kurze Text, Markup erlaubt. Eine leere Zeichenkette entfernt sie
`of_is_selected ( )` → `boolean`	—	—	Ist dieser Eintrag der ausgewählte? Nur lesend, und mit Absicht: die Auswahl ist ein Zustand der ganzen Leiste, kein Merker je Eintrag. Zum Setzen `of_select_item` auf der Komponente
`is_tooltip`	string	`""`	Einfacher Tooltip beim Überfahren des Items
`is_super_tooltip_title`	string	`""`	Titel des erweiterten Item-Tooltips (hat Vorrang vor `is_tooltip`)
`is_super_tooltip_text`	string	`""`	Text des erweiterten Item-Tooltips (Rich-Markup zulässig)
`is_super_tooltip_image`	string	`""`	Bild des erweiterten Item-Tooltips
`il_accent`	long	`-1`	Akzent dieses Eintrags: Der Balken, der ihn als ausgewählt markiert, übernimmt ihn (`-1` = der der Komponente). Für „diesen Eintrag in Rot“: `il_back_color` / `il_text_color`
`il_back_color`	long	`-1`	Eigener Hintergrund des Eintrags, als `RGB(r,g,b)` (`-1` = was das Design vorgibt)
`il_text_color`	long	`-1`	Textfarbe des Eintrags (`-1` = was das Design vorgibt)
`il_back_color_hover`	long	`-1`	Hintergrund des Eintrags unter dem Zeiger (`-1` = was das Design vorgibt)
`il_text_color_hover`	long	`-1`	Textfarbe des Eintrags unter dem Zeiger (`-1` = was das Design vorgibt)

Methoden #

Auf der Komponente #

Methode	Zweck
`of_add_section (string as_key, string as_text)`	Fügt am Ende der Leiste einen Abschnitt hinzu. Ein leerer Text zeichnet keine Titelzeile. Das Handle kommt von `of_section("nav")`, wenn Sie eine Eigenschaft setzen wollen. Gibt `0` zurück, sobald angewendet, `-5`, wenn der Schlüssel leer oder bereits vergeben ist oder `/` bzw. `	`enthält,` -2`, wenn die Komponente nicht erstellt ist
`of_insert_section (string as_key, string as_text, integer ai_index)`	Fügt einen Abschnitt an der gewünschten Position ein (erste Position = 1) statt am Ende. Der Index zählt Abschnitte, keine Zeilen. Ein bereits vergebener Name wird abgelehnt: Zwei Abschnitte unter demselben Namen würden die Adresse jedes ihrer Einträge mehrdeutig machen. Gibt `0` zurück, sobald angewendet, `-5`, wenn der Schlüssel leer oder bereits vergeben ist oder `/` bzw. `	`enthält,` -2`, wenn die Komponente nicht erstellt ist
`of_move_section (string as_key, integer ai_index)`	Verschiebt einen Abschnitt an Position `ai_index`, mitsamt seinen Einträgen. Nur die Kopfzeile zu verschieben würde seine Einträge in den Abschnitt fallen lassen, der dann über ihnen steht. Gibt `0` zurück, sobald angewendet, `-5` für einen Abschnitt, den diese Leiste nie hinzugefügt hat, `-2`, wenn die Komponente nicht erstellt ist
`of_remove_section (string as_key)`	Entfernt einen Abschnitt und alles, was er enthält. Ihn zu leeren und seine Einträge zu behalten, würde sie verwaisen lassen: Sie trügen einen Abschnittsbezeichner, der nichts mehr benennt. Lag die Auswahl darin, meldet `ue_selection_changed`, dass es keine mehr gibt. Gibt `0` zurück, sobald angewendet, `-5` für einen Abschnitt, den diese Leiste nie hinzugefügt hat, `-2`, wenn die Komponente nicht erstellt ist
`of_section (string as_key)`	Handle eines Abschnitts, über seinen Schlüssel: Titel, Symbol, Einklappen und Farben werden darüber gesetzt (beim ersten Zugriff erstellt). Ein Eintrag wird dagegen von der Komponente aus über seine Adresse erreicht (`of_item`)
`of_add_item (string as_keys, string as_text, string as_image)`	Fügt einen Eintrag an seiner Adresse hinzu, `"nav/home"`: der Abschnitt, in dem er landet, dann sein eigener Bezeichner. Eine Überladung lässt das Symbol weg. Gibt `0` zurück, sobald hinzugefügt, `-5`, wenn der Abschnitt nicht von dieser Leiste hinzugefügt wurde, die Adresse bereits vergeben ist oder der Schlüssel `	`enthält,` -2`, wenn die Komponente nicht erstellt ist
`of_item (string as_keys)`	Handle eines Eintrags, über seine Adresse (beim ersten Zugriff erstellt)
`of_insert_item (string as_keys, string as_text, integer ai_index)`	Fügt einen Eintrag an Position `ai_index` innerhalb seines Abschnitts ein (erste Position = 1). Gibt `0` zurück, sobald hinzugefügt, `-5`, wenn der Abschnitt nicht von dieser Leiste hinzugefügt wurde, die Adresse bereits vergeben ist oder der Schlüssel `	`enthält,` -2`, wenn die Komponente nicht erstellt ist
`of_insert_item (string as_keys, string as_text, string as_image, integer ai_index)`	Ebenso, mit dem Symbol des Eintrags: `of_add_item` nimmt eines, also muss Einfügen es auch können. Gibt `0` zurück, sobald hinzugefügt, `-5`, wenn der Abschnitt nicht von dieser Leiste hinzugefügt wurde, die Adresse bereits vergeben ist oder der Schlüssel `	`enthält,` -2`, wenn die Komponente nicht erstellt ist
`of_move_item (string as_keys, integer ai_index)`	Verschiebt einen vorhandenen Eintrag innerhalb seines Abschnitts und behält seinen Zustand bei. Gibt `0` zurück, sobald angewendet, `-5` für eine Adresse, die diese Leiste nie hinzugefügt hat, `-2`, wenn die Komponente nicht erstellt ist
`of_remove_item (string as_keys)`	Entfernt einen Eintrag, bezeichnet über seine Adresse. War er die Auswahl, meldet `ue_selection_changed`, dass es keine mehr gibt. Gibt `0` zurück, sobald angewendet, `-5` für eine Adresse, die diese Leiste nie hinzugefügt hat, `-2`, wenn die Komponente nicht erstellt ist
`of_clear ( )`	Leert die Leiste: alle Abschnitte und alle Einträge. War ein Eintrag ausgewählt, meldet `ue_selection_changed`, dass es keinen mehr gibt (leere Adresse); `ue_layout_changed` wird nicht ausgelöst, Sie bauen neu auf. Liefert `0` nach der Anwendung, `-2` wenn die Komponente nicht erzeugt ist
`of_select_item (string as_keys)`	Wählt einen Eintrag aus wie ein Klick darauf: bei aktivem `ib_veto_selection` wird zuerst `ue_selection_changing` gefragt; dann folgt `ue_selection_changed` wie bei einem Klick (direkt nach Ihrem Skript, aus der Ereigniswarteschlange), und `of_selected_key()` direkt danach gelesen liefert bereits die neue Adresse. Ist der Eintrag schon ausgewählt, wird nichts gefragt und nichts ausgelöst. Gibt `0` zurück, sobald ausgewählt (oder schon ausgewählt), `-4`, wenn Ihr `ue_selection_changing` abgelehnt hat (nichts bewegt sich), `-5` für eine Adresse, die diese Leiste nie hinzugefügt hat, einen ausgeblendeten Eintrag oder einen Eintrag, den die Demo-Obergrenze nicht zeichnet, `-2`, wenn die Komponente nicht erstellt ist
`of_get_layout ( )`	Liest die aktuelle Anordnung als JSON zurück: die Abschnitte in ihrer Reihenfolge, jeder mit seinen Einträgen in Reihenfolge und dem Zustand eingeklappt. Speichern (Datei, Datenbank, Registry) und beim nächsten Start mit `of_set_layout` zurückgeben. Dasselbe Paar trägt auf jeder umsortierbaren Komponente dieselben Namen
`of_set_layout (string as_layout_json)`	Stellt eine mit `of_get_layout` gelesene oder über `ue_layout_changed` empfangene Anordnung wieder her. Was die Anordnung nicht nennt, behält seinen Platz am Ende: Eine gestern gespeicherte Anordnung darf seither Hinzugefügtes nicht verschwinden lassen. Das Anwenden löst kein Event aus — Sie haben sie geliefert. Liefert `0` nach der Anwendung, `-5` bei einem leeren Text oder einen, der kein JSON-Objekt ist (eine abgeschnittene Datei): Es wird nichts gesendet; der Faltzustand eines nicht vorhandenen Abschnitts wird ignoriert, `-2` wenn die Komponente nicht erzeugt ist
`of_clear_selection ( )`	Lässt keinen Eintrag ausgewählt, wie jede Verschiebung: bei aktivem `ib_veto_selection` wird zuerst `ue_selection_changing` gefragt, dann folgt `ue_selection_changed` mit einer leeren Adresse. Ist schon nichts ausgewählt, wird nichts gefragt und nichts ausgelöst. Gibt `0` zurück, sobald angewendet, `-4`, wenn Ihr `ue_selection_changing` abgelehnt hat (der Eintrag bleibt ausgewählt), `-2`, wenn die Komponente nicht erstellt ist
`of_selected_key ( )`	Adresse des ausgewählten Eintrags — `"nav/docs"`, `""`, wenn keiner. Genau das, was Ihnen `ue_selection_changed` übergibt: ein Vergleich ist ein Vergleich, kein Zusammensetzen. Immer der aktuelle Eintrag, aus der Komponente gelesen: nach einem Klick, und auch direkt nach `of_select_item`
`of_reset ( )`	Leert die Leiste und versetzt die Komponente dann in ihren Neuzustand. War ein Eintrag ausgewählt, wird `ue_selection_changed` mit leerer Adresse ausgelöst; `ue_layout_changed` wird nicht ausgelöst. Liefert `0` nach der Anwendung, `-2` wenn die Komponente nicht erzeugt ist
`of_set_redraw (boolean)`	Fasst eine Folge von Änderungen zu einer einzigen Darstellung zusammen. Liefert `0` nach der Anwendung, `-2` wenn die Komponente nicht erzeugt ist
`of_save_as_png (string)` · `of_save_as_jpg (string)`	Exportiert die Darstellung als Bild. Liefert `0` nach dem Schreiben des Bildes, `-4` wenn das Schreiben fehlschlägt, `-2` wenn die Komponente nicht erzeugt ist

Auf einem Abschnitt — `n_pbt_listbar_section` #

Methode	Zweck
`of_count ( )`	Anzahl der Einträge des Abschnitts, ausgeblendete eingeschlossen
`of_keys_at (long al_index)`	Adresse des Eintrags an Position `al_index` (ab 1) — `"nav/docs"`, unverändert an `of_item` übergebbar
`of_has (string as_key)`	Enthält der Abschnitt diesen Eintrag?

Events #

Event	Ausgelöst wenn
`ue_selection_changed (string as_from_keys, string as_keys)`	Die Auswahl hat sich verschoben: Der Benutzer hat einen Eintrag gewählt (Klick, Eingabetaste, Leertaste), Ihr Code hat sie verschoben (`of_select_item`, `of_clear_selection` — ein Befehl löst es ebenfalls aus, wie SelectItem SelectionChanged auslöst), oder der ausgewählte Eintrag ist verschwunden (`of_remove_item`, `of_remove_section`, `of_clear`, `of_reset` — `as_keys` ist dann leer). Dieselben Argumente wie `ue_selection_changing`: Frage und Ergebnis lesen sich gleich, und das Paar `as_from_*` bezeichnet den verlassenen Eintrag (leer, wenn keiner)
`ue_section_toggled (string as_key, boolean ab_collapsed)`	Der Benutzer klappt einen Abschnitt ein oder aus: Klick auf den Titel, Eingabetaste auf dem Titel oder die Pfeiltasten Links / Rechts (von rechts nach links umgekehrt), oder Ihr Code, der `ib_collapsed` eines Abschnitts setzt
`ue_item_reordered (string as_keys, integer ai_index)`	Der Benutzer hat das Ziehen eines Eintrags beendet. `ai_index` ist sein neuer Rang innerhalb seines Abschnitts, ab 1, wie `of_move_item`. Bewahren Sie diese Reihenfolge auf, um dem Benutzer seine Leiste so zurückzugeben, wie er sie verlassen hat
`ue_layout_changed (string as_layout_json)`	Die zu speichernde Anordnung hat sich geändert: Ein Eintrag oder ein Abschnitt wurde verschoben, ein Abschnitt ein- oder ausgeklappt, etwas wurde entfernt — vom Benutzer oder von Ihrem Code. Trägt die gesamte Anordnung, nicht nur das Verschobene: Sie zu speichern ist eine Zuweisung. Hinzufügungen, die schmale Leiste, `of_set_layout`, `of_clear` und `of_reset` lösen es nicht aus: Das ist Aufbau, keine Anordnung
`ue_item_rclicked (string as_keys)`	Der Benutzer hat mit der rechten Maustaste auf einen Eintrag geklickt: seine Adresse, `"nav/docs"`. Ein Ereignis pro Rechtsklick, und der Eintrag wird nicht ausgewählt. Öffnen Sie dort Ihr eigenes Menü, am Mauszeiger: `m_menu.PopMenu(PointerX(), PointerY())`. Ein ausgegrauter Eintrag löst nichts aus
`ue_selection_changing (string as_from_keys, string as_keys)` → boolean	Abbrechbar, gestellt, bevor sich die Auswahl verschiebt — eine Geste des Benutzers, `of_select_item` oder `of_clear_selection` —, und nur wenn `ib_veto_selection = true` (standardmäßig aus). Geben Sie `false` zurück, um zu bleiben, wo Sie sind: nichts bewegt sich, und der Befehl Ihres Codes liefert `-4`
`ue_auto_width (long al_width)`	Die Komponente hat ihre ideale Breite neu berechnet — erfordert `ib_auto_width = true`
`ue_ready ( )`	Die Komponente ist fertig geladen; alles zuvor Gesendete wurde nachgespielt
`ue_runtime_missing ( )`	Die WebView2-Runtime fehlt: die Komponente bleibt leer
`ue_bg_color (long al_color)`	Die Komponente hat ihre Design-Hintergrundfarbe berechnet; das Userobject hat sie bereits übernommen (`backcolor`)

Beispiele #

Vollständiges Seitenmenü #

// Die ganze Leiste in einem einzigen Rendern
uo_nav.of_set_redraw(/*on*/ false)

// Erster Abschnitt und seine drei Eintraege
uo_nav.of_add_section(/*key*/ "folders", /*text*/ "Folders")
uo_nav.of_add_item(/*keys*/ "folders/recent",    /*text*/ "Recent",    /*image*/ "mono:img\clock.svg")
uo_nav.of_add_item(/*keys*/ "folders/customers", /*text*/ "Customers", /*image*/ "mono:img\user.svg")
uo_nav.of_add_item(/*keys*/ "folders/archives",  /*text*/ "Archives",  /*image*/ "mono:img\box.svg")

// Zweiter Abschnitt und seine zwei Eintraege
uo_nav.of_add_section(/*key*/ "tools", /*text*/ "Tools")
uo_nav.of_add_item(/*keys*/ "tools/import", /*text*/ "Import", /*image*/ "mono:img\import.svg")
uo_nav.of_add_item(/*keys*/ "tools/export", /*text*/ "Export", /*image*/ "mono:img\export.svg")

// Ein einziges Rendern fuer alles, dann wird der erste Eintrag ausgewaehlt
uo_nav.of_set_redraw(/*on*/ true)
uo_nav.of_select_item(/*keys*/ "folders/recent")

Einklappbare Leiste, die Platz freigibt #

// Zur Symbolleiste einklappen : die Leiste schrumpft von selbst (und nimmt ihre
// Breite wieder an, wenn Sie sie ausklappen).
uo_nav.ib_collapsed = true

// Ereignis ue_auto_width von uo_nav : (long al_width)
// Die Leiste hat gerade ihre ideale Breite angenommen : das Rechte daneben neu ausrichten.
uo_content.x     = uo_nav.x + al_width
uo_content.width = parent.width - uo_content.x

Akkordeon: einen Abschnitt einklappen #

// Den selten genutzten Archiv-Abschnitt einklappen
uo_nav.of_section(/*key*/ "folders").ib_collapsed = true

// Ereignis ue_section_toggled von uo_nav : (string as_key, boolean ab_collapsed)
// Das vom Benutzer gewaehlte Einklappen merken
of_save_preference("section_" + as_key, String(ab_collapsed))

Einstellungen und Hilfe unten angeheftet #

Ein Abschnitt ohne Titel, angeheftet: keine Kopfzeile, zwei Einträge, die am Fuß der Leiste bleiben, auch wenn die Navigation, länger als das Fenster, scrollt. Ein Klick dort wählt aus wie überall sonst: ue_selection_changed erhält foot/settings.

// Ein Abschnitt OHNE Titel (keine Kopfzeile), unten an die Leiste geheftet :
// er bleibt sichtbar, waehrend die Eintraege darueber scrollen
uo_nav.of_add_section(/*key*/ "foot", /*text*/ "")
uo_nav.of_add_item(/*keys*/ "foot/settings", /*text*/ "Settings", /*image*/ "mono:img\\gear.svg")
uo_nav.of_add_item(/*keys*/ "foot/help",     /*text*/ "Help",     /*image*/ "mono:img\\help.svg")
uo_nav.of_section(/*key*/ "foot").ib_pinned = true

// Ereignis ue_selection_changed von uo_nav : (string as_from_keys, string as_keys)
// Die Adresse traegt beide Ebenen : zwei Abschnitte koennen beide einen Eintrag "list" haben.
// Local variables
n_pbt_utils lnv_utils   // autoinstantiate : nichts zu erzeugen, nichts zu zerstoeren
string ls_keys[]

// Die Adresse zerlegen : [1] = der Abschnitt, [2] = der Eintrag
if lnv_utils.of_split_path(/*keys*/ as_keys, /*out*/ ls_keys) < 2 then return
choose case ls_keys[1]
    case "folders" ; of_open_folder(ls_keys[2])
    case "tools"   ; of_run_tool(ls_keys[2])
end choose

Einen Auswahlwechsel ablehnen #

// Die Frage ist STANDARDMAESSIG aus : einschalten, um einen Wechsel ablehnen zu koennen
uo_nav.ib_veto_selection = true

// Ereignis ue_selection_changing von uo_nav :
//   (string as_from_keys, string as_keys)
// FALSE zurueckgeben laesst den Benutzer auf dem verlassenen Eintrag.
if of_has_unsaved_changes(as_from_keys) then
    MessageBox("Eingabe", "Schliessen Sie den aktuellen Datensatz ab, bevor Sie wechseln.")
    return false
end if
return true

Einen Eintrag im laufenden Betrieb aktualisieren #

// Local variables
n_pbt_listbar_item lnv_entry

// Der Eintrag wird ueber seine Adresse benannt : Abschnitt, dann Eintrag
lnv_entry = uo_nav.of_item(/*keys*/ "folders/recent")
lnv_entry.is_text  = "Recent (12)"
lnv_entry.is_image = "mono:img\clock_full.svg"

// Je nach Rechten ausgrauen oder ausblenden, ohne die Leiste neu aufzubauen
uo_nav.of_item(/*keys*/ "tools/import").ib_enabled = of_is_allowed("import")
uo_nav.of_item(/*keys*/ "tools/export").ib_visible = gb_expert_mode

Auswahl aus dem Code gesteuert #

// Die Auswahl anderswo setzen : das Akzentband folgt, und
// ue_selection_changed geht wie bei einem Klick
uo_nav.of_select_item(/*keys*/ "folders/customers")

// Oder sie ganz entfernen
uo_nav.of_clear_selection()

Die Leiste neu aufbauen #

// of_clear leert Abschnitte und Eintraege ; of_reset stellt zusaetzlich die Standardwerte her
uo_nav.of_clear()
of_build_menu_for_profile()

Best Practices #

Ein Eintrag wird über seine Adresse hinzugefügt: of_add_item("nav/home", ...). Das Abschnitts-Handle dient nur noch dem Setzen einer Eigenschaft, und of_section("nav") liefert es beim ersten Zugriff.
Verwenden Sie mono: für die Symbole: Sie werden mit dem Design umgefärbt, hell wie dunkel, und bleiben lesbar, sobald die Leiste zur Symbolleiste eingeklappt ist.
Ein leerer Abschnittstitel dient als dezente Gruppierung: Die Einträge stehen weiter auseinander, ohne dass eine Kopfzeile erscheint. Ein solcher Abschnitt lässt sich nicht einklappen.
Mit der Tastatur: Die Pfeiltasten Oben / Unten durchlaufen Titel und Einträge, Links / Rechts klappen einen Abschnitt ein und aus (von rechts nach links umgekehrt), Eingabe oder Leertaste wählt, ein Buchstabe springt zur nächsten Zeile, die mit ihm beginnt.
ib_collapsed verkleinert das Userobject auf die Symbolleiste, verschiebt aber Ihre anderen Steuerelemente nicht: Behandeln Sie ue_auto_width, um den frei gewordenen Platz zu nutzen, sonst bleibt er leer.
Im Leistenmodus bleiben nur die Symbole übrig: Jeder Eintrag nennt beim Überfahren seine Beschriftung, und ein Eintrag ohne Symbol zeigt seinen Anfangsbuchstaben. Geben Sie trotzdem jedem ein Symbol — ein Anfangsbuchstabe ist schwer von einem anderen zu unterscheiden.
Die Frage wird nur gestellt, wenn Sie sie einschalten (ib_veto_selection = true): Tun Sie das nur dort, wo Sie einen Wechsel ablehnen können müssen, denn jede Frage kostet einen Hin- und Rückweg zu PowerBuilder. of_select_item stellt sie nie.
ib_enabled = false ist ib_visible = false vorzuziehen, wenn der Eintrag wieder verfügbar wird: Das Menü ändert dann nicht vor den Augen des Benutzers seine Form.

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.

Mitglieder	Rolle	Beschrieben in
`of_count` · `of_keys_at` · `of_has`	Durchlaufen, was die Komponente enthält	3.2 Die Items
`of_reset`	Die Komponente zurücksetzen	3.6 Eine Komponente zurücksetzen: `of_reset()`
`of_register_shortcut` · `of_clear_shortcuts`	Tastenkürzel der Komponente	3.5 Tastenkombinationen
`of_is_created` · `of_is_ready` · `of_get_last_error`	Ob sie entstanden ist, ob sie bereit ist, was fehlschlug	3.7 Diagnose
`of_save_as_png` · `of_save_as_jpg`	Die Darstellung als Bild exportieren	3.8 Die Darstellung als Bild exportieren
`of_set_redraw`	Änderungen zu einem einzigen Neuzeichnen bündeln	3.10 Best Practices
`of_preload_icons`	Symbole ohne Verzögerung	Sofortige Anzeige: `of_icon`
`of_set_translation`	Eine Beschriftung der Komponente übersetzen	5.2 Eine Beschriftung anpassen: `of_set_translation`
`of_focus_webview`	Der Komponente den Fokus geben	6.4 Tastatur und Fokus
`of_print` · `of_print_to_pdf`	Drucken oder ein PDF schreiben	6.9 Drucken
`of_set_property` · `of_get_property` · `of_component_name`	Eine Eigenschaft über ihren Namen steuern	3.1 Die Eigenschaften-Engine

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.