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(keys)`)
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 #

// Ein Rad, gebaut fuer das, was unter dem Mauszeiger liegt
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")

// Es oeffnet sich beim Loslassen der rechten Maustaste: siehe 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.

Der angezeigte Zweig — per Maus oder Tastatur — zeigt seine vollständige Beschriftung, über seinen Nachbarn: Ein Sektor behält höchstens zwei Zeilen (eine ab mehr als acht Zweigen), und genau das erlaubt ihm eine kurze Beschriftung, ohne über seine Wirkung zu täuschen. Die Nabe in der Mitte ist der Ausgang: Ein Klick darauf schließt das Rad; in einem Unterrad führt er eine Ebene zurück. Solange das Rad offen ist, läuft die Anwendung weiter: Ein inzwischen entfernter, ausgegrauter oder ausgeblendeter Zweig lässt sich nicht mehr wählen (stattdessen ue_dismissed); of_clear, of_reset, of_close und ein zweites of_show schließen das offene Rad, of_remove_item ebenfalls, wenn das Rad den entfernten Zweig zeigte — ue_dismissed wird sofort ausgelöst, und of_is_open antwortet false, sobald der Aufruf zurückkehrt.

// Es oeffnet sich beim Loslassen der rechten Maustaste: siehe ue_rclicked
uo_wheel.of_show()

Per Tastatur durchlaufen die Pfeiltasten die Zweige und überspringen ausgegraute, Eingabe oder Leertaste wählt, ← und Rücktaste gehen eine Ebene zurück, und Escape geht in einem Unterrad eine Ebene zurück — erst auf der obersten Ebene schließt es das Rad. Keine dieser Tasten erreicht die Anwendung, solange das Rad offen ist. Bei Leserichtung von rechts nach links dreht sich der Kranz in die andere Richtung, und ← und → tauschen die Rollen: → geht eine Ebene zurück.

Um es per Tastatur zu öffnen — Menütaste, Umschalt+F10 —, rufen Sie of_show_over aus dem Steuerelement auf, das den Fokus hat, mit ab_keyboard auf true: Das Rad wird auf diesem Steuerelement zentriert, wo auch immer die Maus ist, und sein erster Zweig, der antwortet, leuchtet — Eingabe wählt ihn, die Pfeiltasten machen von dort aus weiter. of_show_over(Steuerelement) ohne dieses zweite Argument dient auch einer Symbolleisten-Schaltfläche: Das Rad öffnet sich über ihr.

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 die vollständige Adresse (export/pdf), nicht den bloßen Blattschlüssel. Zwei Unterräder dürfen ihre Zweige also gleich benennen.

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

Um einen Zweig — samt Unterrad — zu entfernen, ohne das ganze Rad neu aufzubauen: of_remove_item("export/csv"). Die anderen Zweige bleiben an ihrem Platz.

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. Über acht hinaus wird das Rad dichter (kleineres Symbol, einzeilige Beschriftung), damit sich die Beschriftungen nicht überlappen
`is_theme_style`	string	`""`	Visueller Stil der Komponente (Konstanten `THEME_STYLE_*`); leer = der der Anwendung, bei jeder Änderung übernommen
`is_theme_mode`	string	`""`	Helle oder dunkle Variante (Konstanten `THEME_MODE_*`); leer = die der Anwendung, bei jeder Änderung übernommen
`il_theme_accent`	long	`-1`	Akzentfarbe dieser Komponente (`-1` = Akzent der Anwendung, sonst der des Designs)

Methoden #

Methode	Rolle
`of_add_item (string as_keys, string as_text)`	Fügt einen Zweig an seiner Adresse hinzu: `format/strike` hängt unter Format, das bereits existieren muss. Genau diese Adresse kommt in `ue_item_selected` zurück, wenn er gewählt wird. Liefert `0` nach dem Hinzufügen, `-5` wenn die Adresse abgelehnt wird (Elternteil nicht gefunden, Adresse schon vergeben, leere Ebene wie `export/` oder `/pdf`, Schlüssel mit `	`oder beginnend mit` __`),` -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 dem Hinzufügen, `-5` wenn die Adresse abgelehnt wird (Elternteil nicht gefunden, Adresse schon vergeben, leere Ebene wie `export/` oder `/pdf`, Schlüssel mit `	`oder beginnend mit` __`),` -2` wenn die Komponente nicht erzeugt ist
`of_clear ( )`	Leert das Rad und gibt die über `of_item` erhaltenen Handles frei (jedes bezeichnete einen Zweig, den es nicht mehr gibt). Liefert `0` nach der Anwendung, `-2` wenn die Komponente nicht erzeugt ist
`of_close ( )`	Schließt das Rad der Komponente, wenn es auf dem Bildschirm ist, ohne Wahl: `ue_dismissed` wird sofort ausgelöst, wie bei einem Klick daneben — auch für ein Rad, das gerade angefordert und noch nicht gezeichnet wurde —, und `of_is_open` antwortet false, sobald der Aufruf zurückkehrt. Nichts offen, nichts geschieht. Liefert `0` nach der Ausführung, `-2` wenn die Komponente nicht erzeugt ist
`of_is_open ( )`	`true`, solange ein Rad der Komponente auf dem Bildschirm ist — geöffnet und noch nicht durch eine Wahl oder ein Schließen beantwortet. `of_show` und `of_close` werden angewendet, bevor sie zurückkehren: Es antwortet true direkt nach `of_show`, false direkt nach `of_close`
`long of_show ( )`	Öffnet das Rad zentriert auf dem Cursor. Aus dem Rechtsklick des Steuerelements aufrufen, das die Geste empfängt. Ein Rad ohne sichtbaren Zweig öffnet sich nicht: `ue_dismissed` wird ausgelöst. Ein noch angezeigtes Rad wird ersetzt: Es löst zuerst `ue_dismissed` aus. Liefert `0` nach der Anforderung, `-2` wenn die Komponente nicht erzeugt ist
`long of_show (long al_x, long al_y)`	Dasselbe, zentriert auf einer Bildschirmposition in Pixeln. Negative Koordinaten sind ein echter Punkt, `(-1, -1)` eingeschlossen: ein Bildschirm links oder oberhalb des Hauptbildschirms. Liefert `0` nach der Anforderung, `-2` wenn die Komponente nicht erzeugt ist
`long of_show_over (dragobject ado_control)`	Öffnet das Rad zentriert auf einem Steuerelement — einem Bild, einem Feld, einer Symbolleisten-Schaltfläche —, wo auch immer die Maus ist. Liefert `0` nach der Anforderung, `-5` wenn das Steuerelement nicht gültig ist, `-2` wenn die Komponente nicht erzeugt ist
`long of_show_over (dragobject ado_control, boolean ab_keyboard)`	Ebenso, mit der Angabe, wie das Rad angefordert wurde: `ab_keyboard` auf true, wenn der Benutzer es per Tastatur geöffnet hat (Menütaste, Umschalt+F10) — sein erster Zweig, der antwortet, leuchtet, Eingabe wählt ihn. Liefert `0` nach der Anforderung, `-5` wenn das Steuerelement nicht gültig ist, `-2` wenn die Komponente nicht erzeugt ist
`of_item (string as_keys)`	Liefert das Handle eines Zweigs über seine Adresse, um ihn später zu ändern (Beschriftung, Zustand, Farben). Ein bloßer Schlüssel wird in die vollständige Adresse des einzigen Zweigs aufgelöst, der ihn trägt: `of_item("csv")` und `of_item("import/csv")` liefern dann dasselbe Handle. Mehrdeutig oder von keinem Zweig getragen, liefert er ein Handle, das nichts ändert, statt den falschen Zweig. `of_key()` des Handles liefert den Schlüssel der letzten Ebene
`of_remove_item (string as_keys)`	Entfernt einen Zweig samt Unterrad; die anderen bleiben. Ein bloßer Schlüssel wird wie bei `of_item` aufgelöst. Das angezeigte Rad schließt sich (`ue_dismissed`) nur, wenn es diesen Zweig zeigte: Das Entfernen eines ausgeblendeten lässt es offen. Liefert `0` nach dem Entfernen, `-5` wenn unter dieser Adresse kein Zweig existiert, `-2` wenn die Komponente nicht erzeugt ist
`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 seine vollständige Adresse (`export/pdf`), nicht der bloße Blattschlüssel. Ein Ereignis je Geste: Ein Doppelklick wählt nur einmal
`ue_dismissed ( )`	Das Rad wurde geschlossen, ohne dass ein Zweig gewählt wurde: Klick auf die Nabe, Klick außerhalb des Rades, Escape auf der obersten Ebene — oder durch den Code: `of_close`, `of_clear`, `of_reset`, `of_remove_item` eines Zweigs, den es zeigte, ein zweites `of_show`, das es ersetzt, ein `of_show`, das nichts anzuzeigen hatte. Einmal je Öffnung, sofort: `of_is_open` antwortet bereits false

Ein Klick in eine Ecke des Fensters, außerhalb der Scheibe, zählt als Klick außerhalb: Das Rad schließt sich (ue_dismissed), und der Klick geht an die dahinterliegende Anwendung, statt von einem unsichtbaren Rechteck verschluckt zu werden.

Elementeigenschaften #

Eigenschaft	Typ	Standard	Rolle
`is_text`	string	`""`	Beschriftung des Zweigs. Halten Sie sie kurz: Ein Sektor ist ein Segment, keine Zeile, und zeigt höchstens zwei Zeilen — der angezeigte Zweig zeigt seine vollständige Beschriftung. Leer wird der Schlüssel angezeigt
`ib_enabled`	boolean	`true`	Auf false ist der Zweig ausgegraut und sein Sektor ignoriert jeden Klick. Liest zurück, was Sie gesetzt haben: Ein Zweig, der mangels sichtbarer Untereinträge ausgegraut ist, liest weiterhin true
`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. Ein Zweig, dessen Untereinträge alle ausgeblendet sind, bleibt ausgegraut auf dem Rad: Er hat nichts mehr zu öffnen und lässt sich nicht wie ein Blatt wählen
`ib_checked`	boolean	`false`	Auf true markiert ein feiner Bogen unter dem Band den Zweig als aktiv
`is_image`	string	`""`	Das Symbol des Zweigs, an Ort und Stelle geändert — ein Abspielen, das zu Pause wird. `""` entfernt es. Dieselben Pfade wie bei `of_add_item` (`mono:`, `tint:`, `datei.dll:NAME`)
`is_tone`	string	`""`	Der Ton des Befehls: seine Beschriftung in Ruhe vom Thema gefärbt, hell oder dunkel — `u_pbt_radialmenu.TONE_DANGER` für den, der zerstört, `TONE_WARN`, `TONE_SUCCESS`, `TONE_INFO`. `""` oder `TONE_NEUTRAL` = der Text des Themas; eine eigene Farbe (`il_text_color`) hat Vorrang
`is_group`	string	`""`	Eine Optionsgruppe: Die Zweige einer Gruppe unter demselben Elternteil schließen sich aus — einen anzuhaken (`ib_checked = true` oder die Wahl des Benutzers, vor `ue_item_selected`) hebt die Haken der anderen auf. `""` = ein gewöhnlicher Zweig
`il_accent`	long	`-1`	Akzent dieses Zweigs: sein Band, wenn er angezeigt wird, und seine Markierung (`-1` = der der Komponente)
`il_back_color`	long	`-1`	Band dieses Zweigs im Ruhezustand (`-1` = das des Themas)
`il_text_color`	long	`-1`	Beschriftungsfarbe dieses Zweigs (`-1` = die des Themas)
`il_back_color_hover`	long	`-1`	Sektor dieses Zweigs, während er angezeigt wird (`-1` = der des Themas). Ohne `il_text_color_hover` gesetzt, erhält er einen darauf lesbaren Text
`il_text_color_hover`	long	`-1`	Beschriftungsfarbe dieses Zweigs, während er angezeigt wird (`-1` = die des Themas)

