contextmenu — u_pbt_contextmenu #

← Komponentenreferenz · Inhalt des Handbuchs

Das Kontextmenü von Windows, im Design der Anwendung: eine kaskadierende Liste, die sich am Cursor, unter einem Steuerelement oder an einem Bildschirmpunkt öffnet — Symbole, angezeigte Tastenkürzel, Häkchen, Optionseinträge, Abschnittsüberschriften, lange Listen, die scrollen und auf Tippen reagieren.

▶ Live ansehen — Demoanwendung, Kachel Context menu: die Vorschau, der erzeugende Code und diese Seite nebeneinander.

Kurz gefasst #

Schnellstart #

// The menu of a grid : three commands, a separator, a cascade
uo_menu.of_add_item(/*keys*/ "copy", /*text*/ "&Copy")
uo_menu.of_add_item(/*keys*/ "paste", /*text*/ "&Paste")
uo_menu.of_add_item(/*keys*/ "delete", /*text*/ "&Delete")
uo_menu.of_add_separator(/*keys*/ "")
uo_menu.of_add_item(/*keys*/ "export", /*text*/ "&Export")
uo_menu.of_add_item(/*keys*/ "export/pdf", /*text*/ "PDF")
uo_menu.of_add_item(/*keys*/ "export/csv", /*text*/ "CSV")

// It opens from the right-click event of the grid : see Where to call of_show

// event ue_item_selected of uo_menu : (string as_keys)
// as_keys is the ADDRESS of the chosen entry
choose case as_keys
	case "copy"
		of_copy_selection()
	case "export/pdf"
		of_export("pdf")
end choose

Das Menü öffnen #

Die Komponente selbst ist unsichtbar: Sie nimmt im Fenster keinen Platz ein. Legen Sie sie irgendwo ab, Breite und Höhe null — sie existiert nur, solange das Menü offen ist. Vier Arten, es zu öffnen:

• of_show() — am Cursor, aus dem Rechtsklick des Steuerelements, das die Geste empfängt — siehe die Tabelle unten.
• of_show_under(Steuerelement) — unter einem Steuerelement: Das Menü hängt an seiner Unterkante, an seiner Anfangskante ausgerichtet (seiner rechten Kante bei Rechts-nach-links-Layout), und öffnet sich darüber, wenn der Bildschirm darunter endet. Was eine Schaltfläche Mehr oder … braucht — und die Tastatur: of_show_under(Steuerelement, true) markiert den ersten aktiven Eintrag.
• of_show(x, y) — an einem Bildschirmpunkt, in Pixeln. Negative Koordinaten sind ein echter Punkt: ein Bildschirm links oder oberhalb des Hauptbildschirms.
• of_show_at(Steuerelement, x, y) — an einem Punkt in einem Steuerelement, in PowerBuilder-Einheiten ab seiner linken oberen Ecke: der Punkt, den PopMenu nahm, nichts umzurechnen. of_source() nennt dieses Steuerelement dann in ue_item_selected — ein Menü für mehrere Steuerelemente.

// event rbuttondown of a DataWindow : the row under the cursor first
if row > 0 then dw_list.SetRow(/*row*/ row)
uo_menu.of_show()

// event ue_clicked of a "More" button : the menu hangs from it
uo_menu.of_show_under(/*control*/ uo_more)

// event rbuttondown of a DataWindow, another way : the point in the control, in
// PowerBuilder units, as PopMenu took it
uo_menu.of_show_at(/*control*/ dw_list, /*x*/ dw_list.PointerX(), /*y*/ dw_list.PointerY())

Wo of_show aufrufen #

of_show() öffnet sich dort, wo der Cursor ist, also wo der Benutzer geklickt hat: keine Einheit umzurechnen. of_show(x, y) erwartet Bildschirmpixel, nie die PowerBuilder-Einheiten eines auf das Steuerelement bezogenen xpos/ypos. Für einen Punkt in einem Steuerelement, in PowerBuilder-Einheiten: of_show_at(Steuerelement, x, y).

Über die Tastatur — Umschalt+F10 oder die Menütaste — ist die Maus irgendwo: Öffnen Sie das Menü unter dem Steuerelement mit dem Fokus, mit of_show_under(Steuerelement, true). Wie in Windows ist dann sein erster aktiver Eintrag markiert: Eingabe wählt ihn, die Pfeiltasten gehen von dort aus. Unter PowerBuilder 10 empfängt pbm_contextmenu nur den Rechtsklick, und Umschalt+F10 erreicht ein Eingabefeld nicht (gemessen: weder pbm_contextmenu noch pbm_keydown noch pbm_syskeydown). Die Taste, die das Menü auf einem PowerBuilder-Steuerelement öffnet, ist also die Menütaste (KeyApps!), in einem Benutzerereignis auf pbm_keydown — pbm_dwnkey bei einem DataWindow, dessen Rechtsklick über sein Ereignis rbuttondown läuft: pbm_contextmenu kommt bei einem Klick in eine Zelle dort nicht an (gemessen). Umschalt+F10 empfangen die PBToolboxAI-Komponenten selbst weiterhin (ihr ue_rclicked).

