radialmenu — `u_pbt_radialmenu` #

← Komponentenreferenz · Inhalt des Handbuchs

Radiales Kontextmenü: die Befehle als Kranz um den Cursor, nach Richtung gewählt statt in einer Liste gelesen.

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

Kurz gefasst #

Userobject	`u_pbt_radialmenu`
Elementklasse	`n_pbt_radialmenu_item` (`of_item(id)`)
Dient zu	Eine Handvoll häufiger Befehle dort anbieten, wo die Hand schon ist
Prinzip	Sie beschreiben die Zweige; das Rad, die Form und die Navigation sind unsere Sache

Schnellstart #

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

Öffnen, dann wählen #

Das Rad öffnet sich beim Loslassen der rechten Maustaste, und erst ein zweiter Klick wählt aus. Das ist kein Implementierungsdetail: Öffnete es sich beim Drücken, würde das Loslassen desselben Klicks sofort den Sektor unter dem Cursor auswählen, und der Benutzer löste einen Befehl aus, ohne ihn je gesehen zu haben.

Deshalb wird of_show() aus dem Rechtsklick-Ereignis des Steuerelements aufgerufen, auf dem die Geste stattfindet (einem statictext, einem button, einem Raster…): Dann ist die Taste bereits oben, und der nächste Klick ist wirklich der wählende. Das radiale Menü selbst hat keine Oberfläche — also auch kein eigenes Mausereignis.

Die Komponente selbst ist unsichtbar: Sie belegt keinen Platz im Fenster. Legen Sie sie irgendwo ab, geben Sie ihr Breite und Höhe null — sie existiert nur, solange das Rad offen ist.

Die Nabe in der Mitte schreibt den angezeigten Zweig vollständig aus. Genau das erlaubt einem Sektor eine kurze Beschriftung, ohne über seine Wirkung zu täuschen. Ein Klick auf die Nabe schließt das Rad; in einem Unterrad führt er eine Ebene zurück.

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

Unterräder #

Eine Adresse hängt Zweige unter einen anderen: export/pdf. Den übergeordneten Zweig zu wählen wählt nichts: Das Rad wird durch das seiner Kinder ersetzt, und die Nabe wird zum Rückweg.

Warum ersetzen statt einen zweiten Ring hinzufügen? Weil ein äußerer Ring die Sektoren auf jeder Ebene halbieren würde. Acht Zweige sind bereits das lesbare Maximum; für zwei Ebenen gleichzeitig ist kein Platz.

Das Ereignis ue_item_selected meldet den vollständigen Pfad (export/pdf), nicht die bloße Blatt-Id. Zwei Unterräder dürfen ihre Zweige also gleich benennen.

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")

Wenn es zu viele Zweige gibt #

Ein Rad wird nach Richtung gelesen, und jenseits von acht Sektoren lassen sich die Segmente nicht mehr unterscheiden. ii_max_sectors setzt diese Obergrenze (3 bis 12, standardmäßig 8).

Darüber hinausgehende Zweige gehen nicht verloren: Der letzte Platz im Kranz wird zu einem Zweig, der sie alle enthält und sich als Unterrad öffnet. Ein Menü, das seinen Rest fallen ließe, wäre ein Menü, das über sein Angebot täuscht.

Den Kranz zu verengen ist oft ein Gewinn: Vier breite Zweige trifft man schneller als acht schmale.

Eigenschaften #

