toolbar — `u_pbt_toolbar` #

← Komponentenreferenz · Inhalt des Handbuchs

Flache Symbolleiste: mehrere Leisten auf Bändern verteilt, Schaltflächen, Umschalter, Dropdown-Menüs, Eingabefelder, automatischer Überlauf und Verschieben am Griff.

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

Auf einen Blick #

Userobject	`u_pbt_toolbar`
Item-Klassen	`n_pbt_toolbar_bar` (Leiste) → `n_pbt_toolbar_item` (Werkzeug)
Wofür	Eine klassische Symbolleiste durch eine moderne, dem Design folgende Leiste mit mehreren umsortierbaren Zeilen ersetzen
Höhe	Intrinsisch: Die Leiste richtet sich immer nach ihren Zeilen, es ist nichts zu aktivieren — siehe Automatische Höhe

Schnellstart #

// open-Event des Fensters
n_pbt_toolbar_bar lnv_bar

// of_bar() liefert die Standardleiste, die immer vorhanden ist (id = MAIN_BAR)
lnv_bar = uo_toolbar.of_bar(uo_toolbar.MAIN_BAR)

lnv_bar.of_add_button(/*id*/ "save", /*text*/ "", /*bild*/ "mono:img\save.svg", /*tooltip*/ "Speichern")
lnv_bar.of_add_button(/*id*/ "find", /*text*/ "", /*bild*/ "mono:img\find.svg", /*tooltip*/ "Suchen")
lnv_bar.of_add_separator()
lnv_bar.of_add_button(/*id*/ "help", /*text*/ "Hilfe",  /*bild*/ "", /*tooltip*/ "Info")

// Event ue_clicked von uo_toolbar: (string as_bar, string as_id)
choose case as_bar + "/" + as_id
    case "main/save" ; of_enregistrer()
    case "main/find" ; of_rechercher()
    case "main/help" ; of_aide()
end choose

Das Modell: Leisten, Bänder, Werkzeuge #

Eine Symbolleiste enthält eine oder mehrere Leisten. Jede Leiste liegt auf einem Band (einer Zeile) und belegt eine Position in dieser Zeile: Zwei Leisten auf demselben Band teilen sich die Zeile, zwei Leisten auf verschiedenen Bändern stapeln sich — genau wie die klassischen Office-Symbolleisten.

Die Werkzeuge (Schaltflächen, Umschalter, Menüs, Felder) gehören zu einer Leiste. Ihr Bezeichner ist nur innerhalb ihrer Leiste eindeutig: Der Zugriff läuft daher immer über den vollständigen Pfad.

uo_toolbar.of_bar("main").of_item("save").ib_enabled = false

Auch die Hinzufügungen leben auf dem Handle des übergeordneten Elements: Sie fügen ein Werkzeug einer Leiste hinzu, nicht der Symbolleiste. Siehe Gemeinsame Basis · Die Items für das allgemeine Prinzip.

Eigenschaften #

