gauge — u_pbt_gauge #

← Riferimento dei componenti · Sommario della guida

Indicatore lineare: un valore letto lungo una scala dritta, orizzontale o verticale — una barra o un segno, intervalli colorati che dicono se va bene, un obiettivo, una lettura nel formato di vostra scelta.

▶ Vederlo dal vivo — Applicazione dimostrativa, riquadro Linear gauge : l'anteprima, il codice che lo produce e questa pagina, affiancati.

In breve #

Avvio rapido #

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

La scala, il valore e gli intervalli #

La scala va da id_minimum a id_maximum (da 0 a 100 per impostazione predefinita). Il valore id_value si rilegge come l'avete dato: fuori scala è disegnato a fondo corsa all'estremo più vicino e la lettura lo scrive comunque — un indicatore che riscrivesse in silenzio ciò che l'applicazione ha misurato mentirebbe due volte. Impostato dal codice, non solleva alcun evento, come SetItem: ue_value_changed dice ciò che ha fatto l'utente. NULL è ignorato: il valore precedente resta — verificate una misura che può mancare (GetItemNumber restituisce NULL) prima di impostarla.

I numeri seguono is_format, il formato di visualizzazione di un DataWindow (#,##0.0, $#,##0, 0% scrive la PARTE della scala — 50 su 0..200 dà 25%, come la barra di avanzamento), con i separatori della lingua di visualizzazione. Senza formato, è la scala a scegliere i decimali della lettura — due per una scala da 0 a 1, nessuno per 0 a 100 —, mai il valore, che scriverebbe 43 un secondo e 42,55 quello dopo; i numeri della scala prendono quelli del loro passo.

Un intervallo colora una porzione della scala: il suo colore è quello che date, altrimenti quello del suo tono (TONE_SUCCESS, TONE_WARN, TONE_DANGER, TONE_INFO = l'accento del tema, TONE_NEUTRAL — un gruppo di colori per modo chiaro o scuro), altrimenti quello della tavolozza. Gli intervalli si sovrappongono nell'ordine di aggiunta; of_current_range() dice in quale si trova il valore. Sono disegnati lungo la traccia, sotto la barra. Un intervallo contiene il suo inizio ma non la sua fine: sul limite che due intervalli condividono (60 tra 0–60 e 60–85), il valore è in quello che comincia lì, qualunque sia l'ordine delle aggiunte; l'estremo della scala appartiene all'intervallo che lo raggiunge. Il colore di tavolozza di un intervallo è fissato alla sua aggiunta: rimuoverne uno non ricolora gli altri. Un intervallo interamente fuori scala non è disegnato.

Proprietà #

Metodi #

Eventi #

Proprietà degli elementi #

Un intervallo si designa con la sua chiave: uo_gauge.of_range("warn").is_tone = u_pbt_gauge.TONE_WARN.

Esempi #

Un cruscotto che 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")

Le vendite contro il loro obiettivo #

// 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 » da cruscotto #

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

Uno scarto rispetto a 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

Un valore che l'utente regola #

// 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 regolato dal vivo #

// 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 su un intervallo #

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

Buone pratiche #

• Tre intervalli al massimo, con i loro toni: bene, attenzione, male. Oltre, l'occhio non legge più il colore sotto la barra.
• Un formato piuttosto che un calcolo: 0% su una scala da 0 a 1, $#,##0 per il denaro — il valore resta quello del codice.
• Su un cruscotto che si aggiorna spesso, tenete l'animazione: il valore scivola da dov'è, non riparte dall'inizio.
• Un colore che significa qualcosa si imposta con il tono; lasciate il valore all'accento del tema, segue il tema chiaro o scuro.
• Per un rapporto, l'immagine dell'indicatore così com'è sullo schermo viene dalla base: of_save_as_png (o of_save_as_jpg), of_print_to_pdf, of_print — il valore finale, mai una barra a metà corsa.

Ereditato dalla base comune #

Questi membri esistono su tutti i componenti visivi — non sono propri di questo. Sono descritti una sola volta, nei capitoli trasversali; questa tabella dice solo dove leggerli.

Due aiuti non sono ereditati: of_icon e of_escape_markup vivono su n_pbt_utils. Ne dichiari uno — n_pbt_utils lnv_utils, niente da creare — e li chiami su di esso.

← Riferimento dei componenti · Sommario della guida