crosstab — u_pbt_crosstab #

← Komponentenreferenz · Inhalt des Handbuchs

Vollständige Crosstab-Tabelle: Bereiche für Zeilen / Spalten / Werte, gespeist aus einem DataStore, Aggregate, Filter, bedingte Formatierung, Datumsgruppierung, berechnete Kennzahlen und Exporte nach CSV / Excel.

▶ Live ansehen — Demoanwendung, Kachel Crosstab: die Vorschau, der zugehörige Code und diese Seite, nebeneinander.

Auf einen Blick #

Das Prinzip #

Sie übergeben der Komponente einen flachen Datenbestand — einen DataStore, also jede beliebige Abfrage, die in Ihrer Anwendung bereits geschrieben ist. Um den Rest kümmert sich das Crosstab: Es leitet daraus die Feldliste ab, und Sie verteilen die Felder auf vier Bereiche.

Die gesamte Berechnung findet in der Komponente statt: Sind die Daten einmal übergeben, löst das Umstellen der Tabelle keinen einzigen Rückweg zur Datenbank oder zu PowerBuilder aus.

Schnellstart #

// Event open des Fensters
// Local variables
datastore lds
lds = create datastore
lds.dataobject = "d_sales"
lds.SetTransObject(SQLCA)
lds.Retrieve()

// 1. Daten uebergeben: die Felder werden aus den Spalten abgeleitet
uo_crosstab.of_from_datastore(/*ads*/ lds)

// 2. Die Felder auf die Bereiche verteilen
uo_crosstab.of_add_row_field(/*field*/ "region")
uo_crosstab.of_add_col_field(/*field*/ "year")
uo_crosstab.of_add_value_field(/*field*/ "amount", /*agg*/ uo_crosstab.AGG_SUM)

// 3. Darstellen: Format der Betraege und Gesamtsummen
uo_crosstab.of_field(/*field*/ "amount").is_format = "$#,##0"
uo_crosstab.ib_row_grand_total = true
uo_crosstab.ib_col_grand_total = true

// Event ue_cell_double_clicked von uo_crosstab: (string as_row_tuple_json, string as_col_tuple_json, integer ai_measure, double ad_value)
// Der Benutzer moechte das Detail hinter einer Zahl: die passende Liste oeffnen.
of_open_detail(as_row_tuple_json, as_col_tuple_json)

Konstanten #

Die Konstanten für Aggregat, Filter, Datum und Trennzeichen werden auf der Komponente gelesen: uo_crosstab.AGG_SUM. Die eines Feldes oder eines Wertes (SHOW_*, CF_*) werden auf der Klasse seines Handles gelesen: n_pbt_crosstab_field.CF_SCALE, n_pbt_crosstab_value.SHOW_PCT_GRAND. AGG_COUNT zählt die nicht leeren Werte, wie die Funktion Anzahl von Excel; AGG_COUNT_ROWS zählt die Zeilen, leere eingeschlossen.

Eigenschaften #

Eigenschaften eines Feldes #

of_field (string as_field) liefert das Handle eines Feldes: Sie holen es einmal und steuern das Feld anschließend über seine Eigenschaften. Das Handle wird beim ersten Aufruf erzeugt und danach wiederverwendet.

Die Werte von is_show und is_conditional_formatting stehen auch als Konstanten auf dem Handle zur Verfügung (SHOW_PCT_COL, CF_SCALE…). Auf dem Feld gesetzt, gelten is_show, is_conditional_formatting und is_format für alle seine Werte im Bereich Werte und für die, die später hinzukommen — vor dem Einfügen des Feldes in Werte gesetzt, werden sie aufbewahrt, so zurückgelesen und bei seinem Eintreffen angewendet. Für einen einzelnen Wert (dasselbe Feld zweimal: der Betrag und sein Anteil an der Summe) dient das Handle des Wertes, siehe unten.

// Local variables
n_pbt_crosstab_field lnv_field

// Das Betragsfeld : seine Bezeichnung und eine Farbskala
lnv_field = uo_crosstab.of_field(/*field*/ "amount")
lnv_field.is_label = "Umsatz"
lnv_field.is_conditional_formatting = lnv_field.CF_SCALE

⚠️ Inkompatible Änderung. Diese Eigenschaft hieß is_cf: Die Abkürzung sagte an der Aufrufstelle nichts aus. Der alte Name existiert nicht mehr — Code, der ihn verwendet, lässt sich nicht kompilieren. Die Ersetzung ist mechanisch: is_cf → is_conditional_formatting, ohne Änderung der Werte oder des Verhaltens.

Eigenschaften eines Wertes #

