angulargauge — `u_pbt_angulargauge` #

← Referencia de componentes · Índice de la guía

Esfera: un valor leído en una escala circular — una aguja, un arco lleno o una marca en el borde, rangos de color que dicen si está bien, un objetivo, una lectura en el formato que usted elija.

▶ Verlo en vivo — Aplicación de demostración, mosaico Angular gauge : la vista previa, el código que lo produce y esta página, lado a lado.

En resumen #

Userobject	`u_pbt_angulargauge`
Clase de elementos	`n_pbt_angulargauge_range (of_range(key))`
Sirve para	Leer una magnitud de un vistazo — velocidad, temperatura, grado de cumplimiento de un objetivo, mando de termostato
Principio	Usted da una escala, un valor y rangos; las marcas, los números, los colores y la animación son cosa nuestra
Familia	Gemelo de gauge: mismos métodos, mismos eventos y, salvo la geometría, mismas propiedades — aquí los ángulos y los extremos redondeados, allí la orientación y la colocación de los rangos

Inicio rápido #

// A scale from 0 to 240, a number every 20
uo_dial.id_maximum = 240
uo_dial.id_tick_step = 20

// Three ranges of the scale, each with the tone of what it means
uo_dial.of_add_range(/*key*/ "city", /*from*/ 0, /*to*/ 130)
uo_dial.of_add_range(/*key*/ "fast", /*from*/ 130, /*to*/ 180)
uo_dial.of_add_range(/*key*/ "limit", /*from*/ 180, /*to*/ 240)
uo_dial.of_range(/*key*/ "city").is_tone = u_pbt_angulargauge.TONE_SUCCESS
uo_dial.of_range(/*key*/ "fast").is_tone = u_pbt_angulargauge.TONE_WARN
uo_dial.of_range(/*key*/ "limit").is_tone = u_pbt_angulargauge.TONE_DANGER

// The unit, and the value : the needle turns to it
uo_dial.is_unit = "km/h"
uo_dial.id_value = 96

La escala, el valor y los rangos #

La escala va de id_minimum a id_maximum (de 0 a 100 por defecto). El valor id_value se relee tal como usted lo dio: fuera de la escala se dibuja en el tope del extremo más cercano y la lectura lo escribe igualmente — un indicador que reescribiera en silencio lo que la aplicación midió mentiría dos veces. Puesto por el código no lanza ningún evento, como SetItem: ue_value_changed dice lo que hizo el usuario. NULL se ignora: el valor anterior se queda — compruebe una medida que puede faltar (GetItemNumber devuelve NULL) antes de ponerla.

