chartcartesian — u_pbt_chartcartesian #

← Referencia de componentes · Índice de la guía

Gráfico cartesiano: columnas, barras, líneas, áreas y nubes de puntos, sobre un eje de categorías y uno o dos ejes de valores. El tipo se fija por serie.

▶ Verlo en vivo — Aplicación de demostración, mosaico Cartesian chart : la vista previa, el código que lo produce y esta página, lado a lado.

En resumen #

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

El tipo pertenece a la SERIE, no al componente #

Es la decisión de la que se sigue todo lo demás. Un componente por tipo — uno para barras, otro para líneas — nunca puede producir un combinado: barras con una línea de objetivo encima, sobre un segundo eje. Y esa es la forma más pedida en un cuadro de mando.

Aquí hay un solo componente, y cada serie lleva su is_type (TYPE_BAR, TYPE_LINE, TYPE_AREA, TYPE_SCATTER, TYPE_STEPLINE). Cambiar el tipo de una serie no toca las demás.

ib_secondary coloca una serie en el segundo eje de valores. Es lo que permite que un número de pedidos y una facturación convivan: sin él, uno de los dos es una línea plana al ras del eje.

of_set_categories va antes que las series: su número fija cuántos valores debe llevar cada serie.

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

Propiedades #

Métodos #

Sin clave (modo demo), el gráfico solo dibuja sus 3 primeras series, leyenda incluida. Las demás se quedan en el modelo — of_count, of_get_series_values y sus handles las ven — y la clave puesta las muestra sin que tenga que volver a enviar nada.

Eventos #

La animación es una entrada, no un cálculo: la geometría final se escribe de inmediato y solo se reproduce la llegada. Un gráfico nunca mostrado — nacido fuera de pantalla, en una pestaña que nadie abre — enseña por tanto las barras correctas, en silencio.

Propiedades de elemento #

Propiedades de eje #

Ejemplos #

Ajustar la animación según la pantalla #

// 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 las filas detrás de 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 cuadro de mando 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)

Un gráfico en directo que se 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)

Una medida que falta, y el gráfico como imagen #

// 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 banda y un objetivo en el eje de 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)"

Un gráfico alimentado por 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()

El color de un punto, un menú en otro #

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

Buenas prácticas #

• Ponga las categorías antes que las series. Su número dice lo que debe contener una serie; al revés no puede funcionar.
• Un segundo eje se justifica, no se padece. Dos escalas en un mismo dibujo engañan al ojo: sáquelo solo cuando las unidades sean realmente distintas.
• Corte la animación en un cuadro de mando que se refresca. Una llegada que vuelve a empezar cada cinco segundos no termina nunca, y cansa en vez de ayudar.
• Las barras parten de cero, y el componente se atiene a ello: el cero entra en el eje en cuanto una barra o un área se apoya en él. Un gráfico de barras truncado exagera cada diferencia. Líneas, nubes y cotizaciones se leen en su propio rango.
• El gráfico conserva el sentido matemático en una aplicación de derecha a izquierda: categorías de izquierda a derecha, eje de valores a la izquierda. Solo la leyenda START/END sigue el sentido de lectura.
• Apile para leer un total, yuxtaponga para comparar. No son dos estilos, son dos preguntas distintas.
• Añada cada serie en un gráfico en directo: of_append_categories y luego of_append_values para cada una, con el mismo máximo — una serie olvidada se desliza bajo la categoría de al lado.
• Un hueco no es un cero. Un valor NULL no se dibuja, ni se etiqueta, ni se puede pulsar; un peso NULL deja vacía la celda de un mapa de calor.
• ue_point_clicked da el rango: úselo para abrir la lista exacta detrás de ese punto, no la pantalla de búsqueda.

Heredado de la base común #

Estos miembros existen en todos los componentes visuales — no son propios de este. Se detallan una sola vez, en los capítulos transversales; esta tabla solo dice dónde leerlos.

Dos ayudas no se heredan: of_icon y of_escape_markup viven en n_pbt_utils. Declare uno — n_pbt_utils lnv_utils, nada que crear — y llámelas sobre él.

← Referencia de componentes · Índice de la guía