commandpalette — `n_pbt_commandpalette` #

← Komponentenreferenz · Inhalt des Leitfadens

Befehlspalette: Der Benutzer drückt ein Tastenkürzel, tippt drei Buchstaben und erreicht jede Aktion Ihrer Anwendung — ohne sie in den Menüs zu suchen.

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

Auf einen Blick #

Objekt	`n_pbt_commandpalette` — nicht visuell: nichts im Fenster zu platzieren
Dient zu	Jede Aktion der Anwendung über die Tastatur erreichbar machen, mit drei Buchstaben
Rückgabe	Nicht blockierend: `of_open()` kehrt sofort zurück; die Auswahl kommt als Event zurück

Die Palette ist ein eigenes, losgelöstes Fenster: Sie schwebt über Ihrer Anwendung, nimmt den Fokus, solange der Benutzer tippt, und gibt ihn beim Schließen zurück.

Schnellstart #

// Einmalig, beim Start : die Aktionen Ihrer Anwendung
inv_palette.ipo_owner = this
inv_palette.of_add_command(/*key*/ "new",  /*label*/ "N", /*group*/ "F")
inv_palette.of_add_command(/*key*/ "open", /*label*/ "O", /*group*/ "F")
inv_palette.of_add_command(/*key*/ "save", /*label*/ "S", /*group*/ "F")
inv_palette.of_register_shortcut()

// event ue_command_selected : (string as_key)
choose case as_key
	case "new";  of_new()
	case "open"; of_open()
	case "save"; of_save()
end choose

Die Verdrahtung: das Hostfenster #

Die Palette ist ein nicht visuelles Objekt, aber Sie haben keinen Empfänger und keine Nachricht zu verdrahten: Setzen Sie ipo_owner auf Ihr Fenster, und die Palette holt ihre Events selbst ab und löst sie an diesem Objekt aus.

Zwei Zeilen, einmalig, beim Öffnen des Fensters:

// Das Fenster, zu dem die Palette gehoert
inv_palette.ipo_owner = this

// Die Palette muss auf ihre Taste antworten
inv_palette.of_register_shortcut()

Mehr ist nicht zu verdrahten. Die Auswahl des Benutzers, das Öffnen und das Schließen kommen danach als schlichte Events an ipo_owner zu Ihnen zurück — kein Empfänger, keine zu mappende Nachricht, kein Timer.

Das Tastenkürzel: die DLL ist es, die es hört #

Das Tastenkürzel, das die Palette öffnet, wird nicht von der Seite abgehört: es wird bei der DLL registriert, die als Einzige die Tasten sieht, während der Fokus auf einem anderen Steuerelement liegt. Genau das ist der Unterschied zwischen einer Palette, die man findet, und einer, die erst antwortet, wenn man sie schon angeklickt hat.

Die DLL hört das Kürzel, öffnet aber von sich aus nichts: Sie meldet es über ue_shortcut, und Sie entscheiden. Eine Palette, die sich über einem modalen Dialog öffnet, hilft niemandem.

// event ue_shortcut : die Taste ist gefallen
if not ib_dialog_open then inv_palette.of_open()

is_shortcut wählt das Kürzel; of_register_shortcut() übergibt es. Rufen Sie es einmal beim Öffnen des Fensters auf — sonst antwortet die Palette erst, nachdem sie schon einmal geöffnet wurde. of_open übergibt es nebenbei erneut, ein später geändertes Kürzel braucht also nichts weiter.

// Das gewohnte Kuerzel, das der Code-Editoren
inv_palette.is_shortcut = inv_palette.SHORTCUT_DEFAULT

// Oder Ihres
inv_palette.is_shortcut = "ctrl+shift+p"

// Oder keines: die Palette oeffnet dann nur ueber of_open()
inv_palette.is_shortcut = inv_palette.SHORTCUT_NONE

Das Kürzel der Palette wird erst nach den Tastenkürzeln der anderen Komponenten des Fensters geprüft, mit oder ohne Fokus: eine Symbolleistenschaltfläche mit demselben Kürzel gewinnt. Das Kürzel dieses Fensters geht einem ohne ipo_owner registrierten Kürzel (ganze Anwendung) vor. Nur Tasten, die der Hook benennen kann, werden angenommen — Buchstaben, Ziffern, F1 bis F24, Eingabe, Esc, Entf, Einfg, Pos1, Ende, Bild auf, Bild ab und, mit Strg oder Alt, die Pfeile, Leertaste, Tab, Rücktaste, + - , .; jede andere liefert -5. Das Tastaturkapitel führt es aus.

