menubar — `u_pbt_menubar` #

← Komponentenreferenz · Inhalt des Leitfadens

Anwendungsmenüleiste: Menüs, Untermenüs, abhakbare Einträge, Trennlinien, Symbole und Tastenkürzel — alles von der Bibliothek gezeichnet, ohne Windows-Menü.

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

Auf einen Blick #

Userobject	`u_pbt_menubar`
Item-Klasse	`n_pbt_menubar_item` (ein Eintrag)
Dient zu	Ihrem Fenster die Menüleiste der Anwendung geben, im selben Thema wie alles andere
Prinzip	Sie deklarieren die Menüs, dann ihre Einträge; jeder Eintrag wird über seine Adresse `menu/id` wiedergefunden

Schnellstart #

// Open-Event des Fensters
uo_menus.of_add_menu(/*key*/ "file", /*text*/ "Datei")
uo_menus.of_add_item(/*keys*/ "file/open", /*text*/ "Oeffnen")
uo_menus.of_add_item(/*keys*/ "file/save", /*text*/ "Speichern")

// event ue_item_selected : (string as_keys)
choose case as_keys
	case "open"; of_ouvrir()
	case "save"; of_enregistrer()
end choose

Das Modell: drei Ebenen, ein Schlüssel je Ebene #

Eine Menüleiste hat drei Ebenen, und jede wird über ihren Schlüssel angesprochen:

Ebene	Hinzugefügt durch	Schlüssel
Das Menü der Leiste	`of_add_menu`	seine `id`
Der Eintrag eines Menüs	`of_add_item`	die Adresse `menu/id`
Der Untereintrag eines Eintrags	`of_add_item`	die Adresse `menu/eintrag/untereintrag` — drei Ebenen

Eine Eintrags-id ist nur innerhalb ihres Menüs eindeutig: deshalb verlangt of_item zwei. Zwei Menüs können also jeweils ihren eigenen Eintrag "open" haben, ohne sich zu stören.

Eine Trennlinie hat keinen Schlüssel: of_add_separator zeichnet dort einen Strich, wo Sie es aufrufen, und es gibt danach nichts zurückzulesen.

Eigenschaften #

Eigenschaft	Typ	Standard	Rolle
`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 Themas)
`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 erlaubt)
`is_super_tooltip_image`	string	`""`	Bild des erweiterten Tooltips

Eigenschaften eines Eintrags — `n_pbt_menubar_item` #

Über of_item(menu/id) erhalten:

Eigenschaft	Typ	Standard	Rolle
`is_text`	string	—	Ändert die Beschriftung des Eintrags, im laufenden Betrieb
`ib_enabled`	boolean	`true`	Eintrag aktiv; ein ausgegrauter Eintrag reagiert nicht mehr auf Klicks
`ib_visible`	boolean	`true`	Eintrag aus der Liste genommen, ohne entfernt zu werden — Untermenü und Tastenkürzel ruhen mit ihm; er behält seinen Schlüssel und kommt unverändert zurück
`is_shortcut`	string	`""`	Die angezeigte Tastenkombination rechts vom Eintrag (`Ctrl+S`) — und aktiv: sie löst `ue_item_selected` für diesen Eintrag aus, wo auch immer der Fokus liegt. In einem Menü lernt man die Kürzel einer Anwendung; eine angezeigte Taste, die nichts tut, lehrt das Falsche. Ein leerer Text nimmt beides zurück
`ib_checked`	boolean	`false`	Häkchen vor dem Eintrag — für eine Option, die an- und ausgeht
`is_tooltip`	string	`""`	Tooltip dieses Eintrags
`is_super_tooltip_title`	string	`""`	Titel seines erweiterten Tooltips
`is_super_tooltip_text`	string	`""`	Text seines erweiterten Tooltips (Rich-Markup erlaubt)
`is_super_tooltip_image`	string	`""`	Bild seines erweiterten Tooltips

Methoden #

