buttonbar — u_pbt_buttonbar #
← Komponentenreferenz · Inhalt des Handbuchs
buttonbar ordnet eine Reihe von Befehlsschaltflächen — Symbol, Beschriftung oder beides — in einer Komponente an. Ein Klick meldet den Schlüssel der Schaltfläche (
ue_clicked); jeder Button wird über ein Handle (of_button) gesteuert, um ihn zu deaktivieren, zu färben oder auszublenden. Die zu bevorzugende Komponente, sobald es mehrere Schaltflächen gibt: ein WebView2 für die ganze Leiste statt N einzelnerbutton.
▶ Live sehen — Demoanwendung, Kachel Button bar, mit dem Code und dieser Seite nebeneinander.
Schnellstart #
// A command bar in three lines : key, label, icon
// ("&Save" underlines the S : Alt+S fires the button from anywhere in the window)
uo_bar.of_add_button(/*key*/ "save", /*text*/ "&Save", /*image*/ "mono:img\packimages.dll:svg/samples/save")
uo_bar.of_add_button(/*key*/ "find", /*text*/ "&Find", /*image*/ "mono:img\packimages.dll:svg/samples/find")
uo_bar.of_add_button(/*key*/ "copy", /*text*/ "&Copy")
// A chord : Ctrl+S fires Save, whatever control has the focus
uo_bar.of_button(/*key*/ "save").is_shortcut = "Ctrl+S"
// Grey out a button
uo_bar.of_button(/*key*/ "copy").ib_enabled = false
// React : ue_clicked carries the button key
// (in the ue_clicked event of the component)
CHOOSE CASE as_key
CASE "save" ; wf_save()
CASE "find" ; wf_find()
END CHOOSEEigenschaften #
| Eigenschaft | Typ | Standard | Beschreibung |
|---|---|---|---|
ib_enabled | boolean | true | Die ganze Leiste aktiv oder deaktiviert. Deaktiviert antwortet keine Schaltfläche — weder Klick noch Enter, Esc, Alt+Buchstabe oder Tastenkürzel: diese Tasten bleiben beim Fenster — und die Leiste verlässt die Tab-Reihenfolge. Jede Schaltfläche behält ihr eigenes ib_enabled |
ii_padding_x | integer | 12 | Linker/rechter Abstand der Leiste, in Pixeln: der Raum vor der ersten und nach der letzten Schaltfläche. 0 drückt die Schaltflächen an die Ränder; -1 = der des Designs |
ii_padding_y | integer | 12 | Oberer/unterer Abstand der Leiste, in Pixeln. Eine Schaltfläche FÜLLT die Höhe der Leiste: dieser Abstand bestimmt also die Höhe der Schaltflächen (höhere Leiste oder kleinerer Abstand = höhere Schaltflächen). Standard 12; -1 = der des Designs |
ii_gap | integer | -1 | Abstand ZWISCHEN zwei Schaltflächen, in Pixeln. -1 (Standard) = der des Designs. 0 fügt die Schaltflächen zusammen, mit einer Trennlinie, wenn das Design eine hat |
ii_image_size | integer | 0 | Größe der Schaltflächensymbole, in Pixeln; 0 = die des Designs (18) |
ii_badge_size | integer | 0 | Höhe der Plaketten, in Pixeln — ihr Text folgt; 0 = die des Designs (16) |
is_align | string | end | Richtet die Reihe aus: start (links), center, end (rechts, Standard, wie ein Dialog) oder justify (gleich breite Schaltflächen über die ganze Breite). Logische (RTL-fähige) Werte — Konstanten ALIGN_* |
is_default | string | "" | Schlüssel der Standard-Schaltfläche — die primäre Aktion, mit dem Akzent gefärbt, die Enter auslöst (wie das OK eines Dialogs). Hat eine Schaltfläche der Leiste den Tastaturfokus, löst Enter DIESE Schaltfläche aus, die dann das Standard-Aussehen trägt (Windows-Konvention); is_default liefert weiterhin den gesetzten Schlüssel. Ohne Standardschaltfläche behält die fokussierte Schaltfläche nur ihren Fokusrahmen. Eine deaktivierte oder ausgeblendete Standardschaltfläche nimmt Enter nicht an: die Taste bleibt beim Fenster — sie geht nie an die Standardschaltfläche einer ANDEREN Leiste, selbst wenn diese allein ist. Haben zwei Leisten desselben Fensters eine Standardschaltfläche (zwei MDI-Blätter, zwei Bereiche), geht Enter an die auf der Seite des Fokus. Die Rolle geht mit ihrer Schaltfläche: sie zu entfernen oder die Leiste zu leeren, leert is_default. Leer = keine; immer nur eine Standardschaltfläche |
is_cancel | string | "" | Schlüssel der Abbrechen-Schaltfläche — diejenige, die Esc auslöst (wie das Abbrechen eines Dialogs). Deaktiviert oder ausgeblendet nimmt sie Esc nicht an. Die Rolle geht mit ihrer Schaltfläche: sie zu entfernen oder die Leiste zu leeren, leert is_cancel. Leer = keine; immer nur eine Abbrechen-Schaltfläche |
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 |
Methoden #
| Methode | Rolle |
|---|---|
of_add_button (string as_key, string as_text {, string as_image}) → long | Fügt am Ende der Leiste eine Befehlsschaltfläche hinzu: ihren Schlüssel, ihre Beschriftung und wahlweise ihr Symbol (Bilddatei; mono: färbt es im Design ein). Die Beschriftung akzeptiert Rich-Markup; &Save unterstreicht das S und lässt Alt+S die Schaltfläche auslösen, && ist ein wörtliches &. Eine leere Beschriftung ergibt eine reine Symbolschaltfläche. Liefert 0, -5 bei einem leeren Schlüssel, einem Schlüssel mit / oder senkrechtem Strich, einem schon vorhandenen Schlüssel oder einer Schaltfläche ohne Bild und Text |
of_insert_button (string as_key, string as_text, string as_image, integer ai_index) → long | Fügt eine Befehlsschaltfläche an Position ai_index ein (ab 1) und verschiebt die folgenden; hinter der letzten kommt sie ans Ende, bei 0 oder weniger an den Anfang. Liefert 0, -5 bei einem leeren Schlüssel, einem Schlüssel mit / oder senkrechtem Strich, einem schon vorhandenen Schlüssel oder einer Schaltfläche ohne Bild und Text |
of_remove_button (string as_key) → long | Entfernt eine Schaltfläche über ihren Schlüssel; die übrigen behalten ihren Zustand. Ihr Alt+Buchstabe, die Kürzel, die die Anwendung ihr gab, ihre Standard-/Abbrechen-Rolle, ihre Farben und ihr Tooltip gehen mit. Liefert 0, -5 bei leerem Schlüssel oder einem Schlüssel, der keine Schaltfläche nennt |
of_move_button (string as_key, integer ai_index) → long | Verschiebt eine Schaltfläche an Position ai_index (1-basiert; hinter der letzten = am Ende, 0 oder weniger = am Anfang), ohne ihren Zustand zu verlieren. Liefert 0, -5 bei leerem Schlüssel oder einem Schlüssel, der keine Schaltfläche nennt |
of_clear_buttons ( ) → long | Entfernt alle Schaltflächen der Leiste, samt Alt+Buchstaben, den Kürzeln, die die Anwendung ihnen gab, den Standard-/Abbrechen-Rollen, Farben und Tooltips. Liefert 0, -2 wenn nicht erzeugt |
of_clear_shortcuts ( ) → long | Entfernt das Kürzel ALLER Schaltflächen: es antwortet nicht mehr, erscheint nicht mehr im Tooltip, und is_shortcut liefert leer. Die Alt+Buchstaben bleiben. Liefert 0, -2 wenn nicht erstellt |
of_focus_button (string as_key) → long | Setzt den Tastaturfokus auf EINE Schaltfläche — Nein statt Ja bei einer zerstörenden Frage, damit Enter mit Nein antwortet. Liefert 0, -5 bei leerem Schlüssel oder einem, der keine Schaltfläche nennt, -4 wenn die Schaltfläche ihn nicht annehmen kann (deaktiviert, ausgeblendet, in einer deaktivierten Leiste oder im Demomodus nicht gezeichnet), -2 wenn nicht erzeugt |
of_register_shortcut (string as_chord, string as_key) → long | Gibt EINER Schaltfläche ein Tastenkürzel (Ctrl+S, F5…), wie ihr is_shortcut: irgendwo im Fenster gedrückt, löst es die Schaltfläche aus (ue_clicked), auch wenn der Fokus anderswo liegt, und es erscheint in ihrem Tooltip. Es ist unabhängig vom Alt+Buchstaben der Schaltfläche. Solange die Schaltfläche nicht auslösen kann (deaktiviert, ausgeblendet, nicht gezeichnet), bleibt die Taste beim Fenster. Ein leeres Kürzel entfernt es. Auf einer Leiste benennt ein Kürzel immer eine Schaltfläche: die Form mit einem Argument oder ein Schlüssel ohne Schaltfläche liefert -5; ein Kürzel, das das Fenster nie auslösen kann (ein Buchstabe allein, Ctrl+Shift), liefert -5 und behält das vorhandene Kürzel. Liefert 0, -2 wenn nicht erstellt |
of_button (string as_key) → n_pbt_buttonbar_button | Liefert das Handle einer Schaltfläche (über ihren Schlüssel), um ihre Eigenschaften zu lesen oder zu ändern (siehe unten). Ein Schlüssel ohne Schaltfläche erhält ein gemeinsames neutrales Handle: was man ihm gibt, geht nirgendwohin. of_count, of_keys_at und of_has zählen auch die ausgeblendeten Schaltflächen |
Ereignisse #
| Ereignis | Wann |
|---|---|
ue_clicked (string as_key) | Eine Schaltfläche wurde benutzt: ein Klick, Enter (die Standardschaltfläche oder die fokussierte), Esc (die Abbrechen-Schaltfläche), ihr Alt+Buchstabe oder ein auf ihr registriertes Kürzel. Ihr Schlüssel wird übergeben: eine Anwendung, die Abbrechen verdrahtet, muss es auch über Esc erwarten. Eine deaktivierte Schaltfläche sendet nichts |
ue_button_rclicked (string as_key, long al_x, long al_y) | Rechtsklick auf EINE Schaltfläche, oder Menütaste auf der fokussierten, mit ihrem Schlüssel: der Ort, um das Menü dieser Schaltfläche zu öffnen. Eine deaktivierte Schaltfläche antwortet nicht. Es ist das einzige Ereignis dieses Rechtsklicks: ue_rclicked wird nicht zusätzlich ausgelöst; al_x, al_y: wo das Menü zu öffnen ist, in Bildschirmpixeln — der Zeiger, oder über die Tastatur (Menütaste, Umschalt+F10) die Ecke unten links der Schaltfläche; ein contextmenu öffnet sich dort unverändert (uo_menu.of_show(al_x, al_y)) |
ue_rclicked ( ) | Rechtsklick auf die Leiste AUSSERHALB jeder Schaltfläche. Ein Rechtsklick auf eine Schaltfläche löst nur ue_button_rclicked aus: ein in beiden geschriebenes Menü öffnet sich nie zweimal |
Eigenschaften einer Schaltfläche (of_button) #
| Eigenschaft | Typ | Standard | Beschreibung |
|---|---|---|---|
ib_enabled | boolean | true | Aktiviert oder deaktiviert eine Schaltfläche; deaktiviert lässt sie sich nicht anklicken und weder Enter, Esc, ihr Alt+Buchstabe noch ihr Kürzel lösen sie aus — diese Tasten bleiben beim Fenster; die Pfeiltasten überspringen sie |
ib_visible | boolean | true | Zeigt oder verbirgt eine Schaltfläche; verborgen behält sie ihren Platz und kehrt zurück |
is_text | string | "" | Die Beschriftung der Schaltfläche, Rich-Markup zulässig; nach dem Hinzufügen änderbar. &Save unterstreicht das S und lässt Alt+S die Schaltfläche von überall im Fenster auslösen, wie ein PowerBuilder-CommandButton; && ist ein wörtliches &. Eine Schaltfläche behält Beschriftung oder Symbol: die Beschriftung einer Schaltfläche ohne Symbol zu leeren wird abgelehnt, die Beschriftung liefert unverändert |
is_image | string | "" | Symbol der Schaltfläche (Bilddatei; mono: folgt dem Design); nach dem Hinzufügen änderbar. Das Symbol einer Schaltfläche ohne Beschriftung zu leeren wird abgelehnt. Eine reine Symbolschaltfläche wird einem Bildschirmleser über ihren Tooltip (is_tooltip) angesagt, sonst über ihren Schlüssel |
is_style | string | standard | Das Aussehen der Schaltfläche: standard, primary (der Akzentblock), flat (ohne Rahmen im Ruhezustand) oder danger (eine zerstörerische Aktion, in der Gefahrenfarbe des Designs) — Konstanten STYLE_*; ein unbekannter Wert liefert standard. Eine deaktivierte Schaltfläche verliert ihre Füllung |
is_badge | string | "" | Eine kleine Plakette in der Ecke der Schaltfläche: eine Zahl (3; über 99 zeigt sie 99+) oder ein kurzes Wort (New, !). "" oder 0 = keine. Ein Bildschirmleser hört sie mit dem Namen der Schaltfläche |
il_badge | long | 0 | Dieselbe Plakette als Zahl (0 = keine); eine Wort-Plakette liefert hier 0 |
il_badge_color | long | -1 | Farbe der Plakette DIESER Schaltfläche; -1 = die des Designs, 0 ist Schwarz. Der Text darauf wird so gewählt, dass er lesbar bleibt |
is_mnemonic | string | "" | Der Alt+Buchstabe der Schaltfläche, wenn es nicht das & ihrer Beschriftung ist — er hat Vorrang: ein Buchstabe oder eine Ziffer, das erste Vorkommen in der Beschriftung wird unterstrichen. Leer = das & der Beschriftung. Solange die Schaltfläche nicht auslösen kann, bleibt ihr Buchstabe beim Fenster |
is_shortcut | string | "" | Ein Tasten-KÜRZEL für diese Schaltfläche — Ctrl+S, F5, Ctrl+Shift+P: irgendwo im Fenster gedrückt, löst es die Schaltfläche aus und erscheint in ihrem Tooltip (Save (Ctrl+S)). Es liefert seine kanonische Form (ctrl+s); ein Kürzel, das das Fenster nie auslösen kann, wird abgelehnt und liefert leer. Wie of_register_shortcut(chord, key). Der Alt+Buchstabe ist das & der Beschriftung oder is_mnemonic |
il_back_color | long | -1 | Hintergrund DIESER Schaltfläche (-1 = der der Komponente, folgt dem Design) |
il_text_color | long | -1 | Textfarbe DIESER Schaltfläche (-1 = die der Komponente) |
il_back_color_hover | long | -1 | Hintergrund DIESER Schaltfläche beim Überfahren (-1 = der der Komponente) |
il_text_color_hover | long | -1 | Textfarbe DIESER Schaltfläche beim Überfahren (-1 = die der Komponente) |
il_accent | long | -1 | Akzent DIESER Schaltfläche: er färbt ihre Plakette und, wenn sie die Standardschaltfläche ist (oder im Stil primary), ihre Füllung (-1 = Akzent der Komponente) |
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 |
is_accessible_name · is_accessible_description | Name und Beschreibung, die ein Bildschirmleser sagt | 3.4 Optionale Eigenschaften und Events |