PBToolboxAI v5 ← Site

angulargauge — u_pbt_angulargauge #

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

Cadran : une valeur lue sur une échelle circulaire — une aiguille, un arc plein ou un repère sur le bord, 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 Angular gauge : l'aperçu, le code qui le produit et cette page, côte à côte.


En bref #

Userobjectu_pbt_angulargauge
Classe d'itemsn_pbt_angulargauge_range (of_range(key))
Sert àLire une grandeur d'un coup d'œil — vitesse, température, taux d'atteinte d'un objectif, bouton de thermostat
PrincipeVous donnez une échelle, une valeur et des plages ; les graduations, les nombres, les couleurs et l'animation sont à nous
FamilleJumeau de gauge : mêmes méthodes, mêmes événements, et les mêmes propriétés hors géométrie — ici les angles et les bouts arrondis, là l'orientation et le placement des plages

Démarrage rapide #

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

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. Sous une aiguille elles sont la bande ; sous un arc plein, un anneau à l'intérieur. 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.

Les angles se comptent en degrés, 0 en haut, dans le sens des aiguilles d'une montre : par défaut l'échelle part de -135 (en bas à gauche) et couvre 270 degrés — un compteur de vitesse. ii_start_angle = -90 et ii_sweep_angle = 180 donnent un demi-cadran, dessiné deux fois plus grand. Un cadran est un instrument de mesure : il ne se retourne pas dans une application de droite à gauche.


Propriétés #