Methode	Rolle
`of_add_menu (string as_key, string as_text)`	Fügt der Leiste ein Menü hinzu. Liefert `0` nach der Anwendung, `-2` wenn die Komponente nicht erzeugt ist
`of_add_item (string as_keys, string as_text)`	Fügt einem Menü einen Eintrag hinzu. Liefert `0` nach der Anwendung, `-5` bei einem ungültigen Argument (leerer Schlüssel, falsche Adresse), `-2` wenn die Komponente nicht erzeugt ist
`of_add_item (string as_keys, string as_text, string as_image, boolean ab_checked)`	Dasselbe, mit Symbol, Häkchen und Anfangszustand. Liefert `0` nach der Anwendung, `-5` bei einem ungültigen Argument (leerer Schlüssel, falsche Adresse), `-2` wenn die Komponente nicht erzeugt ist
`of_add_separator (string as_keys)`	Zeichnet eine Trennlinie am bisherigen Ende des Menüs. Liefert `0` nach der Anwendung, `-2` wenn die Komponente nicht erzeugt ist
`of_item (string as_keys)` → `n_pbt_menubar_item`	Handle eines Eintrags, um seine Eigenschaften zu setzen. `as_key` nimmt beide Schreibweisen: die nackte Blatt-Kennung und den vollständigen Pfad, dessen Schlüssel mit `/` verbunden sind — `of_item("file", "export/pdf")`. Den Pfad liefert `ue_item_selected` zurück: seine zwei Argumente gehen unverändert wieder hier hinein. Eine nackte Kennung ist nur innerhalb ihres Untermenüs eindeutig
`of_menu (string as_key)` → `n_pbt_menubar_menu`	Handle eines Menüs der obersten Ebene, um es umzubenennen oder auszugrauen. `of_add_menu` konnte das nur bei der Erstellung: Admin beim Abmelden auszugrauen hieß, die ganze Leiste neu aufzubauen; `ib_visible` nimmt es aus der Leiste, Einträge und Tastenkürzel ruhen mit ihm
`of_remove_item (string as_keys)` → `long`	Entfernt einen Eintrag; die anderen bleiben. `as_key` nimmt beide Schreibweisen von `of_item`: den vollen Pfad (`export/pdf`) oder die nackte id. Ohne sie gab es nur `of_clear`, das alles leert — das häufigste dynamische Menü überhaupt, eine Liste zuletzt geöffneter Dateien, hieß die ganze Leiste bei jedem Dokument neu aufzubauen. Liefert `0` nach der Anwendung, `-5` bei einem ungültigen Argument (leerer Schlüssel, falsche Adresse), `-2` wenn die Komponente nicht erzeugt ist
`of_remove_menu (string as_key)` → `long`	Entfernt ein Menü der obersten Ebene samt seinen Einträgen. Die Leiste wird neu gezeichnet und ihre Höhe neu gemeldet. Liefert `0` nach der Anwendung, `-2` wenn die Komponente nicht erzeugt ist
`of_clear ( )`	Leert die Leiste — Menüs und Einträge. Liefert `0` nach der Anwendung, `-2` wenn die Komponente nicht erzeugt ist
`of_reset ( )`	Leert die Leiste und setzt alle Eigenschaften auf ihren Standard zurück. 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

Events #

Event	Ausgelöst, wenn
`ue_menu_opening (string as_key)`	Wird in dem Moment ausgelöst, in dem ein Menü der obersten Ebene angeklickt wird, bevor sein Aufklappmenü gebaut ist. Das ist der Moment, seine Einträge rechtzeitig zu aktivieren, auszugrauen oder zu füllen — ohne ihn musste die ganze Leiste ständig mit dem Anwendungszustand mitgehalten werden, oder sie zeigte Einträge, die lügen
`ue_item_selected (string as_keys)`	Der Benutzer hat einen Eintrag gewählt. `as_key` ist ein Pfad, sobald der Eintrag verschachtelt ist — `export/pdf`, nicht `pdf`: das Blatt allein sagt nicht, aus welchem Untermenü es stammt, und zwei Untermenüs dürfen je ihr eigenes haben. Ein Eintrag der obersten Ebene behält seine nackte id. Derselbe Text lässt sich unverändert an `of_item` zurückgeben
`ue_auto_height (long al_height)`	Die Leiste meldet die Höhe, die sie braucht — verschieben Sie, was darunter liegt
`ue_ready ( )`	Die Komponente ist geladen; alles zuvor Gesendete wurde nachgeholt
`ue_runtime_missing ( )`	Die WebView2-Laufzeit fehlt: die Komponente bleibt leer
`ue_bg_color (long al_color)`	Die Komponente hat ihre Themenhintergrundfarbe berechnet; das Userobject hat sie bereits übernommen (`backcolor`)

