datagrid — u_pbt_datagrid #

← Komponentenreferenz · Inhalt des Handbuchs

Das moderne Raster eines DataStores: typisierte Spalten und reichhaltige Zellen, Sortierung, Filter, Gruppierung mit Zwischensummen, Bearbeitung an Ort und Stelle, Seitenweise Anzeige, gefensterte Quelle und CSV-Export — das DataWindow bleibt Herr Ihrer Daten.

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

Auf einen Blick #

Die Positionierung #

Das datagrid ist kein Ersatz für die DataWindow: Es ist eine Präsentationsschicht, die sich darüberlegt. Sie behalten Ihr SQL, Ihre Retrieve(), Ihre Update(), Ihre Ausdrucke — und gewinnen ein modernes Raster für die Anzeige.

Es zielt auf zwei blinde Flecken des klassischen DataWindow-Rasters:

• die Skalierung — nur die sichtbaren Zeilen werden tatsächlich gezeichnet, der Bildlauf bleibt bei Zehntausenden von Zeilen flüssig, und der Fenstermodus trägt Hunderttausende von Zeilen;
• die Rich-Zellen — farbiger Status-Chip, Anzeige, Sparkline, Sternebewertung, Avatar, mehrere Tags, Aktionsschaltfläche, Link.

Die Datenbankanbindung und die Aktualisierung bleiben außerhalb des Umfangs: Sie gehören zur DataWindow.

Der DataStore der Beispiele #

Alle Beispiele dieser Seite — wie die der Demoanwendung — gehen vom selben DataStore mit Kundenkonten aus, eine Zeile pro Konto: city, rep (der Vertriebsmitarbeiter), status, pipeline (ein Prozentsatz), trend (sieben Monatswerte, geschrieben "3,5,2,6,7,4,8"), revenue und rating (eine Note von fünf). Das Raster heißt im Fenster uo_grid, der DataStore ids. Eine mit of_from_datastore geladene Zeile hat ihre RowID im DataStore als Schlüssel: Sie ändert sich nicht, wenn der DataStore sortiert, filtert, einfügt oder löscht. Ein Event gibt sie Ihnen zurück, und ids.GetRowFromRowId(Long(as_key)) ist die Nummer der Zeile, die sie jetzt bezeichnet.

Ein DataStore enthält nur einfache Werte, und das genügt für reichhaltige Zellen: Eine Zahl reicht für eine Anzeige (RENDERER_PROGRESS) und Sterne (RENDERER_RATING), ein Name ergibt einen Avatar, ein Text "3,5,2,6" ein Mini-Diagramm (RENDERER_SPARKLINE) so wie "vip, b2b" Etiketten (RENDERER_TAGS); die Farbe eines Chips (RENDERER_CHIP) wird je Wert mit is_tones vergeben.

Schnellstart #

// open event of the window : the accounts, retrieved the way your application already does
ids = create datastore
ids.dataobject = "d_accounts"
ids.SetTransObject(SQLCA)
ids.Retrieve()

// 1. The grid reads the columns (typed) and every row of the DataStore
uo_grid.of_from_datastore(/*ads*/ ids)

// 2. The titles are the header texts of the DataWindow ; rename one if you like
uo_grid.of_column(/*key*/ "rep").is_title = "Account manager"

// 3. Rich cells : an avatar, a coloured status, a gauge, a mini chart, stars
uo_grid.of_column(/*key*/ "rep").is_renderer = n_pbt_datagrid_column.RENDERER_AVATAR
uo_grid.of_column(/*key*/ "status").is_renderer = n_pbt_datagrid_column.RENDERER_CHIP
uo_grid.of_column(/*key*/ "status").is_tones = "Active=" + n_pbt_datagrid_column.TONE_SUCCESS + "|At risk=" + n_pbt_datagrid_column.TONE_DANGER
uo_grid.of_column(/*key*/ "pipeline").is_renderer = n_pbt_datagrid_column.RENDERER_PROGRESS
uo_grid.of_column(/*key*/ "trend").is_renderer = n_pbt_datagrid_column.RENDERER_SPARKLINE
uo_grid.of_column(/*key*/ "rating").is_renderer = n_pbt_datagrid_column.RENDERER_RATING

// 4. A total, and the city stays in view
uo_grid.of_column(/*key*/ "revenue").is_summary = n_pbt_datagrid_column.SUMMARY_SUM
uo_grid.of_column(/*key*/ "city").is_pin = n_pbt_datagrid_column.PIN_START

