contextmenu — u_pbt_contextmenu #

← Component reference · Guide contents

The Windows context menu, in the theme of the application: a cascading list that opens at the cursor, under a control or at a point of the screen — icons, shortcuts shown, check marks, radio entries, section headers, long lists that scroll and answer to typing.

▶ See it live — Demo application, Context menu tile: the preview, the code behind it and this page, side by side.

In brief #

Quick start #

// 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

Opening the menu #

The component itself is invisible: it takes no room in the window. Drop it anywhere, zero width and height — it only exists while the menu is open. Four ways to open it:

• of_show() — at the cursor, from the right-click of the control that receives the gesture — see the table below.
• of_show_under(control) — under a control: the menu hangs from its bottom edge, aligned on its start edge (its right edge in a right-to-left layout), and opens above it when the screen ends below. What a More or … button needs — and the keyboard: of_show_under(control, true) highlights the first enabled entry.
• of_show(x, y) — at a point of the screen, in pixels. Negative coordinates are a real point: a screen placed to the left of or above the main one.
• of_show_at(control, x, y) — at a point inside a control, in PowerBuilder units from its top-left corner: the point PopMenu took, nothing to convert. of_source() then names that control in ue_item_selected — one menu for several controls.

// 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())

Where to call of_show #

of_show() opens where the cursor is, that is where the user clicked: no unit to convert. of_show(x, y) expects screen pixels, never the PowerBuilder units of an xpos/ypos relative to the control. For a point inside a control, in PowerBuilder units, use of_show_at(control, x, y).

