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 #

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 #

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.

Eigenschaften einer Gruppe — n_pbt_ribbon_group #

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

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.

Eigenschaften eines Menüeintrags — n_pbt_ribbon_menu_item #

Über of_tab(id).of_group(id).of_item(id).of_menu_item(id) erhalten.

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.

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 #

Menüs und Listen füllen #

Alle diese Methoden werden auf dem Handle eines Steuerelements aufgerufen.

Anwendungsmenü und Symbolleiste für den Schnellzugriff #

Kontextbezogene Registerkarten #

Gemeinsame #

Events #

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

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