// ue_row_clicked event of uo_grid : (string as_key)
// The key of a row loaded by of_from_datastore is its RowID : GetRowFromRowId gives
// the row it designates now, even after a sort or a delete in the DataStore.
wf_open_account(ids.GetRowFromRowId(Long(as_key)))

Eigenschaften #

Eigenschaften einer Spalte #

Jede Spalte ist ein eigenständiges Objekt, das über of_column("Bezeichner") erhältlich ist — das Handle wird beim ersten Zugriff erzeugt und bleibt danach gültig.

// A column is reached by its key ; used once, it fits on one line
uo_grid.of_column(/*key*/ "amount").is_summary = n_pbt_datagrid_column.SUMMARY_SUM
uo_grid.of_column(/*key*/ "city").is_pin = n_pbt_datagrid_column.PIN_START

Konstanten #

Verwenden Sie stets die Konstanten statt literaler Zeichenketten: Die IDE vervollständigt sie, und ein Tippfehler wird unmöglich.

Konstanten werden auf dem Objekt gelesen, das sie trägt: u_pbt_datagrid.SELECT_MULTIPLE für eine Eigenschaft der Komponente, n_pbt_datagrid_column.PIN_START für eine Spalteneigenschaft.

Methoden #

Das Raster füllen #

Spalten #

Sortierung, Filter, Darstellung #

Auswahl, Detail, Export #

Sehr große Datenmengen #

Gemeinsame #

Events #

Was der Benutzer ohne eine einzige Codezeile tun kann #

Das Raster bringt seine eigene Symbolleiste und seine Kopfzeilenmenüs mit. Nichts davon verlangt Code von Ihrer Seite:

• sortieren durch Klick auf eine Kopfzeile: aufsteigend, absteigend, keine — nur nach dieser Spalte; Umschalt+Klick fügt sie der Sortierung nach den anderen hinzu (ist sie schon darin, wechselt sie von aufsteigend zu absteigend und wird dann entfernt), und jeder Pfeil trägt dann seinen Rang (1 entscheidet, 2 bei Gleichstand…);
• schnell filtern über das Suchfeld, oder Spalte für Spalte über die Schaltfläche Filter, die eine Eingabezeile unter den Kopfzeilen anzeigt;
• die sichtbaren Spalten wählen über die Schaltfläche Spalten;
• die Größe einer Spalte ändern, indem man die Kante ihrer Kopfzeile zieht;
• die Spalten umsortieren, indem man ihre Kopfzeile zieht;
• eine Spalte über das Kontextmenü ihrer Kopfzeile fixieren oder ausblenden;
• eine Zeile, einen Bereich (Umschalt) oder eine Menge (Strg) auswählen;
• über das Kontextmenü einer Zeile auf sie einwirken: kopieren, alles auswählen, Auswahl aufheben, als CSV exportieren — sowie die Einträge, die Sie hinzufügen.

Jede Änderung der Anordnung kommt in ue_layout_changed zurück: Breiten, Reihenfolge, fixierte oder ausgeblendete Spalten. Bewahren Sie sie auf und geben Sie sie beim nächsten Öffnen mit einem einzigen Aufruf von of_set_layout zurück; of_get_layout liest sie jederzeit.

Über die Tastatur — das Raster ist ein einziger Tabulatorstopp. Einmal erreicht, wird es vollständig über die Tastatur durchlaufen:

Die fokussierte Zelle ist mit der Akzentfarbe umrandet und wird Bildschirmlesern über aria-activedescendant angesagt. Der Fokus überlebt das Scrollen: da das Raster virtualisiert ist, wird er im Speicher gehalten und nach jedem Rendern wieder gesetzt. Er verschwindet hingegen, wenn seine Zeile durch eine Sortierung oder einen Filter aus der Ansicht fällt.

⚠️ Die Zwischenablage des Browsers kann in einer eingebetteten WebView verweigert werden. Deshalb gibt Ihnen ue_copy den Text zurück: legen Sie ihn mit ClipBoard(as_tsv) selbst ab, um des Ergebnisses sicher zu sein.

Beispiele #

Kundenkonten in wenigen Zeilen #

// ids : the accounts DataStore (see above). One repaint for the whole setup.
uo_grid.of_set_redraw(/*on*/ false)