Die Höhe wird nicht gesetzt, sie wird gemeldet. Eine Menüleiste scrollt nicht: eine feste Höhe kann nur Leerraum unter der Leiste oder abgeschnittene Menüs erzeugen. Sie passt sich also immer an, und ue_auto_height sagt Ihnen, um wie viel.

Über die Tastatur #

Taste	Wirkung
Alt	Gibt der Leiste den Fokus, wie in jeder Windows-Anwendung
Pfeiltasten	Durchlaufen die Menüs und ihre Einträge; rechts öffnet einen Untereintrag, links geht zurück
Eingabe oder Leertaste	Wählt den fokussierten Eintrag (`ue_item_selected`)
Esc	Schließt das offene Menü und gibt dann den Fokus zurück

Beispiele #

Eine vollständige Menüleiste #

uo_menus.of_set_redraw(false)

// Das Menue Datei, mit einem Symbol auf Oeffnen und einem Strich vor Beenden
uo_menus.of_add_menu(/*key*/ "file", /*text*/ "F")
uo_menus.of_add_item(/*keys*/ "file/open", /*text*/ "O", /*image*/ "mono:img\packimages.dll:svg/samples/folder-open", /*checked*/ false)
uo_menus.of_add_separator(/*keys*/ "file")
uo_menus.of_add_item(/*keys*/ "file/quit", /*text*/ "Q")

// Ein Untermenue: Exportieren, dann seine beiden Formate
uo_menus.of_add_item(/*keys*/ "file/export", /*text*/ "E")
uo_menus.of_add_item(/*keys*/ "file/export/csv", /*text*/ "CSV")
uo_menus.of_add_item(/*keys*/ "file/export/pdf", /*text*/ "PDF")

// Das Menue Ansicht: eine Option, die sich abhaken laesst
uo_menus.of_add_menu(/*key*/ "view", /*text*/ "V")
uo_menus.of_add_item(/*keys*/ "view/grid", /*text*/ "G", /*image*/ "", /*checked*/ true)

uo_menus.of_set_redraw(true)

Abhaken, entfernen, ausgrauen #

// Der Benutzer hat die Rasteranzeige umgeschaltet
uo_menus.of_item(/*keys*/ "view/grid").ib_checked = not uo_menus.of_item(/*keys*/ "view/grid").ib_checked

// Ein Eintrag, der keinen Sinn mehr hat, wird ausgegraut, nicht entfernt:
// der Benutzer muss sehen koennen, dass es ihn gibt
uo_menus.of_item(/*keys*/ "file/save").ib_enabled = false

Die Leiste neu aufbauen #

// Arbeitsbereich wechseln: leeren und neu aufbauen
// of_set_redraw vermeidet ein Neuzeichnen bei jeder Zeile
uo_menus.of_set_redraw(false)
uo_menus.of_clear()
uo_menus.of_add_menu(/*key*/ "tools", /*text*/ "T")
uo_menus.of_set_redraw(true)

Best Practices #

Geben Sie jedem Eintrag eine stabile fachliche id ("save"): die bekommen Sie in ue_item_selected, nicht eine Beschriftung, die sich mit der Sprache ändert.
Grauen Sie aus, statt zu entfernen: ein fehlender Eintrag lässt den Benutzer suchen, ein ausgegrauter sagt ihm, dass es ihn gibt und etwas fehlt.
Klammern Sie den Aufbau in of_set_redraw(false) / of_set_redraw(true): eine vollständige Leiste sind schnell dreißig Aufrufe.
Verschieben Sie im Event ue_auto_height, was unter der Leiste liegt — die Höhe hängt vom Thema und der Schriftgröße ab, sie ist nicht überall gleich.
Für die Beschriftungen nutzen Sie of_set_translation, wenn Ihre Anwendung mehrsprachig ist: siehe das Sprachkapitel.

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.