# 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_tab("accueil").of_group("presse_papier").of_item("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
    n_pbt_ribbon_tab   lnv_onglet
    n_pbt_ribbon_group lnv_groupe

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

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

    uo_ruban.of_select_tab("accueil")

    // Event ue_clicked von uo_ruban : (string as_tab, string as_group, string as_id)
    choose case as_id
        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(id)` 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_keytip` | string | `""` | Zugriffsbuchstabe, der nach Drücken von Alt angezeigt wird (`"S"` für Start)

### Eigenschaften einer Gruppe — `n_pbt_ribbon_group` #

Über `of_tab(id).of_group(id)` erhalten.

Eigenschaft | Typ | Standard | Zweck
--- | --- | --- | ---
`ib_visible` | boolean | `true` | `false` blendet die Gruppe und alle ihre Steuerelemente aus
`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_tab(id).of_group(id).of_item(id)` 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_tab(id).of_group(id).of_item(id).of_menu_item(id)` erhalten.

Eigenschaft | Typ | Standard | Zweck
--- | --- | --- | ---
`ib_enabled` | boolean | `true` | `false` graut den Eintrag aus
`ib_checked` | boolean | `false` | Haken eines mit `of_add_menu_check` erzeugten Eintrags

## Die zwölf Typen von Steuerelementen #

Alle werden auf dem Handle einer Gruppe hinzugefügt und liefern das Handle des erzeugten Steuerelements zurück — Sie können also unmittelbar danach ein Menü oder eine Liste füllen.

Methode der Gruppe | Erhaltenes Steuerelement | Event
--- | --- | ---
`of_add_big_button (id, label, image)` | Große Schaltfläche über die volle Höhe, Symbol über der Beschriftung | `ue_clicked`
`of_add_big_split (id, label, image)` | Große geteilte Schaltfläche: Der obere Teil handelt, der Pfeil öffnet das Menü | `ue_clicked` · `ue_menu_selected`
`of_add_big_dropdown (id, label, image)` | Große Schaltfläche mit Dropdown-Menü | `ue_menu_selected`
`of_add_button (id, label, image)` | Kleine Schaltfläche (in Spalten zu dritt gestapelt) | `ue_clicked`
`of_add_toggle (id, label, image)` | Kleiner Umschalter, der gedrückt bleibt | `ue_toggled`
`of_add_dropdown (id, label, image)` | Kleine Schaltfläche mit Dropdown-Menü | `ue_menu_selected`
`of_add_checkbox (id, label)` | Kontrollkästchen | `ue_toggled`
`of_add_separator ( )` | Senkrechter Trennstrich zwischen zwei Blöcken von Steuerelementen | —
`of_add_combo (id, largeur_px, modifiable)` | Kombinationsfeld, bearbeitbar oder nicht | `ue_combo_changed`
`of_add_spinner (id, largeur_px, mini, maxi, pas, valeur)` | Numerisches Drehfeld mit Pfeilen | `ue_value_changed`
`of_add_colorpicker (id, label, image, couleur)` | Geteilte Farbschaltfläche: Der Klick wendet erneut an, der Pfeil öffnet die Farbfeldpalette | `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_id, string as_title)` | Fügt eine Registerkarte hinzu und liefert ihr Handle: Hängen Sie die Gruppen daran
`of_insert_tab (string as_id, 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 ihr Handle wie `of_add_tab`. Eine bereits vergebene Id wird abgelehnt
`of_tab (string as_id)` | Handle einer vorhandenen Registerkarte (wird beim ersten Zugriff erzeugt)
`of_add_group (string as_id, string as_title)` | Auf einem Registerkarten-Handle: fügt eine betitelte Gruppe hinzu und liefert ihr Handle
`of_group (string as_id)` | Auf einem Registerkarten-Handle: Handle einer vorhandenen Gruppe
`of_item (string as_id)` | Auf einem Gruppen-Handle: Handle eines vorhandenen Steuerelements
`of_select_tab (string as_id)` | Aktiviert eine Registerkarte — genau gleichbedeutend mit einem Benutzerklick (löst `ue_selection_changed` aus)
`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_id)` | Auf einem Registerkarten-Handle: entfernt eine Gruppe und alle ihre Steuerelemente
`of_remove_item (string as_id)` | Auf einem Gruppen-Handle: entfernt ein Steuerelement
`of_remove_tab (string as_id)` | Entfernt eine Registerkarte und ihren gesamten Inhalt
`of_clear ( )` | Leert das Menüband vollständig: Registerkarten, Gruppen, Steuerelemente, Symbolleiste für den Schnellzugriff, Anwendungsmenü

### Menüs und Listen füllen #

Alle diese Methoden werden auf dem Handle eines Steuerelements aufgerufen.

Methode | Zweck
--- | ---
`of_add_menu_item (string as_id, string as_label, string as_image)` | Wurzeleintrag im Menü einer Dropdown- oder geteilten Schaltfläche
`of_add_menu_item (string as_parent, string as_id, string as_label, string as_image)` | Kaskadierender Eintrag: `as_parent` benennt einen vorhandenen Eintrag dieses Menüs
`of_add_menu_check (string as_id, string as_label)` · `(id, label, image)` | Anhakbarer Eintrag: Der Klick schaltet seinen Zustand um und meldet ihn in `ue_menu_selected`
`of_add_menu_header (string as_label)` | Nicht anklickbare Titelzeile, um ein langes Menü zu gliedern
`of_add_menu_separator ( )` | Trennstrich innerhalb des Menüs
`of_menu_item (string as_id)` | Handle eines Menüeintrags, um ihn im laufenden Betrieb auszugrauen oder anzuhaken
`of_add_combo_item (string as_label)` | Fügt der Liste eines Kombinationsfelds eine Auswahl hinzu
`of_add_gallery_item (string as_id, string as_image, string as_label)` | Fügt einem Katalog eine Kachel hinzu
`of_select_item (string as_id)` | Wählt eine Katalogkachel per Programm aus (ohne ein Event auszulösen)
`of_open ( )` | Öffnet per Programm das Menü, die Liste oder die Farbfeldpalette des Steuerelements

### Anwendungsmenü und Symbolleiste für den Schnellzugriff #

Methode | Zweck
--- | ---
`of_add_app_menu_item (string as_id, string as_label, string as_image)` | Wurzeleintrag des Anwendungsmenüs (jenes, das die Schaltfläche `is_app_button` öffnet)
`of_add_app_menu_item (string as_parent, string as_id, string as_label, string as_image)` | Kaskadierender Eintrag des Anwendungsmenüs
`of_add_app_menu_separator (string as_id)` | Trennstrich im Anwendungsmenü
`of_add_qat (string as_id, string as_image, string as_tooltip)` | Schaltfläche der Symbolleiste für den Schnellzugriff über den Registerkarten; liefert ihr Handle
`of_qat_item (string as_id)` | Handle einer Schnellzugriffsschaltfläche, um sie im laufenden Betrieb auszugrauen oder auszublenden

### Kontextbezogene Registerkarten #

Methode | Zweck
--- | ---
`of_add_contextual_tab (string as_id, 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
`of_add_contextual_group (string as_id, string as_title)` · `(id, title, al_color)` | Gruppe kontextbezogener Registerkarten: Ein farbiges betiteltes Banner krönt ihre Registerkarten. Liefert ihr Handle
`of_ctx_group (string as_id)` | Findet das Handle einer bereits erzeugten kontextbezogenen Gruppe wieder — nützlich, wenn Sie das bei der Erzeugung gelieferte nicht aufbewahrt haben
`of_add_tab (string as_id, string as_title)` | Auf einem Handle einer kontextbezogenen Gruppe: fügt eine vom Banner gekrönte Registerkarte hinzu, ausgeblendet erzeugt
`of_tab (string as_id)` | Auf einem Handle einer kontextbezogenen Gruppe: Handle einer ihrer Registerkarten
`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
`of_set_redraw (boolean)` | Fasst eine Salve von Änderungen zu einer einzigen Darstellung zusammen
`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
`of_save_as_png (string)` · `of_save_as_jpg (string)` | Exportiert die Darstellung als Bild

## 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_tab, string as_group, string as_id)` | Auf eine Schaltfläche, eine große Schaltfläche, den Hauptteil einer geteilten Schaltfläche oder einer Farbauswahl wird geklickt
`ue_toggled (string as_tab, string as_group, string as_id, boolean ab_checked)` | Ein Umschalter oder ein Kontrollkästchen wechselt den Zustand; `ab_checked` trägt den neuen Zustand
`ue_menu_selected (string as_tab, string as_group, string as_dropdown, string as_id, boolean ab_checked)` | Ein Eintrag eines Dropdown-Menüs wird gewählt. `as_dropdown` = das tragende Steuerelement, `as_id` = der Eintrag, `ab_checked` = der Zustand eines anhakbaren Eintrags
`ue_combo_changed (string as_tab, string as_group, string as_id, string as_text)` | Ein Kombinationsfeld wechselt den Wert, durch Auswahl oder durch Eingabe
`ue_value_changed (string as_tab, string as_group, string as_id, double ad_value)` | Ein numerisches Drehfeld wechselt den Wert
`ue_color_changed (string as_tab, string as_group, string as_id, long al_color)` | In einer Farbauswahl wird eine Farbe gewählt
`ue_gallery_selection_changed (string as_tab, string as_group, string as_id, string as_from_item, string as_item)` | Eine Galeriekachel wurde übernommen. Dieselben Argumente wie `ue_gallery_selection_changing`: Frage und Ergebnis lesen sich gleich, und `as_from_item` ist die verlassene Kachel
`ue_gallery_selection_changing (string as_tab, string as_group, string as_id, string as_from_item, string as_item)` → boolean | Abbrechbar, wird vor der Übernahme der Kachel gestellt. Standardmäßig ausgelöst; `ib_veto_gallery = false` entfernt sie. `as_from_item` 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_tab, string as_group)` | Auf den Starterpfeil einer Gruppe wird geklickt — öffnen Sie Ihr Optionsfenster
`ue_selection_changed (string as_id)` | 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_id)` | 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
    n_pbt_ribbon_tab   lnv_onglet
    n_pbt_ribbon_group lnv_groupe
    n_pbt_ribbon_item  lnv_item

    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(/*id*/ "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", /*id*/ "sous_pdf", "PDF-Dokument", "")
    uo_ruban.of_add_app_menu_item(/*parent*/ "enr_sous", /*id*/ "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(/*id*/ "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
    lnv_onglet = uo_ruban.of_add_tab("accueil", "Start")
    lnv_onglet.is_keytip = "S"

    lnv_groupe = lnv_onglet.of_add_group("presse_papier", "Zwischenablage")
    lnv_item = lnv_groupe.of_add_big_split("coller", "Einfügen", "mono:img\paste.svg")
    lnv_item.of_add_menu_item("coller_texte", "Ohne Formatierung einfügen", "")
    lnv_item.of_add_menu_item("coller_lien", "Als Verknüpfung einfügen", "")
    lnv_groupe.of_add_button("couper", "Ausschneiden", "mono:img\cut.svg")
    lnv_groupe.of_add_button("copier", "Kopieren", "mono:img\copy.svg")
    lnv_groupe.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_tab, string as_group, string as_id)
    // 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_group + "/" + as_id
        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_tab("accueil").of_group("presse_papier").of_item("coller").ib_enabled = of_presse_papier_non_vide()
    uo_ruban.of_tab("accueil").of_group("outils").of_item("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_tab("accueil").of_group("presse_papier").of_item("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
    n_pbt_ribbon_ctx_group lnv_ctx
    n_pbt_ribbon_tab       lnv_onglet
    n_pbt_ribbon_group     lnv_groupe

    // Ohne Farbe folgt das Banner dem Akzent des Designs ; RGB(...) erzwingt sie
    lnv_ctx = uo_ruban.of_add_contextual_group(/*id*/ "img", /*titel*/ "Bildtools", &
                                               /*farbe*/ RGB(224, 32, 96))
    lnv_onglet = lnv_ctx.of_add_tab("format", "Format")
    lnv_groupe = lnv_onglet.of_add_group("ajuster", "Anpassen")
    lnv_groupe.of_add_big_button("rogner", "Zuschneiden", "mono:img\crop.svg")
    lnv_groupe.of_add_button("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 #

    n_pbt_ribbon_group lnv_groupe
    n_pbt_ribbon_item  lnv_item

    lnv_groupe = uo_ruban.of_tab("accueil").of_add_group("police", "Schriftart")

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

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

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

    // Katalog von Formatvorlagen : scrollende bebilderte Kacheln
    lnv_item = lnv_groupe.of_add_gallery(/*id*/ "styles", /*breite_px*/ 220, &
                                         /*kachelbreite*/ 64, /*kachelhoehe*/ 48)
    lnv_item.of_add_gallery_item("st_normal", "img\style-normal.png", "Standard")
    lnv_item.of_add_gallery_item("st_titre",  "img\style-titre.png",  "Titel")
    lnv_item.of_add_gallery_item("st_note",   "img\style-note.png",   "Notiz")
    lnv_item.of_add_gallery_item("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.
    lnv_item.ii_visible_items = 4

    lnv_item.of_select_item("st_normal")

    // Event ue_value_changed von uo_ruban : (string as_tab, string as_group, string as_id, double ad_value)
    if as_id = "taille" then of_appliquer_taille(ad_value)

    // Event ue_color_changed von uo_ruban : (string as_tab, string as_group, string as_id, long al_color)
    if as_id = "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_tab, string as_group, string as_id, string as_from_item, string as_item)
    // FALSE zurueckzugeben behaelt die aktuelle Miniatur (as_from_item) bei.
    if as_item = "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_tab("accueil").of_group("police").ib_launcher = true

    // Event ue_launcher von uo_ruban : (string as_tab, string as_group)
    // Der Pfad benennt die Gruppe : das passende Optionsfenster wird geoeffnet.
    choose case as_group
        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_tab("accueil").of_group("presse_papier").of_item("copier").is_keytip = "C"
    uo_ruban.of_tab("accueil").of_group("presse_papier").of_item("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 #

    n_pbt_ribbon_item lnv_item

    lnv_item = uo_ruban.of_tab("accueil").of_group("presse_papier").of_item("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.

← Komponentenreferenz · Inhalt des Handbuchs