gauge — u_pbt_gauge #

← Référence des composants · Sommaire du guide

Jauge linéaire : une valeur lue le long d'une échelle droite, horizontale ou verticale — une barre ou un repère, des plages colorées qui disent si c'est bien, une cible, une lecture au format de votre choix.

▶ Le voir en vrai — Application de démonstration, tuile Linear gauge : l'aperçu, le code qui le produit et cette page, côte à côte.

En bref #

Démarrage rapide #

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

L'échelle, la valeur et les plages #

L'échelle va de id_minimum à id_maximum (0 à 100 par défaut). La valeur id_value se relit telle que vous l'avez donnée : hors de l'échelle, elle est dessinée en butée au bout le plus proche et la lecture l'écrit quand même — une jauge qui réécrirait en silence ce que l'application a mesuré mentirait deux fois. Posée par le code, elle ne lève aucun événement, comme SetItem : ue_value_changed dit ce que l'utilisateur a fait. NULL est ignoré : la valeur précédente reste — testez une mesure qui peut manquer (GetItemNumber rend NULL) avant de la poser.

Les nombres suivent is_format, le format d'affichage d'un DataWindow (#,##0.0, $#,##0, 0% écrit la PART de l'échelle — 50 sur 0..200 s'écrit 25 %, comme la barre de progression), avec les séparateurs de la langue d'affichage. Sans format, l'échelle choisit les décimales de la lecture — deux pour une échelle de 0 à 1, aucune pour 0 à 100 —, jamais la valeur, qui écrirait 43 une seconde et 42,55 la suivante ; les nombres de l'échelle prennent celles de leur pas.

Une plage colore une portion de l'échelle : sa couleur est celle que vous donnez, sinon celle de son ton (TONE_SUCCESS, TONE_WARN, TONE_DANGER, TONE_INFO = l'accent du thème, TONE_NEUTRAL — un jeu de couleurs par mode clair ou sombre), sinon celle de la palette. Les plages se superposent dans l'ordre d'ajout ; of_current_range() dit dans laquelle se trouve la valeur. Elles sont dessinées le long de la piste, sous la barre. Une plage tient son début mais pas sa fin : sur la borne que partagent deux plages (60 entre 0–60 et 60–85), la valeur est dans celle qui commence là, quel que soit l'ordre des ajouts ; le bout de l'échelle appartient à la plage qui l'atteint. La couleur de palette d'une plage est fixée à son ajout : en retirer une ne recolore pas les autres. Une plage tout entière hors de l'échelle n'est pas dessinée.

Propriétés #

Méthodes #

Événements #

Propriétés d'item #

Une plage se désigne par sa clé : uo_gauge.of_range("warn").is_tone = u_pbt_gauge.TONE_WARN.

Exemples #

Un tableau de bord qui vit #

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

Les ventes contre leur objectif #

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

Un « bullet graph » de tableau de bord #

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

Un écart à un budget #

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

Une valeur que l'utilisateur règle #

// 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 volume réglé en direct #

// 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 menu sur une plage #

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

Bonnes pratiques #

• Trois plages au plus, avec leurs tons : bien, attention, danger. Au-delà, l'œil ne lit plus la couleur sous la barre.
• Un format plutôt qu'un calcul : 0% sur une échelle de 0 à 1, $#,##0 pour de l'argent — la valeur reste celle du code.
• Sur un tableau de bord qui se rafraîchit souvent, gardez l'animation : la valeur glisse depuis où elle est, elle ne repart pas du début.
• Une couleur qui veut dire quelque chose se pose par le ton ; laissez la valeur à l'accent du thème, elle suit le thème clair ou sombre.
• Pour un rapport, l'image de la jauge telle qu'elle est à l'écran vient du socle : of_save_as_png (ou of_save_as_jpg), of_print_to_pdf, of_print — la valeur finale, jamais une barre à mi-course.

Hérité du socle commun #

Ces membres existent sur tous les composants visuels — ils ne sont pas propres à celui-ci. Ils sont détaillés une seule fois, dans les chapitres transverses ; cette table dit seulement où les lire.

Deux aides ne sont pas héritées : of_icon et of_escape_markup vivent sur n_pbt_utils. Déclarez-en une — n_pbt_utils lnv_utils, rien à créer — et appelez-les dessus.

← Référence des composants · Sommaire du guide