ribbon — `u_pbt_ribbon` #

← Komponentenreferenz · Inhalt des Handbuchs

Menüband im Office-Stil: Registerkarten, Gruppen, zwölf Typen von Rich-Steuerelementen, Anwendungsmenü, Symbolleiste für den Schnellzugriff, kontextbezogene Registerkarten mit Banner und Keytips.

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

Auf einen Blick #

Userobject	`u_pbt_ribbon`
Item-Klassen	`n_pbt_ribbon_tab` (Registerkarte), `n_pbt_ribbon_group` (Gruppe), `n_pbt_ribbon_item` (Steuerelement), `n_pbt_ribbon_menu_item` (Menüeintrag), `n_pbt_ribbon_ctx_group` (Gruppe kontextbezogener Registerkarten)
Wofür	Eine Menüleiste samt ihren Symbolleisten durch eine moderne, gut lesbare und klar gegliederte Befehlsoberfläche ersetzen
Höhe	Intrinsisch: Das Menüband richtet sich immer nach seinem Inhalt, es ist nichts zu aktivieren — siehe Automatische Höhe
Grenze im Demomodus	Höchstens 2 Registerkarten — siehe Der Demomodus

Die goldene Regel: Alles läuft über den Pfad #

Das Menüband ist eine vierstufige Hierarchie: Registerkarte → Gruppe → Steuerelement → Menüeintrag. Sie müssen keine globalen Bezeichner verwalten: Jedes Objekt wird über den Pfad erreicht, der zu ihm führt, und jede Hinzufügung erfolgt auf dem Handle des übergeordneten Elements.

// Ein Steuerelement lesen oder steuern : immer der vollstaendige Pfad
uo_ribbon.of_item(/*keys*/ "home/clipboard/paste").ib_enabled = false

Zwei praktische und angenehme Folgen: Zwei verschiedene Gruppen können denselben Bezeichner für ein Steuerelement verwenden, ohne sich in die Quere zu kommen, und die Events liefern Ihnen den vollständigen Pfad — Sie wissen immer, woher der Klick kommt.

Schnellstart #

// open-Event des Fensters

// Ein Register
uo_ribbon.of_add_tab(/*key*/ "home", /*title*/ "Start")

// Eine Gruppe: eine grosse Schaltflaeche und zwei kleine
uo_ribbon.of_add_group(/*keys*/ "home/clipboard", /*title*/ "Zwischenablage")
uo_ribbon.of_add_big_button(/*keys*/ "home/clipboard/paste", /*label*/ "Einfügen", /*image*/ "mono:img\paste.svg")
uo_ribbon.of_add_button(/*keys*/ "home/clipboard/cut", /*label*/ "Ausschneiden", /*image*/ "mono:img\cut.svg")
uo_ribbon.of_add_button(/*keys*/ "home/clipboard/copy", /*label*/ "Kopieren", /*image*/ "mono:img\copy.svg")

// Das Register anzeigen
uo_ribbon.of_select_tab(/*key*/ "home")

// Event ue_clicked von uo_ribbon : (string as_keys)
choose case as_keys
    case "home/clipboard/paste" ; of_paste()
    case "home/clipboard/cut" ; of_cut()
    case "home/clipboard/copy" ; of_copy()
end choose

Eigenschaften #

Eigenschaft	Typ	Standard	Zweck
`is_app_button`	string	`""`	Beschriftung der Anwendungsschaltfläche oben links, die das Anwendungsmenü öffnet. Eine Umbenennung behält ihr Menü; eine leere Zeichenkette entfernt die Schaltfläche samt Menü. Die Einträge des Anwendungsmenüs setzen die Schaltfläche voraus
`ib_minimized`	boolean	`false`	`true` klappt das Menüband auf seine bloßen Registerkartenköpfe ein; ein Klick auf eine Registerkarte klappt es vorübergehend auf. Vom Code gesetzt, löst es `ue_minimized` aus wie die Geste des Benutzers — nichts, wenn das Menüband schon in diesem Zustand ist; `ue_size_changed` meldet die neue Höhe
`ib_veto_gallery`	boolean	`false`	Nachfragen, bevor eine Galeriekachel übernommen wird — durch den Benutzer oder durch `of_select_gallery_item` (löst `ue_gallery_selection_changing` aus, das ablehnen kann; ein abgelehntes `of_select_gallery_item` liefert `-4`). Standardmäßig inaktiv, wie jedes abbrechbare Ereignis: Jede Frage kostet einen Hin- und Rückweg zu PowerBuilder (~35 ms). Auf `true` setzen, wenn Ihre Anwendung antwortet
`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

Konstante — ACCENT_LIGHT (-1): als Farbe einer kontextbezogenen Registerkarte oder Gruppe zu übergeben, damit sie dem aufgehellten Akzent des Designs folgt statt einer festen Farbe.

Eigenschaften einer Registerkarte — `n_pbt_ribbon_tab` #

Über of_tab("tab") erhalten, lassen sie sich im laufenden Betrieb ändern.

Eigenschaft	Typ	Standard	Zweck
`ib_visible`	boolean	`true`	`false` blendet die Registerkarte aus, ohne sie zu entfernen — genau das ist der Mechanismus der kontextbezogenen Registerkarten
`is_title`	string	`""`	Titel der Registerkarte. Von `of_add_tab` gesetzt; hier geschrieben ändert er sich, gelesen sagt er, was sie zeigt
`is_keytip`	string	`""`	Zugriffstaste, die nach Drücken von Alt angezeigt wird (`"S"` für Start). Ein Buchstabe oder mehrere (`"FP"`, wie in Office), nacheinander getippt; die Rücktaste nimmt den letzten zurück. Nur Buchstaben und Ziffern

Eigenschaften einer Gruppe — `n_pbt_ribbon_group` #

Über of_group("tab/group") erhalten.

Eigenschaft	Typ	Standard	Zweck
`ib_visible`	boolean	`true`	`false` blendet die Gruppe und alle ihre Steuerelemente aus
`is_title`	string	`""`	Beschriftung unter der Gruppe. Von `of_add_group` gesetzt; hier geschrieben ändert sie sich
`ib_launcher`	boolean	`false`	Zeigt den kleinen Pfeil unten rechts in der Gruppe — den Dialogfeld-Starter (löst `ue_launcher` aus). Der Pfeil sitzt in der Titelleiste der Gruppe, und eine Gruppe, die das Menüband aus Platzmangel einklappen musste, behält ihn an derselben Stelle — er wandert zusätzlich in das Panel, das die eingeklappte Gruppe öffnet.

Moduskonstanten der Farbauswahl: COLORMODE_PALETTE (Farbfeldpalette, Standardmodus) und COLORMODE_OPEN (vollständige Palette mit Bestätigung).

Eigenschaften eines Steuerelements — `n_pbt_ribbon_item` #

Über of_item("tab/group/control") erhalten. Sie gelten für alle Typen von Steuerelementen; Eigenschaften, die für einen bestimmten Typ ohne Belang sind, werden schlicht ignoriert.

Eigenschaft	Typ	Standard	Zweck
`is_label`	string	`""`	Beschriftung des Steuerelements. Zulässig ist Rich-Text-Auszeichnung
`is_image`	string	`""`	Bild des Steuerelements (Schaltfläche, große Schaltfläche, geteilte Schaltfläche, Dropdown-Schaltfläche, Kontrollkästchen, Farbauswahl, Schaltfläche der Symbolleiste für den Schnellzugriff), mit denselben Präfixen wie beim Hinzufügen (`mono:`, `tint:`). `""` entfernt es. Live gelesen
`ib_enabled`	boolean	`true`	`false` graut das Steuerelement aus und blockiert seine Auslösung
`ib_checked`	boolean	`false`	Gedrückter Zustand eines Umschalters oder angehakter Zustand eines Kontrollkästchens
`ib_visible`	boolean	`true`	`false` blendet das Steuerelement aus; die Nachbarn rücken zusammen
`is_text`	string	`""`	In einem Kombinationsfeld eingegebener oder ausgewählter Text
`id_value`	double	`0`	Zahlenwert eines Drehfelds
`id_min`	double	`0`	Nur Drehfeld: Untergrenze des Bereichs, jederzeit änderbar. Der Wert wird sofort und stillschweigend in den neuen Bereich zurückgeholt (kein `ue_value_changed`, wie bei `id_value` per Code). Bei jedem anderen Steuerelement ohne Wirkung und als `0` gelesen
`id_max`	double	`0`	Nur Drehfeld: Obergrenze des Bereichs, jederzeit änderbar; der Wert wird stillschweigend in den Bereich zurückgeholt, wie bei `id_min`. Bei jedem anderen Steuerelement ohne Wirkung und als `0` gelesen
`id_step`	double	`0`	Nur Drehfeld: Schrittweite der Pfeile und der Tasten Auf / Ab, jederzeit änderbar. Ein Schritt von `0` oder weniger wird ignoriert. Bei jedem anderen Steuerelement ohne Wirkung und als `0` gelesen
`il_color`	long	`-1`	Aktuelle Farbe einer Farbauswahl
`ii_visible_items`	integer	`3`	Nur Katalog: Anzahl der Kacheln, die der eingeklappte Streifen auf einmal zeigt. Die übrigen bleiben über die Pfeile erreichbar oder im ausgeklappten Raster
`is_keytip`	string	`""`	Zugriffstaste des Steuerelements, angezeigt nach Alt und dem Buchstaben der Registerkarte. Ein Buchstabe oder mehrere (`"FP"`, wie in Office), nacheinander getippt; die Rücktaste nimmt den letzten zurück. Nur Buchstaben und Ziffern. Ein Steuerelement einer eingeklappten Gruppe behält seine Taste: sie öffnet das Panel der Gruppe
`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

