chartcartesian — u_pbt_chartcartesian #

← Referência dos componentes · Índice do guia

Gráfico cartesiano: colunas, barras, linhas, áreas e nuvens de pontos, num eixo de categorias e num ou dois eixos de valores. O tipo define-se por série.

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

Em resumo #

Arranque rápido #

// Local variables
string ls_months[] = {"Jan", "Feb", "Mar", "Apr", "May", "Jun"}
double ld_sales[] = {420, 510, 480, 620, 700, 660}

// The categories FIRST : they fix how many values a series carries
uo_chart.of_set_categories(/*labels*/ ls_months)
uo_chart.of_add_series(/*key*/ "sales", /*label*/ "Revenue", /*type*/ u_pbt_chartcartesian.TYPE_BAR, /*values*/ ld_sales)

O tipo pertence à SÉRIE, não ao componente #

É a decisão de que decorre tudo o resto. Um componente por tipo — um para barras, outro para linhas — nunca pode produzir um combinado: barras encimadas por uma linha de objectivo, num segundo eixo. E é justamente a forma mais pedida num painel.

Aqui há um só componente, e cada série leva o seu is_type (TYPE_BAR, TYPE_LINE, TYPE_AREA, TYPE_SCATTER, TYPE_STEPLINE). Mudar o tipo de uma série não toca nas outras.

ib_secondary coloca uma série no segundo eixo de valores. É o que permite a um número de encomendas e a uma facturação conviverem: sem ele, uma das duas é uma linha plana rente ao eixo.

of_set_categories vem antes das séries: o seu número fixa quantos valores cada série deve levar.

// Local variables
double ld_target[] = {400, 500, 550, 600, 680, 720}

// Bars and a line in the SAME chart : the type belongs to the series
uo_chart.of_add_series(/*key*/ "target", /*label*/ "Target", /*type*/ u_pbt_chartcartesian.TYPE_LINE, /*values*/ ld_target)

// And its own scale, when the two do not share a unit
uo_chart.of_item(/*key*/ "target").ib_secondary = true

Propriedades #

Métodos #

Sem chave (modo demo), o gráfico só desenha as suas 3 primeiras séries, legenda incluída. As outras ficam no modelo — of_count, of_get_series_values e os seus handles veem-nas — e a chave definida mostra-as sem que tenha de reenviar nada.

Eventos #

A animação é uma entrada, não um cálculo: a geometria final é escrita de imediato e só a chegada é tocada. Um gráfico nunca mostrado — nascido fora do ecrã, num separador que ninguém abre — mostra portanto as barras certas, em silêncio.

Propriedades de item #

Propriedades de eixo #

Exemplos #

Ajustar a animação conforme o ecrã #

// A dashboard that refreshes every few seconds : no arrival animation
uo_chart.ib_animated = false

// Elsewhere, a slower arrival that is actually seen
uo_chart.ii_anim_duration = 1200

Abrir as linhas por trás de um ponto #

// Event ue_point_clicked of uo_chart : the series key, the position of the
// point (from 1) and its value - enough to open the rows behind it
// Local variables
string ls_month

// On a series of values, the position IS the rank of the category
ls_month = is_months[al_index]
wf_open_orders(/*series*/ as_key, /*month*/ ls_month, /*amount*/ ad_value)

Um painel vivo #

// Timer event of the window : new values for the same series, so the bars
// SLIDE to their new height instead of replaying their arrival
// Local variables
double ld_sales[]

// Read the figures, then hand them to the series already on the chart
ld_sales = wf_read_sales()
uo_chart.of_set_series_values(/*key*/ "sales", /*values*/ ld_sales)

Um gráfico em direto que desliza #

// Timer event of the window, every second : ONE new reading. Only that value
// travels ; past sixty, the oldest leaves on both the axis and the series
// Local variables
string ls_time[]
double ld_cpu[]

// The time of the reading on the axis, the reading itself in the series
ls_time[1] = String(Now(), "hh:mm:ss")
ld_cpu[1] = wf_read_cpu()
uo_chart.of_append_categories(/*labels*/ ls_time, /*max_count*/ 60)
uo_chart.of_append_values(/*key*/ "cpu", /*values*/ ld_cpu, /*max_points*/ 60)

Uma medida em falta, e o gráfico como imagem #

// March was not measured : a NULL value is a gap, the line is cut there
// Local variables
double ld_temp[] = {18.5, 19.2, 0, 21.4}