Wo die Palette erscheint #

is_position sagt, wo das Fenster landet. Es wird immer in den Bildschirm zurückgeholt: eine Palette, die unter einem Feld am unteren Fensterrand verankert ist, verschwindet nicht hinter der Taskleiste.

Konstante	Wohin
`POSITION_WINDOW_CENTER`	Auf `ipo_owner` zentriert — der Standard, und was das Auge erwartet
`POSITION_SCREEN_CENTER`	Auf dem Bildschirm zentriert, unabhängig vom Fenster
`POSITION_ABSOLUTE`	Bei `il_x` / `il_y`, in Bildschirmpixeln

PowerBuilder rechnet in PBU, und die Position eines Steuerelements ist relativ zu seinem Fenster: um die Palette unter einem Steuerelement zu verankern, erledigt of_anchor_under(Steuerelement) die Umrechnung und setzt alle drei Eigenschaften. Bei zwei Bildschirmen öffnet sie sich auf dem Bildschirm des angeforderten Punkts.

Ihre Höhe richtet sich nach der Anzahl der angezeigten Befehle und schrumpft beim Filtern — ohne dass die obere Ecke wandert, sonst würde das Suchfeld unter den Fingern wegrutschen. Sie ist auf den halben Bildschirm begrenzt: darüber hinaus scrollt die Liste im Innern, und das Suchfeld bleibt oben.

Ein Klick woanders in der Anwendung schließt die Palette, und dieser Klick erreicht sein Ziel trotzdem — wie beim Verlassen eines Menüs. Dafür ist nichts zu tun.

Eigenschaften #

Eigenschaft	Typ	Standard	Rolle
`ipo_owner`	powerobject	—	Das Fenster, zu dem die Palette gehört: es besitzt das Popup-Fenster und verankert es, sein Kürzel antwortet in diesem Fenster, und die Events der Palette werden an ihm ausgelöst. Vor `of_open` setzen — es ist die einzige Verdrahtung. Leer gelassen, antwortet das Kürzel in allen Fenstern der Anwendung. Zwei Palettenobjekte auf demselben Fenster behalten jedes ihr eigenes Kürzel und ihre eigenen Events: keines erhält die des anderen
`ipo_receiver`	powerobject	—	Optional, veraltet: ein separates visuelles Objekt, an das die Events geliefert werden, anstelle von `ipo_owner` — es ist auch das einzige Fenster, dessen `pbm_custom02` bei jedem Event ausgelöst wird. Lassen Sie es leer — die Palette liefert ihre Events jetzt selbst über `ipo_owner`
`is_shortcut`	string	`"ctrl+k"`	Tastenkürzel, das die Palette von überall im Fenster öffnet. Konstanten `SHORTCUT_DEFAULT` (`ctrl+k`) und `SHORTCUT_NONE` (keines). Wirkt bei `of_register_shortcut`
`is_position`	string	`window-center`	Wo das Fenster landet (`POSITION_*`-Konstanten)
`il_x` · `il_y`	long	`0`	Position in Bildschirmpixeln, nur von `POSITION_ABSOLUTE` gelesen
`is_placeholder`	string	`""`	Grauer Text im Suchfeld, solange nichts getippt wurde
`is_recent`	string	`""`	Nutzungsgedächtnis: die zuletzt gestarteten ids, neueste zuerst, kommagetrennt. Die Palette holt sie nach oben, und die Aktualität entscheidet Gleichstände beim Filtern — sie überstimmt nie die Treffergüte. Nach Gebrauch auslesen und speichern, beim Start zurückgeben. Eine Palette, die jeden Morgen leer beginnt, lernt nichts
`il_max_recent`	long	`8`	Wie viele Einträge der Block « Zuletzt verwendet » hält. Standard `8`. `0` schaltet ihn ab: eine Anwendung, deren Benutzer ihre Gruppen lieber unangetastet sehen, darf das sagen. Ein Eintrag des Blocks bleibt in seiner Gruppe und trägt deren Namen — eine Abkürzung verschiebt nicht, worauf sie abkürzt

Methoden #