Eigenschaften eines Menüeintrags — `n_pbt_ribbon_menu_item` #

Über of_menu_item("tab/group/control/entry") erhalten.

Eigenschaft	Typ	Standard	Zweck
`is_image`	string	`""`	Bild des Menüeintrags. Eine leere Zeichenkette entfernt es
`of_is_separator ( )` → `boolean`	—	—	Ist der Eintrag eine Trennlinie? Nur lesend: was ein Eintrag ist, wurde beim Hinzufügen entschieden
`of_is_header ( )` → `boolean`	—	—	Ist der Eintrag eine nicht anklickbare Überschrift? Nur lesend, gleicher Grund
`of_is_checkable ( )` → `boolean`	—	—	Trägt der Eintrag ein Häkchen? Nur lesend; `ib_checked` sagt, ob es gesetzt ist
`ib_enabled`	boolean	`true`	`false` graut den Eintrag aus
`ib_visible`	boolean	`true`	`false` nimmt den Eintrag beim nächsten Öffnen aus dem Menü — Kaskade inbegriffen — ohne ihn zu entfernen
`ib_checked`	boolean	`false`	Haken eines mit `of_add_menu_check` erzeugten Eintrags

Eigenschaften eines Eintrags des Anwendungsmenüs — `n_pbt_ribbon_app_menu_item` #

Erhalten über of_app_menu_item("recent/a.txt"). Sie ändern sich im laufenden Betrieb: das Menü übernimmt sie beim nächsten Öffnen.

Eigenschaft	Typ	Standard	Zweck
`is_label`	string	`""`	Text des Eintrags
`is_image`	string	`""`	Bild des Eintrags. Eine leere Zeichenkette entfernt es
`ib_enabled`	boolean	`true`	`false` graut den Eintrag aus: angezeigt, nie gewählt — Speichern, solange nichts zu speichern ist
`ib_checked`	boolean	`false`	Häkchen vor dem Eintrag
`ib_visible`	boolean	`true`	`false` nimmt den Eintrag beim nächsten Öffnen aus dem Menü — samt Untermenü — ohne ihn zu entfernen
`of_is_separator ( )` → `boolean`	—	—	Ist der Eintrag eine Trennlinie? Nur lesbar
`of_keys_at (long al_index)` → `string`	—	—	Die Adresse des Eintrags an Position `ai_index` (ab 1) unter diesem — oder auf der ersten Ebene für `of_app_menu_item("")` —, `""` darüber hinaus: die Adresse, die `of_app_menu_item` und `of_remove_app_menu_item` erwarten

Die zwölf Typen von Steuerelementen #

Alle werden an der Adresse einer Gruppe — "home/clipboard" — hinzugefügt und liefern 0 (-5 bei einem ungültigen Argument, -2 wenn die Komponente nicht erzeugt ist); ein Menü oder eine Liste wird anschließend an der Adresse des Steuerelements gefüllt.