// 1. The grid reads the columns (typed) and every row of the DataStore
uo_grid.of_from_datastore(/*ads*/ ids)

// 2. The titles are the header texts of the DataWindow ; rename one if you like
uo_grid.of_column(/*key*/ "rep").is_title = "Account manager"

// 3. Rich cells : an avatar, a coloured status, a gauge, a mini chart, stars
uo_grid.of_column(/*key*/ "rep").is_renderer = n_pbt_datagrid_column.RENDERER_AVATAR
uo_grid.of_column(/*key*/ "status").is_renderer = n_pbt_datagrid_column.RENDERER_CHIP
uo_grid.of_column(/*key*/ "status").is_tones = "Active=" + n_pbt_datagrid_column.TONE_SUCCESS + "|At risk=" + n_pbt_datagrid_column.TONE_DANGER
uo_grid.of_column(/*key*/ "pipeline").is_renderer = n_pbt_datagrid_column.RENDERER_PROGRESS
uo_grid.of_column(/*key*/ "trend").is_renderer = n_pbt_datagrid_column.RENDERER_SPARKLINE
uo_grid.of_column(/*key*/ "rating").is_renderer = n_pbt_datagrid_column.RENDERER_RATING

// A total, a column that stays in view, several rows selectable
uo_grid.of_column(/*key*/ "revenue").is_summary = n_pbt_datagrid_column.SUMMARY_SUM
uo_grid.of_column(/*key*/ "city").is_pin = n_pbt_datagrid_column.PIN_START
uo_grid.is_selection_mode = u_pbt_datagrid.SELECT_MULTIPLE
uo_grid.of_set_redraw(/*on*/ true)

Nach Status, dann nach Stadt gruppieren #

// The subtotal every group header shows
uo_grid.of_column(/*key*/ "revenue").is_summary = n_pbt_datagrid_column.SUMMARY_SUM

// Two levels : the status, then the city inside it ; "" goes back to a flat list
uo_grid.is_group_by = "status|city"

// The rating stays in view on the right
uo_grid.of_column(/*key*/ "rating").is_pin = n_pbt_datagrid_column.PIN_END

Aus Ihrem Code filtern #

// The filter row under the headers : the user types in it
uo_grid.ib_filter_row = true

// Only the accounts in Paris, and only those above one million
uo_grid.is_quick_filter = "Paris"
uo_grid.of_column(/*key*/ "revenue").is_filter = "> 1000000"

Nach mehreren Spalten sortieren #

Die Sortierung wird geschrieben wie die eines DataWindows: Die erste Spalte entscheidet, die folgenden bei Gleichstand. Der Benutzer tut dasselbe mit der Maus per Umschalt+Klick auf die Kopfzeilen; ein einfacher Klick beginnt wieder mit einer einzigen Spalte.

// City first, then the largest revenue in each city
uo_grid.of_sort(/*sort*/ "city A, revenue D")

Was das Raster im DataWindow liest #

of_from_datastore übernimmt mehr als die Daten: Der Kopftext jeder Spalte (<spalte>_t) wird zu ihrem Titel, ihr Anzeigeformat (Format oder die Maske eines EditMask) gilt, und eine Codetabelle — die Values eines Edit, einer DDLB oder von Optionsfeldern, ein DropDown DataWindow, eine CheckBox — zeigt den Anzeigewert (Active), während die Zeile den Datenwert (A) behält. Sortiert und gesucht wird nach dem Sichtbaren; eine Spalte mit Codetabelle wird über eine Liste bearbeitet, und der Datenwert kommt zurück.

// The grid reads titles, formats and code tables in the DataWindow
uo_grid.of_from_datastore(/*ads*/ ids)

// A format of your own on one column, in the DataWindow's syntax
uo_grid.of_column(/*key*/ "revenue").is_format = "$#,##0.00;($#,##0.00)"

// The rating is picked in its code table (Poor to Excellent) ; the number goes into the DataStore
uo_grid.of_column(/*key*/ "rating").ib_editable = true
uo_grid.ib_write_back = true

// Your code changed a row of the DataStore : show it again
ids.SetItem(12, "rating", 5)
uo_grid.of_reload_row(/*row*/ 12)

An Ort und Stelle bearbeiten, im DataStore speichern #