PropriétéTypeDéfautRôle
is_titlestring""Le titre, au-dessus du cadran. Balisage accepté ; il nomme aussi le composant pour un lecteur d'écran. Sans titre, c'est le texte simple de l'info-bulle qui le nomme (is_super_tooltip_title, sinon is_tooltip), sinon le mot « Jauge » dans la langue d'affichage
id_valuedouble0La valeur. Elle glisse à sa place ; hors de l'échelle, dessinée en butée et relue telle quelle. Posée par le code, muette ; NULL est ignoré, la valeur précédente reste
id_minimumdouble0Le début de l'échelle. Une échelle dont le minimum n'est pas sous le maximum est vide : ni graduation, ni nombre, ni plage, ni repère, ni cible, et of_current_range() rend une chaîne vide. Pour renverser une échelle, ib_reversed
id_maximumdouble100La fin de l'échelle
is_formatstring""Le format d'affichage de tous les nombres — lecture, échelle, bornes d'une plage —, syntaxe d'un format de DataWindow (#,##0.00, $#,##0, 0%), séparateurs de la langue d'affichage. Vide = la lecture prend les décimales de l'échelle (deux pour 0 à 1, aucune pour 0 à 100), les nombres de l'échelle celles de leur pas (0,0, 0,2… 1,0)
is_unitstring""Écrit après la valeur dans la lecture (%, km/h)
ib_show_valuebooleantrueAffiche la lecture — la valeur et son unité — sous le pivot d'une aiguille (sous les nombres des deux bouts sur un petit cadran), au milieu d'un arc plein. Sans lecture, un cadran à aiguille est dessiné plus grand
id_tick_stepdouble0Le pas entre deux graduations numérotées. 0 = choisi par l'échelle : un beau pas (1, 2, 2,5 ou 5 fois une puissance de dix, puis 3, 4,5 ou 6) qui tombe sur les deux bouts quand il en existe un — 0 à 90 par 10, −50 à 50 par 25, 0 à 360 par 60 —, sinon compté depuis le minimum (32 à 212 par 20). Un pas que vous donnez se compte toujours depuis le minimum ; un pas qui dessinerait plus de 200 graduations retombe sur l'automatique. Chaque bout porte une graduation numérotée. Quand les nombres ne tiennent pas tous, un sur k est écrit pour garder un pas régulier, et les deux bouts sont toujours écrits. Les nombres prennent les décimales de leur pas. Le pas choisi n'est jamais plus fin que ce qu'écrit is_format (0 à 3 au format #,##0 : 0, 1, 2, 3) ; un pas que vous donnez reste le vôtre, et le format arrondit ses nombres. Sur un cadran trop petit pour un cercle de nombres, aucun n'est écrit ; sur un petit arc plein, la lecture se déplace pour garder les deux bouts
ii_minor_ticksinteger4Petites graduations entre deux numérotées (0 à 9)
ib_show_ticksbooleantrueAffiche les graduations
ib_show_labelsbooleantrueAffiche les nombres de l'échelle ; sur un cadran trop petit pour un cercle de nombres, aucun n'est écrit — la lecture et les plages parlent encore
id_targetdouble0Une cible — un objectif, un seuil —, marquée en travers de la bande tant que ib_show_target est vrai
ib_show_targetbooleanfalseMontre la marque de id_target
is_pointerstringneedleComment la valeur se montre (constantes POINTER_*) : NEEDLE, une aiguille ; BAR, la bande remplie depuis le minimum — une jauge pleine, le nombre au centre ; MARKER, un triangle sur le bord. Inconnu = NEEDLE
il_value_colorlong-1La couleur de la valeur — l'aiguille, l'arc plein ou le repère ; -1 = l'accent du thème
il_track_colorlong-1La couleur de la bande ; -1 = une teinte du texte du thème
ii_thicknessinteger0L'épaisseur de la bande, en pixels (0 à 80, jamais plus de la moitié du rayon) ; 0 = automatique : une part du rayon, bornée entre 6 et 24 px sous une aiguille ou un repère, entre 8 et 36 px pour un arc plein — un grand cadran reste un cadran. Les nombres de l'échelle (11 à 16 px) et la lecture grandissent avec lui
ib_reversedbooleanfalseLe maximum au début de l'arc : l'échelle tourne dans le sens inverse des aiguilles d'une montre. Droite et Haut tournent toujours dans le sens horaire : sur un cadran renversé, ils baissent la valeur
ii_start_angleinteger-135Où commence l'échelle, en degrés : 0 en haut, 90 à droite, -90 à gauche (450 se relit 90)
ii_sweep_angleinteger270La part du cercle que couvre l'échelle, en degrés (10 à 360). Un angle négatif vaut sa valeur absolue : pour faire tourner l'échelle dans l'autre sens, ib_reversed. Le cadran s'ajuste à la place que l'angle occupe
ib_editablebooleanfalseL'utilisateur déplace la valeur : tourner l'aiguille autour du pivot, cliquer le cadran, flèches, Page préc./suiv. (dix pas), Début et Fin. Un clic près du pivot, sur la lecture ou loin du cadran (au-delà de la bande et des marques à côté) ne pose rien ; pendant un glisser, la main peut sortir du cadran, la valeur reste au bout d'où elle vient et ne saute jamais la coupure. Droite et Haut tournent dans le sens horaire, comme un bouton rotatif, où que passe l'arc (sur un cadran renversé, ils baissent la valeur). Chaque geste lève ue_value_changed une fois — une touche, comme la main, pose la valeur d'un coup, et un glisser interrompu (boîte de message, Alt+Tab) se termine comme un relâchement ; Échap pendant un glisser rend la valeur (une valeur écrite par votre code entre-temps reste) sans presser le bouton Annuler de la fenêtre ; la touche Menu nomme la plage où est la valeur
id_stepdouble0Le pas de la main et des touches ; 0 = la précision que la lecture affiche (les décimales de is_format, ou celles que choisit l'échelle) : sur une échelle de 0 à 7 la main rend 2,6, jamais un 2,61 que l'utilisateur n'a pas lu ; une touche avance d'un centième de l'échelle, jamais moins d'un chiffre affiché. Les deux bouts restent atteignables quand le pas ne divise pas l'échelle : de 0 à 100 par 30, la valeur passe par 0, 30, 60, 90, 100
ib_track_dragbooleanfalseAvec ib_editable, sur option : pendant que l'utilisateur fait glisser la valeur, ue_value_tracking suit la main — un volume entendu en direct, un aperçu redessiné. ue_value_changed arrive toujours une seule fois, au relâchement ; quand un glisser est interrompu (Échap, ib_editable ou ib_enabled passés à false par le code), ue_value_tracking dit aussi la valeur d'où il est parti
ib_value_tooltipbooleantrueLe panneau qui nomme la plage sous le pointeur, avec ses bornes. Ce n'est pas is_tooltip, l'info-bulle du composant entier. L'info-bulle d'une plage (son is_tooltip) s'écrit dans ce panneau, même à false
ib_value_follows_rangebooleanfalseSur option : la valeur — l'aiguille, l'arc plein ou le repère — prend la couleur de la plage où elle se trouve (celle dessinée au-dessus si deux se chevauchent) : rouge dans la zone rouge. Hors de toute plage, elle garde il_value_color, sinon l'accent du thème. Pendant un glissement, la couleur suit la valeur dessinée
ib_roundedbooleanfalseSur option : des bouts arrondis sur la bande, l'arc plein et les plages. Chacun est raccourci d'une demi-épaisseur à chaque bout pour rester sur sa part de l'échelle ; une plage plus courte que sa propre épaisseur devient un point. Un cercle complet garde sa bande fermée
ib_pointer_tooltipbooleanfalseSur option : le panneau nomme aussi la valeur sous la souris — sur l'aiguille, l'arc plein ou le repère — et la cible, avec leur nombre au format de la lecture. Les plages gardent leur propre panneau (ib_value_tooltip)
id_origindouble0Où part l'arc plein (POINTER_BAR) : une valeur sous l'origine remplit dans l'autre sens — un écart, une variance, une échelle de −50 à 50 qui part de 0. Tant qu'elle n'est pas posée — ou une fois remise à NULL —, l'arc part du minimum et la propriété relit le minimum ; hors de l'échelle, du bout le plus proche. Le jumeau de id_origin de gauge
ib_auto_heightbooleanfalseLe composant annonce sa hauteur idéale et l'userobject s'y ajuste (ue_auto_height). La largeur la dicte : un demi-cadran est deux fois moins haut
ib_enabledbooleantrueGrisé, il montre toujours sa valeur mais ne répond plus : ni clic, ni clavier, ni glisser, et il sort de l'ordre de tabulation
ib_animatedbooleantrueLa valeur glisse à sa place, image par image — l'aiguille tourne —, et arrive depuis le début de l'échelle (son minimum) quand le composant se dessine. Une propriété changée pendant le glissement (titre, unité, couleur, taille) ne le coupe pas. Un poste réglé pour réduire les animations n'anime jamais ; la main de l'utilisateur n'est jamais animée ; une valeur posée sous of_set_redraw(false) glisse à la reprise
ii_anim_durationinteger450Durée du glissement, en millisecondes (0 à 5000)
is_anim_easingstringease-outLa courbe du glissement (constantes EASING_*, les noms de LiveCharts2) : back-out dépasse puis revient, bounce-out rebondit, elastic-out claque. Un dépassement reste sur l'échelle. Inconnu = ease-out
is_theme_stylestring""Style visuel du composant (constantes THEME_STYLE_*) ; vide = celui de l'application, suivi à chaque changement
is_theme_modestring""Variante claire ou sombre (constantes THEME_MODE_*) ; vide = celle de l'application, suivie à chaque changement
il_theme_accentlong-1Couleur d'accent de ce composant (-1 = accent du thème)
is_tooltipstring""Info-bulle simple affichée au survol du composant
is_super_tooltip_titlestring""Titre de l'info-bulle enrichie (prend le pas sur is_tooltip)
is_super_tooltip_textstring""Texte de l'info-bulle enrichie (balisage riche accepté)
is_super_tooltip_imagestring""Image de l'info-bulle enrichie

Méthodes #

MéthodeRôle
of_add_range ( string as_key, double ad_from, double ad_to { , long al_color } )Ajoute une plage colorée de ad_from à ad_to (des bornes à l'envers se dessinent à l'endroit) ; la surcharge avec couleur la fixe, sinon le ton puis la palette. Renvoie 0 une fois ajoutée, -5 si la clé est vide, contient / ou `, ou est déjà tenue (un ajout ne remplace jamais), -2` si le composant n'est pas créé. La couleur de palette est donnée à l'ajout : retirer une plage ne recolore pas les autres
of_clear_ranges ( )Retire toutes les plages — leurs poignées partent avec elles —, la valeur et les réglages restent. Renvoie 0 une fois fait, -2 si le composant n'est pas créé
of_current_range ( )La clé de la plage où se trouve la valeur maintenant, une chaîne vide s'il n'y en a pas ou si l'échelle est vide. Là où deux plages se chevauchent, la dernière ajoutée — dessinée au-dessus — l'emporte. Une plage masquée ne compte pas ; une plage que le mode démo ne dessine pas compte : ce que lit cette méthode ne dépend jamais de la licence. Une plage tient son début mais pas sa fin : sur la borne commune de deux plages, 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. Une plage hors de l'échelle (non dessinée) compte aussi
of_range ( string as_key )La poignée n_pbt_angulargauge_range d'une plage, pour lire ou changer ses bornes, sa couleur, son ton, son nom ou sa visibilité
of_remove_range ( string as_key )Retire une plage ; sa poignée est détruite. Renvoie 0 une fois retirée, -5 si aucune plage n'a cette clé, -2 si le composant n'est pas créé
of_reset ( )Vide les plages — poignées comprises — et remet toutes les propriétés à leur valeur d'origine. Renvoie 0 une fois fait, -2 si le composant n'est pas créé

Événements #

ÉvénementDéclenché quand
ue_value_changed (double ad_value)Avec ib_editable seulement : l'utilisateur a déplacé la valeur — une fois par glisser (au relâchement, ou quand le glisser est interrompu : une boîte de message ouverte sous la main, Alt+Tab), par clic, par touche. Une valeur posée par votre code ne le lève pas, même pendant un glisser. Pour suivre la main pendant le glisser : ib_track_drag
ue_value_tracking (double ad_value)Avec ib_editable et ib_track_drag seulement, pendant que l'utilisateur fait glisser la valeur : chaque nouvelle place de la main, puis — quand le glisser est interrompu : Échap, ou ib_editable / ib_enabled passés à false par votre code — la valeur d'où il est parti. La valeur finale arrive toujours une fois dans ue_value_changed
ue_range_clicked (string as_key)Une plage a été cliquée — ou validée par Entrée ou Espace sur la plage du clavier (Tab, puis les flèches). Pas sur un composant éditable : un clic y pose la valeur
ue_range_rclicked (string as_key, long al_x, long al_y)Clic droit sur une plage, ou touche Menu (Maj+F10) sur la plage du clavier — sur un composant éditable, la plage où est la valeur : l'endroit où ouvrir un menu ; al_x, al_y : où ouvrir le menu, en pixels d'écran — le pointeur, ou le milieu de la plage au clavier (touche Menu, Maj+F10) ; un contextmenu s'y ouvre tel quel (uo_menu.of_show(al_x, al_y))
ue_auto_height (long al_height)Avec ib_auto_height : l'userobject vient d'être redimensionné à sa hauteur idéale

Propriétés d'item #

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

PropriétéTypeDéfautRôle
id_fromdouble0Le début de la plage, sur l'échelle
id_todouble0Sa fin. Des bornes à l'envers se dessinent à l'endroit et se relisent telles quelles
il_colorlong-1Sa couleur ; -1 = celle de son ton, sinon de la palette. Les couleurs d'item héritées (il_accent, il_back_color, il_text_color et leurs variantes de survol) n'ont aucun effet sur une plage : il_color et is_tone décident
is_tonestring""Son ton (constantes TONE_* du composant) : SUCCESS, WARN, DANGER, INFO (l'accent du thème), NEUTRAL — un jeu par mode clair ou sombre, toute casse comprise. il_color l'emporte ; un ton inconnu vaut aucun ton
is_labelstring""Son nom, dans le panneau sous le pointeur et pour un lecteur d'écran ; vide = sa clé. Balisage accepté
ib_visiblebooleantrueMasque la plage sans la retirer ; comme une case à cocher, ne lève aucun événement
is_tooltipstring""Son info-bulle, écrite dans le panneau qui nomme la plage sous le pointeur — jamais une seconde bulle. Balisage accepté
is_super_tooltip_titlestring""Le titre en gras de son info-bulle, écrit dans le panneau sous son nom
is_super_tooltip_textstring""Le texte de son info-bulle, dans le panneau. Balisage accepté
is_super_tooltip_imagestring""Une image en tête de son info-bulle, dans le panneau (chemin du bundle, chemin absolu ou resources.dll:nom)

Exemples #

Un tableau de bord qui vit #

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

Une demi-jauge pleine #

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

Un écart autour de zéro #

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

Une valeur que l'utilisateur règle #

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

// 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 indicateur moderne #

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

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

Une image du cadran pour un rapport #

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

Bonnes pratiques #


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.

MembresRôleDétaillé dans
of_count · of_keys_at · of_hasParcourir ce que le composant contient3.2 Les items
of_resetRemettre le composant à zéro3.6 Remettre un composant à zéro : of_reset()
of_register_shortcut · of_clear_shortcutsRaccourcis clavier du composant3.5 Les raccourcis clavier
of_is_created · of_is_ready · of_get_last_errorS'il est né, s'il est prêt, ce qui a échoué3.7 Diagnostic
of_save_as_png · of_save_as_jpgExporter le rendu en image3.8 Exporter le rendu en image
of_set_redrawGrouper les modifications en un seul repaint3.10 Bonnes pratiques
of_preload_iconsIcônes affichées sans délaiAffichage instantané : of_icon
of_set_translationTraduire un libellé du composant5.2 Adapter un libellé : of_set_translation
of_focus_webviewDonner le focus au composant6.4 Clavier et focus
of_print · of_print_to_pdfImprimer, ou écrire un PDF6.9 Imprimer
of_set_property · of_get_property · of_component_namePiloter une propriété par son nom3.1 Le moteur de propriétés
is_accessible_name · is_accessible_descriptionLe nom et la description que dit un lecteur d'écran3.4 Propriétés et events optionnels

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