gauge — u_pbt_gauge #
← Referencia de componentes · Índice de la guía
Indicador lineal: un valor leído a lo largo de una escala recta, horizontal o vertical — una barra o una marca, 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 Linear gauge : la vista previa, el código que lo produce y esta página, lado a lado.
En resumen #
| Userobject | u_pbt_gauge |
| Clase de elementos | n_pbt_gauge_range (of_range(key)) |
| Sirve para | Leer una magnitud de un vistazo — ocupación de un disco, ventas del mes frente a su objetivo, nivel de un depósito, control de volumen |
| 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 angulargauge: mismos métodos, mismos eventos y, salvo la geometría, mismas propiedades — aquí la orientación y la colocación de los rangos, allí los ángulos y los extremos redondeados |
Inicio rápido #
// Three ranges of the scale, each with the tone of what it means
uo_gauge.of_add_range(/*key*/ "ok", /*from*/ 0, /*to*/ 70)
uo_gauge.of_add_range(/*key*/ "warn", /*from*/ 70, /*to*/ 90)
uo_gauge.of_add_range(/*key*/ "full", /*from*/ 90, /*to*/ 100)
uo_gauge.of_range(/*key*/ "ok").is_tone = u_pbt_gauge.TONE_SUCCESS
uo_gauge.of_range(/*key*/ "warn").is_tone = u_pbt_gauge.TONE_WARN
uo_gauge.of_range(/*key*/ "full").is_tone = u_pbt_gauge.TONE_DANGER
// The title, the unit, and the value : the bar slides to it
uo_gauge.is_title = "Disk usage"
uo_gauge.is_unit = "%"
uo_gauge.id_value = 64La 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. Se dibujan a lo largo de la pista, bajo la barra. 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.
Propiedades #
| Propiedad | Tipo | Por defecto | Función |
|---|---|---|---|
is_title | string | "" | El título, al principio de la línea de la lectura. 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 — al final de la línea del título |
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 |
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 |
id_target | double | 0 | Un objetivo — una meta, un umbral —, marcado de través sobre la pista mientras ib_show_target sea verdadero |
ib_show_target | boolean | false | Muestra la marca de id_target |
is_pointer | string | bar | Cómo se muestra el valor (constantes POINTER_*): BAR, una barra rellena desde el mínimo; MARKER, un triángulo junto a la pista. Desconocido = BAR |
il_value_color | long | -1 | El color del valor — la barra o la marca; -1 = el acento del tema |
il_track_color | long | -1 | El color de la pista; -1 = un matiz del color de texto del tema |
ii_thickness | integer | 0 | El grosor de la pista, en píxeles (0 a 80); 0 = automático: 14 para una barra, 8 para una marca |
ib_reversed | boolean | false | El máximo al principio de la escala: a la izquierda de un indicador horizontal (a la derecha en lectura de derecha a izquierda), abajo en uno vertical. Las flechas siguen moviendo la marca en su sentido |
is_orientation | string | horizontal | La dirección de la escala (constantes ORIENTATION_*). Una escala horizontal sigue el sentido de lectura: de derecha a izquierda, su mínimo está a la derecha — la tecla Derecha sigue moviendo la marca hacia la derecha. Desconocido = HORIZONTAL |
ib_editable | boolean | false | El usuario mueve el valor: arrastrar la barra, hacer clic en la escala, flechas, Re Pág / Av Pág (diez pasos), Inicio y Fin. Las flechas siguen la pantalla: Derecha empuja hacia la derecha, Arriba hacia arriba, sea lo que sea lo que haya invertido la escala (derecha a izquierda, ib_reversed). 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_pointer_tooltip | boolean | false | Opcional: el panel nombra también el valor bajo el ratón — en la barra 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) |
ib_value_follows_range | boolean | false | Opcional: el valor — la barra 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 |
id_origin | double | 0 | Dónde empieza la barra (POINTER_BAR): un valor por debajo del origen crece 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 devuelta a NULL —, la barra empieza en el mínimo y lo sigue, y la propiedad relee el mínimo; fuera de la escala, en el extremo más cercano |
is_range_placement | string | beside | Dónde se dibujan los rangos (constantes PLACEMENT_*): beside, una banda propia a lo largo de la pista; behind, llenan la pista, más claros, y una barra más fina pasa por encima, con el objetivo atravesado — el « bullet graph » de un panel. Desconocido = beside, y se relee así. Detrás, la barra conserva un borde fino del color de la página: una barra roja sigue viéndose sobre su propia banda roja; las bandas más claras son una decoración, el rango se lee en el panel y con un lector de pantalla |
ib_auto_height | boolean | false | El componente anuncia su altura ideal y el userobject se ajusta (ue_auto_height). Un indicador horizontal dice lo que dibuja, título incluido. Un indicador vertical no anuncia nada: pasado de horizontal a vertical, el userobject conserva la última altura anunciada |
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 barra crece —, 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_gauge_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_gauge.of_range("warn").is_tone = u_pbt_gauge.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 #
// Local variables
double ld_used
// Timer event of the window : the bar slides to each new reading
ld_used = ids_monitor.GetItemNumber(1, "disk_used")
// A missing reading (NULL) is ignored by the gauge : test it, or the last one stays
if not IsNull(ld_used) then uo_gauge.id_value = ld_used
// Which range is it in now ? An alert outside the good one
st_alert.visible = (uo_gauge.of_current_range() <> "ok")Las ventas frente a su objetivo #
// Dollars, a number every 50 000, up to 250 000
uo_gauge.id_maximum = 250000
uo_gauge.id_tick_step = 50000
uo_gauge.is_format = "$#,##0"
// The goal : a mark across the bar
uo_gauge.id_target = 200000
uo_gauge.ib_show_target = true
// Point at the bar or at the goal : the panel says its number
uo_gauge.ib_pointer_tooltip = true
uo_gauge.id_value = 168400Un « bullet graph » de panel #
// Dollars in thousands, on a scale up to 300
uo_gauge.is_format = "$#,##0k"
uo_gauge.id_maximum = 300
// Three qualitative zones : poor, satisfactory, good
uo_gauge.of_add_range(/*key*/ "poor", /*from*/ 0, /*to*/ 150)
uo_gauge.of_add_range(/*key*/ "fair", /*from*/ 150, /*to*/ 225)
uo_gauge.of_add_range(/*key*/ "good", /*from*/ 225, /*to*/ 300)
uo_gauge.of_range(/*key*/ "poor").is_tone = u_pbt_gauge.TONE_DANGER
uo_gauge.of_range(/*key*/ "fair").is_tone = u_pbt_gauge.TONE_WARN
uo_gauge.of_range(/*key*/ "good").is_tone = u_pbt_gauge.TONE_SUCCESS
// The zones BEHIND a thinner bar, the plan across it
uo_gauge.is_range_placement = u_pbt_gauge.PLACEMENT_BEHIND
uo_gauge.id_target = 250
uo_gauge.ib_show_target = true
// The bar takes the colour of the zone it is in
uo_gauge.ib_value_follows_range = true
uo_gauge.id_value = 212Una desviación frente a un presupuesto #
// A scale centred on zero : the bar starts at 0, to the left below it
uo_gauge.id_minimum = -50
uo_gauge.id_maximum = 50
uo_gauge.id_origin = 0
uo_gauge.id_value = -18Un valor que el usuario ajusta #
// The user moves the value, by steps of 5
uo_gauge.ib_editable = true
uo_gauge.id_step = 5
// Event ue_value_changed of uo_gauge : 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_gauge.ib_editable = true
uo_gauge.ib_track_drag = true
// Event ue_value_tracking of uo_gauge : the volume heard while the hand moves
inv_player.ii_volume = Integer(ad_value)
// Event ue_value_changed of uo_gauge : the volume kept when the hand lets go
ii_saved_volume = Integer(ad_value)Un menú en un rango #
// Event ue_range_rclicked of uo_gauge : 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())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 barra.
- Un formato mejor que un cálculo:
0%en una escala de 0 a 1,$#,##0para 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 del indicador tal como está en pantalla viene de la base:
of_save_as_png(oof_save_as_jpg),of_print_to_pdf,of_print— el valor final, nunca una barra 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.