PBToolboxAI v5 ← Site

angulargauge — u_pbt_angulargauge #

← Riferimento dei componenti · Sommario della guida

Quadrante: un valore letto su una scala circolare — una lancetta, un arco pieno o un segno sul bordo, intervalli colorati che dicono se va bene, un obiettivo, una lettura nel formato di vostra scelta.

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


In breve #

Userobjectu_pbt_angulargauge
Classe di elementin_pbt_angulargauge_range (of_range(key))
Serve aLeggere una grandezza a colpo d'occhio — velocità, temperatura, grado di raggiungimento di un obiettivo, manopola di un termostato
PrincipioVoi date una scala, un valore e degli intervalli; tacche, numeri, colori e animazione sono affar nostro
FamigliaGemello di gauge: stessi metodi, stessi eventi e, geometria a parte, stesse proprietà — qui gli angoli e le estremità arrotondate, lì l'orientamento e la posizione degli intervalli

Avvio rapido #

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

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. Sotto una lancetta sono la fascia; sotto un arco pieno, un anello all'interno. 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.

Gli angoli si contano in gradi, 0 in alto, in senso orario: per impostazione predefinita la scala parte da -135 (in basso a sinistra) e copre 270 gradi — un tachimetro. ii_start_angle = -90 e ii_sweep_angle = 180 danno un mezzo quadrante, disegnato grande il doppio. Un quadrante è uno strumento di misura: non si capovolge in un'applicazione da destra a sinistra.


Proprietà #