// User event ue_contextmenu of an edit field, mapped on pbm_contextmenu :
// the right-click opens the menu at the cursor
uo_menu.of_show()

// The field does not open its own Windows menu as well
return 1

// User event ue_key of the same field, mapped on pbm_keydown : the Menu key
// opens the menu under the field, its first entry highlighted
if key = KeyApps! then
	uo_menu.of_show_under(/*control*/ this, /*keyboard*/ true)
	return 1
end if

// User event ue_key of a DataWindow, mapped on pbm_dwnkey : the Menu key
if key = KeyApps! then
	uo_menu.of_show_under(/*control*/ this, /*keyboard*/ true)
	return 1
end if

Eine Antwort pro Öffnung: Ein geöffnetes Menü endet mit einer Wahl (ue_item_selected) oder ohne (ue_dismissed — ein Klick daneben, Esc, of_close). Ein Menü, das nichts zu zeigen hat, öffnet sich nicht: ue_dismissed kommt sofort. Solange das Menü auf dem Bildschirm ist, läuft die Anwendung weiter: Ein inzwischen ausgegrauter, ausgeblendeter oder entfernter Eintrag kann nicht mehr gewählt werden (stattdessen ue_dismissed), und of_remove_item, of_clear oder of_reset schließen das offene Menü. ue_dismissed(as_reason) sagt, warum: REASON_ESCAPE (Esc), REASON_OUTSIDE (ein Klick daneben), REASON_FOCUS (ein anderes Fenster hat den Fokus genommen), REASON_USER (auf andere Weise, ein anderes Menü übernimmt), REASON_CODE (of_close, ein entfernter Eintrag oder das geleerte Menü), REASON_REPLACED (ein zweites of_show), REASON_EMPTY (nichts zu zeigen), REASON_UNAVAILABLE (der gewählte Eintrag war nicht mehr verfügbar).

Ein Menü zur Zeit: Ein zweites of_show ersetzt das offene Menü, das zuerst ue_dismissed liefert. Und of_close direkt nach of_show schließt das Menü, noch bevor es gezeichnet ist — auch dann folgt ue_dismissed.

Über die Tastatur durchlaufen die Pfeiltasten die Einträge und überspringen ausgegraute, → öffnet eine Kaskade und ← schließt sie, Eingabe wählt, Esc steigt eine Ebene hinauf und schließt dann. Der unterstrichene Buchstabe — der nach & in der Beschriftung, && für ein kaufmännisches Und — wählt den Eintrag direkt; sonst führt das Tippen der ersten Buchstaben einer Beschriftung zu diesem Eintrag, Leerzeichen inbegriffen („report 2“). Eine lange Liste (auch fünfhundert Einträge und mehr) scrollt und bleibt flüssig. Von rechts nach links gelesen richtet sich das Menü rechts aus und die Kaskaden öffnen sich nach links.

Kaskaden, Abschnitte und Markierungen #

Ein Eintrag wird über seine Adresse benannt: oben sein Schlüssel allein (copy), in einer Kaskade die Schlüssel seiner Eltern und dann der eigene, durch / verbunden (export/pdf). Das Elternelement muss existieren; ein Schlüssel enthält weder / noch | und beginnt nicht mit __. ue_item_selected liefert genau diese Adresse zurück: Zwei Kaskaden dürfen ihre Einträge gleich benennen.

Eine Trennlinie (of_add_separator) und eine Abschnittsüberschrift (of_add_header) kommen ans Ende des Menüs (leere Adresse) oder der Kaskade eines Eintrags. Keine von beiden ist ein Eintrag: nie gewählt, nie gezählt. Eine Trennlinie erscheint nie am Anfang, am Ende oder doppelt; eine Überschrift, deren Einträge alle ausgeblendet sind, verschwindet mit ihnen.

