radialmenu — `u_pbt_radialmenu` #

← Riferimento dei componenti · Sommario della guida

Menu contestuale radiale: i comandi a corona attorno al cursore, scelti per direzione anziché letti in un elenco.

▶ Vederlo dal vivo — Applicazione dimostrativa, riquadro Radial menu: l'anteprima, il codice che lo produce e questa pagina, affiancati.

In breve #

Userobject	`u_pbt_radialmenu`
Classe di elementi	`n_pbt_radialmenu_item` (`of_item(keys)`)
Serve a	Offrire una manciata di comandi frequenti dove la mano già si trova
Principio	Voi descrivete i rami; la ruota, la forma e la navigazione sono affar nostro

Avvio rapido #

// Una ruota costruita per cio che sta sotto il cursore
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")

// Si apre al rilascio del tasto destro: vedere ue_rclicked

Aprire, poi scegliere #

La ruota si apre al rilascio del tasto destro, e serve un secondo clic per scegliere. Non è un dettaglio implementativo: se si aprisse alla pressione, il rilascio di quello stesso clic selezionerebbe subito il settore capitato sotto il cursore, e l'utente lancerebbe un comando senza averlo visto.

Per questo of_show() si chiama dall'evento di clic destro del controllo su cui l'utente compie il gesto (uno statictext, un button, una griglia…): a quel punto il tasto è già alzato, e il clic successivo è davvero quello che sceglie. Il menu radiale, di suo, non ha alcuna superficie — quindi nessun evento del mouse.

Il componente in sé è invisibile: non occupa spazio nella finestra. Mettetelo ovunque, con larghezza e altezza nulle — esiste solo finché la ruota è aperta.

Il ramo puntato — con il mouse o da tastiera — mostra l'etichetta intera, sopra i vicini: un settore tiene al massimo due righe (una sola oltre gli otto rami), ed è ciò che gli permette di portare un'etichetta breve senza mentire su ciò che fa. Il mozzo centrale è l'uscita: un clic chiude la ruota; dentro una sotto-ruota, risale di un livello. Finché la ruota è aperta l'applicazione continua a girare: un ramo rimosso, disattivato o nascosto nel frattempo non si sceglie più (al suo posto ue_dismissed); of_clear, of_reset, of_close e un secondo of_show chiudono la ruota aperta, così come of_remove_item quando la ruota mostrava il ramo rimosso — ue_dismissed viene sollevato subito, e of_is_open risponde falso appena la chiamata ritorna.

// Si apre al rilascio del tasto destro: vedere ue_rclicked
uo_wheel.of_show()

Da tastiera, le frecce percorrono i rami saltando quelli disattivati, Invio o Spazio sceglie, ← e Backspace risalgono di un livello, ed Esc risale di un livello in una sotto-ruota — chiude la ruota solo alla radice. Nessuno di questi tasti arriva all'applicazione finché la ruota è aperta. In lettura da destra a sinistra, la corona gira nell'altro senso e ← e → si scambiano: → risale di un livello.

Per aprirla da tastiera — il tasto Menu, Maiusc+F10 —, chiamate of_show_over dal controllo che ha il focus, con ab_keyboard a vero: la ruota si centra su quel controllo, ovunque sia il mouse, e il suo primo ramo che risponde è acceso — Invio lo sceglie, le frecce proseguono da lì. of_show_over(controllo) senza quel secondo argomento serve anche a un pulsante di barra degli strumenti: la ruota si apre sopra di esso.

Le sotto-ruote #

Un indirizzo aggancia rami sotto un altro: export/pdf. Scegliere il ramo padre non sceglie nulla: la ruota viene sostituita da quella dei suoi figli, e il mozzo diventa la via del ritorno.

Perché sostituire invece di aggiungere una seconda corona? Perché un anello esterno dimezzerebbe i settori a ogni livello. Otto rami sono già il massimo leggibile; non c'è spazio per mostrarne due livelli insieme.

L'evento ue_item_selected riporta l'indirizzo completo (export/pdf), non la sola chiave della foglia. Due sotto-ruote possono quindi chiamare i loro rami allo stesso modo.

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

Per rimuovere un ramo — con la sua sotto-ruota — senza ricostruire tutta la ruota: of_remove_item("export/csv"). Gli altri rami restano al loro posto.

Quando i rami sono troppi #

Una ruota si legge per direzione, e oltre gli otto settori le fette smettono di distinguersi. ii_max_sectors fissa questo tetto (da 3 a 12, 8 per impostazione predefinita).