of_value (integer ai_position) liefert das Handle eines Wertes des Bereichs Werte, über seine Position (1 = der erste). Ein Feld kann dort zweimal stehen — der Betrag und sein Anteil an der Gesamtsumme — und jeder Wert hat seine eigenen Einstellungen, die Vorrang vor denen seines Feldes haben. Das Handle bezeichnet eine Position: nach of_remove_value, of_move_value, of_remove_field, of_remove_calc_measure, of_clear_layout oder of_set_layout wird es freigegeben — rufen Sie of_value erneut auf. Seine Konstanten SHOW_* und CF_* sind die von n_pbt_crosstab_field.

// Local variables
n_pbt_crosstab_value lnv_share, lnv_amount

// Der Betrag zweimal in Werte : die Summe, dann sein Anteil an der Gesamtsumme
uo_crosstab.of_add_value_field(/*field*/ "amount", /*agg*/ uo_crosstab.AGG_SUM)
uo_crosstab.of_add_value_field(/*field*/ "amount", /*agg*/ uo_crosstab.AGG_SUM)

// Nur der zweite Wert : sein Anteil an der Gesamtsumme, unter eigener Bezeichnung
lnv_share = uo_crosstab.of_value(/*position*/ 2)
lnv_share.is_show = n_pbt_crosstab_value.SHOW_PCT_GRAND
lnv_share.is_label = "Umsatzanteil"

// Der erste Wert : zwei Dezimalstellen, negative Betraege in Rot
lnv_amount = uo_crosstab.of_value(/*position*/ 1)
lnv_amount.is_format = "#,##0.00"
lnv_amount.ib_negative_red = true

Methoden #

Speisen und benennen #

Die Tabelle aufbauen #

Die von of_add_value_field akzeptierten Aggregate werden von der Komponente als Konstanten bereitgestellt: AGG_SUM (Standard), AGG_COUNT (die Anzahl der nicht leeren Werte, wie die Funktion Anzahl von Excel), AGG_COUNT_ROWS (die Anzahl der Zeilen, leere eingeschlossen), AGG_DISTINCT_COUNT (Zählung eindeutiger Werte, leere Zellen werden wie in Excel ignoriert), AGG_AVG, AGG_MIN, AGG_MAX. Eine Summe ohne jeden Wert ist eine leere Zelle, nicht 0; eine „Abweichung zum Vorherigen“, bei der eine der beiden Zellen leer ist, ist ebenfalls leer. Prozentwerte werden so geschrieben, wie die Anzeigesprache sie schreibt (57.9% auf Englisch, 57,9 % auf Französisch).

Summen und Zwischensummen #

Summen werden über Eigenschaften eingestellt, siehe oben: ib_row_grand_total und ib_col_grand_total für die Gesamtsummen, ib_row_subtotals und ib_col_subtotals für die Zwischensummen, is_totals_position für die Lage der Gesamtsummenzeile. Das Menü Optionen des Rasters (das Zahnrad) bietet dieselben vier Schalter, ein Eintrag je Achse: Gesamtsummenzeile, Gesamtsummenspalte, Zeilen-Zwischensummen, Spalten-Zwischensummen.

Filtern #

Die Werte, die of_set_member_filter und of_set_member_order erwarten, sind die, die das Raster hält, nicht immer die, die es anzeigt: Bei einem von einem Datum abgeleiteten Feld wird ein Monat "01"…"12" geschrieben, ein Quartal "1"…"4", ein Jahr "2024"; ein nicht gruppiertes Datumselement wird yyyy-mm-dd geschrieben. Der Benutzer findet den Bezeichnungsfilter im Menü des Chips jedes Feldes — Text, Zahl oder Datum.

Formatieren #

Das Format eines Wertes wird über eine Eigenschaft gesetzt: of_field("amount").is_format = "$#,##0.00" für alle Werte eines Feldes, of_value(2).is_format für einen einzelnen (siehe Eigenschaften eines Feldes und Eigenschaften eines Wertes). Es ist ein PowerBuilder-Anzeigeformat, gelesen von der Maskenengine der Bibliothek; leer übernimmt der Wert das Format der DataWindow-Spalte. Negative in Rot: of_value(n).ib_negative_red = true. Das Tausendertrennzeichen der Werte ohne Format bleibt is_thousands, die Währung des Chip-Menüs is_currency_symbol.

Datumsangaben und berechnete Felder #

Eine Formel akzeptiert die Operatoren + - * / ( ), Zahlen (12, 0.5, .5, 1e3, immer mit Punkt) und Felder in eckigen Klammern; ^ ist kein Operator. Eine ungültige Formel löst ue_calc_field_error aus — nichts stürzt ab.