Methode	Rolle
`of_add_command (string as_key, string as_label, string as_group)`	Deklariert eine Aktion: ihren Bezeichner, ihre Beschriftung und die Gruppe, unter der sie erscheint. Liefert `0` nach dem Hinzufügen, `-5` wenn der Schlüssel leer ist, `/`, `	`oder ein Komma enthält (`is_recent` ist eine kommagetrennte Liste) oder schon vergeben ist. Zehntausende von Befehlen bleiben flüssig: die Palette zeichnet nur die sichtbaren Zeilen
`of_add_command (string as_key, string as_label, string as_group, string as_hint, string as_shortcut, string as_keywords)`	Dasselbe, mit dem Hinweis rechts, dem anzuzeigenden Kürzel, das seinen Befehl ausführt, solange die Palette offen ist — so lernt man es ; außerhalb behält Ihre Anwendung ihre eigenen Tastenkombinationen, und beim Tippen bleiben `Ctrl+C`, `Ctrl+V`, `Ctrl+Z` und `Ctrl+A` beim Suchfeld — und Schlüsselwörtern, die die Suche liest, ohne sie zu zeigen. Liefert `0` nach dem Hinzufügen, `-5` wenn der Schlüssel leer ist, `/`, `	`oder ein Komma enthält (`is_recent` ist eine kommagetrennte Liste) oder schon vergeben ist
`of_insert_command (string as_key, string as_label, string as_group, integer ai_index)`	Deklariert eine Aktion an einer gewählten Position (1 = zuerst) statt am Ende: ein gemeinsames Modul ordnet seine Befehle dort ein, wo sie hingehören. `0` oder weniger, oder hinter dem Ende, hängt an. Hinweis, Kürzel, Schlüsselwörter und Symbol werden danach über `of_command` gesetzt. Liefert `0` nach dem Hinzufügen, `-5` für dieselben Schlüssel wie `of_add_command`
`of_remove_command (string as_key)`	Entfernt eine Aktion; die anderen bleiben. Liefert `0` nach dem Entfernen, `-5` wenn kein Befehl diesen Schlüssel trägt
`of_command (string as_key)` → `n_pbt_commandpalette_command`	Das Handle eines Befehls, um ihn umzubenennen, sein Kürzel zu ändern, ihn auszugrauen oder zu verbergen – über seine Eigenschaften. Ausgrauen statt entfernen: was der Benutzer gerade nicht tun kann zu entfernen, nimmt ihm auch jede Chance zu entdecken, dass es existiert. Der Zustand reist mit den Befehlen: eine Änderung bei offener Palette zeigt sich beim nächsten Öffnen
`of_key ( )` → `string`	Auf dem Handle, das `of_command` liefert: der Schlüssel des Befehls, den es bezeichnet — was `of_command` erhalten hat, um es zu holen, und was man behält, wenn das Handle weitergereicht wird
`of_clear_commands ( )`	Leert die Palette. Liefert `0`
`of_count ( )` → `long`	Liefert die Anzahl der Befehle, die die Palette trägt
`of_keys_at ( long al_index )` → `string`	Die Kennung des Befehls an Position `al_index` (ab 1), oder `""` jenseits beider Enden. Zusammen mit `of_count` lässt sich so eine Palette durchlaufen, die man nicht selbst gefüllt hat — ein gemeinsames Modul fügt seine eigenen hinzu
`of_has ( string as_key )` → `boolean`	Gibt es einen Befehl unter dieser Kennung? Fragen ist besser als raten: `of_add_command` lehnt (`-5`) eine bereits vergebene Kennung ab
`of_anchor_under ( dragobject ado_control )`	Verankert die Palette unter einem Steuerelement — einem Feld, einer Schaltfläche: setzt `is_position` auf `POSITION_ABSOLUTE` und `il_x` / `il_y` auf die linke untere Ecke des Steuerelements, in Bildschirmpixeln. Vor `of_open` aufrufen; die Palette wird weiterhin in den Bildschirm zurückgeholt. Liefert `0`, oder `-5`, wenn das Steuerelement ungültig ist
`of_open ( )`	Öffnet die Palette: ein eigenes Fenster, im Besitz von `ipo_owner`, platziert durch `is_position`. Sie nimmt den Fokus und gibt ihn beim Schließen zurück. Liefert `0` nach der Anforderung — `ue_opened` (sichtbar) oder `ue_closed` (mit dem Grund, warum sie nie erschien) folgt immer —, `-6` wenn die WebView2-Laufzeit fehlt, `-4` wenn ihr Fenster nicht erzeugt werden konnte
`of_is_open ( )`	TRUE, solange die Palette auf dem Bildschirm ist. Genau das lässt das Kürzel umschalten: ein zweiter Druck schließt eine Palette — ein erneutes `of_open` würde das Fenster zerstören und identisch neu aufbauen, was als Flackern erscheint, nicht als Schließen. Die DLL entscheidet weiterhin nichts: sie informiert. Einmal offen, hält die Palette den Fokus in ihrem eigenen Fenster: das dort gedrückte Kürzel schließt sie von selbst. Es antwortet für die Palette dieses Objekts: öffnet ein anderes Palettenobjekt seine eigene, ersetzt diese die hiesige und `of_is_open` antwortet hier FALSE
`of_close ( )`	Schließt die Palette, die dieses Objekt geöffnet hat — nie die eines anderen Palettenobjekts. Der Verlust des Fokus schließt sie ebenfalls, wie ein Menü. Liefert `0`
`of_register_shortcut ( )`	Übergibt das Kürzel aus `is_shortcut` an die DLL. Einmal beim Öffnen des Fensters aufrufen. Ein Kürzel pro Palettenobjekt: ein erneuter Aufruf nach dem Ändern von `is_shortcut` ersetzt das vorige, das sofort nicht mehr antwortet — es ist nie etwas vorher zu entfernen. Liefert `0` beim Setzen, `1` beim Ersetzen, `2` wenn ein leeres `is_shortcut` kein Kürzel übrig lässt (entfernt, oder es gab keines), `-5` wenn die Taste eine ist, die der Hook nicht sieht (siehe oben) — das vorige Kürzel bleibt dann bestehen. Ohne `ipo_owner` antwortet das Kürzel in allen Fenstern der Anwendung. Zwei Palettenobjekte eines Fensters behalten jedes ihr eigenes; dasselbe Kürzel, von einem zweiten Objekt registriert, geht an dieses (`1`). Das Zerstören des Objekts entfernt sein Kürzel — nie das, das ein anderes Palettenobjekt hält
`of_process_events ( )`	Holt die wartenden Events ab und löst sie an `ipo_owner` aus. Die Komponente ruft sie selbst auf, solange die Palette lebt: Normalerweise müssen Sie das nicht tun
`of_reset ( )`	Leert die Befehle und das Nutzungsgedächtnis (`is_recent`), setzt die Eigenschaften auf ihre Standardwerte zurück, schließt eine offene Palette und setzt ein registriertes Kürzel auf `SHORTCUT_DEFAULT` zurück. `ipo_owner` und `ipo_receiver` bleiben unberührt: sie sind die Verdrahtung, nicht der Inhalt

