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_rclickedAprire, 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), e of_clear, of_remove_item o of_reset chiudono la ruota aperta.
// 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.
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) |
is_tooltip | string | "" | Descrizione comando semplice. Mantenuta per compatibilità: il lanciatore è invisibile, non ha alcuna superficie da sorvolare, e nulla la mostra |
is_super_tooltip_title | string | "" | Titolo della descrizione arricchita. Mantenuto per compatibilità, mai mostrato — vedere is_tooltip |
is_super_tooltip_text | string | "" | Testo della descrizione arricchita. Mantenuto per compatibilità, mai mostrato — vedere is_tooltip |
is_super_tooltip_image | string | "" | Immagine della descrizione arricchita. Mantenuta per compatibilità, mai mostrata — vedere is_tooltip |
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 | |
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. 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 | |
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. 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 — e anche quando of_show non aveva nulla da mostrare |
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 |
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 |
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) |
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 chooseSegnare, 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 = 4Buone 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à |
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.