Ein Häkchen (ib_checked) zeigt, dass eine Option aktiv ist; ein Optionseintrag (is_group) ist eine Wahl unter mehreren: Die Einträge einer Gruppe unter demselben Elternelement schließen sich aus — einen anzuhaken, per Code oder durch die Wahl des Benutzers, entfernt den Haken der anderen, und ein runder Punkt ersetzt das Häkchen. Das Tastenkürzel (is_shortcut) steht rechts neben dem Eintrag; es wird nur angezeigt: Die Taste gehört dem Steuerelement, um das es im Menü geht (ein Eingabefeld kopiert bereits mit Strg+C), und ein Kontextmenü, das sie belegte, nähme sie allen Steuerelementen des Fensters weg.

Ein angehakter Eintrag außerhalb einer Gruppe schaltet nicht von selbst um, wenn der Benutzer ihn wählt — wie in jedem Windows-Menü: Schalten Sie ihn in ue_item_selected um. Ein zerstörender Befehl hebt sich durch seinen Ton ab: is_tone = TONE_DANGER schreibt seinen Text im Rot des Designs, hell wie dunkel lesbar. Damit eine Option bei der Wahl von selbst umschaltet, setzen Sie ib_auto_check = true: Das Häkchen wechselt vor ue_item_selected. Eine Option ist ein Kontrollkästchen — von einem Bildschirmleser als „nicht aktiviert“ angesagt —, sobald sie einmal angehakt war oder sobald ib_checkable = true gilt.

// A section of three exclusive entries in the View cascade
uo_menu.of_add_header(/*keys*/ "view", /*text*/ "Layout")
uo_menu.of_add_item(/*keys*/ "view/list", /*text*/ "&List")
uo_menu.of_add_item(/*keys*/ "view/details", /*text*/ "&Details")
uo_menu.of_item(/*keys*/ "view/list").is_group = "layout"
uo_menu.of_item(/*keys*/ "view/details").is_group = "layout"

// Checking one unchecks the other
uo_menu.of_item(/*keys*/ "view/details").ib_checked = true

// The shortcut SHOWN at the right of an entry
uo_menu.of_item(/*keys*/ "copy").is_shortcut = "Ctrl+C"

// A command that destroys : the red of the theme
uo_menu.of_item(/*keys*/ "delete").is_tone = uo_menu.TONE_DANGER

// event ue_item_selected : a check mark outside a group is switched by you
if as_keys = "wrap" then uo_menu.of_item(/*keys*/ as_keys).ib_checked = not uo_menu.of_item(/*keys*/ as_keys).ib_checked

// ... or by the entry itself, before ue_item_selected
uo_menu.of_item(/*keys*/ "grid").ib_auto_check = true

Ein PowerBuilder-Menü übernehmen #

Ihre Popup-Menüs sind schon geschrieben? of_load_menu macht daraus das Menü der Komponente: Übergeben Sie das Element, auf dem Sie PopMenu aufriefen. Jedes Element wird ein Eintrag, Kaskaden inbegriffen, mit seinem Text (& inbegriffen), seinem Zustand (Enabled, Checked, Visible), seinem rechts angezeigten Shortcut — wie der Text nach einem Tabulator — und seinem Symbolleistenbild, wenn es eine vorhandene Datei ist. Sein Schlüssel ist der ClassName des Elements, auf jeder Ebene. Bei einer Wahl läuft zuerst das Clicked-Skript des Elements, dann ue_item_selected: Der für PopMenu geschriebene Code funktioniert weiter. Das Menü bleibt lebendig, wie mit PopMenu: Jedes Öffnen liest die Elemente erneut (Text, Enabled, Checked, Visible, Shortcut). Der Code vor PopMenu — m_paste.Enabled = (Clipboard() <> "") — und ein Clicked, das this.Checked = not this.Checked ausführt, zeigen sich also beim nächsten Öffnen; ein Element, das bei offenem Menü ausgegraut oder ausgeblendet wird, startet sein Clicked nicht (ue_dismissed(REASON_UNAVAILABLE)). Halten Sie das Menüobjekt am Leben, solange die Komponente es nutzt. of_loaded_item liefert das Element eines Eintrags, um zu lesen, was nur das Menü weiß (seine MicroHelp) — prüfen Sie es mit IsValid, ein von Hand hinzugefügter Eintrag hat keines. Ein Clicked-Skript, das ParentWindow liest, findet dort ein gültiges Fenster — gemessen unter PowerBuilder 10, auch für ein mit create erzeugtes und nie an ein Fenster gebundenes Menü —, doch PowerBuilder wählt es aus: Nichts garantiert, dass es das Fenster ist, das das Kontextmenü trägt. Damit ein Clicked ein bestimmtes Fenster erreicht, geben Sie es dem Menü in einer Instanzvariablen, gesetzt vor of_load_menu, oder verlegen Sie diesen Code nach ue_item_selected.

// Instance variable of the window : the menu lives as long as it does
// m_popup im_popup