Methode der Gruppe	Erhaltenes Steuerelement	Event
`of_add_big_button (string as_keys, string as_label, string as_image)` → `long`	Große Schaltfläche über die volle Höhe, Symbol über der Beschriftung. Liefert `0` nach der Anwendung, `-5` bei einem ungültigen Argument (leerer Schlüssel, falsche Adresse), `-2` wenn die Komponente nicht erzeugt ist	`ue_clicked`
`of_add_big_split (string as_keys, string as_label, string as_image)` → `long`	Große geteilte Schaltfläche: Der obere Teil handelt, der Pfeil öffnet das Menü. Liefert `0` nach der Anwendung, `-5` bei einem ungültigen Argument (leerer Schlüssel, falsche Adresse), `-2` wenn die Komponente nicht erzeugt ist	`ue_clicked` · `ue_menu_selected`
`of_add_big_dropdown (string as_keys, string as_label, string as_image)` → `long`	Große Schaltfläche mit Dropdown-Menü. Liefert `0` nach der Anwendung, `-5` bei einem ungültigen Argument (leerer Schlüssel, falsche Adresse), `-2` wenn die Komponente nicht erzeugt ist	`ue_menu_selected`
`of_add_button (string as_keys, string as_label, string as_image)` → `long`	Kleine Schaltfläche (in Spalten zu dritt gestapelt). Liefert `0` nach der Anwendung, `-5` bei einem ungültigen Argument (leerer Schlüssel, falsche Adresse), `-2` wenn die Komponente nicht erzeugt ist	`ue_clicked`
`of_add_toggle (string as_keys, string as_label, string as_image)` → `long`	Kleiner Umschalter, der gedrückt bleibt. Liefert `0` nach der Anwendung, `-5` bei einem ungültigen Argument (leerer Schlüssel, falsche Adresse), `-2` wenn die Komponente nicht erzeugt ist	`ue_toggled`
`of_add_dropdown (string as_keys, string as_label, string as_image)` → `long`	Kleine Schaltfläche mit Dropdown-Menü. Liefert `0` nach der Anwendung, `-5` bei einem ungültigen Argument (leerer Schlüssel, falsche Adresse), `-2` wenn die Komponente nicht erzeugt ist	`ue_menu_selected`
`of_add_checkbox (string as_keys, string as_label)` → `long`	Kontrollkästchen. Liefert `0` nach der Anwendung, `-5` bei einem ungültigen Argument (leerer Schlüssel, falsche Adresse), `-2` wenn die Komponente nicht erzeugt ist	`ue_toggled`
`of_add_separator (string as_keys)` → `long`	Senkrechter Trennstrich zwischen zwei Blöcken von Steuerelementen. 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_combo (string as_keys, integer ai_width_px, boolean ab_editable)` → `long`	Kombinationsfeld, bearbeitbar oder nicht. Liefert `0` nach der Anwendung, `-5` bei einem ungültigen Argument (leerer Schlüssel, falsche Adresse), `-2` wenn die Komponente nicht erzeugt ist	`ue_combo_changed`
`of_add_spinner (string as_keys, integer ai_width_px, double ad_min, double ad_max, double ad_step, double ad_value)` → `long`	Numerisches Drehfeld mit Pfeilen. Liefert `0` nach der Anwendung, `-5` bei einem ungültigen Argument (leerer Schlüssel, falsche Adresse), `-2` wenn die Komponente nicht erzeugt ist	`ue_value_changed`
`of_add_colorpicker (string as_keys, string as_label, string as_image, long al_color)` → `long`	Geteilte Farbschaltfläche: Der Klick wendet erneut an, der Pfeil öffnet die Farbfeldpalette. Liefert `0` nach der Anwendung, `-5` bei einem ungültigen Argument (leerer Schlüssel, falsche Adresse), `-2` wenn die Komponente nicht erzeugt ist	`ue_clicked` · `ue_color_changed`
`of_add_gallery (string as_keys, integer ai_width_px, integer ai_tile_w, integer ai_tile_h)` → `long`	Scrollbares Band aus bebilderten Kacheln	`ue_gallery_selection_changed`

of_add_colorpicker nimmt ein fünftes Argument as_mode entgegen: COLORMODE_PALETTE (Farbfeldpalette) oder COLORMODE_OPEN (vollständige Palette mit den Schaltflächen OK und Abbrechen).

Methoden #

Das Menüband aufbauen #

Methode	Zweck
`of_add_tab (string as_key, string as_title)`	Fügt eine Registerkarte hinzu und liefert `0` (`-5` bei einem ungültigen Argument, `-2` wenn die Komponente nicht erzeugt ist): Gruppen werden anschließend an ihrer Adresse hinzugefügt
`of_insert_tab (string as_key, string as_title, integer ai_index)`	Fügt eine Registerkarte an der Position ein, die Sie wählen (`1` = ganz vorne), statt am Ende, und liefert `0` (`-5` bei einem ungültigen Argument, `-2` wenn die Komponente nicht erzeugt ist) wie `of_add_tab`. Eine bereits vergebene Id wird abgelehnt
`of_tab (string as_key)`	Handle einer vorhandenen Registerkarte (wird beim ersten Zugriff erzeugt)
`of_add_group (string as_keys, string as_title)`	Fügt einer Registerkarte — `"home/clipboard"` — eine betitelte Gruppe hinzu und liefert `0` (`-5` bei einem ungültigen Argument, `-2` wenn die Komponente nicht erzeugt ist)
`of_group (string as_keys)`	Handle einer vorhandenen Gruppe, über ihre Adresse
`of_item (string as_keys)`	Handle eines vorhandenen Steuerelements, über seine Adresse — `"home/clipboard/paste"`
`of_select_tab (string as_key)`	Aktiviert eine Registerkarte wie ein Klick darauf: `ue_selection_changed` folgt (direkt nach Ihrem Skript, aus der Ereigniswarteschlange; nichts, wenn die Registerkarte schon aktiv ist), und `of_selected_key` liest sie sofort zurück. Anders als ein Klick klappt sie ein eingeklapptes Menüband nicht auf. Liefert `0` nach der Anwendung, `-5` für eine unbekannte oder ausgeblendete Registerkarte, `-2` wenn die Komponente nicht erzeugt ist
`of_selected_key ( )`	Schlüssel der aktiven Registerkarte, `""`, wenn keine aktiv ist. Live aus der Komponente gelesen: schon in `ue_selection_changed` oder direkt nach `of_select_tab` nennt er die neue Registerkarte
`of_remove_group (string as_keys)`	Entfernt eine Gruppe und alle ihre Steuerelemente, über ihre Adresse; die Handles des Entfernten werden freigegeben. Liefert `0` nach der Anwendung, `-5` wenn unter dieser Adresse keine Gruppe liegt, `-2` wenn die Komponente nicht erzeugt ist
`of_remove_item (string as_keys)`	Entfernt ein Steuerelement über seine Adresse (`registerkarte/gruppe/steuerelement`) oder eine Schaltfläche der Symbolleiste für den Schnellzugriff allein über ihren Schlüssel; ihr Handle wird freigegeben. Liefert `0` nach der Anwendung, `-5` wenn unter dieser Adresse nichts dergleichen liegt, `-2` wenn die Komponente nicht erzeugt ist
`of_remove_tab (string as_key)`	Entfernt eine Registerkarte und ihren gesamten Inhalt; die Handles des Entfernten werden freigegeben. Liefert `0` nach der Anwendung, `-5` wenn keine Registerkarte diesen Schlüssel trägt, `-2` wenn die Komponente nicht erzeugt ist
`of_clear ( )`	Leert das Menüband vollständig: Registerkarten, Gruppen, Steuerelemente, Symbolleiste für den Schnellzugriff, Anwendungsmenü. Liefert `0` nach der Anwendung, `-2` wenn die Komponente nicht erzeugt ist

Menüs und Listen füllen #

Alle diese Methoden werden auf der Komponente aufgerufen, mit der Adresse des Steuerelements (Registerkarte/Gruppe/Steuerelement) — der Eintrag, die Auswahl oder die Kachel als vierte Ebene.

Methode	Zweck
`of_add_menu_item (string as_keys, string as_label, string as_image)`	Eintrag des Menüs einer Dropdown- oder geteilten Schaltfläche: `registerkarte/gruppe/steuerelement/eintrag`, eine Ebene mehr pro Kaskade. Liefert `0` nach der Anwendung, `-5` bei falscher Adresse, einem Elternteil, das weder Dropdown noch Eintrag ist, oder einen in diesem Menü bereits vergebenen Schlüssel, `-2` wenn die Komponente nicht erzeugt ist
`of_add_menu_check (string as_keys, string as_label)` · `(id, label, image)`	Anhakbarer Eintrag: Der Klick schaltet seinen Zustand um und meldet ihn in `ue_menu_selected`. 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_menu_header (string as_keys, string as_label)`	Nicht anklickbare Titelzeile, um ein langes Menü zu gliedern. 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_menu_separator (string as_keys)`	Trennstrich in einem Menü: `as_keys` nennt das Steuerelement für sein eigenes Menü oder einen Eintrag für die Kaskade darunter. 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_item (string as_keys)`	Entfernt einen Menüeintrag samt Kaskade (`registerkarte/gruppe/steuerelement/eintrag`, tiefer für einen kaskadierten Eintrag); seine Handles werden freigegeben. Liefert `0` nach der Anwendung, `-5` wenn unter dieser Adresse kein Eintrag liegt, `-2` wenn die Komponente nicht erzeugt ist
`of_clear_menu (string as_keys)`	Leert das Menü einer Dropdown- oder geteilten Schaltfläche (`registerkarte/gruppe/steuerelement`): eine Liste „Zuletzt verwendet“ wird Eintrag für Eintrag neu aufgebaut, ohne das Steuerelement neu anzulegen. Liefert `0` nach der Anwendung, `-5` wenn die Adresse weder ein Dropdown noch eine geteilte Schaltfläche ist, `-2` wenn die Komponente nicht erzeugt ist
`of_menu_item (string as_keys)`	Handle eines Menüeintrags, um ihn im laufenden Betrieb auszugrauen oder anzuhaken
`of_add_combo_item (string as_keys, string as_label)`	Fügt der Liste eines Kombinationsfelds eine Auswahl hinzu; eine Auswahl hat ihre Beschriftung als Schlüssel. Liefert `0` nach der Anwendung, `-5` wenn die Adresse kein Kombinationsfeld ist, oder bei einer Beschriftung, die schon in der Liste steht, leer ist oder `/` oder einen senkrechten Strich enthält, `-2` wenn die Komponente nicht erzeugt ist
`of_remove_combo_item (string as_keys)`	Entfernt eine Auswahl eines Kombinationsfelds: `registerkarte/gruppe/liste/beschriftung`. Liefert `0` nach der Anwendung, `-5` wenn das Feld diese Auswahl nicht hat, `-2` wenn die Komponente nicht erzeugt ist
`of_clear_combo (string as_keys)`	Leert die Liste eines Kombinationsfelds (`registerkarte/gruppe/liste`); sein Text bleibt. Liefert `0` nach der Anwendung, `-5` wenn die Adresse kein Kombinationsfeld ist, `-2` wenn die Komponente nicht erzeugt ist
`of_add_gallery_item (string as_keys, string as_image, string as_label)`	Fügt einem Katalog eine Kachel hinzu (`registerkarte/gruppe/katalog/kachel`); ihre Beschriftung ist auch ihr Name für eine Sprachausgabe. Liefert `0` nach der Anwendung, `-5` bei falscher Adresse, einer dritten Ebene, die kein Katalog ist, oder einer bereits vergebenen Kachel, `-2` wenn die Komponente nicht erzeugt ist
`of_remove_gallery_item (string as_keys)`	Entfernt eine Kachel eines Katalogs (`registerkarte/gruppe/katalog/kachel`). Geht die ausgewählte Kachel, ist nichts mehr ausgewählt. Liefert `0` nach der Anwendung, `-5` wenn es diese Kachel nicht gibt, `-2` wenn die Komponente nicht erzeugt ist
`of_select_gallery_item (string as_keys)`	Wählt eine Katalogkachel per Programm aus, über ihre vierstufige Adresse, wie eine Auswahl: bei aktivem `ib_veto_gallery` wird zuerst `ue_gallery_selection_changing` gefragt; dann folgt `ue_gallery_selection_changed`. Ist die Kachel schon ausgewählt, wird nichts gefragt und nichts ausgelöst. Liefert `0` nach der Anwendung (oder wenn schon ausgewählt), `-4` wenn Ihr `ue_gallery_selection_changing` abgelehnt hat (die Kachel bleibt), `-5` für eine andere Tiefe oder eine Kachel, die `of_add_gallery_item` nie hinzugefügt hat, `-2` wenn die Komponente nicht erzeugt ist
`of_open (string as_keys)`	Öffnet per Programm das Menü, die Liste oder die Farbpalette des Steuerelements an dieser Adresse (`registerkarte/gruppe/steuerelement`); die Adresse einer Gruppe (`registerkarte/gruppe`) öffnet ihr Panel, wenn ein zu schmales Fenster sie eingeklappt hat. Liefert `0` nach der Anwendung, `-5` für eine Adresse, die weder ein Steuerelement noch eine Gruppe nennt (eine Schaltfläche der Symbolleiste für den Schnellzugriff hat kein Menü), `-2` wenn die Komponente nicht erzeugt ist