Eigenschaft	Typ	Standard	Rolle
`ii_max_sectors`	integer	`8`	Wie viele Zweige ein Kranz tragen darf (3 bis 12). Was darüber hinausgeht, wandert unter einen letzten Zweig, der sich als Unterrad öffnet
`is_theme_style`	string	`fluent`	Visueller Stil der Komponente (Konstanten `THEME_STYLE_*`)
`is_theme_mode`	string	`light`	Helle oder dunkle Variante (Konstanten `THEME_MODE_*`)
`il_theme_accent`	long	`-1`	Akzentfarbe dieser Komponente (`-1` = Akzent des Themas)
`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 erlaubt)
`is_super_tooltip_image`	string	`""`	Bild des erweiterten Tooltips

Methoden #

Methode	Rolle
`of_add_item (string as_keys, string as_text)`	Fügt dem Rad einen Zweig hinzu; die Id kommt zurück, wenn er gewählt wird. Liefert `0` nach der Anwendung, `-2` wenn die Komponente nicht erzeugt ist
`of_add_item (string as_keys, string as_text, string as_image, boolean ab_checked)`	Dasselbe, mit Symbol und Markierung — das Symbol als drittes Argument, wie überall sonst in der Bibliothek. Ein Zweig wird über sein Handle ausgegraut: `of_item(keys).ib_enabled = false`. Liefert `0` nach der Anwendung, `-2` wenn die Komponente nicht erzeugt ist
`of_clear ( )`	Leert das Rad. Liefert `0` nach der Anwendung, `-2` wenn die Komponente nicht erzeugt ist
`of_show ( )`	Öffnet das Rad zentriert auf dem Cursor. Aus dem Rechtsklick des Steuerelements aufrufen, das die Geste empfängt
`of_show (long al_x, long al_y)`	Dasselbe, zentriert auf einer Bildschirmposition in Pixeln
`of_item (string as_keys)`	Liefert einen Zweiggriff, um ihn später zu ändern (Beschriftung, aktiv, markiert)
`of_reset ( )`	Leert das Rad und setzt alle Eigenschaften auf ihren Ausgangswert zurück. Liefert `0` nach der Anwendung, `-2` wenn die Komponente nicht erzeugt ist

Ereignisse #

Ereignis	Ausgelöst wenn
`ue_item_selected (string as_keys)`	Der Benutzer hat einen Zweig gewählt. `as_keys` ist der vollständige Pfad (`export/pdf`), nicht die bloße Blatt-Id
`ue_dismissed ( )`	Das Rad wurde geschlossen, ohne dass ein Zweig gewählt wurde: Klick auf die Nabe, Klick außerhalb oder Escape-Taste

Das Fenster des Rades ist rund: Die Ecken lassen Klicks zur dahinterliegenden Anwendung durch, statt sie in einem unsichtbaren Rechteck zu verschlucken.

Elementeigenschaften #

Eigenschaft	Typ	Standard	Rolle
`is_text`	string	`""`	Beschriftung des Zweigs. Halten Sie sie kurz: Ein Sektor ist ein Segment, keine Zeile — die Nabe schreibt den Rest aus
`ib_enabled`	boolean	`true`	Auf false ist der Zweig ausgegraut und sein Sektor ignoriert jeden Klick
`ib_visible`	boolean	`true`	Auf false verlässt der Zweig das Rad — Unterrad inbegriffen — ohne entfernt zu werden; die Sektoren rücken zusammen, und er kommt unverändert zurück
`ib_checked`	boolean	`false`	Auf true markiert ein Punkt den Zweig als aktiv

Beispiele #

Ein Rad je Kontext #

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

Auf den gewählten Pfad reagieren #

// 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_exporter_pdf()
	case "delete"
		of_supprimer()
end choose

Markieren, ausgrauen, verengen #

// Mark a branch as being on
uo_wheel.of_item(/*key*/ "bold").ib_checked = true
// Grey out the one that makes no sense here
uo_wheel.of_item(/*key*/ "paste").ib_enabled = false
uo_wheel.ii_max_sectors = 4

Bewährte Praxis #

Beim LOSGELASSENEN Rechtsklick des Steuerelements öffnen, nie beim Drücken. Das trennt das Öffnen vom Wählen, und der Benutzer braucht beides.
Kurze Beschriftungen. Ein oder zwei Wörter. Die Nabe ist für den ganzen Text da, der Sektor für die Richtung.
Vier bis sechs Zweige schlagen acht. Ein Rad merkt man sich über die Position; je weniger Positionen, desto schneller sind sie gelernt.
Die häufigsten Befehle nach oben und unten. Das sind die beiden Richtungen, die die Hand ohne Nachdenken trifft.
Halten Sie die Reihenfolge stabil von einer Öffnung zur nächsten: Der ganze Sinn eines Rades ist, dass die Geste dem Lesen vorauseilt.
Ein radiales Menü ersetzt kein Listenmenü. Zwanzig seltene Befehle liest man besser in einer Liste; behalten Sie das Rad für die ständig benutzte Handvoll.

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

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.