Das Raster bearbeitet, der DataStore bewahrt die Wahrheit: Mit ib_write_back wird jede Eingabe in die Zeile geschrieben, die der Schlüssel bezeichnet (ihre RowID, dort gefunden, wo sie ist), nach dem Typ der Spalte, vor ue_cell_edited — und die Anzeige folgt. Eine bearbeitete Zelle behält eine kleine Ecke in der Akzentfarbe bis of_reset_update.

// The pipelines can be edited : double-click, type a percentage, Enter
uo_grid.of_column(/*key*/ "pipeline").ib_editable = true

// Every edit goes into the DataStore itself, on the row the key designates
uo_grid.ib_write_back = true

Eine bearbeitbar gemachte boolesche Spalte (TYPE_BOOL oder eine CheckBox-Spalte eines DataWindows, gelesen von of_from_datastore) zeigt in jeder Zelle ein echtes Kontrollkästchen: Ein Klick, Leertaste, Enter oder F2 schaltet es sofort um — kein Texteditor, und ein Doppelklick schaltet es nicht zweimal um. Die Zelle erhält den Wert des anderen Zustands — true/false oder die ON/OFF-Werte der CheckBox des DataWindows — auf demselben Weg wie eine Eingabe: Veto ib_veto_edits / ue_cell_editing, dann ue_cell_edited, Markierung „geändert“ und ib_write_back. Schreibgeschützt behält eine boolesche Spalte ihr Häkchen ✓.

// A yes/no column the user ticks : a check box in every cell
uo_grid.of_add_column(/*key*/ "vip", /*title*/ "VIP", /*type*/ u_pbt_datagrid.TYPE_BOOL)
uo_grid.of_column(/*key*/ "vip").ib_editable = true

// Saving stays with the DataStore : when the user confirms
if ids.Update() = 1 then
	COMMIT USING SQLCA;

	// the edited cells are no longer marked as modified
	uo_grid.of_reset_update()
else
	ROLLBACK USING SQLCA;
end if

Eine aufklappbare Zeile, aus dem DataStore geschrieben #

// Local variables
long ll_row

// A detail panel for the first 20 accounts, written from their DataStore row
for ll_row = 1 to 20
    uo_grid.of_fill_detail(/*key*/ String(ll_row), /*markup*/ "[b]" + ids.GetItemString(ll_row, "rep") + "[/b] follows the " + ids.GetItemString(ll_row, "city") + " account")
next

// The first one is open right away ; the chevron opens the others
uo_grid.of_expand_row(/*key*/ "1")

Seiten statt Bildlauf, und die Summe von allem #

Sobald es blättert, hält das Raster nur eine Seite: Seine Fußzeile summiert die Seite. Die Summe aller Konten hat der DataStore.

// Local variables
n_pbt_json lnv_totals
double ld_revenue
long ll_row

// Pages of 25 rows past 100 rows ; the footer totals the page
uo_grid.ii_page_size = 25
uo_grid.il_page_threshold = 100
uo_grid.of_column(/*key*/ "revenue").is_summary = n_pbt_datagrid_column.SUMMARY_SUM

// The grand total of ALL the accounts, from the DataStore
for ll_row = 1 to ids.RowCount()
    ld_revenue = ld_revenue + ids.GetItemDecimal(ll_row, "revenue")
next
lnv_totals.of_set_number(/*path*/ "revenue", /*value*/ ld_revenue)
uo_grid.of_supply_grand_totals(/*values_json*/ lnv_totals.of_text())

Eine Quelle, die das Raster nie ganz hält #

Bei Hunderttausenden von Zeilen erfährt das Raster nur deren Anzahl und fordert die an, die es anzeigt. Hier liest Ihre Anwendung den angeforderten Ausschnitt aus der Datenbank; die Zeilennummern beginnen bei 1, wie die des DataStores.

// The grid only learns HOW MANY rows exist ; it asks for the ones on screen
uo_grid.of_open_source(/*total*/ ids.RowCount())

// ue_rows_needed event of uo_grid : (long al_from, long al_to)
// Rows al_from to al_to, both included, counted from 1 like the DataStore
n_pbt_json lnv_row
string ls_rows
long ll_row

