gauge — u_pbt_gauge #

← Komponentenreferenz · Inhalt des Handbuchs

Lineare Anzeige: ein Wert entlang einer geraden Skala, waagerecht oder senkrecht — ein Balken oder eine Marke, farbige Bereiche, die sagen, ob es gut ist, ein Zielwert, eine Anzeige im Format Ihrer Wahl.

▶ Live ansehen — Demoanwendung, Kachel Linear gauge : die Vorschau, der erzeugende Code und diese Seite nebeneinander.

Kurz gefasst #

Schnellstart #

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

Skala, Wert und Bereiche #

Die Skala reicht von id_minimum bis id_maximum (standardmäßig 0 bis 100). Der Wert id_value wird so zurückgelesen, wie Sie ihn angegeben haben: Außerhalb der Skala wird er am nächsten Ende als Anschlag gezeichnet, und die Anzeige schreibt ihn trotzdem — eine Anzeige, die stillschweigend umschriebe, was die Anwendung gemessen hat, würde zweimal lügen. Vom Code gesetzt, löst er kein Ereignis aus, wie SetItem: ue_value_changed sagt, was der Benutzer getan hat. NULL wird ignoriert: der vorige Wert bleibt — prüfen Sie einen Messwert, der fehlen kann (GetItemNumber liefert NULL), bevor Sie ihn setzen.

Die Zahlen folgen is_format, dem Anzeigeformat eines DataWindow (#,##0.0, $#,##0, 0% schreibt den ANTEIL der Skala — 50 auf 0..200 ergibt 25 %, wie der Fortschrittsbalken), mit den Trennzeichen der Anzeigesprache. Ohne Format wählt die Skala die Nachkommastellen der Anzeige — zwei für eine Skala von 0 bis 1, keine für 0 bis 100 —, nie der Wert, der in einer Sekunde 43 und in der nächsten 42,55 schriebe; die Zahlen der Skala haben die ihres Abstands.

Ein Bereich färbt einen Teil der Skala: seine Farbe ist die, die Sie angeben, sonst die seines Tons (TONE_SUCCESS, TONE_WARN, TONE_DANGER, TONE_INFO = der Akzent des Themas, TONE_NEUTRAL — ein Farbsatz je hellem oder dunklem Modus), sonst die der Palette. Bereiche überlagern sich in der Reihenfolge des Hinzufügens; of_current_range() sagt, in welchem der Wert liegt. Sie werden entlang der Spur gezeichnet, unter dem Balken. Ein Bereich enthält seinen Anfang, aber nicht sein Ende: auf der Grenze, die zwei Bereiche teilen (60 zwischen 0–60 und 60–85), liegt der Wert in dem, der dort beginnt, unabhängig von der Reihenfolge des Hinzufügens; das Ende der Skala gehört dem Bereich, der es erreicht. Die Palettenfarbe eines Bereichs wird beim Hinzufügen festgelegt: das Entfernen eines Bereichs färbt keinen anderen um. Ein Bereich ganz außerhalb der Skala wird nicht gezeichnet.

Eigenschaften #

Methoden #

Ereignisse #

Elementeigenschaften #

Ein Bereich wird über seinen Schlüssel angesprochen: uo_gauge.of_range("warn").is_tone = u_pbt_gauge.TONE_WARN.

Beispiele #

Ein lebendiges Dashboard #

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

Umsatz gegen sein Ziel #

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

Ein Bullet Graph für das Dashboard #

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

Eine Abweichung vom 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

Ein Wert, den der Benutzer einstellt #

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

Eine live eingestellte Lautstärke #

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

Ein Menü auf einem Bereich #

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

Bewährte Praxis #

• Höchstens drei Bereiche, mit ihren Tönen: gut, Vorsicht, schlecht. Darüber hinaus liest das Auge die Farbe unter dem Balken nicht mehr.
• Ein Format statt einer Rechnung: 0% auf einer Skala von 0 bis 1, $#,##0 für Geld — der Wert bleibt der des Codes.
• Bei einem oft aktualisierten Dashboard behalten Sie die Animation: der Wert gleitet von seiner Position aus, er beginnt nicht von vorn.
• Eine Farbe mit Bedeutung setzen Sie über den Ton; überlassen Sie den Wert dem Akzent des Themas, er folgt dem hellen oder dunklen Thema.
• Für einen Bericht kommt das Bild der Anzeige, wie sie auf dem Bildschirm steht, vom Sockel: of_save_as_png (oder of_save_as_jpg), of_print_to_pdf, of_print — der Endwert, nie ein Balken auf halbem Weg.

Vom gemeinsamen Sockel geerbt #

Diese Mitglieder gibt es bei jeder visuellen Komponente — sie sind nicht dieser eigen. Sie werden einmal in den übergreifenden Kapiteln beschrieben; diese Tabelle sagt nur, wo man sie liest.

Zwei Helfer werden nicht geerbt: of_icon und of_escape_markup liegen auf n_pbt_utils. Deklarieren Sie eines — n_pbt_utils lnv_utils, nichts zu erzeugen — und rufen Sie sie darauf auf.

← Komponentenreferenz · Inhalt des Handbuchs