Eigenschaften eines Befehls — `n_pbt_commandpalette_command` #

Erhalten über of_command(Schlüssel). Die Palette baut ihr Fenster bei jedem of_open aus ihrer Liste neu auf: eine Eigenschaft, die geändert wird, während sie offen ist, zeigt sich beim nächsten Öffnen.

Eigenschaft	Typ	Standard	Rolle
`is_label`	string	—	Der Text der Zeile
`is_shortcut`	string	`""`	Das rechts in der Zeile gezeigte Kürzel, das gilt, solange die Palette offen ist (`Ctrl+Shift+S`)
`is_group`	string	—	Die Gruppe, unter der der Befehl steht; eine Änderung verschiebt ihn, ohne ihn zu entfernen (er behält seine Position unter den Befehlen)
`is_hint`	string	`""`	Die kleine Zeile unter der Beschriftung
`is_keywords`	string	`""`	Die Wörter, die die Suche liest, ohne sie zu zeigen — die Wörter des Benutzers
`is_icon`	string	`""`	Ein Symbol links in der Zeile: eine Datei, ein Bibliotheksbild oder `mono:` / `tint:` für eines, das dem Design folgt
`ib_enabled`	boolean	`true`	Befehl ausgegraut: sichtbar, suchbar und inaktiv – weder Klick, Eingabe noch sein Kürzel
`ib_visible`	boolean	`true`	Befehl verborgen: aus der Liste und den Kürzeln genommen, ohne entfernt zu werden; er kommt unverändert zurück

Events #