Anwendungsmenü und Symbolleiste für den Schnellzugriff #

Methode	Zweck
`of_add_app_menu_item (string as_keys, string as_label, string as_image)`	Eintrag des Anwendungsmenüs (jenes, das die Schaltfläche `is_app_button` öffnet), über seine Adresse: `recent` an der Wurzel, `recent/a.txt` im Untermenü von `recent`. Liefert `0` nach der Anwendung, `-5` bei einen ungültigen Schlüssel (leer, `/` oder senkrechter Strich in einer Ebene, beginnend mit `__`), einem bereits vergebenen Schlüssel, einem unbekannten Elterneintrag oder ohne Anwendungsschaltfläche, `-2` wenn die Komponente nicht erzeugt ist
`of_add_app_menu_separator (string as_keys)`	Trennlinie im Anwendungsmenü. `as_keys` ist ihre Adresse, wie die eines Eintrags: `s1` an der Wurzel, `saveas/s1` im Untermenü von `saveas`; eine leere Adresse erhält einen eigenen Schlüssel. Liefert `0` nach der Anwendung, `-5` bei einem bereits vergebenen Schlüssel, einem unbekannten Elterneintrag oder ohne Anwendungsschaltfläche, `-2` wenn die Komponente nicht erzeugt ist
`of_remove_app_menu_item (string as_keys)`	Entfernt einen Eintrag (oder eine Trennlinie) des Anwendungsmenüs über seine Adresse, samt Untermenü; seine Handles werden freigegeben. Liefert `0` nach der Anwendung, `-5` wenn es diesen Eintrag nicht gibt, `-2` wenn die Komponente nicht erzeugt ist
`of_app_menu_item (string as_keys)`	Handle eines Eintrags des Anwendungsmenüs (`save`, `recent/a.txt`), um ihn im laufenden Betrieb auszugrauen, abzuhaken, auszublenden oder umzubenennen — siehe unten. `of_app_menu_item("")` steht für das Menü selbst: `of_count` und `of_keys_at` durchlaufen seine erste Ebene
`of_add_qat (string as_key, string as_image, string as_tooltip)`	Schaltfläche der Symbolleiste für den Schnellzugriff, über den Registerkarten; ihr Tooltip ist auch ihr Name für eine Sprachausgabe. Liefert `0` nach der Anwendung, `-5` bei einen ungültigen Schlüssel (leer, `/` oder senkrechter Strich in einer Ebene, beginnend mit `__`) oder einem Schlüssel, der schon in der Leiste steht, `-2` wenn die Komponente nicht erzeugt ist
`of_qat_item (string as_key)`	Handle einer Schnellzugriffsschaltfläche, um sie im laufenden Betrieb auszugrauen oder auszublenden

Kontextbezogene Registerkarten #