ProprietàTipoPredefinitoRuolo
is_titlestring""Il titolo, sopra il quadrante. Markup accettato; nomina anche il componente per un lettore di schermo. Senza titolo, lo nomina il testo semplice del tooltip (is_super_tooltip_title, altrimenti is_tooltip), altrimenti la parola « Indicatore » nella lingua di visualizzazione
id_valuedouble0Il valore. Scivola al suo posto; fuori scala, disegnato a fondo corsa e riletto così com'è. Impostato dal codice, muto; NULL è ignorato, il valore precedente resta
id_minimumdouble0L'inizio della scala. Una scala il cui minimo non è sotto il massimo è vuota: né tacca, né numero, né intervallo, né segno, né obiettivo, e of_current_range() rende una stringa vuota. Per capovolgere una scala, ib_reversed
id_maximumdouble100La fine della scala
is_formatstring""Il formato di visualizzazione di tutti i numeri — lettura, scala, estremi di un intervallo —, nella sintassi di un formato DataWindow (#,##0.00, $#,##0, 0%), separatori della lingua di visualizzazione. Vuoto = la lettura prende i decimali della scala (due per 0 a 1, nessuno per 0 a 100), i numeri della scala quelli del loro passo (0,0, 0,2… 1,0)
is_unitstring""Scritto dopo il valore nella lettura (%, km/h)
ib_show_valuebooleantrueMostra la lettura — il valore e la sua unità — sotto il perno di una lancetta (sotto i numeri dei due estremi su un piccolo quadrante), al centro di un arco pieno. Senza lettura, un quadrante a lancetta è disegnato più grande
id_tick_stepdouble0Il passo tra due tacche numerate. 0 = scelto dalla scala: un passo tondo (1, 2, 2,5 o 5 volte una potenza di dieci, poi 3, 4,5 o 6) che cade su entrambi gli estremi quando esiste — da 0 a 90 di 10, da −50 a 50 di 25, da 0 a 360 di 60 —, altrimenti contato dal minimo (da 32 a 212 di 20). Un passo che date voi si conta sempre dal minimo; un passo che disegnerebbe più di 200 tacche ricade su quello automatico. Ogni estremo porta una tacca numerata. Quando i numeri non ci stanno tutti, ne viene scritto uno su k per mantenere un passo regolare, e i due estremi sono sempre scritti. I numeri prendono i decimali del loro passo. Il passo scelto non è mai più fine di ciò che scrive is_format (da 0 a 3 al formato #,##0: 0, 1, 2, 3); un passo che date resta il vostro, e il formato arrotonda i suoi numeri. Su un quadrante troppo piccolo per un cerchio di numeri non ne viene scritto nessuno; su un piccolo arco pieno la lettura si sposta per tenere i due estremi
ii_minor_ticksinteger4Piccole tacche tra due numerate (da 0 a 9)
ib_show_ticksbooleantrueMostra le tacche
ib_show_labelsbooleantrueMostra i numeri della scala; su un quadrante troppo piccolo per un cerchio di numeri non ne viene scritto nessuno — la lettura e gli intervalli parlano ancora
id_targetdouble0Un obiettivo — una meta, una soglia —, segnato di traverso su la fascia finché ib_show_target è vero
ib_show_targetbooleanfalseMostra il segno di id_target
is_pointerstringneedleCome si mostra il valore (costanti POINTER_*): NEEDLE, una lancetta; BAR, la fascia riempita dal minimo — un indicatore pieno, il numero al centro; MARKER, un triangolo sul bordo. Sconosciuto = NEEDLE
il_value_colorlong-1Il colore del valore — la lancetta, l'arco pieno o il segno; -1 = l'accento del tema
il_track_colorlong-1Il colore di la fascia; -1 = una tinta del testo del tema
ii_thicknessinteger0Lo spessore della fascia, in pixel (da 0 a 80, mai più di metà del raggio); 0 = automatico: una parte del raggio, tenuta tra 6 e 24 px sotto una lancetta o un segno, tra 8 e 36 px per un arco pieno — un grande quadrante resta un quadrante. I numeri della scala (da 11 a 16 px) e la lettura crescono con esso
ib_reversedbooleanfalseIl massimo all'inizio dell'arco: la scala gira in senso antiorario. Destra e Su girano sempre in senso orario: su un quadrante capovolto abbassano il valore
ii_start_angleinteger-135Dove inizia la scala, in gradi: 0 in alto, 90 a destra, -90 a sinistra (450 si rilegge 90)
ii_sweep_angleinteger270Quanta parte del cerchio copre la scala, in gradi (da 10 a 360). Un angolo negativo vale il suo valore assoluto: per far girare la scala nell'altro verso, ib_reversed. Il quadrante si adatta allo spazio che l'angolo occupa
ib_editablebooleanfalseL'utente sposta il valore: girare l'ago attorno al perno, cliccare il quadrante, frecce, Pag su/giù (dieci passi), Inizio e Fine. Un clic vicino al perno, sulla lettura o lontano dal quadrante (oltre la banda e i segni accanto) non pone nulla; durante un trascinamento la mano può uscire dal quadrante, il valore resta all'estremo da cui viene e non salta mai l'apertura. Destra e Su girano in senso orario, come una manopola, ovunque passi l'arco (su un quadrante capovolto abbassano il valore). Ogni gesto solleva ue_value_changed una volta — un tasto, come la mano, pone il valore di colpo, e un trascinamento interrotto (finestra di messaggio, Alt+Tab) finisce come un rilascio; Esc durante un trascinamento ripristina il valore (un valore scritto dal vostro codice nel frattempo resta) senza premere il pulsante Annulla della finestra; il tasto Menu nomina l'intervallo in cui si trova il valore
id_stepdouble0Il passo della mano e dei tasti; 0 = la precisione che la lettura mostra (i decimali di is_format, o quelli scelti dalla scala): su una scala da 0 a 7 la mano rende 2,6, mai un 2,61 che l'utente non ha letto; un tasto avanza di un centesimo della scala, mai meno di una cifra mostrata. I due estremi restano raggiungibili quando il passo non divide la scala: da 0 a 100 di 30, il valore passa per 0, 30, 60, 90, 100
ib_track_dragbooleanfalseCon ib_editable, su opzione: mentre l'utente trascina il valore, ue_value_tracking segue la mano — un volume sentito dal vivo, un'anteprima ridisegnata. ue_value_changed arriva sempre una sola volta, al rilascio; quando un trascinamento è interrotto (Esc, ib_editable o ib_enabled portati a false dal codice), ue_value_tracking dice anche il valore da cui è partito
ib_value_tooltipbooleantrueIl pannello che nomina l'intervallo sotto il puntatore, con i suoi estremi. Non è is_tooltip, il tooltip del componente intero. Il tooltip di un intervallo (il suo is_tooltip) è scritto in questo pannello, anche a false
ib_value_follows_rangebooleanfalseSu opzione: il valore — l'ago, l'arco pieno o il segno — prende il colore dell'intervallo in cui si trova (quello disegnato sopra se due si sovrappongono): rosso nella zona rossa. Fuori da ogni intervallo tiene il_value_color, altrimenti l'accento del tema. Mentre il valore scivola, il colore segue il valore disegnato
ib_roundedbooleanfalseSu opzione: estremi arrotondati sulla banda, sull'arco pieno e sugli intervalli. Ognuno è accorciato di mezzo spessore a ogni estremo per restare sulla sua parte della scala; un intervallo più corto del proprio spessore diventa un punto. Un cerchio completo tiene la banda chiusa
ib_pointer_tooltipbooleanfalseSu opzione: il pannello nomina anche il valore sotto il mouse — sull'ago, sull'arco pieno o sul segno — e l'obiettivo, con il loro numero nel formato della lettura. Gli intervalli tengono il loro pannello (ib_value_tooltip)
id_origindouble0Dove parte l'arco pieno (POINTER_BAR): un valore sotto l'origine riempie nell'altro verso — uno scarto, una varianza, una scala da −50 a 50 che parte da 0. Finché non è impostata — o una volta riportata a NULL —, l'arco parte dal minimo e la proprietà rilegge il minimo; fuori scala, dall'estremo più vicino. Il gemello di id_origin di gauge
ib_auto_heightbooleanfalseIl componente annuncia la sua altezza ideale e l'userobject vi si adatta (ue_auto_height). La larghezza la detta: un mezzo quadrante è alto la metà
ib_enabledbooleantrueIn grigio mostra sempre il suo valore ma non risponde più: né clic, né tasti, né trascinamento, ed esce dall'ordine di tabulazione
ib_animatedbooleantrueIl valore scivola al suo posto, fotogramma per fotogramma — la lancetta gira —, e arriva dall'inizio della scala (il suo minimo) quando il componente si disegna. Una proprietà cambiata durante lo scivolamento (titolo, unità, colore, dimensione) non lo interrompe. Una postazione impostata per ridurre le animazioni non anima mai; la mano dell'utente non è mai animata; un valore impostato sotto of_set_redraw(false) scivola alla ripresa
ii_anim_durationinteger450Durata dello scivolamento, in millisecondi (da 0 a 5000)
is_anim_easingstringease-outLa curva dello scivolamento (costanti EASING_*, i nomi di LiveCharts2): back-out supera e torna, bounce-out rimbalza, elastic-out scatta. Un superamento resta sulla scala. Sconosciuto = ease-out
is_theme_stylestring""Stile visivo del componente (costanti THEME_STYLE_*); vuoto = quello dell'applicazione, seguito a ogni cambio
is_theme_modestring""Variante chiara o scura (costanti THEME_MODE_*); vuoto = quella dell'applicazione, seguita a ogni cambio
il_theme_accentlong-1Colore di accento di questo componente (-1 = accento del tema)
is_tooltipstring""Descrizione comando semplice mostrata al passaggio sul componente
is_super_tooltip_titlestring""Titolo della descrizione arricchita (prevale su is_tooltip)
is_super_tooltip_textstring""Testo della descrizione arricchita (markup ricco accettato)
is_super_tooltip_imagestring""Immagine della descrizione arricchita

Metodi #

MetodoRuolo
of_add_range ( string as_key, double ad_from, double ad_to { , long al_color } )Aggiunge un intervallo colorato da ad_from a ad_to (estremi scritti al contrario sono disegnati nel verso giusto); l'overload con colore lo fissa, altrimenti il tono poi la tavolozza. Restituisce 0 una volta aggiunto, -5 se la chiave è vuota, contiene / o `, o è già presente (un'aggiunta non sostituisce mai), -2` se il componente non è creato. Il colore di tavolozza è dato all'aggiunta: rimuovere un intervallo non ricolora gli altri
of_clear_ranges ( )Rimuove tutti gli intervalli — i loro handle se ne vanno con loro —, il valore e le impostazioni restano. Restituisce 0 una volta fatto, -2 se il componente non è creato
of_current_range ( )La chiave dell'intervallo in cui si trova il valore adesso, una stringa vuota se non è in nessuno o se la scala è vuota. Dove due intervalli si sovrappongono, vince l'ultimo aggiunto — quello disegnato sopra. Un intervallo nascosto non conta; un intervallo che la modalità demo non disegna conta: ciò che legge questo metodo non dipende mai dalla licenza. Un intervallo contiene il suo inizio ma non la sua fine: sul limite comune di due intervalli il valore è in quello che comincia lì, qualunque sia l'ordine delle aggiunte; l'estremo della scala appartiene all'intervallo che lo raggiunge. Conta anche un intervallo fuori scala (non disegnato)
of_range ( string as_key )L'handle n_pbt_angulargauge_range di un intervallo, per leggere o cambiare estremi, colore, tono, nome o visibilità
of_remove_range ( string as_key )Rimuove un intervallo; il suo handle è distrutto. Restituisce 0 una volta rimosso, -5 se nessun intervallo ha questa chiave, -2 se il componente non è creato
of_reset ( )Svuota gli intervalli — handle compresi — e riporta tutte le proprietà al valore d'origine. Restituisce 0 una volta fatto, -2 se il componente non è creato

Eventi #

EventoSollevato quando
ue_value_changed (double ad_value)Solo con ib_editable: l'utente ha spostato il valore — una volta per trascinamento (al rilascio, o quando il trascinamento viene interrotto: una finestra di messaggio aperta sotto la mano, Alt+Tab), per clic, per tasto. Un valore impostato dal vostro codice non lo solleva, nemmeno durante un trascinamento. Per seguire la mano durante il trascinamento: ib_track_drag
ue_value_tracking (double ad_value)Solo con ib_editable e ib_track_drag, mentre l'utente trascina il valore: ogni nuova posizione della mano, poi — quando il trascinamento è interrotto: Esc, oppure ib_editable / ib_enabled portati a false dal vostro codice — il valore da cui è partito. Il valore finale arriva sempre una volta in ue_value_changed
ue_range_clicked (string as_key)Un intervallo è stato cliccato — o confermato con Invio o Spazio sull'intervallo della tastiera (Tab, poi le frecce). Non su un componente modificabile: lì un clic imposta il valore
ue_range_rclicked (string as_key, long al_x, long al_y)Clic destro su un intervallo, o tasto Menu (Maiusc+F10) sull'intervallo della tastiera — su un componente modificabile, l'intervallo in cui si trova il valore: il posto dove aprire un menu; al_x, al_y: dove aprire il menu, in pixel dello schermo — il puntatore, o da tastiera (tasto Menu, Maiusc+F10) il centro dell'intervallo; un contextmenu vi si apre così com'è (uo_menu.of_show(al_x, al_y))
ue_auto_height (long al_height)Con ib_auto_height: l'userobject è appena stato ridimensionato alla sua altezza ideale

Proprietà degli elementi #

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

ProprietàTipoPredefinitoRuolo
id_fromdouble0L'inizio dell'intervallo, sulla scala
id_todouble0La sua fine. Estremi al contrario si disegnano nel verso giusto e si rileggono così come sono
il_colorlong-1Il suo colore; -1 = quello del suo tono, altrimenti della tavolozza. I colori di elemento ereditati (il_accent, il_back_color, il_text_color e le loro varianti al passaggio) non hanno alcun effetto su un intervallo: decidono il_color e is_tone
is_tonestring""Il suo tono (costanti TONE_* del componente): SUCCESS, WARN, DANGER, INFO (l'accento del tema), NEUTRAL — un gruppo per modo chiaro o scuro, maiuscole o minuscole indifferenti. il_color prevale; un tono sconosciuto vale nessun tono
is_labelstring""Il suo nome, nel pannello sotto il puntatore e per un lettore di schermo; vuoto = la sua chiave. Markup accettato
ib_visiblebooleantrueNasconde l'intervallo senza rimuoverlo; come una casella di spunta, non solleva eventi
is_tooltipstring""Il suo tooltip, scritto nel pannello che nomina l'intervallo sotto il puntatore — mai una seconda bolla. Markup accettato
is_super_tooltip_titlestring""Il titolo in grassetto del suo tooltip, scritto nel pannello sotto il suo nome
is_super_tooltip_textstring""Il testo del suo tooltip, nel pannello. Markup accettato
is_super_tooltip_imagestring""Un'immagine in cima al suo tooltip, nel pannello (percorso del bundle, percorso assoluto o resources.dll:nome)

Esempi #

Un cruscotto che vive #

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

Un mezzo indicatore pieno #

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

Uno scarto attorno a zero #

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

Un valore che l'utente regola #

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

// 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 indicatore moderno #

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

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

Un'immagine del quadrante per un rapporto #

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

Buone pratiche #


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.

MembriRuoloDescritto in
of_count · of_keys_at · of_hasPercorrere ciò che il componente contiene3.2 Gli item
of_resetRiportare il componente a zero3.6 Riportare un componente a zero: of_reset()
of_register_shortcut · of_clear_shortcutsScorciatoie da tastiera del componente3.5 Le scorciatoie da tastiera
of_is_created · of_is_ready · of_get_last_errorSe è nato, se è pronto, cosa è fallito3.7 Diagnostica
of_save_as_png · of_save_as_jpgEsportare il rendering in immagine3.8 Esportare il rendering come immagine
of_set_redrawRaggruppare le modifiche in un solo ridisegno3.10 Buone pratiche
of_preload_iconsIcone mostrate senza ritardoVisualizzazione istantanea: of_icon
of_set_translationTradurre una dicitura del componente5.2 Adattare un'etichetta: of_set_translation
of_focus_webviewDare il focus al componente6.4 Tastiera e focus
of_print · of_print_to_pdfStampare, o scrivere un PDF6.9 Stampare
of_set_property · of_get_property · of_component_namePilotare una proprietà per nome3.1 Il motore delle proprietà
is_accessible_name · is_accessible_descriptionIl nome e la descrizione che dice un lettore di schermo3.4 Proprietà ed event opzionali

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