Event	Ausgelöst, wenn
`ue_command_selected (string as_key)`	Der Benutzer hat eine Aktion gewählt. Die Palette ist bereits geschlossen: das Angekündigte zu tun, liegt bei Ihnen
`ue_shortcut ( )`	Das Kürzel wurde gedrückt. Die DLL meldet, PB entscheidet. Eine Palette schaltet auf ihrer eigenen Taste um: `if of_is_open() then of_close() else of_open()` — in der offenen Palette gedrückt, schließt das Kürzel sie von selbst. Sie dürfen auch ablehnen
`ue_opened ( )`	Die Palette ist auf dem Bildschirm — über `of_open`
`ue_closed (string as_reason)`	Sie hat sich gerade geschlossen, ob etwas gewählt wurde oder nicht. Folgt jedem `of_open`, das `0` geliefert hat: `as_reason` ist leer für eine Palette, die sichtbar war, `cancelled`, wenn sie geschlossen — oder durch eine andere Palette ersetzt — wurde, bevor sie erschien, `failed`, wenn ihr Fenster nicht entstehen konnte, `blocked` bei Remote-Debugging ohne Lizenz

Die Palette tut von sich aus nichts. Sie meldet den gewählten Bezeichner und schließt sich. Handeln muss Ihre Anwendung — dieselbe Aktion, aus einem Menü oder aus der Palette ausgelöst, läuft also über denselben Code.

Über die Tastatur #

Taste	Wirkung
Das Kürzel aus `is_shortcut`	Meldet es Ihrem Code über `ue_shortcut`; dieser öffnet
Tippen	Filtert während der Eingabe: die Buchstaben müssen nicht aufeinanderfolgen, `ndt` findet „Neues Dokument“, und Akzente zählen nicht (`preferences` findet « Préférences »)
Pfeile hoch / runter	Verschieben die Auswahl in der Liste
Eingabetaste	Wählt die markierte Aktion (`ue_command_selected`)
Das auf einer Zeile angezeigte Kürzel	Führt diesen Befehl aus, ohne ihn erst auswählen zu müssen
Escape	Schließt, ohne etwas zu wählen

Beispiele #

Die Palette aus Ihrem Menü füllen #

// Schluesselwoerter werden nicht angezeigt, die Suche liest sie aber :
// "pdf" findet den Export, auch wenn die Beschriftung es nie sagt
inv_palette.of_add_command(/*key*/ "export", /*label*/ "E", /*group*/ "F", /*hint*/ "H", /*shortcut*/ "Ctrl+E", /*keywords*/ "pdf csv xlsx")

Ein anderes Tastenkürzel wählen #

// Ctrl+K schon von Ihrer Anwendung belegt ? Waehlen Sie ein anderes.
// of_register_shortcut uebergibt es, das alte geht von selbst.
inv_palette.is_shortcut = "ctrl+shift+p"
inv_palette.of_register_shortcut()

Sie unter einem Feld verankern #

// Unter einem Eingabefeld verankert, in Bildschirmpixeln
// Die Palette wird in den Bildschirm zurueckgeholt, wenn sie ueberstand
inv_palette.of_anchor_under(/*control*/ sle_1)
inv_palette.is_placeholder = "P"
inv_palette.of_open()

// Remove one command, empty the list, close the palette
inv_palette.of_remove_command(/*key*/ "print")
inv_palette.of_clear_commands()
inv_palette.of_close()

Best Practices #

Geben Sie jedem Befehl denselben Bezeichner wie im Menü: eine einzige Funktion bedient beide, und der Benutzer bekommt genau dasselbe.
Rufen Sie of_register_shortcut() beim Öffnen des Fensters auf, nicht beim ersten of_open: eine Palette, die erst nach dem Öffnen per Maus auf ihre Taste hört, nützt nichts.
Füllen Sie die Schlüsselwörter aus: das unterscheidet eine genutzte Palette von einer, in der man nie etwas findet. Denken Sie an die Wörter des Benutzers, nicht an Ihre.
Zeigen Sie das Kürzel der Aktion in as_shortcut: die Palette wird so zum Weg, sie zu lernen.
Nehmen Sie nur sofortige Aktionen auf. Ein Befehl, der einen Einstellungsdialog öffnet, ja; einer, der drei Parameter braucht, nein.
Entfernen Sie Befehle, die keinen Sinn mehr ergeben, statt sie scheitern zu lassen: eine Palette, die Unmögliches anbietet, verliert das Vertrauen auf einen Schlag.