// open event of the window : the items of m_popup.m_edit become the menu
im_popup = create m_popup
uo_menu.of_load_menu(/*menu*/ im_popup.m_edit)

// event rbuttondown of the DataWindow : the code before PopMenu stays,
// of_show replaces PopMenu - the items are read again as it opens
im_popup.m_edit.m_paste.Enabled = (Clipboard() <> "")
uo_menu.of_show()

// event ue_item_hover of uo_menu (ib_track_hover = true) : the MicroHelp
if IsValid(uo_menu.of_loaded_item(/*keys*/ as_keys)) then st_help.text = uo_menu.of_loaded_item(/*keys*/ as_keys).MicroHelp

// A Clicked that must reach ONE given window : the menu keeps that window
// itself. Instance variable of m_popup : window iw_owner
// Clicked of m_edit.m_copy
iw_owner.TriggerEvent("ue_copy")

// open event of the window, before of_load_menu
im_popup.iw_owner = this

Eigenschaften #

Methoden #

Ereignisse #

Elementeigenschaften #

Ein Eintrag zeigt keine QuickInfo: Das native Menü hat keine. Das vom Handle geerbte is_tooltip wird gespeichert und lässt sich zurücklesen, wird aber nie angezeigt — für eine Hilfe ib_track_hover und ue_item_hover.

Beispiele #

Ein Menü für das Angeklickte #

// event ue_rclicked of the list : the menu is rebuilt for the current row
uo_menu.of_clear()
uo_menu.of_add_item(/*keys*/ "open", /*text*/ "&Open")
uo_menu.of_add_item(/*keys*/ "rename", /*text*/ "Re&name")
uo_menu.of_add_separator(/*keys*/ "")
uo_menu.of_add_item(/*keys*/ "delete", /*text*/ "&Delete")

// A row the user may not change : its commands are greyed
uo_menu.of_item(/*keys*/ "rename").ib_enabled = ib_can_edit
uo_menu.of_item(/*keys*/ "delete").ib_enabled = ib_can_edit

// At the cursor
uo_menu.of_show()

Eine Schaltfläche Mehr #

// event ue_clicked of the button : the menu hangs from it
uo_menu.of_show_under(/*control*/ uo_more)

Eine Hilfezeile in der Statusleiste #

// Once, after the menu is built : report the pointed entry
uo_menu.ib_track_hover = true

// event ue_item_hover of uo_menu : (string as_keys), "" when the menu closes
choose case as_keys
	case "delete"
		st_help.text = "Deletes the row, without the clipboard."
	case else
		st_help.text = ""
end choose

Bewährte Praxis #

• Öffnen Sie aus dem Rechtsklick-Ereignis des Steuerelements (siehe Tabelle): Nur ein Drücken wählt einen Eintrag, das folgende Loslassen wählt nichts.
• Ein kurzes Menü. Die häufigen Befehle oben, die zerstörenden unten, nach einer Trennlinie, mit TONE_DANGER.
• Lieber ausgrauen als ausblenden, wenn ein Befehl existiert, hier aber nicht gilt: Der Benutzer lernt, wo er ist.
• Zeigen Sie die Tastenkürzel Ihrer Befehle: In einem Kontextmenü lernt man sie.
• Eine Kaskade, nicht zwei: Jenseits einer Ebene liest sich ein Dialog besser.

Demoversion #

Ohne Schlüssel zeigt jede Liste des Menüs — die Wurzel wie jede Kaskade — ihre ersten sechs sichtbaren Einträge; Trennlinien und Überschriften zählen nicht. Die letzte, ausgegraute Zeile sagt, wie viele Einträge nicht angezeigt werden — oder trägt, wenn nichts gekürzt ist, den Vermerk „PBToolboxAI — DEMO“. Das Modell behält alles: Ein Schlüssel zeigt beim nächsten Öffnen das ganze Menü.

Der Starter hat keine Fläche: Von den unten geerbten Mitgliedern haben of_save_as_png, of_print und of_focus_webview nichts aufzunehmen, zu drucken oder zu empfangen. of_register_shortcut bleibt nützlich — ein Fensterkürzel, das das Menü mit of_show_under öffnet.

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.

Bei diesem unsichtbaren Starter durchlaufen of_count und of_keys_at, was Sie hinzugefügt haben, ausgeblendete Zweige eingeschlossen — nicht, was das Rad zeichnen wird. Der Bildexport, das Drucken, of_focus_webview und of_set_redraw haben hier keine nützliche Wirkung: Die Komponente zeichnet nichts Eigenes, das Rad lebt in seinem eigenen Fenster.

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.

← Komponentenreferenz · Inhalt des Handbuchs