gauge — u_pbt_gauge #

← Referência dos componentes · Índice do guia

Indicador linear: um valor lido ao longo de uma escala reta, horizontal ou vertical — uma barra ou uma marca, intervalos coloridos que dizem se está bem, um objetivo, uma leitura no formato à sua escolha.

▶ Ver ao vivo — Aplicação de demonstração, mosaico Linear gauge : a pré-visualização, o código que o produz e esta página, lado a lado.

Em resumo #

Arranque rápido #

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

A escala, o valor e os intervalos #

A escala vai de id_minimum a id_maximum (de 0 a 100 por omissão). O valor id_value relê-se tal como o deu: fora da escala é desenhado no batente da ponta mais próxima e a leitura escreve-o na mesma — um indicador que reescrevesse em silêncio o que a aplicação mediu mentiria duas vezes. Definido pelo código não lança nenhum evento, como SetItem: ue_value_changed diz o que o utilizador fez. NULL é ignorado: o valor anterior fica — teste uma medida que pode faltar (GetItemNumber devolve NULL) antes de a definir.

Os números seguem is_format, o formato de apresentação de um DataWindow (#,##0.0, $#,##0, 0% escreve a PARTE da escala — 50 em 0..200 dá 25 %, como a barra de progresso), com os separadores da língua de apresentação. Sem formato, é a escala que escolhe as casas decimais da leitura — duas para uma escala de 0 a 1, nenhuma para 0 a 100 —, nunca o valor, que escreveria 43 num segundo e 42,55 no seguinte; os números da escala tomam as do seu passo.

Um intervalo colore uma parte da escala: a sua cor é a que dá, senão a do seu tom (TONE_SUCCESS, TONE_WARN, TONE_DANGER, TONE_INFO = o acento do tema, TONE_NEUTRAL — um conjunto de cores por modo claro ou escuro), senão a da paleta. Os intervalos sobrepõem-se pela ordem em que foram acrescentados; of_current_range() diz em qual está o valor. São desenhados ao longo da pista, sob a barra. Um intervalo contém o seu início mas não o seu fim: no limite que dois intervalos partilham (60 entre 0–60 e 60–85), o valor está no que começa aí, seja qual for a ordem em que foram acrescentados; a ponta da escala pertence ao intervalo que a atinge. A cor de paleta de um intervalo fica fixada quando é acrescentado: retirar um não muda a cor dos outros. Um intervalo inteiramente fora da escala não é desenhado.

Propriedades #

Métodos #

Eventos #

Propriedades de item #

Um intervalo designa-se pela sua chave: uo_gauge.of_range("warn").is_tone = u_pbt_gauge.TONE_WARN.

Exemplos #

Um painel que 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")

As vendas face ao objetivo #

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

Um « bullet graph » de painel #

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

Um desvio face a um orçamento #

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

Um valor que o utilizador ajusta #

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

Um volume ajustado em direto #

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

Um menu num intervalo #

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

Boas práticas #

• No máximo três intervalos, com os seus tons: bem, cuidado, mal. Para além disso, o olho já não lê a cor sob a barra.
• Um formato em vez de um cálculo: 0% numa escala de 0 a 1, $#,##0 para dinheiro — o valor continua a ser o do código.
• Num painel que se atualiza muitas vezes, mantenha a animação: o valor desliza de onde está, não recomeça.
• Uma cor que quer dizer algo define-se pelo tom; deixe o valor com o acento do tema, ele segue o tema claro ou escuro.
• Para um relatório, a imagem do indicador tal como está no ecrã vem da base: of_save_as_png (ou of_save_as_jpg), of_print_to_pdf, of_print — o valor final, nunca uma barra a meio caminho.

Herdado da base comum #

Estes membros existem em todos os componentes visuais — não são próprios deste. São detalhados uma só vez, nos capítulos transversais; esta tabela apenas diz onde os ler.

Duas ajudas não são herdadas: of_icon e of_escape_markup vivem em n_pbt_utils. Declare um — n_pbt_utils lnv_utils, nada a criar — e chame-as nele.

← Referência dos componentes · Índice do guia