Los números siguen is_format, el formato de visualización de un DataWindow (#,##0.0, $#,##0, 0% escribe la PARTE de la escala — 50 sobre 0..200 da 25 %, como la barra de progreso), con los separadores del idioma de visualización. Sin formato, la escala elige los decimales de la lectura — dos para una escala de 0 a 1, ninguno para 0 a 100 —, nunca el valor, que escribiría 43 un segundo y 42,55 el siguiente; los números de la escala toman los de su paso.

Un rango colorea una parte de la escala: su color es el que usted da, si no el de su tono (TONE_SUCCESS, TONE_WARN, TONE_DANGER, TONE_INFO = el acento del tema, TONE_NEUTRAL — un juego de colores por modo claro u oscuro), si no el de la paleta. Los rangos se superponen en el orden en que se añadieron; of_current_range() dice en cuál está el valor. Bajo una aguja son la banda; bajo un arco lleno, un anillo en su interior. Un rango contiene su principio pero no su fin: en el límite que comparten dos rangos (60 entre 0–60 y 60–85), el valor está en el que empieza ahí, sea cual sea el orden en que se añadieron; el extremo de la escala pertenece al rango que lo alcanza. El color de paleta de un rango se fija al añadirlo: quitar uno no cambia el color de los demás. Un rango entero fuera de la escala no se dibuja.

Los ángulos se cuentan en grados, 0 arriba, en el sentido de las agujas del reloj: por defecto la escala empieza en -135 (abajo a la izquierda) y cubre 270 grados — un velocímetro. ii_start_angle = -90 e ii_sweep_angle = 180 dan media esfera, dibujada el doble de grande. Una esfera es un instrumento de medida: no se invierte en una aplicación de derecha a izquierda.

Propiedades #

Propiedad	Tipo	Por defecto	Función
`is_title`	string	`""`	El título, encima de la esfera. Se admite marcado; también nombra el componente para un lector de pantalla. Sin título, lo nombra el texto simple de la información sobre herramientas (`is_super_tooltip_title`, si no `is_tooltip`), si no la palabra « Indicador » en el idioma de visualización
`id_value`	double	`0`	El valor. Se desliza a su sitio; fuera de la escala, dibujado en el tope y releído tal cual. Puesto por el código, mudo; `NULL` se ignora, el valor anterior se queda
`id_minimum`	double	`0`	El principio de la escala. Una escala cuyo mínimo no está por debajo del máximo está vacía: ni marca, ni número, ni rango, ni indicador, ni objetivo, y `of_current_range()` devuelve una cadena vacía. Para invertir una escala, `ib_reversed`
`id_maximum`	double	`100`	El final de la escala
`is_format`	string	`""`	El formato de visualización de todos los números — lectura, escala, extremos de un rango —, con la sintaxis de un formato de DataWindow (`#,##0.00`, `$#,##0`, `0%`), separadores del idioma de visualización. Vacío = la lectura toma los decimales de la escala (dos para 0 a 1, ninguno para 0 a 100), los números de la escala los de su paso (0,0, 0,2… 1,0)
`is_unit`	string	`""`	Se escribe tras el valor en la lectura (`%`, `km/h`)
`ib_show_value`	boolean	`true`	Muestra la lectura — el valor y su unidad — bajo el pivote de una aguja (bajo los números de los dos extremos en una esfera pequeña), en el centro de un arco lleno. Sin lectura, una esfera de aguja se dibuja más grande
`id_tick_step`	double	`0`	El paso entre dos marcas numeradas. `0` = elegido por la escala: un paso redondo (1, 2, 2,5 o 5 veces una potencia de diez, luego 3, 4,5 o 6) que cae en los dos extremos cuando lo hay — de 0 a 90 de 10 en 10, de −50 a 50 de 25 en 25, de 0 a 360 de 60 en 60 —, si no contado desde el mínimo (de 32 a 212 de 20 en 20). Un paso que usted da se cuenta siempre desde el mínimo; un paso que dibujaría más de 200 marcas vuelve al automático. Cada extremo lleva una marca numerada. Cuando no caben todos los números, se escribe uno de cada k para mantener un paso regular, y los dos extremos se escriben siempre. Los números toman los decimales de su paso. El paso elegido nunca es más fino que lo que escribe `is_format` (de 0 a 3 con el formato `#,##0`: 0, 1, 2, 3); un paso que usted da sigue siendo el suyo, y el formato redondea sus números. En una esfera demasiado pequeña para un círculo de números no se escribe ninguno; en un arco lleno pequeño la lectura se desplaza para conservar los dos extremos
`ii_minor_ticks`	integer	`4`	Marcas pequeñas entre dos numeradas (0 a 9)
`ib_show_ticks`	boolean	`true`	Muestra las marcas
`ib_show_labels`	boolean	`true`	Muestra los números de la escala; en una esfera demasiado pequeña para un círculo de números no se escribe ninguno — la lectura y los rangos siguen hablando
`id_target`	double	`0`	Un objetivo — una meta, un umbral —, marcado de través sobre la banda mientras `ib_show_target` sea verdadero
`ib_show_target`	boolean	`false`	Muestra la marca de `id_target`
`is_pointer`	string	`needle`	Cómo se muestra el valor (constantes `POINTER_*`): `NEEDLE`, una aguja; `BAR`, la banda rellena desde el mínimo — un indicador lleno, el número en el centro; `MARKER`, un triángulo en el borde. Desconocido = `NEEDLE`
`il_value_color`	long	`-1`	El color del valor — la aguja, el arco lleno o la marca; `-1` = el acento del tema
`il_track_color`	long	`-1`	El color de la banda; `-1` = un matiz del color de texto del tema
`ii_thickness`	integer	`0`	El grosor de la banda, en píxeles (0 a 80, nunca más de la mitad del radio); `0` = automático: una parte del radio, mantenida entre 6 y 24 px bajo una aguja o una marca, entre 8 y 36 px para un arco lleno — una esfera grande sigue siendo una esfera. Los números de la escala (11 a 16 px) y la lectura crecen con ella
`ib_reversed`	boolean	`false`	El máximo al principio del arco: la escala gira en sentido contrario a las agujas del reloj. Derecha y Arriba siguen girando en el sentido de las agujas: en una esfera invertida bajan el valor
`ii_start_angle`	integer	`-135`	Dónde empieza la escala, en grados: `0` arriba, `90` a la derecha, `-90` a la izquierda (450 se relee 90)
`ii_sweep_angle`	integer	`270`	Cuánto del círculo cubre la escala, en grados (10 a 360). Un ángulo negativo vale su valor absoluto: para que la escala gire en el otro sentido, `ib_reversed`. La esfera se ajusta al espacio que ocupa el ángulo
`ib_editable`	boolean	`false`	El usuario mueve el valor: girar la aguja alrededor del pivote, hacer clic en la esfera, flechas, Re Pág / Av Pág (diez pasos), Inicio y Fin. Un clic cerca del pivote, en la lectura o lejos de la esfera (más allá de la banda y de las marcas de al lado) no pone nada; durante un arrastre la mano puede salir de la esfera, el valor se queda en el extremo del que viene y nunca salta el hueco. Derecha y Arriba giran en sentido horario, como un mando giratorio, pase por donde pase el arco (en una esfera invertida bajan el valor). Cada gesto lanza `ue_value_changed` una vez — una tecla, como la mano, pone el valor de golpe, y un arrastre interrumpido (cuadro de mensaje, Alt+Tab) termina como al soltar; Esc durante un arrastre devuelve el valor (un valor escrito por su código entretanto se queda) sin pulsar el botón Cancelar de la ventana; la tecla Menú nombra el rango en el que está el valor
`id_step`	double	`0`	El paso de la mano y de las teclas; `0` = la precisión que la lectura muestra (los decimales de `is_format`, o los que elige la escala): en una escala de 0 a 7 la mano da 2,6, nunca un 2,61 que el usuario no ha leído; una tecla avanza una centésima de la escala, nunca menos de una cifra mostrada. Los dos extremos siguen siendo alcanzables cuando el paso no divide la escala: de 0 a 100 de 30 en 30, el valor pasa por 0, 30, 60, 90, 100
`ib_track_drag`	boolean	`false`	Con `ib_editable`, opcional: mientras el usuario arrastra el valor, `ue_value_tracking` sigue la mano — un volumen oído en directo, una vista previa redibujada. `ue_value_changed` sigue llegando una sola vez, al soltar; cuando un arrastre se interrumpe (Esc, `ib_editable` o `ib_enabled` puestos a `false` por el código), `ue_value_tracking` dice también el valor del que partió
`ib_value_tooltip`	boolean	`true`	El panel que nombra el rango bajo el puntero, con sus extremos. No es `is_tooltip`, la información sobre herramientas del componente entero. La información de un rango (su `is_tooltip`) se escribe en este panel, incluso en `false`
`ib_value_follows_range`	boolean	`false`	Opcional: el valor — la aguja, el arco lleno o la marca — toma el color del rango en el que está (el dibujado encima si dos se solapan): rojo en la zona roja. Fuera de todo rango conserva `il_value_color`, si no el acento del tema. Mientras el valor se desliza, el color sigue al valor dibujado
`ib_rounded`	boolean	`false`	Opcional: extremos redondeados en la banda, el arco lleno y los rangos. Cada uno se acorta medio grosor en cada extremo para quedarse en su parte de la escala; un rango más corto que su propio grosor se convierte en un punto. Un círculo completo mantiene su banda cerrada
`ib_pointer_tooltip`	boolean	`false`	Opcional: el panel nombra también el valor bajo el ratón — en la aguja, el arco lleno o la marca — y el objetivo, con su número en el formato de la lectura. Los rangos conservan su propio panel (`ib_value_tooltip`)
`id_origin`	double	`0`	Dónde empieza el arco lleno (`POINTER_BAR`): un valor por debajo del origen llena en el otro sentido — una desviación, una varianza, una escala de −50 a 50 que empieza en 0. Mientras no se pone — o una vez devuelto a `NULL` —, el arco empieza en el mínimo y la propiedad relee el mínimo; fuera de la escala, en el extremo más cercano. El gemelo de `id_origin` de gauge
`ib_auto_height`	boolean	`false`	El componente anuncia su altura ideal y el userobject se ajusta (`ue_auto_height`). La anchura la dicta: media esfera es la mitad de alta
`ib_enabled`	boolean	`true`	En gris sigue mostrando su valor pero deja de responder: ni clic, ni teclas, ni arrastre, y sale del orden de tabulación
`ib_animated`	boolean	`true`	El valor se desliza a su sitio, fotograma a fotograma — la aguja gira —, y llega desde el principio de la escala (su mínimo) cuando el componente se dibuja. Una propiedad cambiada durante el deslizamiento (título, unidad, color, tamaño) no lo corta. Un puesto configurado para reducir las animaciones nunca anima; la mano del usuario nunca se anima; un valor puesto bajo `of_set_redraw(false)` se desliza al reanudar
`ii_anim_duration`	integer	`450`	Duración del deslizamiento, en milisegundos (0 a 5000)
`is_anim_easing`	string	`ease-out`	La curva del deslizamiento (constantes `EASING_*`, los nombres de LiveCharts2): `back-out` se pasa y vuelve, `bounce-out` rebota, `elastic-out` restalla. Un exceso se queda en la escala. Desconocido = `ease-out`
`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 del tema)
`is_tooltip`	string	`""`	Información sobre herramientas simple al pasar por encima del componente
`is_super_tooltip_title`	string	`""`	Título de la información enriquecida (tiene prioridad sobre `is_tooltip`)
`is_super_tooltip_text`	string	`""`	Texto de la información enriquecida (se acepta marcado enriquecido)
`is_super_tooltip_image`	string	`""`	Imagen de la información enriquecida

Métodos #

Método	Función
`of_add_range ( string as_key, double ad_from, double ad_to { , long al_color } )`	Añade un rango de color de `ad_from` a `ad_to` (unos extremos escritos al revés se dibujan al derecho); la sobrecarga con color lo fija, si no el tono y luego la paleta. Devuelve `0` una vez añadido, `-5` si la clave está vacía, contiene `/` o `	`, o ya existe (añadir nunca reemplaza),` -2` si el componente no está creado. El color de paleta se da al añadir: quitar un rango no cambia el color de los demás
`of_clear_ranges ( )`	Quita todos los rangos — sus manejadores se van con ellos —, el valor y los ajustes se quedan. Devuelve `0` una vez hecho, `-2` si el componente no está creado
`of_current_range ( )`	La clave del rango en el que está el valor ahora, una cadena vacía si no está en ninguno o si la escala está vacía. Donde dos rangos se solapan, gana el último añadido — el dibujado encima. Un rango oculto no cuenta; un rango que el modo demo no dibuja sí cuenta: lo que lee este método nunca depende de la licencia. Un rango contiene su principio pero no su fin: en el límite común de dos rangos, el valor está en el que empieza ahí, sea cual sea el orden en que se añadieron; el extremo de la escala pertenece al rango que lo alcanza. Un rango fuera de la escala (no dibujado) también cuenta
`of_range ( string as_key )`	El manejador `n_pbt_angulargauge_range` de un rango, para leer o cambiar sus extremos, color, tono, nombre o visibilidad
`of_remove_range ( string as_key )`	Quita un rango; su manejador se destruye. Devuelve `0` una vez quitado, `-5` si ningún rango tiene esa clave, `-2` si el componente no está creado
`of_reset ( )`	Vacía los rangos — manejadores incluidos — y devuelve todas las propiedades a su valor de origen. Devuelve `0` una vez hecho, `-2` si el componente no está creado

Eventos #

Evento	Se lanza cuando
`ue_value_changed (double ad_value)`	Solo con `ib_editable`: el usuario ha movido el valor — una vez por arrastre (al soltar, o cuando el arrastre se interrumpe: un cuadro de mensaje abierto bajo la mano, Alt+Tab), por clic, por tecla. Un valor puesto por su código no lo lanza, ni siquiera durante un arrastre. Para seguir la mano durante el arrastre: `ib_track_drag`
`ue_value_tracking (double ad_value)`	Solo con `ib_editable` e `ib_track_drag`, mientras el usuario arrastra el valor: cada nueva posición de la mano, y luego — cuando el arrastre se interrumpe: Esc, o `ib_editable` / `ib_enabled` puestos a `false` por su código — el valor del que partió. El valor final sigue llegando una vez en `ue_value_changed`
`ue_range_clicked (string as_key)`	Se hizo clic en un rango — o se validó con Intro o Espacio en el rango del teclado (Tab, luego las flechas). No en un componente editable: allí un clic pone el valor
`ue_range_rclicked (string as_key, long al_x, long al_y)`	Clic derecho en un rango, o tecla Menú (Mayús+F10) en el rango del teclado — en un componente editable, el rango en el que está el valor: el lugar donde abrir un menú; `al_x`, `al_y`: dónde abrir el menú, en píxeles de pantalla — el puntero, o con el teclado (tecla Menú, Mayús+F10) el centro del rango; un `contextmenu` se abre allí tal cual (`uo_menu.of_show(al_x, al_y)`)
`ue_auto_height (long al_height)`	Con `ib_auto_height`: el userobject acaba de redimensionarse a su altura ideal

Propiedades de elemento #

Un rango se designa por su clave: uo_dial.of_range("warn").is_tone = u_pbt_angulargauge.TONE_WARN.

Propiedad	Tipo	Por defecto	Función
`id_from`	double	`0`	El principio del rango, en la escala
`id_to`	double	`0`	Su final. Unos extremos al revés se dibujan al derecho y se releen tal cual
`il_color`	long	`-1`	Su color; `-1` = el de su tono, si no el de la paleta. Los colores de elemento heredados (`il_accent`, `il_back_color`, `il_text_color` y sus variantes al pasar el ratón) no tienen efecto sobre un rango: deciden `il_color` e `is_tone`
`is_tone`	string	`""`	Su tono (constantes `TONE_*` del componente): `SUCCESS`, `WARN`, `DANGER`, `INFO` (el acento del tema), `NEUTRAL` — un juego por modo claro u oscuro, sin importar mayúsculas o minúsculas. `il_color` prevalece; un tono desconocido equivale a ningún tono
`is_label`	string	`""`	Su nombre, en el panel bajo el puntero y para un lector de pantalla; vacío = su clave. Se admite marcado
`ib_visible`	boolean	`true`	Oculta el rango sin quitarlo; como una casilla, no lanza ningún evento
`is_tooltip`	string	`""`	Su información sobre herramientas, escrita en el panel que nombra el rango bajo el puntero — nunca una segunda burbuja. Se admite marcado
`is_super_tooltip_title`	string	`""`	El título en negrita de su información, escrito en el panel bajo su nombre
`is_super_tooltip_text`	string	`""`	El texto de su información, en el panel. Se admite marcado
`is_super_tooltip_image`	string	`""`	Una imagen en la cabecera de su información, en el panel (ruta del bundle, ruta absoluta o `resources.dll:nombre`)

Ejemplos #

Un panel que vive #

// Timer event of the window : the needle turns to each new reading
uo_dial.id_value = ids_monitor.GetItemNumber(1, "speed")

// Which range is it in now ? An alert outside the good one
st_alert.visible = (uo_dial.of_current_range() <> "city")

Un medio indicador lleno #

// The band fills from the minimum, the number in the middle
uo_dial.is_pointer = u_pbt_angulargauge.POINTER_BAR

// From the left, over half a circle : the upper half
uo_dial.ii_start_angle = -90
uo_dial.ii_sweep_angle = 180

// A scale from 0 to 1, written as a percentage
uo_dial.id_maximum = 1
uo_dial.is_format = "0%"
uo_dial.id_value = 0.72

Una desviación en torno a cero #

// A scale centred on zero : the filled arc starts at 0, not at the minimum
uo_dial.is_pointer = u_pbt_angulargauge.POINTER_BAR
uo_dial.id_minimum = -50
uo_dial.id_maximum = 50
uo_dial.id_origin = 0

// Below the budget, the arc fills to the left of 0
uo_dial.id_value = -18

Un valor que el usuario ajusta #

// The user moves the value, by steps of 5
uo_dial.ib_editable = true
uo_dial.id_step = 5

// Event ue_value_changed of uo_dial : apply what the user chose
ii_level = Integer(ad_value)

Un volumen ajustado en directo #

// The user drags the value, and the sound follows the hand
uo_dial.ib_editable = true
uo_dial.ib_track_drag = true

// Event ue_value_tracking of uo_dial : the volume heard while the hand moves
inv_player.ii_volume = Integer(ad_value)

// Event ue_value_changed of uo_dial : the volume kept when the hand lets go
ii_saved_volume = Integer(ad_value)

Un indicador moderno #

// A filled arc with round ends, in the colour of the zone it is in
uo_dial.is_pointer = u_pbt_angulargauge.POINTER_BAR
uo_dial.ib_rounded = true
uo_dial.ib_value_follows_range = true

// The goal, and its number under the mouse
uo_dial.id_target = 85
uo_dial.ib_show_target = true
uo_dial.ib_pointer_tooltip = true
uo_dial.id_value = 74

Un menú en un rango #

// Event ue_range_rclicked of uo_dial : remember the range, then open the menu
// at the pointer of the window
is_menu_range = as_key
m_range.PopMenu(/*xlocation*/ w_main.PointerX(), /*ylocation*/ w_main.PointerY())

Una imagen de la esfera para un informe #

// The dial as it is on screen, title and readout included, to a PNG file
uo_dial.of_save_as_png(/*path*/ "C:\Reports\speed.png")

// The same, printed into a PDF file without any dialog
uo_dial.of_print_to_pdf(/*path*/ "C:\Reports\speed.pdf")

Buenas prácticas #

Tres rangos como mucho, con sus tonos: bien, cuidado, mal. Más allá, el ojo ya no lee el color bajo la aguja.
Un formato mejor que un cálculo: 0% en una escala de 0 a 1, $#,##0 para dinero — el valor sigue siendo el del código.
En un panel que se refresca a menudo, mantenga la animación: el valor se desliza desde donde está, no vuelve a empezar.
Un color que significa algo se pone mediante el tono; deje el valor al acento del tema, sigue el tema claro u oscuro.
Para un informe, la imagen de la esfera tal como está en pantalla viene de la base: of_save_as_png (o of_save_as_jpg), of_print_to_pdf, of_print — el valor final, nunca una aguja a medio camino.

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
`is_accessible_name` · `is_accessible_description`	El nombre y la descripción que dice un lector de pantalla	3.4 Propiedades y eventos opcionales

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.