Aufklappen, speichern, exportieren #

Gemeinsame #

Events #

Was der Benutzer ohne eine einzige Zeile Code tun kann #

Die Tabelle ist lebendig: Genau darin liegt der Sinn der Komponente. Bei eingeblendetem Feldpanel (ib_field_list = true) kann der Benutzer:

• ein Feld von einem Bereich in einen anderen ziehen und die Kreuzauswertung beliebig umstellen;
• das Aggregat einer Kennzahl ändern (Summe, Mittelwert, Anzahl…);
• die Werte eines Feldes über eine Ankreuzliste filtern;
• eine Zeilen- oder Spaltengruppe ein- oder ausklappen;
• über eine Kopfzeile sortieren;
• einen Zellblock auswählen und kopieren, samt Kopfzeilen, damit ein Einfügen in eine Tabellenkalkulation sagt, was die Zahlen sind (ib_copy_headers).

Jede dieser Aktionen, abgesehen vom Kopieren (es löst ue_copy aus), wird in ue_layout_changed gemeldet: Zusammen mit of_get_layout / of_set_layout können Sie Ihren Benutzern damit „gespeicherte Ansichten“ anbieten.

Über die Tastatur. Der Aufbau der Tabelle geht ohne Maus — Chips, Menüs, Ein- und Ausklappen, Sortieren: Tab führt auf ein Feld, ein Zuklapp-Dreieck oder eine sortierbare Kopfzeile, Eingabe oder Leertaste löst sie aus. Auf einem Feld öffnet das dessen Menü — jenes mit Zu Zeilen / Spalten / Werten / Filtern hinzufügen und Entfernen: der gesamte Aufbau der Tabelle läuft darüber. Umschalt+F10 oder die Menütaste öffnen dieses Menü ebenfalls, und der Fokus folgt dem gerade verschobenen Feld, auch in eine andere Zone. Zellen auswählen und kopieren (Strg+C) erfordert heute die Maus.

Beispiele #

Ein vollständiger Vertriebsbericht #

// Zeilen: Region, dann Stadt innerhalb jeder Region
uo_crosstab.of_clear_layout()
uo_crosstab.of_add_row_field(/*field*/ "region")
uo_crosstab.of_add_row_field(/*field*/ "city")

// Spalten: eine je Jahr
uo_crosstab.of_add_col_field(/*field*/ "year")

// Zellen: der Gesamtbetrag
uo_crosstab.of_add_value_field(/*field*/ "amount", /*agg*/ uo_crosstab.AGG_SUM)

// Darstellung: lesbare Betraege, Zwischen- und Gesamtsummen
uo_crosstab.of_field(/*field*/ "amount").is_format = "$#,##0"
uo_crosstab.ib_row_subtotals = true
uo_crosstab.ib_row_grand_total = true
uo_crosstab.ib_col_grand_total = true

// Die Zellen einfaerben, um grosse Betraege auf einen Blick zu erkennen
uo_crosstab.of_field(/*field*/ "amount").is_conditional_formatting = n_pbt_crosstab_field.CF_SCALE

Lesbare Bezeichnungen #

Ihre Spalten heißen oft mt_ht oder cd_reg. Benennen Sie sie ein für alle Mal um, direkt nach of_from_datastore.

// Zuerst die Daten : die Felder tragen die Namen der Spalten
uo_crosstab.of_from_datastore(/*ads*/ lds)

// Dann eine lesbare Bezeichnung fuer jedes Feld
uo_crosstab.of_field(/*field*/ "region").is_label    = "Region"
uo_crosstab.of_field(/*field*/ "city").is_label     = "Stadt"
uo_crosstab.of_field(/*field*/ "category").is_label = "Kategorie"
uo_crosstab.of_field(/*field*/ "year").is_label     = "Jahr"
uo_crosstab.of_field(/*field*/ "amount").is_label   = "Umsatz"
uo_crosstab.of_field(/*field*/ "quantity").is_label  = "Menge"

Anteile statt Beträge auswerten #

// Local variables
n_pbt_crosstab_field lnv_amount

// Mit leeren Bereichen beginnen, dann die Felder platzieren
uo_crosstab.of_clear_layout()
uo_crosstab.of_add_row_field(/*field*/ "category")
uo_crosstab.of_add_col_field(/*field*/ "year")
uo_crosstab.of_add_value_field(/*field*/ "amount", /*agg*/ uo_crosstab.AGG_SUM)

// Nur zwei Kategorien auf dem Bildschirm behalten (Werte durch einen Tabulator getrennt)
uo_crosstab.of_set_member_filter(/*field*/ "category", /*values_tab*/ "Informatique~tMobilier")

