radialmenu — u_pbt_radialmenu #
← Referencia de componentes · Índice de la guía
Menú contextual radial: los comandos en corona alrededor del cursor, elegidos por su dirección en lugar de leídos en una lista.
▶ Verlo en vivo — Aplicación de demostración, mosaico Radial menu: la vista previa, el código que lo produce y esta página, lado a lado.
En resumen #
| Userobject | u_pbt_radialmenu |
| Clase de elementos | n_pbt_radialmenu_item (of_item(keys)) |
| Sirve para | Ofrecer un puñado de comandos frecuentes donde la mano ya está |
| Principio | Usted describe las ramas; la rueda, la forma y la navegación son cosa nuestra |
Inicio rápido #
// Una rueda montada para lo que esta bajo el 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")
// Se abre al soltar el boton derecho: ver ue_rclickedAbrir y luego elegir #
La rueda se abre al soltar el botón derecho, y hace falta un segundo clic para elegir. No es un detalle de implementación: si se abriera al pulsar, el soltado de ese mismo clic seleccionaría de inmediato el sector caído bajo el cursor, y el usuario lanzaría un comando sin haberlo visto.
Por eso of_show() se llama desde el evento de clic derecho del control sobre el que el usuario hace el gesto (un statictext, un button, una rejilla…): en ese instante el botón ya está arriba, y el clic siguiente es realmente el que elige. El menú radial en sí no tiene superficie — por tanto ningún evento de ratón propio.
El componente en sí es invisible: no ocupa sitio en la ventana. Colóquelo donde sea, con anchura y altura cero — solo existe mientras la rueda está abierta.
La rama señalada — con el ratón o el teclado — muestra su etiqueta entera, por encima de sus vecinas: un sector conserva dos líneas como máximo (una sola a partir de nueve ramas), y eso es lo que le permite llevar una etiqueta corta sin mentir sobre lo que hace. El cubo central es la salida: hacer clic en él cierra la rueda; dentro de una sub-rueda, sube un nivel. Mientras la rueda está abierta la aplicación sigue funcionando: una rama retirada, atenuada u oculta entretanto ya no se elige (en su lugar, ue_dismissed), y of_clear, of_remove_item u of_reset cierran la rueda abierta.
// Se abre al soltar el boton derecho: ver ue_rclicked
uo_wheel.of_show()Con el teclado, las flechas recorren las ramas saltando las atenuadas, Intro o Espacio elige, ← y Retroceso suben un nivel, y Escape sube un nivel en una sub-rueda — solo cierra la rueda en la raíz. Ninguna de estas teclas llega a la aplicación mientras la rueda está abierta. En lectura de derecha a izquierda, la corona gira en el otro sentido y ← y → se intercambian: → sube un nivel.
Las sub-ruedas #
Una dirección cuelga ramas bajo otra: export/pdf. Elegir la rama padre no elige nada: la rueda es sustituida por la de sus hijos, y el cubo pasa a ser la vuelta atrás.
¿Por qué sustituir en lugar de añadir una segunda corona? Porque un anillo exterior dividiría los sectores por dos en cada nivel. Ocho ramas ya es el máximo legible; no hay sitio para mostrar dos niveles a la vez.
El evento ue_item_selected informa de la dirección completa (export/pdf), no de la clave de la hoja sola. Dos sub-ruedas pueden por tanto nombrar sus ramas igual.
// 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")Para quitar una rama — con su sub-rueda — sin reconstruir toda la rueda: of_remove_item("export/csv"). Las demás ramas se quedan en su sitio.
Cuando hay demasiadas ramas #
Una rueda se lee por dirección, y más allá de ocho sectores las porciones dejan de distinguirse. ii_max_sectors fija ese tope (de 3 a 12, 8 por defecto).
Las ramas sobrantes no se pierden: el último lugar de la corona pasa a ser una rama que las contiene todas y que se abre como sub-rueda. Un menú que dejara caer su cola sería un menú que miente sobre lo que ofrece.
Estrechar la corona suele salir a cuenta: cuatro ramas anchas se apuntan más deprisa que ocho estrechas.
Propiedades #
| Propiedad | Tipo | Predeterminado | Función |
|---|---|---|---|
ii_max_sectors | integer | 8 | Cuántas ramas puede llevar una corona (3 a 12). Lo que sobra pasa bajo una última rama que se abre como sub-rueda. Por encima de ocho, la rueda se compacta (icono más pequeño, etiqueta en una línea) para que las etiquetas no se solapen |
is_theme_style | string | "" | Estilo visual del componente (constantes THEME_STYLE_*); vacío = el de la aplicación, seguido en cada cambio |
is_theme_mode | string | "" | Variante clara u oscura (constantes THEME_MODE_*); vacío = la de la aplicación, seguida en cada cambio |
il_theme_accent | long | -1 | Color de acento de este componente (-1 = acento de la aplicación, o el del tema) |
is_tooltip | string | "" | Información sobre herramientas simple. Conservada por compatibilidad: el lanzador es invisible, no tiene superficie que sobrevolar, y nada la muestra |
is_super_tooltip_title | string | "" | Título de la información enriquecida. Conservado por compatibilidad, nunca se muestra — véase is_tooltip |
is_super_tooltip_text | string | "" | Texto de la información enriquecida. Conservado por compatibilidad, nunca se muestra — véase is_tooltip |
is_super_tooltip_image | string | "" | Imagen de la información enriquecida. Conservada por compatibilidad, nunca se muestra — véase is_tooltip |
Métodos #
| Método | Función | |
|---|---|---|
of_add_item (string as_keys, string as_text) | Añade una rama en su dirección: format/strike cuelga bajo Format, que debe existir ya. Esa misma dirección vuelve en ue_item_selected cuando se elige. Devuelve 0 una vez añadida, -5 si la dirección se rechaza (padre no encontrado, dirección ya ocupada, nivel vacío como export/ o /pdf, clave que contiene ` | o empieza por __), -2` si el componente no está creado |
of_add_item (string as_keys, string as_text, string as_image, boolean ab_checked) | Lo mismo, con el icono y la marca — el icono como tercer argumento, como en todo el resto de la biblioteca. Una rama se atenúa mediante su manejador: of_item(keys).ib_enabled = false. Devuelve 0 una vez añadida, -5 si la dirección se rechaza (padre no encontrado, dirección ya ocupada, nivel vacío como export/ o /pdf, clave que contiene ` | o empieza por __), -2` si el componente no está creado |
of_clear ( ) | Vacía la rueda y libera los manejadores obtenidos con of_item (cada uno designaba una rama que ya no existe). Devuelve 0 una vez aplicado, -2 si el componente no está creado | |
long of_show ( ) | Abre la rueda centrada en el cursor. Llámelo desde el clic derecho del control que recibe el gesto. Una rueda sin ninguna rama visible no se abre: se lanza ue_dismissed. Devuelve 0 una vez solicitado, -2 si el componente no está creado | |
long of_show (long al_x, long al_y) | Lo mismo, centrada en una posición de pantalla en píxeles. Unas coordenadas negativas son un punto real, (-1, -1) incluido: una pantalla situada a la izquierda o por encima de la principal. Devuelve 0 una vez solicitado, -2 si el componente no está creado | |
of_item (string as_keys) | Devuelve el manejador de una rama, por su dirección, para modificarla después (etiqueta, estado, colores). Una clave sola se resuelve en la dirección completa de la única rama que la lleva: of_item("csv") y of_item("import/csv") devuelven entonces el mismo manejador. Ambigua, o sin ninguna rama que la lleve, devuelve un manejador que no cambia nada en lugar de la rama equivocada. of_key() del manejador devuelve la clave del último nivel | |
of_remove_item (string as_keys) | Quita una rama y su sub-rueda; las demás se quedan. Devuelve 0 una vez quitada, -5 si ninguna rama vive en esa dirección, -2 si el componente no está creado | |
of_reset ( ) | Vacía la rueda y devuelve todas las propiedades a su valor de origen. Devuelve 0 una vez aplicado, -2 si el componente no está creado |
Eventos #
| Evento | Se dispara cuando |
|---|---|
ue_item_selected (string as_keys) | El usuario ha elegido una rama. as_keys es su dirección completa (export/pdf), no la clave de la hoja sola. Un solo evento por gesto: un doble clic elige una sola vez |
ue_dismissed ( ) | La rueda se cerró sin que se eligiera ninguna rama: clic en el cubo, clic fuera de la rueda, Escape en la raíz — y también cuando of_show no tenía nada que mostrar |
Un clic en una esquina de la ventana, fuera del disco, cuenta como un clic fuera: la rueda se cierra (
ue_dismissed) y el clic pasa a la aplicación de detrás, en lugar de ser tragado por un cuadrado invisible.
Propiedades de elemento #
| Propiedad | Tipo | Predeterminado | Función |
|---|---|---|---|
is_text | string | "" | Etiqueta de la rama. Manténgala corta: un sector es una porción, no una línea, y muestra dos líneas como máximo — la rama señalada muestra su etiqueta entera. Vacía, se muestra la clave |
ib_enabled | boolean | true | A falso, la rama queda atenuada y su sector ignora todo clic |
ib_visible | boolean | true | A falso, la rama sale de la rueda — subrueda incluida — sin ser eliminada; los sectores se cierran, y vuelve tal cual. Una rama cuyas subentradas están todas ocultas se queda en la rueda, atenuada: ya no tiene nada que abrir y no se elige como una hoja |
ib_checked | boolean | false | A verdadero, un arco fino bajo la banda marca la rama como activa |
il_accent | long | -1 | Acento de esta rama: su banda cuando está señalada, y su marca (-1 = el del componente) |
il_back_color | long | -1 | Banda de esta rama en reposo (-1 = la del tema) |
il_text_color | long | -1 | Color de la etiqueta de esta rama (-1 = el del tema) |
il_back_color_hover | long | -1 | Porción de esta rama mientras está señalada (-1 = la del tema) |
il_text_color_hover | long | -1 | Color de la etiqueta de esta rama mientras está señalada (-1 = el del tema) |
Una rama no muestra ninguna información sobre herramientas: la ventana redonda no tiene sitio fuera del disco. El is_tooltip heredado por el manejador se conserva y se relee, pero nunca se muestra — es la rama señalada la que muestra su etiqueta entera.
Ejemplos #
Una rueda por contexto #
// Una rueda montada para lo que esta bajo el 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)Reaccionar a la ruta elegida #
// Evento ue_item_selected del menu radial
// as_keys lleva la ruta completa, p. ej. "export/pdf"
choose case as_keys
case "export/pdf"
of_export_pdf()
case "delete"
of_delete_selection()
end chooseMarcar, atenuar, estrechar #
// 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
// Cuatro ramas como maximo en una corona
uo_wheel.ii_max_sectors = 4Buenas prácticas #
- Abra al SOLTAR el clic derecho del control, nunca al pulsar. Es lo que separa abrir de elegir, y el usuario necesita ambas cosas.
- Etiquetas cortas. Una o dos palabras. El sector está para la dirección; el texto entero solo se lee al señalar la rama.
- De cuatro a seis ramas superan a ocho. Una rueda se recuerda por la posición; cuantas menos posiciones, antes se aprenden.
- Ponga los comandos más frecuentes arriba y abajo. Son las dos direcciones que la mano alcanza sin pensar.
- Mantenga el orden estable de una apertura a otra: todo el interés de una rueda es que el gesto acabe precediendo a la lectura.
- Un menú radial no sustituye a un menú de lista. Veinte comandos raros se leen mejor en una lista; reserve la rueda para el puñado que se usa sin parar.
Heredado de la base común #
Estos miembros existen en todos los componentes visuales — no son propios de este. Se detallan una sola vez, en los capítulos transversales; esta tabla solo dice dónde leerlos.
| Miembros | Función | Detallado en |
|---|---|---|
of_count · of_keys_at · of_has | Recorrer lo que el componente contiene | 3.2 Los items |
of_reset | Poner el componente a cero | 3.6 Poner un componente a cero: of_reset() |
of_register_shortcut · of_clear_shortcuts | Atajos de teclado del componente | 3.5 Los atajos de teclado |
of_is_created · of_is_ready · of_get_last_error | Si ha nacido, si está listo, qué ha fallado | 3.7 Diagnóstico |
of_save_as_png · of_save_as_jpg | Exportar el render como imagen | 3.8 Exportar la representación como imagen |
of_set_redraw | Agrupar los cambios en un solo repintado | 3.10 Buenas prácticas |
of_preload_icons | Iconos mostrados sin retardo | Visualización instantánea: of_icon |
of_set_translation | Traducir una etiqueta del componente | 5.2 Adaptar una etiqueta: of_set_translation |
of_focus_webview | Dar el foco al componente | 6.4 Teclado y foco |
of_print · of_print_to_pdf | Imprimir, o escribir un PDF | 6.9 Imprimir |
of_set_property · of_get_property · of_component_name | Controlar una propiedad por su nombre | 3.1 El motor de propiedades |
Dos ayudas no se heredan: of_icon y of_escape_markup viven en n_pbt_utils. Declare uno — n_pbt_utils lnv_utils, nada que crear — y llámelas sobre él.