radialmenu — u_pbt_radialmenu #

← Component reference · Guide contents

Radial context menu: the commands in a ring around the cursor, picked by direction rather than read down a list.

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

In brief #

Quick start #

// A wheel built for whatever is under the cursor
uo_wheel.of_add_item(/*keys*/ "cut",    /*text*/ "Cut")
uo_wheel.of_add_item(/*keys*/ "copy",   /*text*/ "Copy")
uo_wheel.of_add_item(/*keys*/ "paste",  /*text*/ "Paste")
uo_wheel.of_add_item(/*keys*/ "delete", /*text*/ "Delete")

// It opens when the right button is released: see ue_rclicked

Open, then choose #

The wheel opens when the right button is released, and a second click is what chooses. That is not an implementation detail: were it to open on the press, the release of that very click would immediately pick whatever sector had landed under the cursor, and the user would fire a command without ever seeing it.

That is why of_show() is called from the right-click event of the control the user made the gesture on (a statictext, a button, a grid…): by then the button is already up, and the next click really is the one that chooses. The radial menu itself has no surface — so no mouse event of its own.

The component itself is invisible: it takes no room in the window. Drop it anywhere, give it zero width and height — it only exists while the wheel is up.

The pointed branch — by the mouse or the keyboard — shows its whole label, above its neighbours: a sector keeps two lines at most (one past eight branches), and that is what lets it carry a short label without lying about what it does. The hub in the middle is the way out: clicking it closes the wheel; inside a sub-wheel, it climbs one level back. While the wheel is open the application keeps running: a branch removed, greyed or hidden in the meantime can no longer be chosen (ue_dismissed instead); of_clear, of_reset, of_close and a second of_show close the open wheel, and so does of_remove_item when the wheel showed the branch removed — ue_dismissed is raised at once, and of_is_open answers false as soon as the call returns.

// It opens when the right button is released: see ue_rclicked
uo_wheel.of_show()

From the keyboard, the arrows walk the branches, stepping over greyed ones, Enter or Space chooses, ← and Backspace climb back one level, and Escape climbs one level out of a sub-wheel — it only closes the wheel at the root. None of these keys reaches the application while the wheel is open. Read right to left, the ring turns the other way and ← and → trade places: → climbs back one level.

To open it from the keyboard — the Menu key, Shift+F10 —, call of_show_over from the control that has the focus, with ab_keyboard true: the wheel is centred on that control, wherever the mouse is, and its first branch that answers is lit — Enter chooses it, the arrows go on from there. of_show_over(control) without that second argument also serves a toolbar button: the wheel opens over it.

Sub-wheels #

An address hangs branches under another one: export/pdf. Choosing the parent branch chooses nothing: the wheel is replaced by a wheel of its children, and the hub becomes the way back.

Why replace rather than add a second ring? Because an outer ring would halve the sectors at every level. Eight branches is already the readable maximum; there is no room to show two levels at once.

The ue_item_selected event reports the full address (export/pdf), not the bare leaf key. Two sub-wheels are therefore free to name their branches alike.

// A branch, then two entries at its address
uo_wheel.of_add_item(/*keys*/ "export", /*text*/ "Export")
uo_wheel.of_add_item(/*keys*/ "export/pdf", /*text*/ "PDF")
uo_wheel.of_add_item(/*keys*/ "export/csv", /*text*/ "CSV")

To remove one branch — its sub-wheel with it — without rebuilding the whole wheel: of_remove_item("export/csv"). The other branches stay in place.

When there are too many branches #

A wheel is read by direction, and past eight sectors the slices stop being distinguishable. ii_max_sectors sets that ceiling (3 to 12, 8 by default).

Branches beyond it are not lost: the last place in the ring becomes a branch holding all of them, which opens as a sub-wheel. A menu that dropped its tail would be a menu lying about what it offers.

Tightening the ring is often a gain: four wide branches are quicker to aim at than eight narrow ones.

Properties #

Methods #

Events #

A click in a corner of the window, outside the disc, counts as a click outside: the wheel closes (ue_dismissed) and the click goes through to the application behind, instead of being swallowed by an invisible square.

Item properties #

A branch shows no tooltip: the round window has no room outside its disc. The is_tooltip the handle inherits is kept and reads back, but it is never shown — the pointed branch is what shows its whole label.

Examples #

One wheel per context #

// A wheel built for whatever is under the cursor
uo_wheel.of_clear()
uo_wheel.of_add_item(/*keys*/ "bold", /*text*/ "Bold", /*image*/ "mono:img\packimages.dll:svg/samples/bold", /*checked*/ true)
uo_wheel.of_add_item(/*keys*/ "find", /*text*/ "Find", /*image*/ "mono:img\packimages.dll:svg/samples/find", /*checked*/ false)

Acting on the chosen path #

// ue_item_selected event of the radial menu
// as_keys carries the full path, e.g. "export/pdf"
choose case as_keys
	case "export/pdf"
		of_export_pdf()
	case "delete"
		of_delete_selection()
end choose

Mark, grey out, tighten #

// Mark a branch as being on
uo_wheel.of_item(/*keys*/ "bold").ib_checked = true

// Grey out the one that makes no sense here
uo_wheel.of_item(/*keys*/ "paste").ib_enabled = false

// Four branches at most on one ring
uo_wheel.ii_max_sectors = 4

From the keyboard, and closed by the code #

// Menu key on the grid: the wheel opens centred on it, first branch lit
uo_wheel.of_show_over(/*control*/ dw_orders, /*keyboard*/ true)

// Later, from a timer: the wheel closes without a choice (ue_dismissed)
if uo_wheel.of_is_open() then uo_wheel.of_close()

A radio group, a command that destroys #

// Three exclusive branches: choosing one unchecks the other two
uo_wheel.of_item(/*keys*/ "align/left").is_group = "align"
uo_wheel.of_item(/*keys*/ "align/center").is_group = "align"
uo_wheel.of_item(/*keys*/ "align/right").is_group = "align"

// Delete takes the tone of danger, light or dark
uo_wheel.of_item(/*keys*/ "delete").is_tone = u_pbt_radialmenu.TONE_DANGER

Good practice #

• Open on the control's RELEASED right-click, never on the press. That is what separates opening from choosing, and the user needs both.
• Short labels. One or two words. The sector is there for the direction; the whole text only reads once the branch is pointed at.
• Four to six branches beat eight. A wheel is remembered by position; the fewer positions, the faster they are learnt.
• Put the most frequent commands at the top and the bottom. Those are the two directions the hand reaches without thinking.
• Keep the order stable from one opening to the next: the whole point of a wheel is that the gesture ends up preceding the reading.
• A radial menu does not replace a list menu. Twenty rare commands read better in a list; keep the wheel for the handful used constantly.

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