// The third reading is missing : NULL, not zero
SetNull(ld_temp[3])
uo_chart.of_add_series(/*key*/ "temp", /*label*/ "Temperature", /*type*/ u_pbt_chartcartesian.TYPE_LINE, /*values*/ ld_temp)

// The chart as it is on screen, title and legend included, to a PNG file
uo_chart.of_save_as_png(/*path*/ "C:\Reports\temperature.png")

Uma faixa e um objetivo no eixo dos valores #

// A pale red band below 200 and a target line at 600, behind the bars
uo_chart.of_add_axis_section(/*axis*/ u_pbt_chartcartesian.AXIS_VALUE, /*key*/ "low", /*from*/ 0, /*to*/ 200, /*color*/ RGB(/*red*/ 255, /*green*/ 220, /*blue*/ 220))
uo_chart.of_add_axis_threshold(/*axis*/ u_pbt_chartcartesian.AXIS_VALUE, /*key*/ "target", /*at*/ 600, /*color*/ RGB(/*red*/ 200, /*green*/ 70, /*blue*/ 70), /*thickness*/ 2)

// The value axis says what it measures
uo_chart.of_axis(/*axis*/ u_pbt_chartcartesian.AXIS_VALUE).is_title = "Sales ($K)"

Um gráfico alimentado por um DataStore #

// The month on the category axis, one series per product category, the amounts
// of the rows summed by the chart - what the graph of a DataWindow does
// Local variables
datastore lds_sales

// Your DataStore and its Retrieve, sorted : the categories come in the order of the rows
lds_sales = create datastore
lds_sales.DataObject = "d_sales"
lds_sales.SetTransObject(SQLCA)
lds_sales.Retrieve()
lds_sales.SetSort("month A")
lds_sales.Sort()

// Which column plays which role, then ONE call reads every row
uo_chart.of_map(/*role*/ u_pbt_chartcartesian.ROLE_CATEGORY, /*column*/ "month")
uo_chart.of_map(/*role*/ u_pbt_chartcartesian.ROLE_SERIES, /*column*/ "category")
uo_chart.of_map(/*role*/ u_pbt_chartcartesian.ROLE_VALUE, /*column*/ "amount")
uo_chart.of_from_datastore(/*ads*/ lds_sales)

// Later, the rows changed (an edit, a new Retrieve) : read again IN PLACE, the
// bars slide and every series keeps what you set on it
lds_sales.Retrieve()
uo_chart.of_reload()

A cor de um ponto, um menu noutro #

// May passed its limit : ONE bar of the series in red, the others keep their colour
uo_chart.of_set_point_color(/*key*/ "sales", /*position*/ 5, /*color*/ RGB(/*red*/ 200, /*green*/ 40, /*blue*/ 40))

// Event ue_point_rclicked of uo_chart : a menu about the point under the mouse
// Local variables
m_point lm_menu

// Remember which point the menu is about, then open it where the pointer is
is_menu_series = as_key
il_menu_position = al_index
lm_menu = create m_point
lm_menu.m_popup.PopMenu(w_main.PointerX(), w_main.PointerY())
destroy lm_menu

Boas práticas #

• Ponha as categorias antes das séries. O seu número diz o que uma série deve conter; ao contrário não pode funcionar.
• Um segundo eixo justifica-se, não se sofre. Duas escalas no mesmo desenho enganam o olho: só o traga quando as unidades forem mesmo diferentes.
• Corte a animação num painel que se actualiza. Uma chegada que recomeça de cinco em cinco segundos nunca termina, e cansa em vez de ajudar.
• As barras partem do zero, e o componente cumpre-o: o zero entra no eixo assim que uma barra ou uma área assenta nele. Um gráfico de barras truncado exagera cada diferença. Linhas, nuvens e cotações leem-se no seu próprio intervalo.
• O gráfico mantém o sentido matemático numa aplicação da direita para a esquerda: categorias da esquerda para a direita, eixo dos valores à esquerda. Só a legenda START/END segue o sentido de leitura.
• Empilhe para ler um total, justaponha para comparar. Não são dois estilos, são duas perguntas diferentes.
• Acrescente cada série num gráfico em direto: of_append_categories e depois of_append_values para cada uma, com o mesmo máximo — uma série esquecida desliza para debaixo da categoria ao lado.
• Um buraco não é um zero. Um valor NULL não é desenhado, nem etiquetado, nem clicável; um peso NULL deixa vazia a célula de um mapa de calor.
• ue_point_clicked dá a ordem: use-a para abrir a lista exacta por trás desse ponto, não o ecrã de pesquisa.

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