Ein Zweig zeigt keinen Tooltip: Das runde Fenster hat außerhalb seiner Scheibe keinen Platz. Das vom Handle geerbte is_tooltip bleibt erhalten und lässt sich zurücklesen, wird aber nie angezeigt — der angezeigte Zweig zeigt seine vollständige Beschriftung.

Beispiele #

Ein Rad je Kontext #

// Ein Rad, gebaut fuer das, was unter dem Mauszeiger liegt
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 #

// Ereignis ue_item_selected des Radialmenues
// as_keys traegt den vollstaendigen Pfad, z. B. "export/pdf"
choose case as_keys
	case "export/pdf"
		of_export_pdf()
	case "delete"
		of_delete_selection()
end choose

Markieren, ausgrauen, verengen #

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

// Hoechstens vier Zweige auf einem Ring
uo_wheel.ii_max_sectors = 4

Per Tastatur, und per Code geschlossen #

// Menuetaste auf dem Raster: das Rad oeffnet sich zentriert darauf, erster Zweig leuchtet
uo_wheel.of_show_over(/*control*/ dw_orders, /*keyboard*/ true)

// Spaeter, aus einem Zeitgeber: das Rad schliesst ohne Wahl (ue_dismissed)
if uo_wheel.of_is_open() then uo_wheel.of_close()

Eine Optionsgruppe, ein zerstörender Befehl #

// Drei sich ausschliessende Zweige: einen zu waehlen hebt die anderen auf
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 nimmt den Ton der Gefahr an, hell oder dunkel
uo_wheel.of_item(/*keys*/ "delete").is_tone = u_pbt_radialmenu.TONE_DANGER

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. Der Sektor ist für die Richtung da; der ganze Text ist erst lesbar, wenn der Zweig angezeigt wird.
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
`is_accessible_name` · `is_accessible_description`	Name und Beschreibung, die ein Bildschirmleser sagt	3.4 Optionale Eigenschaften und Events

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.