Methode	Zweck
`of_add_contextual_tab (string as_key, string as_title, long al_color)`	Einzelne kontextbezogene Registerkarte: ausgeblendet angelegt, mit einem farbigen Streifen markiert. Übergeben Sie `ACCENT_LIGHT`, um dem Akzent des Designs zu folgen. Liefert `0` nach der Anwendung, `-5` bei einen ungültigen Schlüssel (leer, `/` oder senkrechter Strich in einer Ebene, beginnend mit `__`) oder einem bereits vergebenen Schlüssel, `-2` wenn die Komponente nicht erzeugt ist
`of_add_contextual_group (string as_key, string as_title)` · `(id, title, al_color)`	Gruppe kontextbezogener Registerkarten: ein farbiges Band mit Titel krönt ihre Registerkarten. Liefert `0` nach der Anwendung, `-5` bei einen ungültigen Schlüssel (leer, `/` oder senkrechter Strich in einer Ebene, beginnend mit `__`) oder einem bereits vergebenen Schlüssel (ihre Farbe ändert sich über `of_ctx_group(schlüssel).il_color`), `-2` wenn die Komponente nicht erzeugt ist
`of_ctx_group (string as_key)`	Findet das Handle einer bereits erzeugten kontextbezogenen Gruppe über ihren Schlüssel — an ihm werden ihre Eigenschaften gesetzt
`of_remove_contextual_group (string as_key)`	Entfernt eine Gruppe kontextbezogener Registerkarten und die Registerkarten, die sie krönt — sie gehören zu ihr; ihre Handles werden freigegeben. Liefert `0` nach der Anwendung, `-5` wenn `of_add_contextual_group` diese Gruppe nie angelegt hat, `-2` wenn die Komponente nicht erzeugt ist
`of_add_contextual_tab (string as_key, string as_title, string as_group_key)`	Fügt eine Registerkarte unter einer kontextbezogenen Gruppe hinzu: ausgeblendet angelegt, vom farbigen Band der Gruppe gekrönt. Liefert `0` nach der Anwendung, `-5` bei einem ungültigen oder bereits vergebenen Schlüssel oder einer Gruppe, die `of_add_contextual_group` nie angelegt hat, `-2` wenn die Komponente nicht erzeugt ist
`il_color` (Eigenschaft)	Auf einem Handle einer kontextbezogenen Gruppe: färbt das Banner im laufenden Betrieb um (`ACCENT_LIGHT`, um zum Akzent zurückzukehren)

Gemeinsame #

Methode	Zweck
`of_reset ( )`	Leert das Menüband und bringt es in seinen fabrikneuen Zustand zurück, Eigenschaften eingeschlossen. Liefert `0` nach der Anwendung, `-2` wenn die Komponente nicht erzeugt ist
`of_set_redraw (boolean)`	Fasst eine Salve von Änderungen zu einer einzigen Darstellung zusammen. Liefert `0` nach der Anwendung, `-2` wenn die Komponente nicht erzeugt ist
`of_preload_icons (string as_icons[])`	Wärmt beim Start einen Satz Symbole vor: Eine später geöffnete Registerkarte zeigt die ihren sofort an. 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 #

Alle Events der Steuerelemente tragen den vollständigen Pfad: Sie brauchen nie einen anwendungsweit eindeutigen Bezeichner.