Eigenschaft	Typ	Standard	Zweck
`is_theme_style`	string	`fluent`	Visueller Stil der Komponente (Konstanten `THEME_STYLE_*`)
`is_theme_mode`	string	`light`	Helle oder dunkle Variante (Konstanten `THEME_MODE_*`)
`il_theme_accent`	long	`-1`	Akzentfarbe dieser Komponente (`-1` = Akzent 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
`ib_reorderable`	boolean	`false`	Erlaubt dem Benutzer, die Leisten mit der Maus neu anzuordnen: die Verschiebegriffe erscheinen und eine Leiste kann in ein anderes Band gezogen werden. Standardmäßig aus — eine versehentlich zerlegte Symbolleiste ist ein Supportfall. Ihr Code ordnet sie ohnehin um (`of_set_layout`, `of_add_bar`): der Schalter beschränkt den Benutzer, nie die Anwendung

Konstante #

Konstante	Wert	Zweck
`MAIN_BAR`	`"main"`	Bezeichner der Standardleiste, immer verfügbar, ohne sie erst anlegen zu müssen

Methoden #

Methode	Zweck
`of_bar (string as_id)` → `n_pbt_toolbar_bar`	Liefert das Handle einer Leiste (wird beim ersten Zugriff erzeugt)
`of_add_bar (string as_bar)` → `n_pbt_toolbar_bar`	Fügt eine Leiste hinzu und liefert ihr Handle
`of_add_bar (string as_bar, integer ai_band, integer ai_index)` → `n_pbt_toolbar_bar`	Fügt eine Leiste an einem bestimmten Band und an einer bestimmten Position hinzu (beide ab 0 gezählt)
`of_remove_bar (string as_id)`	Entfernt eine Leiste samt ihren Werkzeugen. Die anderen behalten ihren aktiven Zustand, und die Bänder rücken hinter der ausscheidenden zusammen. Das ist nicht dasselbe wie Ausblenden (`ib_visible` auf ihrem Handle): Ausblenden behält sie im Modell, bereit, genau dorthin zurückzukehren, wo sie war; Entfernen vergisst sie
`of_get_layout ()`	Liest die aktuelle Anordnung als JSON zurück: welche Leiste auf welchem Band, an welcher Position, sichtbar oder nicht. Speichern und mit `of_set_layout` zurückgeben
`of_set_layout (string as_layout_json)`	Stellt eine zuvor über `ue_layout_changed` empfangene Leistenanordnung wieder her
`of_clear ( )`	Entfernt alle Leisten und alle Werkzeuge
`of_reset ( )`	Leert den Inhalt und setzt die Eigenschaften auf ihre Standardwerte zurück

Auf einer Leiste — `n_pbt_toolbar_bar` #

Mitglied	Typ	Standard	Zweck
`ii_band`	integer	`0`	Band (Zeile), das die Leiste trägt; `0` = erste Zeile
`ii_index`	integer	`0`	Position der Leiste innerhalb ihres Bands
`ib_visible`	boolean	`true`	Zeigt oder verbirgt eine Leiste. Eine verborgene Leiste behält ihr Band, ihren Rang und ihre Elemente: Beim erneuten Anzeigen steht sie wieder genau dort, wo sie war, ohne dass etwas neu aufgebaut wird — das ist der Unterschied zu `of_clear`, das sie verlieren würde
`of_item (string as_id)` → `n_pbt_toolbar_item`			Liefert das Handle eines Werkzeugs dieser Leiste
`of_add_button (as_id, as_text, as_image, as_tooltip)` → `n_pbt_toolbar_item`			Aktionsschaltfläche; der Klick löst `ue_clicked` aus
`of_add_toggle (as_id, as_text, as_image, as_tooltip)` → `n_pbt_toolbar_item`			Umschalter mit zwei Zuständen; der Klick löst `ue_toggled` aus
`of_add_dropdown (as_id, as_text, as_image, as_tooltip)` → `n_pbt_toolbar_item`			Schaltfläche mit Dropdown-Menü; eine Auswahl löst `ue_menu_selected` aus
`of_add_label (as_id, as_text)` → `n_pbt_toolbar_item`			Informative Beschriftung, nicht anklickbar
`of_add_textbox (as_id, as_text, ai_width, as_tooltip)` → `n_pbt_toolbar_item`			Eingabefeld; Eingabetaste oder Fokusverlust löst `ue_text_changed` aus. `ai_width` in Pixeln
`of_add_datepicker (as_id, as_date, as_tooltip)` → `n_pbt_toolbar_item`			Datumsauswahl; eine Auswahl löst `ue_date_changed` aus. Datumsangaben im Format `"jjjj-mm-tt"`
`of_add_separator ( )`			Senkrechter Trennstrich
`of_insert_button (as_id, as_text, as_image, as_tooltip, ai_index)` → `n_pbt_toolbar_item`			Schaltflaeche an der gewaehlten Position (erste = 0) statt am Ende
`of_move_item (string as_id, integer ai_index)`			Verschiebt ein Werkzeug an eine andere Position in dieser Leiste (erste = 0). Es behaelt seine Art, sein Menue und seinen aktuellen Zustand: das Werkzeug wechselt den Platz, es wird nicht neu gebaut. Gilt fuer jede Art, daher fuegen die `of_add_` ohne `of_insert_` ein, indem sie hinzufuegen und dann verschieben
`of_remove_item (string as_id)`			Entfernt ein Werkzeug aus dieser Leiste. Die Leiste bleibt, und alles andere darin ebenfalls, samt aktivem Zustand — nur das genannte Werkzeug geht. Um es kommen und gehen zu lassen, behält `ib_visible` auf seinem Handle es im Modell

Auf einem Werkzeug — `n_pbt_toolbar_item` #

Mitglied	Typ	Standard	Zweck
`ib_visible`	boolean	`true`	Zeigt oder verbirgt ein Element. Es behält seinen Rang in der Leiste: Beim erneuten Anzeigen steht es wieder genau dort, wo es war, nicht am Ende. Nicht zu verwechseln mit `ib_enabled`, das es ausgegraut an Ort und Stelle lässt — verbergen Sie, was nicht zutrifft, und grauen Sie aus, was vorübergehend nicht verfügbar ist
`ib_enabled`	boolean	`true`	Werkzeug aktiv oder ausgegraut
`ib_checked`	boolean	`false`	Zustand eines Umschalters (ohne Wirkung auf die anderen Typen)
`is_text`	string	`""`	Beschriftung, Rich-Text-Auszeichnung zulässig
`is_shortcut`	string	`""`	Tastenkombination (`"Ctrl+S"`), im Tooltip angezeigt und aktiv
`of_add_menu_item (as_id, as_label, as_image)`			Eintrag im Menü einer Dropdown-Schaltfläche
`of_add_menu_item (as_parent, as_id, as_label, as_image)`			Kaskadierender Eintrag, unter einem vorhandenen Eintrag einsortiert
`of_add_menu_separator (as_id)`			Trennstrich innerhalb des Menüs

Die Bilder akzeptieren alle von der Bibliothek erkannten Formen: Pfad, mono:, tint:, DLL-Ressource.

Events #

Event	Ausgelöst wenn
`ue_clicked (string as_bar, string as_id)`	Auf eine Schaltfläche wird geklickt (oder sie wird über ihre Tastenkombination ausgelöst)
`ue_toggled (string as_bar, string as_id, boolean ab_checked)`	Ein Umschalter wechselt den Zustand; `ab_checked` trägt den neuen Zustand
`ue_menu_selected (string as_bar, string as_dropdown, string as_id)`	Ein Eintrag eines Dropdown-Menüs wird gewählt
`ue_text_changed (string as_bar, string as_id, string as_text)`	Ein Eingabefeld wird bestätigt (Eingabetaste oder Fokusverlust)
`ue_date_changed (string as_bar, string as_id, string as_date)`	Ein Datum wird gewählt (`"jjjj-mm-tt"`)
`ue_bar_reordered (string as_id, integer ai_band, integer ai_index)`	Der Benutzer hat eine Leiste am Griff in ein anderes Band oder auf einen anderen Rang gezogen (erfordert `ib_reorderable`). Nennt welche Leiste sich bewegt hat und wohin, während `ue_layout_changed` die gesamte Anordnung trägt. Band und Rang beginnen bei 1
`ue_layout_changed (string as_layout_json)`	Die Anordnung hat sich geändert — der Benutzer hat eine Leiste am Griff gezogen, oder Ihr eigener Code hat eine verschoben oder verborgen. Trägt die gesamte Anordnung, nicht nur das Verschobene
`ue_auto_height (long al_height)`	Die ideale Höhe hat sich geändert und die Leiste hat sich daran angepasst — immer aktiv: Die Anzahl der Zeilen bestimmt die Höhe
`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 #

Vorab aktivierte Umschalter und ein ausgegrautes Werkzeug #

n_pbt_toolbar_bar lnv_bar
lnv_bar = uo_toolbar.of_bar(uo_toolbar.MAIN_BAR)

lnv_bar.of_add_toggle(/*id*/ "bold",   /*text*/ "", /*bild*/ "mono:img\bold.svg",   /*tooltip*/ "Fett")
lnv_bar.of_add_toggle(/*id*/ "italic", /*text*/ "", /*bild*/ "mono:img\italic.svg", /*tooltip*/ "Kursiv")
lnv_bar.of_add_separator()
lnv_bar.of_add_button(/*id*/ "undo",   /*text*/ "", /*bild*/ "mono:img\undo.svg",   /*tooltip*/ "Rueckgaengig")

// Jedes Werkzeug wird ueber sein Handle gesteuert, das man von SEINER Leiste erhaelt
lnv_bar.of_item("bold").ib_checked = true    // Umschalter von vornherein aktiviert
lnv_bar.of_item("undo").ib_enabled = false   // vorerst nichts rueckgaengig zu machen

// Event ue_toggled von uo_toolbar
if as_id = "bold" then of_appliquer_gras(ab_checked)

n_pbt_toolbar_bar  lnv_bar
n_pbt_toolbar_item lnv_menu

lnv_bar = uo_toolbar.of_bar(uo_toolbar.MAIN_BAR)

// Das Menue wird ueber das von of_add_dropdown gelieferte Handle gefuellt
lnv_menu = lnv_bar.of_add_dropdown(/*id*/ "export", /*text*/ "Exportieren", &
                                   /*bild*/ "mono:img\save.svg", /*tooltip*/ "Die Akte exportieren")
lnv_menu.of_add_menu_item(/*id*/ "exp_pdf", /*label*/ "PDF",  /*bild*/ "")
lnv_menu.of_add_menu_item(/*id*/ "exp_csv", /*label*/ "CSV",  /*bild*/ "")
lnv_menu.of_add_menu_separator(/*id*/ "sep1")

// Untermenue: Der uebergeordnete Eintrag wird als erstes Argument genannt
lnv_menu.of_add_menu_item(/*id*/ "exp_img", /*label*/ "Bild...", /*bild*/ "")
lnv_menu.of_add_menu_item(/*parent*/ "exp_img", /*id*/ "exp_png", /*label*/ "PNG", /*bild*/ "")
lnv_menu.of_add_menu_item(/*parent*/ "exp_img", /*id*/ "exp_jpg", /*label*/ "JPEG", /*bild*/ "")

// Event ue_menu_selected von uo_toolbar: (as_bar, as_dropdown, as_id)
if as_dropdown = "export" then of_exporter(as_id)

Suchfeld und Datumsauswahl #

n_pbt_toolbar_bar lnv_bar
lnv_bar = uo_toolbar.of_bar(uo_toolbar.MAIN_BAR)

lnv_bar.of_add_button(/*id*/ "save", /*text*/ "", /*bild*/ "mono:img\save.svg", /*tooltip*/ "Speichern")
lnv_bar.of_item("save").is_shortcut = "Ctrl+S"    // Tastenkombination aktiv und angezeigt
lnv_bar.of_add_separator()

// 160 px breit; die Eingabe wird bei der Bestaetigung gemeldet
lnv_bar.of_add_textbox(/*id*/ "search", /*text*/ "", /*breite*/ 160, /*tooltip*/ "Suchen (Eingabetaste zum Bestaetigen)")

lnv_bar.of_add_label(/*id*/ "lbl_due", /*text*/ "Fällig am:")
lnv_bar.of_add_datepicker(/*id*/ "due", /*datum*/ "2026-07-11", /*tooltip*/ "Faelligkeitsdatum")

// Event ue_text_changed von uo_toolbar
if as_id = "search" then of_filtrer(as_text)

// Event ue_date_changed von uo_toolbar: as_date im Format "jjjj-mm-tt"
if as_id = "due" then id_echeance = Date(as_date)

Zwei Leisten und eine gemerkte Anordnung #

Der Benutzer kann eine Leiste an ihrem Griff (links von der Leiste) fassen und auf ein anderes Band oder an eine andere Position verschieben. Bewahren Sie die Anordnung beim Schließen auf und stellen Sie sie beim Öffnen wieder her.

n_pbt_toolbar_bar lnv_std, lnv_fmt

lnv_std = uo_toolbar.of_bar(uo_toolbar.MAIN_BAR)
lnv_std.of_add_button(/*id*/ "new",  /*text*/ "Neu", /*bild*/ "", /*tooltip*/ "")
lnv_std.of_add_button(/*id*/ "open", /*text*/ "Öffnen",  /*bild*/ "", /*tooltip*/ "")

// Zweite Leiste, auf Band 1 (zweite Zeile) an erster Position abgelegt
lnv_fmt = uo_toolbar.of_add_bar(/*leiste*/ "format", /*band*/ 1, /*index*/ 0)
lnv_fmt.of_add_toggle(/*id*/ "bold", /*text*/ "F", /*bild*/ "", /*tooltip*/ "Fett")

// Eine Leiste laesst sich auch jederzeit ueber ihre Eigenschaften umsetzen
uo_toolbar.of_bar("format").ii_band  = 0
uo_toolbar.of_bar("format").ii_index = 1    // zweite Leiste der ersten Zeile

// Event ue_layout_changed von uo_toolbar: die gewaehlte Anordnung aufbewahren
is_disposition = as_layout_json

// Beim naechsten Oeffnen: wiederherstellen, was der Benutzer eingerichtet hatte
if is_disposition <> "" then uo_toolbar.of_set_layout(is_disposition)

Überlauf: „Weitere Werkzeuge“ #

Wenn die Breite nicht mehr ausreicht, werden die Werkzeuge, die nicht mehr hineinpassen, in ein Menü Weitere Werkzeuge eingeklappt, das durch einen Winkel am Ende der Leiste gekennzeichnet ist. Das geschieht automatisch, es ist nichts zu programmieren: Die eingeklappten Werkzeuge bleiben anklickbar und lösen dieselben Events aus. Ein eingeklapptes Feld — Textfeld oder Datumsauswahl — bleibt ein echtes Feld: Sie tippen darin, Sie wählen darin ein Datum, und das Event wird ausgelöst, als wäre das Werkzeug in der Leiste geblieben.

Automatische Höhe #

Es ist nichts zu aktivieren: Die Anzahl der Zeilen (of_set_layout) bestimmt die Höhe, die Leiste passt sich von selbst an und benachrichtigt Sie.

// Event ue_auto_height von uo_toolbar
uo_contenu.y      = uo_toolbar.y + al_height
uo_contenu.height = parent.workspaceheight() - uo_contenu.y

Siehe Gemeinsame Basis.

Best Practices #

Verwenden Sie MAIN_BAR, solange eine einzige Leiste genügt: Sie ist bereits vorhanden, ein Hinzufügen erübrigt sich.
Sprechen Sie ein Werkzeug immer über seinen Pfad an — of_bar(...).of_item(...) — und nie über den bloßen Bezeichner: Genau das macht Bezeichner von einer Leiste zur nächsten wiederverwendbar.
Gruppieren Sie verwandte Werkzeuge mit of_add_separator() statt mit zusätzlichen Leisten.
Füllen Sie bei Schaltflächen mit reinem Symbol stets den Tooltip aus: Er ist die einzige Beschriftung, die dem Benutzer zur Verfügung steht.
Wenn Sie den Benutzer die Leisten umsortieren lassen, merken Sie sich ue_layout_changed und spielen Sie of_set_layout beim Öffnen wieder ein, sonst ist die Mühe bei jedem Start verloren.
Rufen Sie of_reset() auf, bevor Sie die Symbolleiste für einen anderen Kontext vollständig neu aufbauen.
Wenn die Befehle für eine Leiste zu zahlreich werden, wechseln Sie zum ribbon, der nach Registerkarten und Gruppen gegliedert ist.