// One JSON row per DataStore row asked for, its key being the row number
ls_rows = "["
for ll_row = al_from to Min(al_to, ids.RowCount())
    lnv_row.of_clear()
    lnv_row.of_set_string(/*path*/ "_k", /*value*/ String(ll_row))
    lnv_row.of_set_string(/*path*/ "city", /*value*/ ids.GetItemString(ll_row, "city"))
    lnv_row.of_set_string(/*path*/ "rep", /*value*/ ids.GetItemString(ll_row, "rep"))
    lnv_row.of_set_string(/*path*/ "trend", /*value*/ ids.GetItemString(ll_row, "trend"))
    lnv_row.of_set_number(/*path*/ "revenue", /*value*/ Double(ids.GetItemDecimal(ll_row, "revenue")))
    if ll_row > al_from then ls_rows = ls_rows + ","
    ls_rows = ls_rows + lnv_row.of_text()
next
uo_grid.of_supply_rows(/*from*/ al_from, /*rows_json*/ ls_rows + "]")

// ue_sort_changed event of uo_grid : (string as_col, string as_dir, string as_sort)
// as_sort is the whole sort, written as SetSort reads it ("" for none) :
// sort the source with it, the grid then asks for its rows again
ids.SetSort(as_sort)
ids.Sort()

Exportieren, was angezeigt wird #

// What is shown - filters, sort, visible columns - to a CSV file
uo_grid.of_export_csv(/*path*/ "C:\exports\accounts.csv")

// ue_csv_saved event of uo_grid : (string as_path, boolean ab_ok, string as_error)
if ab_ok then
    st_status.Text = "Written : " + as_path
else
    st_status.Text = as_error
end if

Ihre eigenen Einträge im Zeilenmenü #

// The row menu, entry by entry
uo_grid.of_add_row_menu_item(/*key*/ "open", /*label*/ "Open the account")
uo_grid.of_add_row_menu_separator()
uo_grid.of_add_row_menu_item(/*key*/ "call", /*label*/ "Call the sales rep")

// ue_row_menu_clicked event of uo_grid : (string as_menu_key, string as_row_key, string as_keys_json)
choose case as_menu_key
    case "open"
        wf_open_account(Long(as_row_key))
    case "call"
        wf_call(ids.GetItemString(Long(as_row_key), "rep"))
end choose

Auf die Auswahl reagieren #

// ue_selection_changed event of uo_grid : (string as_keys_json)
// '["3","7"]' : the RowIDs of the selected accounts (ids.GetRowFromRowId gives their rows)
cb_delete.Enabled = (Pos(as_keys_json, "[]") = 0)

Die Anordnung des Benutzers merken #

// ue_layout_changed event of uo_grid : (string as_layout_json)
// Order, widths, pins, hidden columns, sort, filters, grouping : keep it
SetProfileString(gs_ini, "grids", "accounts", as_layout_json)

// open event of the window, once the grid is filled : the layout of last time
uo_grid.of_set_layout(/*layout_json*/ ProfileString(gs_ini, "grids", "accounts", ""))

Best Practices #

• Rahmen Sie den Aufbau eines Rasters mit of_set_redraw(false) / of_set_redraw(true) ein: Die Spalten und die Zeilen erscheinen auf einen Schlag, ohne Flackern.
• Rufen Sie of_reset() auf, bevor Sie ein Raster neu aufbauen: Ohne ihn addieren sich die bereits durch of_add_column deklarierten Spalten zu den neuen.
• of_from_datastore gibt jeder Zeile ihre RowID als Schlüssel: Sie reist in jedem Event mit, und ids.GetRowFromRowId(Long(as_key)) findet die Zeile auch nach einer Sortierung oder einer Löschung im DataStore. Zeilen, die Sie selbst als JSON laden, tragen einen eindeutigen Schlüssel _k.
• Das Raster bearbeitet, Ihr DataStore speichert: ue_cell_edited → SetItem, dann Update(), wenn der Benutzer bestätigt. Die Komponente macht weder Update() noch Druck.
• Ab einigen Zehntausend Zeilen wechseln Sie in den Fenstermodus, statt alles zu übertragen: Der Speicher und die Öffnungszeit spüren es sofort.
• Sobald das Raster in Seiten aufteilt, ergänzen Sie die Seitensumme um ein of_supply_grand_totals: Ohne sie liest der Anwender eine Teilsumme dort, wo er die Gesamtsumme erwartet.
• Behalten Sie die Rich-Zellen den Spalten vor, die wirklich beim Lesen helfen: Drei Rich-Spalten von zwölf fangen das Auge, zwölf von zwölf ermüden es.
• Um auszuwerten und zu kreuzen statt aufzulisten, brauchen Sie crosstab.

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