Event	Ausgelöst wenn
`ue_clicked (string as_keys)`	Der Benutzer klickt eine Schaltfläche, eine große Schaltfläche, den Hauptteil einer geteilten Schaltfläche oder eine Schaltfläche der Symbolleiste für den Schnellzugriff — im Menüband, im Panel einer eingeklappten Gruppe oder über ihre Zugriffstaste. `as_keys` ist die Adresse `registerkarte/gruppe/steuerelement` oder allein der Schlüssel einer Schnellzugriffsschaltfläche
`ue_toggled (string as_keys, boolean ab_checked)`	Der Benutzer schaltet eine Umschaltfläche oder ein Kontrollkästchen um (im Menüband oder im Panel einer eingeklappten Gruppe); `ab_checked` trägt den neuen Zustand. `ib_checked` per Code zu schreiben löst nichts aus
`ue_menu_selected (string as_keys, boolean ab_checked)`	Der Benutzer wählt einen Eintrag im Menü einer Dropdown- oder geteilten Schaltfläche. `as_keys` ist seine vollständige Adresse: Registerkarte, Gruppe, tragendes Steuerelement, dann der Eintrag — eine Ebene mehr pro Kaskade. Ein abhakbarer Eintrag schaltet zuerst um, und `ab_checked` trägt seinen neuen Zustand. Ein ausgegrauter oder ausgeblendeter Eintrag lässt sich nicht wählen
`ue_combo_changed (string as_keys, string as_text)`	Der Benutzer bestätigt den Text eines Kombinationsfelds: eine Auswahl in seiner Liste, Eingabe im Feld oder das Verlassen des Felds nach einer Eingabe. Escape verwirft die Eingabe und löst nichts aus; `is_text` per Code zu schreiben löst ebenfalls nichts aus
`ue_value_changed (string as_keys, double ad_value)`	Der Benutzer ändert den Wert eines Drehfelds: seine Pfeile, Auf / Ab im Feld, Eingabe oder das Verlassen des Felds nach einer Eingabe (Escape verwirft sie). `ad_value` ist der neue Wert, auf den Bereich des Drehfelds begrenzt. `id_value` per Code zu schreiben löst nichts aus
`ue_color_changed (string as_keys, long al_color)`	Der Benutzer wählt eine Farbe (Palette oder Auswahl) oder klickt den Hauptteil einer Farbauswahl, um ihre aktuelle Farbe erneut anzuwenden; `al_color` ist die PowerBuilder-Farbe. `il_color` per Code zu schreiben löst nichts aus
`ue_gallery_selection_changed (string as_from_keys, string as_keys)`	Eine Galeriekachel wurde übernommen — durch den Benutzer oder durch `of_select_gallery_item` (ein Befehl Ihres Codes löst es ebenfalls aus). Dieselben Argumente wie `ue_gallery_selection_changing`: Frage und Ergebnis lesen sich gleich, und `as_from_keys` ist die verlassene Kachel
`ue_gallery_selection_changing (string as_from_keys, string as_keys)` → boolean	Abbrechbar, wird vor der Übernahme der Kachel gestellt. Nur ausgelöst, wenn `ib_veto_gallery = true`. `as_from_keys` ist die aktuelle Kachel. Auch für `of_select_gallery_item` gestellt. Geben Sie `false` zurück, um sie zu behalten (ein Stil, den das Dokument noch nicht annehmen kann): `of_select_gallery_item` liefert dann `-4`
`ue_launcher (string as_keys)`	Der Benutzer klickt den Startpfeil einer Gruppe (auch im Panel einer eingeklappten Gruppe): `as_keys` ist die Adresse der Gruppe `registerkarte/gruppe` — öffnen Sie Ihr Optionsfenster
`ue_selection_changed (string as_keys)`	Eine andere Registerkarte kommt nach vorn: ein Klick, das Mausrad über dem Menüband, eine Zugriffstaste, oder `of_select_tab` (ein Befehl Ihres Codes löst es ebenfalls aus). `as_keys` ist der Schlüssel der Registerkarte — leer, wenn keine mehr übrig ist, nachdem die aktive ausgeblendet oder entfernt wurde
`ue_app_button ( )`	Auf die Anwendungsschaltfläche wird geklickt
`ue_app_menu_selected (string as_keys)`	Der Benutzer wählt einen Eintrag des Anwendungsmenüs: `as_keys` ist seine Adresse (`saveas/as_pdf`). Ein ausgegrauter oder ausgeblendeter Eintrag lässt sich nicht wählen
`ue_minimized (boolean ab_minimized)`	Das Menüband klappt ein oder auf: das Chevron am Ende der Registerkartenzeile, ein Doppelklick auf eine Registerkarte, oder `ib_minimized` aus Ihrem Code (ein Befehl löst es ebenfalls aus); `ue_size_changed` meldet die neue Höhe in jedem Fall
`ue_size_changed (long al_height, boolean ab_minimized)`	Die Höhe des Menübands hat sich von selbst geändert: eingeklappt, ausgeklappt, eine kontextbezogene Registerkarte eingeblendet, ein schmaleres Fenster, das eine Zeile verliert. Anders als `ue_auto_height` — das nur spricht, wenn sich die Komponente selbst bemisst — löst dieses Ereignis unabhängig von der automatischen Höhe aus: reine Information, um das darunter Liegende neu anzuordnen
`ue_keytips (boolean ab_on, integer ai_level)`	Die Keytips erscheinen (`true`) oder verschwinden (`false`). `ai_level` gibt an, wo die Navigation gerade steht: `1` = die Registerkarten sind mit Buchstaben versehen, `2` = die Befehle der aktuellen Registerkarte sind es, `0` = kein Keytip mehr
`ue_auto_height (long al_height)`	Das Menüband meldet seine ideale Höhe und hat sich soeben daran angepasst — immer aktiv: Die Höhe eines Menübands ist intrinsisch
`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 #

Ein vollständiges Menüband, vom Anwendungsmenü bis zu den Gruppen #

// open-Event : der gesamte Aufbau wird zu einer einzigen Darstellung zusammengefasst

// Das Zeichnen anhalten und die Anwendungsschaltflaeche benennen
uo_ribbon.of_set_redraw(/*on*/ false)
uo_ribbon.is_app_button = "Datei"

// Anwendungsmenue, mit einer Kaskade unter "Speichern unter"
uo_ribbon.of_add_app_menu_item(/*keys*/ "new", /*label*/ "Neu", /*image*/ "mono:img\new.svg")
uo_ribbon.of_add_app_menu_item(/*keys*/ "open", /*label*/ "Öffnen...", /*image*/ "mono:img\open.svg")
uo_ribbon.of_add_app_menu_item(/*keys*/ "save_as", /*label*/ "Speichern unter", /*image*/ "mono:img\saveas.svg")
uo_ribbon.of_add_app_menu_item(/*keys*/ "save_as/as_pdf", /*label*/ "PDF-Dokument", /*image*/ "")
uo_ribbon.of_add_app_menu_item(/*keys*/ "save_as/as_csv", /*label*/ "CSV-Datei", /*image*/ "")
uo_ribbon.of_add_app_menu_separator(/*keys*/ "sep1")
uo_ribbon.of_add_app_menu_item(/*keys*/ "quit", /*label*/ "Beenden", /*image*/ "mono:img\exit.svg")

// Symbolleiste fuer den Schnellzugriff, ueber den Registerkarten
uo_ribbon.of_add_qat(/*key*/ "qat_save", /*image*/ "mono:img\save.svg", /*tooltip*/ "Speichern")
uo_ribbon.of_add_qat(/*key*/ "qat_undo", /*image*/ "mono:img\undo.svg", /*tooltip*/ "Rückgängig")

// Registerkarte Start
uo_ribbon.of_add_tab(/*key*/ "home", /*title*/ "Start")
uo_ribbon.of_tab(/*key*/ "home").is_keytip = "S"

// Eine Gruppe: eine geteilte Schaltflaeche mit ihrem Menue, dann zwei kleine
uo_ribbon.of_add_group(/*keys*/ "home/clipboard", /*title*/ "Zwischenablage")
uo_ribbon.of_add_big_split(/*keys*/ "home/clipboard/paste", /*label*/ "Einfügen", /*image*/ "mono:img\paste.svg")
uo_ribbon.of_add_menu_item(/*keys*/ "home/clipboard/paste/paste_text", /*label*/ "Ohne Formatierung einfügen", /*image*/ "")
uo_ribbon.of_add_menu_item(/*keys*/ "home/clipboard/paste/paste_link", /*label*/ "Als Verknüpfung einfügen", /*image*/ "")
uo_ribbon.of_add_button(/*keys*/ "home/clipboard/cut", /*label*/ "Ausschneiden", /*image*/ "mono:img\cut.svg")
uo_ribbon.of_add_button(/*keys*/ "home/clipboard/copy", /*label*/ "Kopieren", /*image*/ "mono:img\copy.svg")
uo_ribbon.of_group(/*keys*/ "home/clipboard").ib_launcher = true       // Optionspfeil unten rechts

// Alles auf einmal zeichnen, dann das Register anzeigen
uo_ribbon.of_set_redraw(/*on*/ true)
uo_ribbon.of_select_tab(/*key*/ "home")

Eine einzige Klickverteilung #

// Event ue_clicked von uo_ribbon : (string as_keys)
// Der vollstaendige Pfad kommt mit dem Event : eine einzige Verteilung genuegt,
// und zwei Gruppen koennen denselben Bezeichner wiederverwenden, ohne sich zu stoeren.
choose case as_keys
    case "clipboard/cut" ; of_cut()
    case "clipboard/copy" ; of_copy()
    case "clipboard/paste" ; of_paste()
    case "font/bold"          ; of_toggle_bold()
end choose

Den Zustand der Steuerelemente nach Rechten steuern #

// Immer ueber den Pfad : Registerkarte > Gruppe > Steuerelement
uo_ribbon.of_item(/*keys*/ "home/clipboard/paste").ib_enabled = of_clipboard_has_data()
uo_ribbon.of_item(/*keys*/ "home/tools/brush").ib_checked = true
uo_ribbon.of_tab(/*key*/ "admin").ib_visible = gb_administrator

// Einen Eintrag INNERHALB eines Dropdown-Menues ausgrauen (Stufe 4)
uo_ribbon.of_item(/*keys*/ "home/clipboard/paste") &
        .of_menu_item(/*keys*/ "paste_link").ib_enabled = false

Kontextbezogene Registerkarten mit Banner #

Das Prinzip von Office: Registerkarten, die nur erscheinen, wenn die Auswahl sie rechtfertigt, gekrönt von einem farbigen betitelten Banner.

// open-Event : die kontextbezogene Gruppe wird vorbereitet, standardmaessig ausgeblendet

// Ohne Farbe folgt das Banner dem Akzent des Designs ; RGB(...) erzwingt sie
uo_ribbon.of_add_contextual_group(/*key*/ "img", /*title*/ "Bildtools", &
                                           /*color*/ RGB(/*red*/ 224, /*green*/ 32, /*blue*/ 96))
uo_ribbon.of_add_contextual_tab(/*key*/ "format", /*title*/ "Format", /*group_key*/ "img")
uo_ribbon.of_add_group(/*keys*/ "format/adjust", /*title*/ "Anpassen")
uo_ribbon.of_add_big_button(/*keys*/ "format/adjust/crop", /*label*/ "Zuschneiden", /*image*/ "mono:img\crop.svg")
uo_ribbon.of_add_button(/*keys*/ "format/adjust/rotate", /*label*/ "Drehen", /*image*/ "mono:img\rotate.svg")

// Bei der Auswahl eines Bildes : die Registerkarte wird eingeblendet und aktiviert
uo_ribbon.of_tab(/*key*/ "format").ib_visible = true
uo_ribbon.of_select_tab(/*key*/ "format")

// Bei der Abwahl : sie wird ausgeblendet, das Banner verschwindet mit ihr
uo_ribbon.of_tab(/*key*/ "format").ib_visible = false

Kombinationsfeld, Drehfeld, Farbauswahl und Katalog #


// Eine neue Gruppe im Register
uo_ribbon.of_add_group(/*keys*/ "home/font", /*title*/ "Schriftart")

// Bearbeitbares Kombinationsfeld : es wird ueber sein Handle gefuellt
uo_ribbon.of_add_combo(/*keys*/ "home/font/font_name", /*width_px*/ 140, /*editable*/ true)
uo_ribbon.of_add_combo_item(/*keys*/ "home/font/font_name", /*label*/ "Segoe UI")
uo_ribbon.of_add_combo_item(/*keys*/ "home/font/font_name", /*label*/ "Arial")
uo_ribbon.of_add_combo_item(/*keys*/ "home/font/font_name", /*label*/ "Calibri")
uo_ribbon.of_item(/*keys*/ "home/font/font_name").is_text = "Segoe UI"

// Numerisches Drehfeld : Minimum, Maximum, Schritt, Anfangswert
uo_ribbon.of_add_spinner(/*keys*/ "home/font/size", /*width_px*/ 70, /*min*/ 6, /*max*/ 96, &
                          /*step*/ 1, /*value*/ 11)

// Farbauswahl im Modus vollstaendige Palette (mit OK / Abbrechen)
uo_ribbon.of_add_colorpicker(/*keys*/ "home/font/color", /*label*/ "Farbe", &
                              /*image*/ "mono:img\font-color.svg", &
                              /*color*/ RGB(/*red*/ 0, /*green*/ 0, /*blue*/ 0), &
                              /*mode*/ u_pbt_ribbon.COLORMODE_OPEN)

// Katalog von Formatvorlagen : scrollende bebilderte Kacheln
uo_ribbon.of_add_gallery(/*keys*/ "home/font/styles", /*width_px*/ 220, &
                                     /*tile_w*/ 64, /*tile_h*/ 48)
uo_ribbon.of_add_gallery_item(/*keys*/ "home/font/styles/st_normal", /*image*/ "img\style-normal.png", /*label*/ "Standard")
uo_ribbon.of_add_gallery_item(/*keys*/ "home/font/styles/st_title",  /*image*/ "img\style-titre.png",  /*label*/ "Titel")
uo_ribbon.of_add_gallery_item(/*keys*/ "home/font/styles/st_note",   /*image*/ "img\style-note.png",   /*label*/ "Notiz")
uo_ribbon.of_add_gallery_item(/*keys*/ "home/font/styles/st_code",   /*image*/ "img\style-code.png",   /*label*/ "Code")

// Der eingeklappte Streifen zeigt 4 Miniaturen auf einmal ; die uebrigen bleiben
// ueber die Pfeile erreichbar, oder im ausgeklappten Raster.
uo_ribbon.of_item(/*keys*/ "home/font/styles").ii_visible_items = 4

// Der zu Beginn ausgewaehlte Stil
uo_ribbon.of_select_gallery_item(/*keys*/ "home/font/styles/st_normal")

// Event ue_value_changed von uo_ribbon : (string as_keys, double ad_value)
n_pbt_utils lnv_utils   // autoinstantiate : nichts zu erzeugen, nichts zu zerstoeren
if lnv_utils.of_leaf(/*keys*/ as_keys) = "size" then of_apply_size(ad_value)

Bereich und Schrittweite eines Drehfelds lassen sich nachträglich über id_min, id_max und id_step seines Handles ändern: Der Wert wird sofort in den neuen Bereich zurückgeholt, ohne ue_value_changed auszulösen. Sein Bild ändert sich, wie das jedes Steuerelements, über is_image.

// Die groesste Groesse haengt von der gewaehlten Schriftart ab : 96, dann 400 in Schritten von 2
uo_ribbon.of_item(/*keys*/ "home/font/size").id_max = 400
uo_ribbon.of_item(/*keys*/ "home/font/size").id_step = 2

// Event ue_color_changed von uo_ribbon : (string as_keys, long al_color)
n_pbt_utils lnv_utils   // autoinstantiate : nichts zu erzeugen, nichts zu zerstoeren
if lnv_utils.of_leaf(/*keys*/ as_keys) = "color" then of_apply_color(al_color)

Die Wahl einer Katalogminiatur ablehnen #

// Die Frage wird nur auf Wunsch gestellt: diese Zeile schaltet sie ein, und
// ue_gallery_selection_changing entscheidet dann ueber jede Kachel.
uo_ribbon.ib_veto_gallery = true

// Event ue_gallery_selection_changing von uo_ribbon :
//   (string as_from_keys, string as_keys)
// FALSE zurueckzugeben behaelt die aktuelle Miniatur (as_from_keys) bei.
n_pbt_utils lnv_utils   // autoinstantiate : nichts zu erzeugen, nichts zu zerstoeren
if lnv_utils.of_leaf(/*keys*/ as_keys) = "st_code" and not of_document_supports_code() then
    MessageBox("Formatvorlage", "Dieses Dokument kann die Formatvorlage Code nicht annehmen.")
    return false
end if
return true

Der Dialogfeld-Starter #

// Der kleine Pfeil unten rechts in der Gruppe
uo_ribbon.of_group(/*keys*/ "home/font").ib_launcher = true

// Event ue_launcher von uo_ribbon : (string as_keys)
// Der Pfad benennt die Gruppe : das passende Optionsfenster wird geoeffnet.
n_pbt_utils lnv_utils   // autoinstantiate : nichts zu erzeugen, nichts zu zerstoeren
choose case lnv_utils.of_leaf(/*keys*/ as_keys)
    case "font"        ; open(w_font_options)
    case "clipboard" ; open(w_paste_options)
end choose

Keytips: das Menüband über die Tastatur führen #

// Alt zeigt die Buchstaben ; Alt, dann S, dann C loest "copy" aus
uo_ribbon.of_tab(/*key*/ "home").is_keytip = "S"
uo_ribbon.of_item(/*keys*/ "home/clipboard/copy").is_keytip = "C"
uo_ribbon.of_item(/*keys*/ "home/clipboard/cut").is_keytip = "X"

Ein Druck auf Alt übergibt dem Menüband das Kommando, gleichgültig wo der Fokus im Fenster liegt: Es übernimmt den Tastaturfokus und blendet seine Buchstaben ein. Sie müssen nichts verdrahten — es genügt, dass mindestens ein Keytip deklariert ist. Esc, ein zweites Alt oder die Wahl eines Befehls geben den Fokus an das Steuerelement zurück, das der Anwender verlassen hatte. Eine Zugriffstaste kann mehrere Buchstaben haben ("FP", wie in Office): der Benutzer tippt sie nacheinander, die Abzeichen, die nicht mehr mit dem Getippten beginnen, treten zurück, und die Rücktaste bringt sie wieder. Ein Steuerelement einer eingeklappten Gruppe behält seine Taste: sie öffnet das Panel der Gruppe.

ue_keytips benachrichtigt Sie bei jedem Zustandswechsel und nennt Ihnen die aktuelle Ebene:

// Event ue_keytips von uo_ribbon : (boolean ab_on, integer ai_level)
// Die Tastatur steuert das Menueband : den Hinweis in der Statusleiste
// loeschen, der von der Maus spricht, und ihn zuruecksetzen, sobald die
// Buchstaben wieder verschwinden.
if ab_on then
    uo_statusbar.of_item(/*keys*/ "main").is_text = "Buchstabe eingeben (Ebene " + String(ai_level) + ")"
else
    uo_statusbar.of_item(/*keys*/ "main").is_text = ""
end if

Erweiterte Tooltips auf einem Steuerelement #


// Der Super-Tooltip der Schaltflaeche Einfuegen: ein Titel, ein Text, ein Bild
lnv_item = uo_ribbon.of_item(/*keys*/ "home/clipboard/paste")
lnv_item.is_super_tooltip_title = "Einfügen (Strg+V)"
lnv_item.is_super_tooltip_text  = "Fügt den Inhalt der Zwischenablage ein." &
                                + "[br][br][size-=15]Verwenden Sie den Pfeil, um ohne Formatierung einzufügen.[/size-=15]"
lnv_item.is_super_tooltip_image = "img\paste.png"

Diese vier Eigenschaften sind exakt dieselben wie bei jedem anderen Item der Bibliothek. Für einen einzeiligen Tooltip genügt is_tooltip.

Automatische Höhe #

Das Menüband bemisst sich selbst: Es ist nichts zu aktivieren. Es benachrichtigt Sie bei jeder Höhenänderung (Einklappen, kontextbezogene Registerkarte, Designwechsel), damit Sie neu platzieren, was darunter liegt.

// Event ue_auto_height von uo_ribbon : (long al_height)
// Das Menueband hat sich bereits neu bemessen : wir setzen um, was darunter liegt.
uo_content.y      = uo_ribbon.y + uo_ribbon.height
uo_content.height = this.height - uo_content.y

Das Menüband einklappen, um Platz zu gewinnen #

// Start with the ribbon folded: only the tab headers show
uo_ribbon.ib_minimized = true

// Event ue_minimized von uo_ribbon : (boolean ab_minimized)
// Wir merken uns die Vorliebe des Benutzers fuer das naechste Oeffnen.
of_save_preference("ribbon_collapsed", ab_minimized)

Mit einem leeren Menüband neu beginnen #

// of_reset leert Registerkarten, Gruppen, Steuerelemente, Schnellzugriffsleiste und Menue
uo_ribbon.of_reset()
uo_ribbon.of_add_tab(/*key*/ "home", /*title*/ "Start")

Aus einem vorhandenen PowerBuilder-Menü #

Eine PowerBuilder-Anwendung hat ihre Befehle bereits einmal beschrieben: in ihrem Menü. Beschriftungen, Tastenkombinationen, Bilder, Trenner, Untermenüs, Tooltips — alles ist da. n_pbt_menu2ribbon liest dieses Menü per RTTI zurück und schreibt das PowerScript, das das passende Ribbon aufbaut.

// Einmalig, von Hand : der Generator SCHREIBT Code, er laeuft nicht in
// Produktion. Fuegen Sie sein Ergebnis in das open-Event Ihres Fensters ein.
n_pbt_menu2ribbon lnv_gen
string ls_code

// Den Code aus dem Menue erzeugen
lnv_gen = create n_pbt_menu2ribbon
ls_code = lnv_gen.of_generate(/*menu*/ m_principal, /*ribbon_var*/ "uo_ribbon")
destroy lnv_gen

// In die Zwischenablage, bereit zum Einfuegen
ClipBoard(ls_code)

Die Umwandlung ist deterministisch: keine KI, kein Netzwerkaufruf, nichts verlässt den Rechner. Jeder erzeugte Schlüssel ist der ClassName des Menüeintrags (m_fichier, m_ouvrir): Die Adresse, die das Menüband meldet (m_fichier/g1/m_ouvrir), führt also zum Eintrag zurück, und der am Ende des Codes geschriebene Router löst dessen Clicked aus ue_clicked, ue_toggled und ue_menu_selected aus - Ihr vorhandener Code läuft unverändert. Untermenüs werden in jeder Tiefe übernommen, ein ausgeblendeter Eintrag entfällt, ein ausgegrauter bleibt ausgegraut, ein abgehakter wird zu einem Umschalter oder einem abhakbaren Eintrag, der abgehakt beginnt.

Der erzeugte Code ist ein Ausgangspunkt zum Durchsehen, kein fertiges Ergebnis: Ein Menü ist eine Liste, ein Ribbon ist ein Layout. Fassen Sie zusammen, wählen Sie Ihre großen Schaltflächen, streichen Sie, was nicht dauerhaft sichtbar sein muss. Beispiel 9 der Ribbon-Seite in der Demo-Anwendung zeigt ein vollständiges Ergebnis.

Best Practices #

Klammern Sie den gesamten Aufbau mit of_set_redraw(false) / of_set_redraw(true) ein: Ein vollständiges Menüband wird dann in einem Zug gezeichnet, ohne Flackern.
Jedes Hinzufügen liefert einen Code: 0, oder -5 für eine falsche Adresse, einen Elternteil der falschen Art oder einen bereits vergebenen Schlüssel. Prüfen Sie ihn dort, wo ein Aufbaufehler für Sie zählt; um ein Steuerelement danach zu steuern, liefert of_item(adresse) sein Handle.
Rufen Sie of_preload_icons beim Start auf: Andernfalls zeigt die erste Anzeige einer nie geöffneten Registerkarte eine kurze Verzögerung, bevor ihre Symbole erscheinen.
Ein Bezeichner muss nur innerhalb seiner Gruppe eindeutig sein. Nutzen Sie das, um Ihre Steuerelemente schlicht zu benennen (copy, paste) statt mit Präfixen.
Behalten Sie kontextbezogene Registerkarten den Befehlen vor, die außerhalb ihres Kontexts keinen Sinn ergeben: Eine ausgegraute feste Registerkarte ist erholsamer als eine, die auftaucht und wieder verschwindet.
Die Frage vor einer Kachel ist standardmäßig inaktiv: Schalten Sie sie mit ib_veto_gallery = true nur ein, wenn ue_gallery_selection_changing ablehnen können muss, denn jede Frage kostet einen Hin- und Rückweg zu PowerBuilder.
Höchstens ein Dialogfeld-Starter je Gruppe, und nur dann, wenn die Gruppe wirklich erweiterte Optionen zu bieten hat.
Um ein ganzes Menüband neu aufzubauen, ziehen Sie of_clear() (oder of_reset()) einer Reihe von of_remove_tab vor: ein einziger Befehl, und alle ausgegebenen Handles werden auf einmal freigegeben.
Für eine leichtere Befehlsleiste ohne Registerkarten und Gruppen siehe toolbar; für eine seitliche Navigation listbar.

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.