chartcartesian — u_pbt_chartcartesian #

← Komponentenreferenz · Inhalt des Handbuchs

Kartesisches Diagramm: Säulen, Balken, Linien, Flächen und Punktwolken, auf einer Kategorienachse und einer oder zwei Wertachsen. Der Typ wird je Reihe gesetzt.

▶ Live ansehen — Demoanwendung, Kachel Cartesian chart : die Vorschau, der erzeugende Code und diese Seite nebeneinander.

Kurz gefasst #

Schnellstart #

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

Der Typ gehört zur REIHE, nicht zur Komponente #

Das ist die Entscheidung, aus der alles Übrige folgt. Eine Komponente je Typ — eine für Balken, eine für Linien — kann nie eine Kombination erzeugen: Balken mit einer Ziellinie darüber, auf einer zweiten Achse. Und genau das ist die meistgefragte Form auf einem Dashboard.

Hier gibt es eine Komponente, und jede Reihe trägt ihr is_type (TYPE_BAR, TYPE_LINE, TYPE_AREA, TYPE_SCATTER, TYPE_STEPLINE). Den Typ einer Reihe zu ändern lässt die anderen unberührt.

ib_secondary legt eine Reihe auf die zweite Wertachse. Das lässt eine Auftragszahl und einen Umsatz zusammen leben: ohne sie ist eine der beiden eine flache Linie an der Achse.

of_set_categories kommt vor den Reihen: Ihre Anzahl legt fest, wie viele Werte jede Reihe tragen muss.

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

Eigenschaften #

Methoden #

Ohne Schlüssel (Demomodus) zeichnet das Diagramm nur seine ersten 3 Reihen, Legende inbegriffen. Die übrigen bleiben im Modell — of_count, of_get_series_values und ihre Griffe sehen sie — und der gesetzte Schlüssel zeigt sie, ohne dass Sie etwas erneut senden müssen.

Ereignisse #

Die Animation ist ein Weg hinein, keine Berechnung: Die endgültige Geometrie steht sofort, und nur die Ankunft wird gespielt. Ein nie angezeigtes Diagramm — außerhalb des Bildschirms geboren, auf einem Reiter, den niemand öffnet — zeigt daher stillschweigend die richtigen Balken.

Elementeigenschaften #

Achseneigenschaften #

Beispiele #

Die Animation zum Bildschirm passend einstellen #

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

Die Zeilen hinter einem Punkt öffnen #

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

Ein lebendiges Dashboard #

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

Ein gleitendes Live-Diagramm #

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

Ein fehlender Messwert und das Diagramm als Bild #

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

Ein Band und ein Ziel auf der Wertachse #

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

Ein Diagramm aus einem 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()

Die Farbe eines Punktes, ein Menü auf einem anderen #

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

Bewährte Praxis #

• Setzen Sie die Kategorien vor den Reihen. Ihre Anzahl sagt, was eine Reihe enthalten muss; umgekehrt geht es nicht.
• Eine zweite Achse wird begründet, nicht erlitten. Zwei Skalen in einer Zeichnung täuschen das Auge: Holen Sie sie nur hervor, wenn die Einheiten wirklich verschieden sind.
• Schalten Sie die Animation auf einem sich auffrischenden Dashboard ab. Eine Ankunft, die alle fünf Sekunden neu beginnt, endet nie und ermüdet, statt zu helfen.
• Balken beginnen bei null, und die Komponente hält sich daran: Die Null kommt in die Achse, sobald ein Balken oder eine Fläche darauf steht. Ein abgeschnittenes Balkendiagramm übertreibt jeden Abstand. Linien, Punktwolken und Kurse werden auf ihrer eigenen Spanne gelesen.
• Das Diagramm behält seine mathematische Richtung in einer Rechts-nach-links-Anwendung: Kategorien von links nach rechts, Wertachse links. Nur die Legende START/END folgt der Leserichtung.
• Stapeln, um eine Summe zu lesen; nebeneinander, um zu vergleichen. Das sind nicht zwei Stile, das sind zwei verschiedene Fragen.
• Hängen Sie jede Reihe an in einem Live-Diagramm: of_append_categories, dann of_append_values für jede, mit demselben Maximum — eine vergessene Reihe rutscht unter die Nachbarkategorie.
• Eine Lücke ist keine Null. Ein NULL-Wert wird weder gezeichnet noch beschriftet noch angeklickt; ein NULL-Gewicht lässt die Zelle einer Wärmekarte leer.
• ue_point_clicked liefert den Rang: Nutzen Sie ihn, um genau die Liste hinter diesem Punkt zu öffnen, nicht die Suchmaske.

Vom gemeinsamen Sockel geerbt #

Diese Mitglieder gibt es bei jeder visuellen Komponente — sie sind nicht dieser eigen. Sie werden einmal in den übergreifenden Kapiteln beschrieben; diese Tabelle sagt nur, wo man sie liest.

Zwei Helfer werden nicht geerbt: of_icon und of_escape_markup liegen auf n_pbt_utils. Deklarieren Sie eines — n_pbt_utils lnv_utils, nichts zu erzeugen — und rufen Sie sie darauf auf.

← Komponentenreferenz · Inhalt des Handbuchs