// Das Betragsfeld, um seine Anzeige einzustellen
lnv_amount = uo_crosstab.of_field(/*field*/ "amount")

// Den Anteil jeder Zelle an der Summe ihrer Spalte anzeigen
lnv_amount.is_show = lnv_amount.SHOW_PCT_COL

// Ein kleiner Balken in jeder Zelle, um die Anteile auf einen Blick zu vergleichen
lnv_amount.is_conditional_formatting = lnv_amount.CF_BARS

Eine eigene Kennzahl: der Durchschnittspreis #

Eine berechnete Kennzahl wird auf den Summen jeder Zelle ausgewertet, nicht Zeile für Zeile: Genau das macht ein Verhältnis korrekt.

// Mit leeren Bereichen beginnen, dann die Felder platzieren
uo_crosstab.of_clear_layout()
uo_crosstab.of_add_row_field(/*field*/ "region")

// Die beiden Summen, die als Grundlage der Berechnung dienen
uo_crosstab.of_add_value_field(/*field*/ "amount",  /*agg*/ uo_crosstab.AGG_SUM)
uo_crosstab.of_add_value_field(/*field*/ "quantity", /*agg*/ uo_crosstab.AGG_SUM)

// Durchschnittspreis = Gesamtbetrag geteilt durch Gesamtmenge
uo_crosstab.of_add_calc_measure(/*name*/ "avg_price", /*label*/ "Durchschnittspreis", /*formula*/ "[amount] / [quantity]")
uo_crosstab.of_field(/*field*/ "avg_price").is_format = "$#,##0.00"

// Dann wie jedes Feld unter die Werte stellen (das Aggregat zaehlt nicht: eine Kennzahl wird berechnet)
uo_crosstab.of_add_value_field(/*field*/ "avg_price", /*agg*/ uo_crosstab.AGG_SUM)

// Event ue_calc_field_error von uo_crosstab: (string as_field, string as_message)
// Ungueltige Formel: warnen, ohne etwas zu zerstoeren, die Tabelle bleibt sichtbar.
uo_status.of_panel(/*key*/ "main").is_text = "Formel " + as_field + ": " + as_message

Nach Monat, Quartal oder Jahr auswerten #

Eine Datumsspalte lässt sich nicht unverändert kreuzen — jeder einzelne Tag ergäbe eine eigene Zeile. Leiten Sie zuerst die gewünschte Ebene ab.

// Drei aus der Spalte sale_date abgeleitete Felder erzeugen
uo_crosstab.of_group_date_field(/*field*/ "sale_date", /*part*/ uo_crosstab.DATE_YEAR)
uo_crosstab.of_group_date_field(/*field*/ "sale_date", /*part*/ uo_crosstab.DATE_QUARTER)
uo_crosstab.of_group_date_field(/*field*/ "sale_date", /*part*/ uo_crosstab.DATE_MONTH)

// Dann wie jedes andere Feld kreuzen: Jahr in den Spalten, Quartal darunter
uo_crosstab.of_add_col_field(/*field*/ "sale_date__year")
uo_crosstab.of_add_col_field(/*field*/ "sale_date__quarter")

Die Rangliste der zehn besten Regionen #

// Nur die 10 Regionen mit der hoechsten Summe der ersten Kennzahl behalten
uo_crosstab.of_set_value_filter(/*field*/ "region", /*type*/ uo_crosstab.VALUEFILTER_TOP, /*a*/ 10, /*b*/ 0, /*measure_index*/ 1)

Bei einem Feld, das unter einem anderen steht, wird innerhalb jedes übergeordneten Elements gereiht: die beste Stadt jeder Region, nicht die beste Stadt des Landes. Gleichstände bleiben alle.

// Die Staedte unter den Regionen
uo_crosstab.of_add_row_field(/*field*/ "region")
uo_crosstab.of_add_row_field(/*field*/ "city")

// Die beste Stadt jeder Region, nach der ersten Kennzahl
uo_crosstab.of_set_value_filter(/*field*/ "city", /*type*/ uo_crosstab.VALUEFILTER_TOP, /*a*/ 1, /*b*/ 0, /*measure_index*/ 1)

Exportieren #

Der Export übernimmt exakt die aktuelle Ansicht: dieselben Filter, dieselben Summen, dieselbe Formatierung.

// Nach Excel: die Datei wird direkt unter dem angegebenen Pfad geschrieben
uo_crosstab.of_export_xlsx(/*path*/ "C:\temp\ventes.xlsx")