I rami in eccesso non vanno persi: l'ultimo posto della corona diventa un ramo che li contiene tutti e che si apre come sotto-ruota. Un menu che lasciasse cadere la coda sarebbe un menu che mente su ciò che offre.

Stringere la corona è spesso un guadagno: quattro rami larghi si mirano più in fretta di otto stretti.

Proprietà #

Proprietà	Tipo	Predefinito	Ruolo
`ii_max_sectors`	integer	`8`	Quanti rami può portare una corona (da 3 a 12). Ciò che eccede passa sotto un ultimo ramo che si apre come sotto-ruota. Oltre otto, la ruota si stringe (icona più piccola, etichetta su una riga) perché le etichette non si sovrappongano
`is_theme_style`	string	`""`	Stile visivo del componente (costanti `THEME_STYLE_*`); vuoto = quello dell'applicazione, seguito a ogni cambio
`is_theme_mode`	string	`""`	Variante chiara o scura (costanti `THEME_MODE_*`); vuoto = quella dell'applicazione, seguita a ogni cambio
`il_theme_accent`	long	`-1`	Colore d'accento di questo componente (`-1` = accento dell'applicazione, o quello del tema)

Metodi #

Metodo	Ruolo
`of_add_item (string as_keys, string as_text)`	Aggiunge un ramo al suo indirizzo: `format/strike` si aggancia sotto Format, che deve già esistere. È questo stesso indirizzo che torna in `ue_item_selected` quando viene scelto. Restituisce `0` una volta aggiunto, `-5` se l'indirizzo è rifiutato (padre non trovato, indirizzo già occupato, livello vuoto come `export/` o `/pdf`, chiave che contiene `	`o inizia con` __`),` -2` se il componente non è creato
`of_add_item (string as_keys, string as_text, string as_image, boolean ab_checked)`	Lo stesso, con l'icona e il segno — l'icona come terzo argomento, come ovunque altrove nella libreria. Un ramo si disattiva tramite la sua maniglia: `of_item(keys).ib_enabled = false`. Restituisce `0` una volta aggiunto, `-5` se l'indirizzo è rifiutato (padre non trovato, indirizzo già occupato, livello vuoto come `export/` o `/pdf`, chiave che contiene `	`o inizia con` __`),` -2` se il componente non è creato
`of_clear ( )`	Svuota la ruota e libera le maniglie ottenute con `of_item` (ognuna designava un ramo che non esiste più). Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_close ( )`	Chiude la ruota del componente se è sullo schermo, senza scelta: `ue_dismissed` viene sollevato subito, come per un clic fuori — anche per una ruota chiesta un istante prima e non ancora disegnata — e `of_is_open` risponde falso appena ritorna. Niente di aperto, non succede nulla. Restituisce `0` una volta fatto, `-2` se il componente non è creato
`of_is_open ( )`	`true` finché una ruota del componente è sullo schermo — aperta, e non ancora conclusa da una scelta o da una chiusura. `of_show` e `of_close` sono applicati prima di ritornare: risponde vero subito dopo `of_show`, falso subito dopo `of_close`
`long of_show ( )`	Apre la ruota centrata sul cursore. Da chiamare dal clic destro del controllo che riceve il gesto. Una ruota senza alcun ramo visibile non si apre: viene sollevato `ue_dismissed`. Una ruota ancora sullo schermo viene sostituita: solleva prima `ue_dismissed`. Restituisce `0` una volta richiesto, `-2` se il componente non è creato
`long of_show (long al_x, long al_y)`	Lo stesso, centrata su una posizione schermo in pixel. Coordinate negative sono un punto vero, `(-1, -1)` compreso: uno schermo posto a sinistra o sopra quello principale. Restituisce `0` una volta richiesto, `-2` se il componente non è creato
`long of_show_over (dragobject ado_control)`	Apre la ruota centrata su un controllo — un'immagine, un campo, un pulsante di barra degli strumenti —, ovunque sia il mouse. Restituisce `0` una volta richiesto, `-5` se il controllo non è valido, `-2` se il componente non è creato
`long of_show_over (dragobject ado_control, boolean ab_keyboard)`	Idem, dicendo come la ruota è stata chiesta: `ab_keyboard` a vero quando l'utente l'ha aperta da tastiera (tasto Menu, Maiusc+F10) — il suo primo ramo che risponde è acceso, Invio lo sceglie. Restituisce `0` una volta richiesto, `-5` se il controllo non è valido, `-2` se il componente non è creato
`of_item (string as_keys)`	Restituisce la maniglia di un ramo, tramite il suo indirizzo, per modificarlo in seguito (etichetta, stato, colori). Una chiave nuda viene risolta nell'indirizzo completo dell'unico ramo che la porta: `of_item("csv")` e `of_item("import/csv")` restituiscono allora la stessa maniglia. Ambigua, o portata da nessun ramo, restituisce una maniglia che non cambia nulla piuttosto che il ramo sbagliato. `of_key()` della maniglia restituisce la chiave dell'ultimo livello
`of_remove_item (string as_keys)`	Rimuove un ramo e la sua sotto-ruota; gli altri restano. Una chiave nuda viene risolta come fa `of_item`. La ruota sullo schermo si chiude (`ue_dismissed`) solo se mostrava quel ramo: rimuoverne uno nascosto la lascia aperta. Restituisce `0` una volta rimosso, `-5` se nessun ramo vive a quell'indirizzo, `-2` se il componente non è creato
`of_reset ( )`	Svuota la ruota e riporta ogni proprietà al suo valore d'origine. Restituisce `0` una volta applicato, `-2` se il componente non è creato

Eventi #

Evento	Scatta quando
`ue_item_selected (string as_keys)`	L'utente ha scelto un ramo. `as_keys` è il suo indirizzo completo (`export/pdf`), non la sola chiave della foglia. Un solo evento per gesto: un doppio clic sceglie una volta sola
`ue_dismissed ( )`	La ruota si è chiusa senza che alcun ramo fosse scelto: clic sul mozzo, clic fuori dalla ruota, Esc alla radice — o dal codice: `of_close`, `of_clear`, `of_reset`, `of_remove_item` di un ramo che mostrava, un secondo `of_show` che la sostituisce, un `of_show` che non aveva nulla da mostrare. Una volta per apertura, subito: `of_is_open` risponde già falso

Un clic in un angolo della finestra, fuori dal disco, conta come un clic all'esterno: la ruota si chiude (ue_dismissed) e il clic passa all'applicazione retrostante, invece di essere inghiottito da un quadrato invisibile.

Proprietà di elemento #

Proprietà	Tipo	Predefinito	Ruolo
`is_text`	string	`""`	Etichetta del ramo. Tenetela breve: un settore è una fetta, non una riga, e mostra al massimo due righe — il ramo puntato mostra l'etichetta intera. Vuota, si mostra la chiave
`ib_enabled`	boolean	`true`	A falso il ramo è disattivato e il suo settore ignora ogni clic. Si rilegge come l'avete impostato: un ramo disattivato perché nessuna sotto-voce è visibile rilegge sempre vero
`ib_visible`	boolean	`true`	A falso, il ramo esce dalla ruota — sotto-ruota compresa — senza essere rimosso; i settori si stringono, e torna com'era. Un ramo le cui sotto-voci sono tutte nascoste resta sulla ruota, disattivato: non ha più nulla da aprire e non si sceglie come una foglia
`ib_checked`	boolean	`false`	A vero, un arco sottile sotto la fascia segna il ramo come attivo
`is_image`	string	`""`	L'icona del ramo, cambiata sul posto — un Riproduci che diventa Pausa. `""` la toglie. Stessi percorsi di `of_add_item` (`mono:`, `tint:`, `file.dll:NOME`)
`is_tone`	string	`""`	Il tono del comando: la sua etichetta colorata dal tema, chiaro o scuro, a riposo — `u_pbt_radialmenu.TONE_DANGER` per quello che distrugge, `TONE_WARN`, `TONE_SUCCESS`, `TONE_INFO`. `""` o `TONE_NEUTRAL` = il testo del tema; un colore vostro (`il_text_color`) prevale
`is_group`	string	`""`	Un gruppo radio: i rami di uno stesso gruppo sotto lo stesso genitore si escludono — spuntarne uno (`ib_checked = true`, o la scelta dell'utente, prima di `ue_item_selected`) toglie la spunta agli altri. `""` = un ramo ordinario
`il_accent`	long	`-1`	Accento di questo ramo: la sua fascia quando è puntato, e il suo segno (`-1` = quello del componente)
`il_back_color`	long	`-1`	Fascia di questo ramo a riposo (`-1` = quella del tema)
`il_text_color`	long	`-1`	Colore dell'etichetta di questo ramo (`-1` = quello del tema)
`il_back_color_hover`	long	`-1`	Spicchio di questo ramo quando è puntato (`-1` = quello del tema). Dato senza `il_text_color_hover`, riceve un testo leggibile sopra
`il_text_color_hover`	long	`-1`	Colore dell'etichetta di questo ramo quando è puntato (`-1` = quello del tema)

Un ramo non mostra alcuna descrizione comando: la finestra rotonda non ha spazio fuori dal disco. L'is_tooltip ereditato dalla maniglia è conservato e si rilegge, ma non viene mai mostrato — è il ramo puntato a mostrare l'etichetta intera.

Esempi #

Una ruota per contesto #

// Una ruota costruita per cio che sta sotto il cursore
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)

Reagire al percorso scelto #

// Evento ue_item_selected del menu radiale
// as_keys porta il percorso completo, ad es. "export/pdf"
choose case as_keys
	case "export/pdf"
		of_export_pdf()
	case "delete"
		of_delete_selection()
end choose

Segnare, disattivare, stringere #

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

// Al massimo quattro rami su una corona
uo_wheel.ii_max_sectors = 4

Da tastiera, e chiusa dal codice #

// Tasto Menu sulla griglia: la ruota si apre centrata su di essa, primo ramo acceso
uo_wheel.of_show_over(/*control*/ dw_orders, /*keyboard*/ true)

// Piu tardi, da un timer: la ruota si chiude senza scelta (ue_dismissed)
if uo_wheel.of_is_open() then uo_wheel.of_close()

Un gruppo radio, un comando che distrugge #

// Tre rami esclusivi: sceglierne uno toglie la spunta agli altri due
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 prende il tono del pericolo, chiaro o scuro
uo_wheel.of_item(/*keys*/ "delete").is_tone = u_pbt_radialmenu.TONE_DANGER

Buone pratiche #

Aprite al RILASCIO del clic destro del controllo, mai alla pressione. È ciò che separa l'aprire dallo scegliere, e all'utente servono entrambi.
Etichette brevi. Una o due parole. Il settore è lì per la direzione; il testo intero si legge solo puntando il ramo.
Da quattro a sei rami battono otto. Una ruota si ricorda per posizione; meno posizioni ci sono, più in fretta si imparano.
Mettete i comandi più frequenti in alto e in basso. Sono le due direzioni che la mano raggiunge senza pensarci.
Tenete l'ordine stabile da un'apertura all'altra: tutto il senso di una ruota è che il gesto finisca per precedere la lettura.
Un menu radiale non sostituisce un menu a elenco. Venti comandi rari si leggono meglio in un elenco; riservate la ruota alla manciata che si usa di continuo.

Ereditato dalla base comune #

Questi membri esistono su tutti i componenti visivi — non sono propri di questo. Sono descritti una sola volta, nei capitoli trasversali; questa tabella dice solo dove leggerli.

Membri	Ruolo	Descritto in
`of_count` · `of_keys_at` · `of_has`	Percorrere ciò che il componente contiene	3.2 Gli item
`of_reset`	Riportare il componente a zero	3.6 Riportare un componente a zero: `of_reset()`
`of_register_shortcut` · `of_clear_shortcuts`	Scorciatoie da tastiera del componente	3.5 Le scorciatoie da tastiera
`of_is_created` · `of_is_ready` · `of_get_last_error`	Se è nato, se è pronto, cosa è fallito	3.7 Diagnostica
`of_save_as_png` · `of_save_as_jpg`	Esportare il rendering in immagine	3.8 Esportare il rendering come immagine
`of_set_redraw`	Raggruppare le modifiche in un solo ridisegno	3.10 Buone pratiche
`of_preload_icons`	Icone mostrate senza ritardo	Visualizzazione istantanea: `of_icon`
`of_set_translation`	Tradurre una dicitura del componente	5.2 Adattare un'etichetta: `of_set_translation`
`of_focus_webview`	Dare il focus al componente	6.4 Tastiera e focus
`of_print` · `of_print_to_pdf`	Stampare, o scrivere un PDF	6.9 Stampare
`of_set_property` · `of_get_property` · `of_component_name`	Pilotare una proprietà per nome	3.1 Il motore delle proprietà
`is_accessible_name` · `is_accessible_description`	Il nome e la descrizione che dice un lettore di schermo	3.4 Proprietà ed event opzionali

Su questo lanciatore invisibile, of_count e of_keys_at percorrono ciò che avete aggiunto, rami nascosti compresi — non ciò che la ruota disegnerà. L'esportazione come immagine, la stampa, of_focus_webview e of_set_redraw non hanno qui alcun effetto utile: il componente non disegna nulla di suo, la ruota vive nella propria finestra.

Due aiuti non sono ereditati: of_icon e of_escape_markup vivono su n_pbt_utils. Ne dichiari uno — n_pbt_utils lnv_utils, niente da creare — e li chiami su di esso.