datagrid — u_pbt_datagrid #

← Riferimento dei componenti · Sommario della guida

La griglia moderna di un DataStore: colonne tipizzate e celle ricche, ordinamento, filtri, raggruppamento con subtotali, modifica sul posto, paginazione, sorgente a finestra ed esportazione CSV — il DataWindow resta il padrone dei suoi dati.

▶ Vederlo dal vivo — Applicazione dimostrativa, riquadro Data grid: l'anteprima, il codice che lo produce e questa pagina, affiancati.

In breve #

Il posizionamento #

Il datagrid non sostituisce la DataWindow: è uno strato di presentazione che si sovrappone ad essa. Lei mantiene il Suo SQL, i Suoi Retrieve(), i Suoi Update(), le Sue stampe — e guadagna una griglia moderna per la visualizzazione.

Punta a due punti ciechi della griglia DataWindow classica:

• la scalabilità — vengono realmente disegnate solo le righe visibili, lo scorrimento resta fluido su decine di migliaia di righe e la modalità a finestra regge centinaia di migliaia di righe;
• le celle ricche — chip di stato colorato, indicatore, mini-curva, valutazione a stelle, avatar, tag multipli, pulsante d'azione, collegamento.

Il collegamento alla base dati e l'aggiornamento restano fuori perimetro: appartengono alla DataWindow.

Il DataStore degli esempi #

Tutti gli esempi di questa pagina — come quelli dell'applicazione dimostrativa — partono dallo stesso DataStore di conti clienti, una riga per conto: city, rep (il commerciale), status, pipeline (una percentuale), trend (sette cifre mensili scritte "3,5,2,6,7,4,8"), revenue e rating (un voto su cinque). La griglia si chiama uo_grid nella finestra, il DataStore ids. Una riga caricata da of_from_datastore ha come chiave il suo RowID nel DataStore: non cambia quando il DataStore ordina, filtra, inserisce o elimina. Un event glielo restituisce, e ids.GetRowFromRowId(Long(as_key)) è il numero della riga che designa adesso.

Un DataStore contiene solo valori semplici, e basta per le celle ricche: un numero è tutto ciò che serve a un indicatore (RENDERER_PROGRESS) e alle stelle (RENDERER_RATING), un nome dà un avatar, un testo "3,5,2,6" un mini grafico (RENDERER_SPARKLINE) come "vip, b2b" delle etichette (RENDERER_TAGS); il colore di un chip (RENDERER_CHIP) si dà per valore con is_tones.

Avvio rapido #

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

Proprietà #

Proprietà di colonna #

Ogni colonna è un oggetto a sé stante, ottenuto con of_column("identificatore") — l'handle viene creato al primo accesso e resta valido in seguito.

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

Costanti #

Usi sempre le costanti anziché le stringhe letterali: l'IDE le completa e un errore di battitura diventa impossibile.

Le costanti si leggono sull'oggetto che le porta: u_pbt_datagrid.SELECT_MULTIPLE per una proprietà del componente, n_pbt_datagrid_column.PIN_START per una proprietà di colonna.

Metodi #

Alimentare la griglia #

Colonne #

Ordinamento, filtro, presentazione #

Selezione, dettaglio, esportazione #

Volumi molto grandi #

Comuni #

Event #

Ciò che l'utente può fare senza una riga di codice #

La griglia integra la propria barra degli strumenti e i propri menu d'intestazione. Nulla di tutto questo richiede codice da parte Sua:

• ordinare facendo clic su un'intestazione: crescente, decrescente, nessuno — su quella sola colonna; Maiusc+clic la aggiunge all'ordinamento dopo le altre (se c'è già, la passa da crescente a decrescente, poi la toglie), e ogni freccia porta allora il suo rango (1 decide, 2 risolve le parità…);
• filtrare rapidamente tramite la casella di ricerca, oppure colonna per colonna tramite il pulsante Filtri, che mostra una riga di immissione sotto le intestazioni;
• scegliere le colonne visibili tramite il pulsante Colonne;
• ridimensionare una colonna trascinando il bordo della sua intestazione;
• riordinare le colonne trascinandone l'intestazione;
• bloccare o nascondere una colonna tramite il menu contestuale della sua intestazione;
• selezionare una riga, un intervallo (Maiusc) o un insieme (Ctrl);
• agire su una riga tramite il suo menu contestuale: copiare, selezionare tutto, cancellare la selezione, esportare in CSV — e le voci che vi aggiunge.

Ogni modifica della disposizione ritorna in ue_layout_changed: larghezze, ordine, colonne bloccate o nascoste. La conservi, e la restituisca con una sola chiamata a of_set_layout alla prossima apertura; of_get_layout la rilegge in qualsiasi momento.

Da tastiera — la griglia è un unico punto di tabulazione. Una volta raggiunta, la si percorre interamente da tastiera:

La cella con il fuoco è contornata dal colore d'accento e annunciata ai lettori di schermo tramite aria-activedescendant. Il fuoco sopravvive allo scorrimento: essendo la griglia virtualizzata, viene tenuto in memoria e riposato dopo ogni rendering. Scompare invece se la sua riga esce dalla vista per un ordinamento o un filtro.

⚠️ Gli appunti del browser possono essere rifiutati in una WebView ospitata. È per questo che ue_copy vi restituisce il testo: mettetelo voi stessi con ClipBoard(as_tsv) per essere certi del risultato.

Esempi #

Conti clienti in poche righe #

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

Raggruppare per stato, poi per città #

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

Filtrare dal suo codice #

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

Ordinare su più colonne #

L'ordinamento si scrive come quello di un DataWindow: la prima colonna decide, le successive risolvono le parità. L'utente fa lo stesso con il mouse con Maiusc+clic sulle intestazioni; un clic semplice riparte da una sola colonna.

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

Ciò che la griglia legge nella DataWindow #

of_from_datastore non prende solo i dati: il testo d'intestazione di ogni colonna (<colonna>_t) diventa il suo titolo, il suo formato di visualizzazione (Format, o la maschera di un EditMask) si applica, e una tabella di codici — i Values di un Edit, di una DDLB o di pulsanti radio, una DropDown DataWindow, una CheckBox — mostra il valore visualizzato (Active) mentre la riga conserva il dato (A). Si ordina e si cerca su ciò che si vede; una colonna con tabella di codici si modifica tramite un elenco, e torna il dato.

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

Modificare sul posto, salvare nel DataStore #

La griglia modifica, il DataStore custodisce la verità: con ib_write_back, ogni immissione vi è scritta sulla riga che la chiave designa (il suo RowID, ritrovato dov'è), tipizzata dalla colonna, prima di ue_cell_edited — e l'indicatore segue. Una cella modificata conserva un piccolo angolo nel colore d'accento fino a 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

Una colonna booleana resa modificabile (TYPE_BOOL, o una colonna CheckBox di un DataWindow letta da of_from_datastore) mostra una vera casella di controllo in ogni cella: un clic, Spazio, Invio o F2 la inverte subito — nessun editor di testo, e un doppio clic non la inverte due volte. La cella riceve il valore dell'altro stato — true/false, o i valori ON/OFF della CheckBox del DataWindow — per la stessa via di un'immissione: veto ib_veto_edits / ue_cell_editing, poi ue_cell_edited, marca «modificata» e ib_write_back. In sola lettura, una colonna booleana conserva il suo segno ✓.

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

Una riga espandibile, scritta dal DataStore #

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

Pagine invece di uno scorrimento, e il totale di tutto #

Una volta paginata, la griglia contiene una sola pagina: il suo piede totalizza la pagina. Il totale di tutti i conti ce l'ha il 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())

Una sorgente che la griglia non tiene mai per intero #

Per centinaia di migliaia di righe, la griglia ne conosce solo il numero e richiede quelle che mostra. È qui che la sua applicazione legge dalla base la porzione richiesta; i numeri di riga partono da 1, come quelli del DataStore.

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

Esportare ciò che è mostrato #

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

Le sue voci nel menu di riga #

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

Reagire alla selezione #

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

Ricordare la disposizione dell'utente #

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

Buone pratiche #

• Racchiuda la costruzione di una griglia tra of_set_redraw(false) / of_set_redraw(true): le colonne e le righe compaiono in una sola volta, senza sfarfallio.
• Chiami of_reset() prima di ricostruire una griglia: senza di esso, le colonne già dichiarate da of_add_column si aggiungono a quelle nuove.
• of_from_datastore dà a ogni riga il suo RowID come chiave: è lui che viaggia in tutti gli event, e ids.GetRowFromRowId(Long(as_key)) ritrova la riga anche dopo un ordinamento o un'eliminazione nel DataStore. Le righe che carica Lei stesso in JSON portano una chiave _k distinta.
• La griglia modifica, il suo DataStore salva: ue_cell_edited → SetItem, poi Update() quando l'utente conferma. Il componente non fa né Update() né stampa.
• Oltre alcune decine di migliaia di righe, passi alla modalità a finestra anziché trasferire tutto: la memoria e il tempo di apertura ne risentono immediatamente.
• Non appena la griglia pagina, accompagni il totale di pagina con un of_supply_grand_totals: senza di esso, l'utente legge un totale parziale là dove si aspetta il totale complessivo.
• Riservi le celle ricche alle colonne che aiutano davvero a leggere: tre colonne ricche su dodici catturano l'occhio, dodici su dodici lo affaticano.
• Per analizzare e incrociare anziché elencare, è crosstab che Le serve.

Ereditato dalla base comune #

Questi membri esistono su tutti i componenti visivi — non sono propri di questo. Sono descritti una sola volta, nei capitoli trasversali; questa tabella dice solo dove leggerli.

Due aiuti non sono ereditati: of_icon e of_escape_markup vivono su n_pbt_utils. Ne dichiari uno — n_pbt_utils lnv_utils, niente da creare — e li chiami su di esso.

← Riferimento dei componenti · Sommario della guida