chartcartesian — u_pbt_chartcartesian #

← Riferimento dei componenti · Sommario della guida

Grafico cartesiano: colonne, barre, linee, aree e nuvole di punti, su un asse di categorie e uno o due assi di valori. Il tipo si imposta per serie.

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

In breve #

Avvio rapido #

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

Il tipo appartiene alla SERIE, non al componente #

È la decisione da cui discende tutto il resto. Un componente per tipo — uno per le barre, uno per le linee — non può mai produrre un combinato: barre sormontate da una linea di obiettivo, su un secondo asse. Ed è proprio la forma più richiesta di un cruscotto.

Qui c'è un solo componente, e ogni serie porta il suo is_type (TYPE_BAR, TYPE_LINE, TYPE_AREA, TYPE_SCATTER, TYPE_STEPLINE). Cambiare il tipo di una serie non tocca le altre.

ib_secondary mette una serie sul secondo asse dei valori. È ciò che permette a un numero di ordini e a un fatturato di convivere: senza, una delle due è una linea piatta a filo dell'asse.

of_set_categories viene prima delle serie: il loro numero fissa quanti valori ogni serie deve portare.

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

Proprietà #

Metodi #

Senza chiave (modalità demo), il grafico disegna solo le sue prime 3 serie, legenda compresa. Le altre restano nel modello — of_count, of_get_series_values e i loro handle le vedono — e la chiave impostata le mostra senza che Lei debba rinviare nulla.

Eventi #

L'animazione è un ingresso, non un calcolo: la geometria finale è scritta subito, e si riproduce solo l'arrivo. Un grafico mai mostrato — nato fuori schermo, in una scheda che nessuno apre — mostra dunque le barre giuste, in silenzio.

Proprietà di elemento #

Proprietà d'asse #

Esempi #

Regolare l'animazione secondo lo schermo #

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

Aprire le righe dietro un punto #

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

Un cruscotto che vive #

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

Un grafico in diretta che scorre #

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

Una misura mancante, e il grafico come immagine #

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

Una fascia e un obiettivo sull'asse dei valori #

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

Un grafico alimentato da un 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()

Il colore di un punto, un menu su un altro #

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

Buone pratiche #

• Ponete le categorie prima delle serie. Il loro numero dice cosa una serie deve contenere; il contrario non può funzionare.
• Un secondo asse si giustifica, non si subisce. Due scale su uno stesso disegno ingannano l'occhio: tiratelo fuori solo quando le unità sono davvero diverse.
• Spegnete l'animazione su un cruscotto che si aggiorna. Un arrivo che ricomincia ogni cinque secondi non finisce mai, e stanca invece di aiutare.
• Le barre partono da zero, e il componente vi si attiene: lo zero entra nell'asse appena una barra o un'area vi poggia. Un grafico a barre troncato esagera ogni scarto. Linee, nuvole e quotazioni si leggono sul loro intervallo.
• Il grafico conserva il senso matematico in un'applicazione da destra a sinistra: categorie da sinistra a destra, asse dei valori a sinistra. Solo la legenda START/END segue il senso di lettura.
• Impilate per leggere un totale, affiancate per confrontare. Non sono due stili, sono due domande diverse.
• Aggiunga ogni serie in un grafico in diretta: of_append_categories, poi of_append_values per ciascuna, con lo stesso massimo — una serie dimenticata scivola sotto la categoria accanto.
• Un buco non è uno zero. Un valore NULL non è né disegnato, né etichettato, né cliccabile; un peso NULL lascia vuota la cella di una mappa di calore.
• ue_point_clicked dà il rango: servitevene per aprire l'elenco esatto dietro quel punto, non la maschera di ricerca.

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