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_ruban.of_item("accueil/presse_papier/coller").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

uo_ruban.of_add_tab("accueil", "Start")

uo_ruban.of_add_group("accueil/presse_papier", "Zwischenablage")
uo_ruban.of_add_big_button("accueil/presse_papier/coller", "Einfügen", "mono:img\paste.svg")
uo_ruban.of_add_button("accueil/presse_papier/couper", "Ausschneiden", "mono:img\cut.svg")
uo_ruban.of_add_button("accueil/presse_papier/copier", "Kopieren", "mono:img\copy.svg")

uo_ruban.of_select_tab("accueil")

// Event ue_clicked von uo_ruban : (string as_keys)
choose case as_key
    case "coller" ; of_coller()
    case "couper" ; of_couper()
    case "copier" ; of_copier()
end choose

Eigenschaften #

Eigenschaft	Typ	Standard	Zweck
`is_app_button`	string	`""`	Beschriftung der Anwendungsschaltfläche oben links, die das Anwendungsmenü öffnet. Leer = Beschriftung `File`
`ib_minimized`	boolean	`false`	`true` klappt das Menüband auf seine bloßen Registerkartenköpfe ein; ein Klick auf eine Registerkarte klappt sie vorübergehend auf (löst `ue_minimized` aus)
`ib_veto_gallery`	boolean	`true`	Nachfragen, bevor eine Galeriekachel übernommen wird (löst `ue_gallery_selection_changing` aus, das ablehnen kann). Standardmäßig aktiv: Wird nichts geskriptet, ist die Auswahl immer erlaubt. Auf `false` setzen, um den Hin- und Rückweg zu PowerBuilder (~35 ms) dort zu sparen, wo er auffiele
`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

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	`""`	Zugriffsbuchstabe, der nach Drücken von Alt angezeigt wird (`"S"` für Start)

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
`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
`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	`""`	Zugriffsbuchstabe des Steuerelements, angezeigt nach Drücken von Alt
`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

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 (id, breite_px, kachel_breite, kachel_hoehe)`	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 (`0` = 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 — genau gleichbedeutend mit einem Benutzerklick (löst `ue_selection_changed` aus). Liefert `0` nach der Anwendung, `-2` wenn die Komponente nicht erzeugt ist
`of_selected_key ( )`	Bezeichner der aktiven Registerkarte, `""`, wenn keine aktiv ist. Wird durch `ue_selection_changed` aktuell gehalten und stimmt daher schon beim Start
`of_remove_group (string as_keys)`	Entfernt eine Gruppe und alle ihre Steuerelemente, über ihre Adresse. 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_item (string as_keys)`	Entfernt ein Steuerelement, über seine Adresse. 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_tab (string as_key)`	Entfernt eine Registerkarte und ihren gesamten Inhalt. Liefert `0` nach der Anwendung, `-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)`	Wurzeleintrag im Menü einer Dropdown- oder geteilten Schaltfläche. 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_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 innerhalb des Menüs. Liefert `0` nach der Anwendung, `-5` bei einem ungültigen Argument (leerer Schlüssel, falsche Adresse), `-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. 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_gallery_item (string as_keys, string as_image, string as_label)`	Fügt einem Katalog eine Kachel 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_select_gallery_item (string as_keys)`	Wählt eine Katalogkachel per Programm aus, über ihre vierstufige Adresse (ohne ein Event auszulösen). Liefert `0` nach der Anwendung, `-5` bei einem ungültigen Argument (leerer Schlüssel, falsche Adresse), `-2` wenn die Komponente nicht erzeugt ist
`of_open (string as_keys)`	Öffnet per Programm das Menü, die Liste oder die Farbfeldpalette des Steuerelements an dieser Adresse; eine Schaltfläche der Schnellzugriffsleiste wird allein über ihren Schlüssel adressiert. Liefert `0` nach der Anwendung, `-5` bei einem ungültigen Argument (leerer Schlüssel, falsche Adresse), `-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)`	Wurzeleintrag des Anwendungsmenüs (jenes, das die Schaltfläche `is_app_button` öffnet). Liefert `0` nach der Anwendung, `-2` wenn die Komponente nicht erzeugt ist
`of_add_app_menu_separator (string as_keys)`	Trennstrich im Anwendungsmenü. Liefert `0` nach der Anwendung, `-2` wenn die Komponente nicht erzeugt ist
`of_add_qat (string as_key, string as_image, string as_tooltip)`	Schaltfläche der Symbolleiste für den Schnellzugriff über den Registerkarten; liefert `0` (`-5` bei einem ungültigen Argument, `-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 erzeugt, mit einer farbigen Linie gekennzeichnet. Übergeben Sie `ACCENT_LIGHT`, damit sie dem Akzent des Designs folgt. Liefert `0` nach der Anwendung, `-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 betiteltes Banner krönt ihre Registerkarten. Liefert `0` (`-5` bei einem ungültigen Argument, `-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_add_contextual_tab (string as_key, string as_title, string as_group_key)`	Fügt eine Registerkarte unter einer kontextuellen Gruppe hinzu: verborgen erzeugt, gekrönt vom farbigen Banner der Gruppe. Das ist der einzige Weg — das Gruppen-Handle fügt nichts mehr hinzu. Liefert `0` nach der Anwendung, `-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)`	Auf eine Schaltfläche, eine große Schaltfläche, den Hauptteil einer geteilten Schaltfläche oder einer Farbauswahl wird geklickt
`ue_toggled (string as_keys, boolean ab_checked)`	Ein Umschalter oder ein Kontrollkästchen wechselt den Zustand; `ab_checked` trägt den neuen Zustand
`ue_menu_selected (string as_keys, boolean ab_checked)`	Ein Eintrag eines Dropdown-Menüs wird gewählt. `as_keys` trägt vier Ebenen: Registerkarte, Gruppe, tragendes Steuerelement, dann den gewählten Eintrag, `ab_checked` = der Zustand eines anhakbaren Eintrags
`ue_combo_changed (string as_keys, string as_text)`	Ein Kombinationsfeld wechselt den Wert, durch Auswahl oder durch Eingabe
`ue_value_changed (string as_keys, double ad_value)`	Ein numerisches Drehfeld wechselt den Wert
`ue_color_changed (string as_keys, long al_color)`	In einer Farbauswahl wird eine Farbe gewählt
`ue_gallery_selection_changed (string as_from_keys, string as_keys)`	Eine Galeriekachel wurde übernommen. 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. Standardmäßig ausgelöst; `ib_veto_gallery = false` entfernt sie. `as_from_keys` ist die aktuelle Kachel. Geben Sie `false` zurück, um sie zu behalten (ein Stil, den das Dokument noch nicht annehmen kann)
`ue_launcher (string as_keys)`	Auf den Starterpfeil einer Gruppe wird geklickt — öffnen Sie Ihr Optionsfenster
`ue_selection_changed (string as_keys)`	Eine Registerkarte wird aktiv, durch Klick oder durch `of_select_tab`
`ue_app_button ( )`	Auf die Anwendungsschaltfläche wird geklickt
`ue_app_menu_selected (string as_keys)`	Ein Eintrag des Anwendungsmenüs wird gewählt
`ue_minimized (boolean ab_minimized)`	Das Menüband wird vom Benutzer ein- oder ausgeklappt
`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

uo_ruban.of_set_redraw(false)
uo_ruban.is_app_button = "Datei"

// Anwendungsmenue, mit einer Kaskade unter "Speichern unter"
uo_ruban.of_add_app_menu_item(/*key*/ "nouveau", /*beschriftung*/ "Neu", /*bild*/ "mono:img\new.svg")
uo_ruban.of_add_app_menu_item("ouvrir", "Öffnen...", "mono:img\open.svg")
uo_ruban.of_add_app_menu_item("enr_sous", "Speichern unter", "mono:img\saveas.svg")
uo_ruban.of_add_app_menu_item(/*parent*/ "enr_sous", /*key*/ "sous_pdf", "PDF-Dokument", "")
uo_ruban.of_add_app_menu_item(/*parent*/ "enr_sous", /*key*/ "sous_csv", "CSV-Datei", "")
uo_ruban.of_add_app_menu_separator("sep1")
uo_ruban.of_add_app_menu_item("quitter", "Beenden", "mono:img\exit.svg")

// Symbolleiste fuer den Schnellzugriff, ueber den Registerkarten
uo_ruban.of_add_qat(/*key*/ "qat_enr", /*bild*/ "mono:img\save.svg", /*tooltip*/ "Speichern")
uo_ruban.of_add_qat("qat_annuler", "mono:img\undo.svg", "Rückgängig")

// Registerkarte Start
uo_ruban.of_add_tab("accueil", "Start")
uo_ruban.of_tab("accueil").is_keytip = "S"

uo_ruban.of_add_group("accueil/presse_papier", "Zwischenablage")
uo_ruban.of_add_big_split("accueil/presse_papier/coller", "Einfügen", "mono:img\paste.svg")
uo_ruban.of_add_menu_item("accueil/presse_papier/coller/coller_texte", "Ohne Formatierung einfügen", "")
uo_ruban.of_add_menu_item("accueil/presse_papier/coller/coller_lien", "Als Verknüpfung einfügen", "")
uo_ruban.of_add_button("accueil/presse_papier/couper", "Ausschneiden", "mono:img\cut.svg")
uo_ruban.of_add_button("accueil/presse_papier/copier", "Kopieren", "mono:img\copy.svg")
uo_ruban.of_group("accueil/presse_papier").ib_launcher = true       // Optionspfeil unten rechts

uo_ruban.of_set_redraw(true)
uo_ruban.of_select_tab("accueil")

Eine einzige Klickverteilung #

// Event ue_clicked von uo_ruban : (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 "presse_papier/couper" ; of_couper()
    case "presse_papier/copier" ; of_copier()
    case "presse_papier/coller" ; of_coller()
    case "police/gras"          ; of_basculer_gras()
end choose

Den Zustand der Steuerelemente nach Rechten steuern #

// Immer ueber den Pfad : Registerkarte > Gruppe > Steuerelement
uo_ruban.of_item("accueil/presse_papier/coller").ib_enabled = of_presse_papier_non_vide()
uo_ruban.of_item("accueil/outils/pinceau").ib_checked = true
uo_ruban.of_tab("admin").ib_visible = gb_administrateur

// Einen Eintrag INNERHALB eines Dropdown-Menues ausgrauen (Stufe 4)
uo_ruban.of_item("accueil/presse_papier/coller") &
        .of_menu_item("coller_lien").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_ruban.of_add_contextual_group(/*key*/ "img", /*titel*/ "Bildtools", &
                                           /*farbe*/ RGB(224, 32, 96))
uo_ruban.of_add_contextual_tab("format", "Format", "img")
uo_ruban.of_add_group("format/ajuster", "Anpassen")
uo_ruban.of_add_big_button("format/ajuster/rogner", "Zuschneiden", "mono:img\crop.svg")
uo_ruban.of_add_button("format/ajuster/pivoter", "Drehen", "mono:img\rotate.svg")

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

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

Kombinationsfeld, Drehfeld, Farbauswahl und Katalog #


uo_ruban.of_add_group("accueil/police", "Schriftart")

// Bearbeitbares Kombinationsfeld : es wird ueber sein Handle gefuellt
uo_ruban.of_add_combo("accueil/police/nom_police", /*breite_px*/ 140, /*bearbeitbar*/ true)
uo_ruban.of_add_combo_item("accueil/police/nom_police", "Segoe UI")
uo_ruban.of_add_combo_item("accueil/police/nom_police", "Arial")
uo_ruban.of_add_combo_item("accueil/police/nom_police", "Calibri")
uo_ruban.of_item("accueil/police/nom_police").is_text = "Segoe UI"

// Numerisches Drehfeld : Minimum, Maximum, Schritt, Anfangswert
uo_ruban.of_add_spinner("accueil/police/taille", /*breite_px*/ 70, /*minimum*/ 6, /*maximum*/ 96, &
                          /*schritt*/ 1, /*wert*/ 11)

// Farbauswahl im Modus vollstaendige Palette (mit OK / Abbrechen)
uo_ruban.of_add_colorpicker("accueil/police/couleur", /*beschriftung*/ "Farbe", &
                              /*bild*/ "mono:img\font-color.svg", &
                              /*farbe*/ RGB(0, 0, 0), &
                              /*modus*/ u_pbt_ribbon.COLORMODE_OPEN)

// Katalog von Formatvorlagen : scrollende bebilderte Kacheln
uo_ruban.of_add_gallery("accueil/police/styles", /*breite_px*/ 220, &
                                     /*kachelbreite*/ 64, /*kachelhoehe*/ 48)
uo_ruban.of_add_gallery_item("accueil/police/styles/st_normal", "img\style-normal.png", "Standard")
uo_ruban.of_add_gallery_item("accueil/police/styles/st_titre",  "img\style-titre.png",  "Titel")
uo_ruban.of_add_gallery_item("accueil/police/styles/st_note",   "img\style-note.png",   "Notiz")
uo_ruban.of_add_gallery_item("accueil/police/styles/st_code",   "img\style-code.png",   "Code")

// Der eingeklappte Streifen zeigt 4 Miniaturen auf einmal ; die uebrigen bleiben
// ueber die Pfeile erreichbar, oder im ausgeklappten Raster.
uo_ruban.of_item("accueil/police/styles").ii_visible_items = 4

uo_ruban.of_select_gallery_item("accueil/police/styles/st_normal")

// Event ue_value_changed von uo_ruban : (string as_keys, double ad_value)
n_pbt_utils lnv_utils   // autoinstantiate : nichts zu erzeugen, nichts zu zerstoeren
if lnv_utils.of_leaf(as_keys) = "taille" then of_appliquer_taille(ad_value)

// Event ue_color_changed von uo_ruban : (string as_keys, long al_color)
n_pbt_utils lnv_utils   // autoinstantiate : nichts zu erzeugen, nichts zu zerstoeren
if lnv_utils.of_leaf(as_keys) = "couleur" then of_appliquer_couleur(al_color)

Die Wahl einer Katalogminiatur ablehnen #

// Die Frage wird STANDARDMAESSIG gestellt: nichts zu aktivieren. Diese Zeile tut
// das Gegenteil und entfernt sie, wo die Abwaegung nichts bringt.
uo_ruban.ib_veto_gallery = false

// Event ue_gallery_selection_changing von uo_ruban :
//   (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(as_keys) = "st_code" and not of_document_supporte_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_ruban.of_group("accueil/police").ib_launcher = true

// Event ue_launcher von uo_ruban : (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(as_keys)
    case "police"        ; open(w_options_police)
    case "presse_papier" ; open(w_options_collage)
end choose

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

// Alt zeigt die Buchstaben ; Alt, dann S, dann C loest "copier" aus
uo_ruban.of_tab("accueil").is_keytip = "S"
uo_ruban.of_item("accueil/presse_papier/copier").is_keytip = "C"
uo_ruban.of_item("accueil/presse_papier/couper").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.

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

// Event ue_keytips von uo_ruban : (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_statut.of_item("main").is_text = "Buchstabe eingeben (Ebene " + String(ai_level) + ")"
else
    uo_statut.of_item("main").is_text = ""
end if

Erweiterte Tooltips auf einem Steuerelement #


lnv_item = uo_ruban.of_item("accueil/presse_papier/coller")
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_ruban : (long al_height)
// Das Menueband hat sich bereits neu bemessen : wir setzen um, was darunter liegt.
uo_contenu.y      = uo_ruban.y + uo_ruban.height
uo_contenu.height = this.height - uo_contenu.y

Das Menüband einklappen, um Platz zu gewinnen #

uo_ruban.ib_minimized = true

// Event ue_minimized von uo_ruban : (boolean ab_minimized)
// Wir merken uns die Vorliebe des Benutzers fuer das naechste Oeffnen.
of_enregistrer_preference("ruban_replie", ab_minimized)

Mit einem leeren Menüband neu beginnen #

// of_reset leert Registerkarten, Gruppen, Steuerelemente, Schnellzugriffsleiste und Menue
uo_ruban.of_reset()
uo_ruban.of_add_tab("accueil", "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

lnv_gen = create n_pbt_menu2ribbon
ls_code = lnv_gen.of_generate(/*menue*/ m_principal, /*variable*/ "uo_ruban")
destroy lnv_gen

ClipBoard(ls_code)

Die Umwandlung ist deterministisch: keine KI, kein Netzwerkaufruf, nichts verlässt den Rechner. Und die erzeugten Bezeichner behalten den Menüpfad (m_principal.m_fichier.m_ouvrir), sodass das choose case Ihrer vorhandenen Aktionen unverändert aus ue_clicked funktioniert.

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.
Bewahren Sie die gelieferten Handles (n_pbt_ribbon_tab, n_pbt_ribbon_group, n_pbt_ribbon_item) für die Dauer des Aufbaus in lokalen Variablen auf: Der Code bleibt kurz und lesbar. Um ein Steuerelement später zu steuern, gehen Sie einfach wieder über den Pfad.
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 (copier, coller) 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 wird standardmäßig gestellt: Ein leer gelassenes ue_gallery_selection_changing erlaubt die Auswahl immer, Sie müssen nichts tun. Schalten Sie sie mit ib_veto_gallery = false ab, wenn die Abwägung Ihnen nichts bringt, 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: Andernfalls schlägt die Wiederverwendung eines Registerkartenbezeichners fehl.
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

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.