From the keyboard — Shift+F10 or the Menu key — the mouse is anywhere: open the menu under the control that has the focus, with of_show_under(control, true). As in Windows, its first enabled entry is then highlighted: Enter chooses it, the arrows go on from there. Under PowerBuilder 10, pbm_contextmenu only receives the right-click, and Shift+F10 does not reach an edit field (measured: neither pbm_contextmenu, nor pbm_keydown, nor pbm_syskeydown). The keyboard key that opens the menu on a PowerBuilder control is therefore the Menu key (KeyApps!), taken in a user event on pbm_keydown — pbm_dwnkey for a DataWindow, whose right-click goes through its rbuttondown event: pbm_contextmenu does not come there for a click in a cell (measured). Shift+F10 is still received by the PBToolboxAI components themselves (their 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

One answer per opening: an open menu ends with a choice (ue_item_selected) or without one (ue_dismissed — a click outside, Escape, of_close). A menu with nothing to show does not open: ue_dismissed comes at once. While the menu is on screen the application keeps running: an entry greyed, hidden or removed in the meantime can no longer be chosen (ue_dismissed instead), and of_remove_item, of_clear or of_reset close the open menu. ue_dismissed(as_reason) says why: REASON_ESCAPE (Escape), REASON_OUTSIDE (a click outside), REASON_FOCUS (another window took the focus), REASON_USER (another way, another menu taking over), REASON_CODE (of_close, an entry removed or the menu cleared), REASON_REPLACED (a second of_show), REASON_EMPTY (nothing to show), REASON_UNAVAILABLE (the chosen entry was no longer available).

One menu at a time: a second of_show replaces the open menu, which answers ue_dismissed first. And of_close called right after of_show closes the menu before it is even drawn — ue_dismissed follows too.

From the keyboard, the arrows walk the entries, stepping over greyed ones, → opens a cascade and ← closes it, Enter chooses, Escape climbs one level then closes. The underlined letter — the one after & in the label, && for an ampersand — chooses the entry straight away; elsewhere, typing the first letters of a label goes to that entry, spaces included ("report 2"). A long list (five hundred entries and more) scrolls and stays fluid. Read right to left, the menu aligns on the right and the cascades open to the left.

Cascades, sections and marks #

An entry is named by its address: its key alone at the top (copy), the keys of its parents then its own, joined by /, in a cascade (export/pdf). The parent must exist; a key holds neither / nor | and does not start with __. ue_item_selected hands back that same address: two cascades may name their entries alike.

A separator (of_add_separator) and a section header (of_add_header) go at the end of the menu (empty address) or of the cascade of an entry. Neither is an entry: never chosen, never counted. A separator is never shown leading, trailing or doubled; a header whose entries are all hidden goes with them.

A check mark (ib_checked) says an option is on; a radio entry (is_group) is one choice among several: the entries of one group under the same parent exclude each other — checking one, by the code or by the user's choice, unchecks the others, and a round bullet replaces the tick. The shortcut (is_shortcut) is shown at the right of the entry; it is shown only: the key belongs to the control the menu is about (an edit field already copies on Ctrl+C), and a context menu that armed it would take it from every control of the window.

A checked entry outside a group does not toggle by itself when the user chooses it — as in every Windows menu: switch it in ue_item_selected. A command that destroys stands out by its tone: is_tone = TONE_DANGER writes its text in the red of the theme, readable in light and dark alike. For an option that switches itself when chosen, set ib_auto_check = true: the mark changes before ue_item_selected. An option is a check box — announced "not checked" by a screen reader — once it has been checked, or as soon as ib_checkable = true.

// 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

Taking over a PowerBuilder menu #

Your popup menus are already written? of_load_menu makes them the menu of the component: pass the item you called PopMenu on. Each item becomes an entry, cascades included, with its text (& included), its state (Enabled, Checked, Visible), its Shortcut shown at the right — as is the text after a tab — and its toolbar picture when it is a file that exists. Its key is the ClassName of the item, at every level. On a choice, the Clicked script of the item runs first, then ue_item_selected: the code written for PopMenu keeps working. The menu stays alive, as with PopMenu: each opening reads the items again (Text, Enabled, Checked, Visible, Shortcut). The code that came before PopMenu — m_paste.Enabled = (Clipboard() <> "") — and a Clicked that does this.Checked = not this.Checked therefore show at the next opening; an item greyed or hidden while the menu is open does not run its Clicked (ue_dismissed(REASON_UNAVAILABLE)). Keep the menu object alive for as long as the component uses it. of_loaded_item returns the item of an entry, to read what only the menu knows (its MicroHelp) — test it with IsValid, an entry added by hand has none. A Clicked script that reads ParentWindow finds a valid window there — measured under PowerBuilder 10, even for a menu created with create and never attached to a window — but PowerBuilder chooses it: nothing says it is the window that holds the context menu. For a Clicked to reach one given window, give it to the menu in an instance variable, set before of_load_menu, or move that code to 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

Properties #

Methods #

Events #

Item properties #

An entry shows no tooltip: the native menu has none. The is_tooltip the handle inherits is kept and reads back, but it is never shown — for help, ib_track_hover and ue_item_hover.

Examples #

A menu for what was clicked #

// 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()

A More button #

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

A help line in the status bar #

// 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

Good practice #

• Open from the right-click event of the control (see the table): only a press chooses an entry, the release that follows chooses nothing.
• A short menu. The frequent commands at the top, the destructive ones at the bottom, after a separator, with TONE_DANGER.
• Grey out rather than hide a command that exists but does not apply here: the user learns where it is.
• Show the shortcuts of your commands: a context menu is where people learn them.
• One cascade, not two: beyond one level, a dialog reads better.

Demo version #

Without a key, each list of the menu — the root as each cascade — shows its first six visible entries; separators and headers do not count. The last line, greyed, says how many entries are not shown — or, with nothing cut, reads "PBToolboxAI — DEMO". The model keeps everything: a key shows the whole menu at the next opening.

The launcher has no surface: of the inherited members below, of_save_as_png, of_print and of_focus_webview have nothing to capture, print or receive. of_register_shortcut stays useful — a window shortcut that opens the menu with of_show_under.

Inherited from the common base #

These members exist on every visual component — they are not specific to this one. They are detailed once, in the transverse chapters; this table only says where to read them.

On this invisible launcher, of_count and of_keys_at walk what you added, hidden branches included — not what the wheel will draw. Exporting as an image, printing, of_focus_webview and of_set_redraw have no useful effect here: the component draws nothing of its own, the wheel lives in its own window.

Two helpers are not inherited: of_icon and of_escape_markup live on n_pbt_utils. Declare one — n_pbt_utils lnv_utils, nothing to create — and call them on it.

← Component reference · Guide contents