chartcartesian — u_pbt_chartcartesian #

← Référence des composants · Sommaire du guide

Graphique cartésien : colonnes, barres, lignes, aires et nuages de points, sur un axe de catégories et un ou deux axes de valeurs. Le type se règle par série.

▶ Le voir en vrai — Application de démonstration, tuile Cartesian chart : l'aperçu, le code qui le produit et cette page, côte à côte.

En bref #

Démarrage rapide #

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

Le type appartient à la SÉRIE, pas au composant #

C'est la décision qui structure tout le reste. Un composant par type — un pour les barres, un pour les lignes — ne peut jamais produire un combiné : des barres surmontées d'une ligne d'objectif, avec un second axe. C'est pourtant la forme la plus demandée d'un tableau de bord.

Ici il y a un seul composant, et chaque série porte son is_type (TYPE_BAR, TYPE_LINE, TYPE_AREA, TYPE_SCATTER, TYPE_STEPLINE). Changer le type d'une série ne touche pas les autres.

ib_secondary place une série sur le second axe de valeurs. C'est ce qui permet à un nombre de commandes et à un chiffre d'affaires de cohabiter : sans lui, l'un des deux est une ligne plate au ras de l'axe.

of_set_categories vient avant les séries : leur nombre fixe combien de valeurs chaque série doit porter.

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

Propriétés #

Méthodes #

Sans clé (mode démo), le graphique ne dessine que ses 3 premières séries, légende comprise. Les autres restent dans le modèle — of_count, of_get_series_values et leurs poignées les voient — et la clé posée les montre sans que vous ayez rien à renvoyer.

Événements #

L'animation est une entrée, pas un calcul : la géométrie finale est posée tout de suite, et seule l'arrivée est jouée. Un graphique jamais affiché — né hors écran, dans un onglet que personne n'ouvre — montre donc les bonnes barres, en silence.

Propriétés d'item #

Propriétés d'axe #

Exemples #

Régler l'animation selon l'écran #

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

Ouvrir les lignes derrière un point #

// 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 tableau de bord qui vit #

// 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 graphique en direct qui glisse #

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

Une mesure manquante, et le graphique en image #

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

Une bande et un objectif sur l'axe des valeurs #

// 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 graphique nourri par 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()

La couleur d'un point, un menu sur un autre #

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

Bonnes pratiques #

• Posez les catégories avant les séries. Leur nombre dit ce qu'une série doit contenir ; l'inverse ne peut pas marcher.
• Un second axe se justifie, il ne se subit pas. Deux échelles sur un même dessin trompent l'œil : ne le sortez que quand les unités sont vraiment différentes.
• Coupez l'animation sur un tableau de bord qui se rafraîchit. Une arrivée qui recommence toutes les cinq secondes ne se termine jamais, et fatigue au lieu d'aider.
• Les barres partent de zéro, et le composant s'y tient : zéro entre dans l'axe dès qu'une barre ou une aire s'y tient. Un graphique en barres tronqué exagère chaque écart. Des lignes, des nuages et des cours se lisent, eux, sur leur propre étendue.
• Le graphique garde le sens mathématique dans une application de droite à gauche : catégories de gauche à droite, axe des valeurs à gauche. Seule la légende START/END suit le sens de lecture.
• Empilez pour lire un total, juxtaposez pour comparer. Ce ne sont pas deux styles, ce sont deux questions différentes.
• Poussez chaque série dans un graphique en direct : of_append_categories puis of_append_values pour chacune, avec le même maximum — une série oubliée glisse sous la catégorie d'à côté.
• Un trou n'est pas un zéro. Une valeur NULL n'est ni dessinée, ni étiquetée, ni cliquable ; un poids NULL de carte de chaleur laisse la case vide.
• ue_point_clicked donne le rang : servez-vous en pour ouvrir la liste exacte derrière ce point, pas l'écran de recherche.

Hérité du socle commun #

Ces membres existent sur tous les composants visuels — ils ne sont pas propres à celui-ci. Ils sont détaillés une seule fois, dans les chapitres transverses ; cette table dit seulement où les lire.

Deux aides ne sont pas héritées : of_icon et of_escape_markup vivent sur n_pbt_utils. Déclarez-en une — n_pbt_utils lnv_utils, rien à créer — et appelez-les dessus.

← Référence des composants · Sommaire du guide