// Event ue_xlsx_saved von uo_crosstab: (string as_path, boolean ab_ok, string as_error)
// inv_notif = ein n_pbt_toaster, als Instanzvariable des Fensters deklariert
if ab_ok then
    inv_notif.is_title = "Export abgeschlossen"
    inv_notif.is_text  = as_path
    inv_notif.is_kind  = inv_notif.KIND_SUCCESS
else
    inv_notif.is_title = "Export nicht möglich"
    inv_notif.is_text  = as_error
    inv_notif.is_kind  = inv_notif.KIND_ERROR
end if
inv_notif.of_show()

// Nach CSV: eine Datei, wie bei Excel; ue_csv_saved bestaetigt
uo_crosstab.of_export_csv(/*path*/ "C:\exports\ventes.csv")

Gespeicherte Ansichten anbieten #

// Local variables
string ls_view

// Aktuelle Ansicht sichern : of_get_layout antwortet sofort
ls_view = uo_crosstab.of_get_layout()

// Den Inhalt UNVERAENDERT aufbewahren: er wird ohne Umwandlung wieder abgespielt.
of_save_view(is_current_view, ls_view)

// Spaeter: eine gespeicherte Ansicht wieder abspielen
uo_crosstab.of_set_layout(/*state_json*/ of_read_view("Ventes par region"))

Hinter einer Zahl ins Detail gehen #

// Event ue_cell_double_clicked von uo_crosstab: (string as_row_tuple_json, string as_col_tuple_json, integer ai_measure, double ad_value)
// Local variables
long ll_rows[], ll_count, ll_i

// Die Zeilen des DataStore hinter der doppelt angeklickten Zahl
ll_count = uo_crosstab.of_get_cell_rows(/*row_tuple_json*/ as_row_tuple_json, /*col_tuple_json*/ as_col_tuple_json, /*rows*/ ll_rows)

// Nichts zu zeigen : keine Zeile, oder eine gerade nicht lesbare Zelle
if ll_count <= 0 then return

// Sie in die Detailliste kopieren : ids_sales ist der an of_from_datastore uebergebene DataStore
dw_detail.Reset()
for ll_i = 1 to ll_count
	ids_sales.RowsCopy(ll_rows[ll_i], ll_rows[ll_i], Primary!, dw_detail, dw_detail.RowCount() + 1, Primary!)
next

Die beiden Tupel und ai_measure bilden die Adresse der Zelle: of_get_cell_value liest sie später wieder, so wie die Tabelle sie in diesem Moment anzeigt.

// ue_cell_double_clicked event of uo_crosstab : the address of the cell, read again later
// Local variables
double ld_value

// Read the cell again from its address : 0 when it exists
if uo_crosstab.of_get_cell_value(/*row_tuple_json*/ as_row_tuple_json, /*col_tuple_json*/ as_col_tuple_json, /*measure*/ ai_measure, /*value*/ ld_value) = 0 then

	// ld_value is what the cell shows ; NULL for an empty cell
end if

Eine Zelle lässt sich auch ohne Klick über ihre Elemente lesen: ein unvollständiges Tupel bezeichnet eine Zwischensumme. Und of_remove_field nimmt ein Feld auf einmal aus all seinen Bereichen, Filter inbegriffen.

// The sales of Nord in 2025, first measure of Values
// Local variables
double ld_north

// A partial address : the region and the year, no other member
uo_crosstab.of_get_cell_value(/*row_tuple_json*/ '{"region":"Nord"}', /*col_tuple_json*/ '{"year":"2025"}', /*measure*/ 1, /*value*/ ld_north)

// Take the year out of the table, filters included
uo_crosstab.of_remove_field(/*field*/ "year")

Best Practices #

• Rufen Sie of_from_datastore nur ein einziges Mal je Datenbestand auf: Die Tabelle danach umzustellen kostet nichts, die Daten erneut zu übergeben ist teuer.
• Setzen Sie die Bezeichnungen (of_field("...").is_label) direkt nach of_from_datastore: Sie folgen dem Feld überallhin, auch in das Feldpanel und in die Exporte.
• Filtern Sie auf SQL-Seite weg, was nicht ausgewertet werden soll: Das Crosstab ist schnell, aber ein halb so großer DataStore öffnet sich doppelt so schnell.
• of_clear_layout() leert die Bereiche, ohne die Daten erneut zu übergeben: Das ist der richtige Aufruf, um mehrere Auswertungen auf derselben Quelle anzubieten.
• Ein Datumsfeld wird immer über of_group_date_field gekreuzt, niemals direkt.
• Lassen Sie das Feldpanel auf Auswertungsbildschirmen sichtbar und blenden Sie es auf festen Dashboards aus.

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