datagrid — u_pbt_datagrid #

← Référence des composants · Sommaire du guide

La grille moderne d'un DataStore : colonnes typées et cellules riches, tri, filtres, regroupement avec sous-totaux, édition sur place, pagination, source fenêtrée et export CSV — la DataWindow reste le maître de vos données.

▶ Le voir en vrai — Application de démonstration, tuile Data grid : l'aperçu, le code qui le produit et cette page, côte à côte.

En bref #

Le positionnement #

Le datagrid n'est pas un remplaçant de la DataWindow : c'est une couche de présentation qui se pose par-dessus. Vous gardez votre SQL, vos Retrieve(), vos Update(), vos impressions — et vous gagnez une grille moderne pour l'affichage.

Il vise deux angles morts de la grille DataWindow classique :

• le passage à l'échelle — seules les lignes visibles sont réellement dessinées, le défilement reste fluide sur des dizaines de milliers de lignes, et le mode fenêtré tient des centaines de milliers de lignes ;
• les cellules riches — jeton de statut coloré, jauge, mini-courbe, notation par étoiles, avatar, jetons multiples, bouton d'action, lien.

La liaison à la base de données et la mise à jour restent hors périmètre : elles appartiennent à la DataWindow.

Le DataStore des exemples #

Tous les exemples de cette page — comme ceux de l'application de démonstration — partent du même DataStore de comptes clients, une ligne par compte : city, rep (le commercial), status, pipeline (un pourcentage), trend (sept chiffres mensuels écrits "3,5,2,6,7,4,8"), revenue et rating (une note sur cinq). La grille s'appelle uo_grid sur la fenêtre, le DataStore ids. Une ligne chargée par of_from_datastore a pour clé son RowID dans le DataStore : il ne bouge ni quand le DataStore trie, filtre, insère ou supprime. Un event vous le rend, et ids.GetRowFromRowId(Long(as_key)) est le numéro de la ligne qu'il désigne maintenant.

Un DataStore ne porte que des valeurs simples, et c'est assez pour les cellules riches : un nombre suffit à une jauge (RENDERER_PROGRESS) et à des étoiles (RENDERER_RATING), un nom à un avatar, un texte "3,5,2,6" à un mini-graphe (RENDERER_SPARKLINE) comme "vip, b2b" à des étiquettes (RENDERER_TAGS) ; la couleur d'une pastille (RENDERER_CHIP) se donne par valeur avec is_tones.

Démarrage rapide #

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

Propriétés #

Propriétés de colonne #

Chaque colonne est un objet à part entière, obtenu par of_column("identifiant") — le handle est créé au premier accès et reste valable ensuite.

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

Constantes #

Utilisez toujours les constantes plutôt que les chaînes littérales : l'IDE les complète et une faute de frappe devient impossible.

Les constantes se lisent sur l'objet qui les porte : u_pbt_datagrid.SELECT_MULTIPLE pour une propriété du composant, n_pbt_datagrid_column.PIN_START pour une propriété de colonne.

Méthodes #

Alimenter la grille #

Colonnes #

Tri, filtre, présentation #

Sélection, détail, export #

Très gros volumes #

Communes #

Événements #

Ce que l'utilisateur peut faire sans une ligne de code #

La grille embarque sa propre barre d'outils et ses menus d'en-tête. Rien de tout cela ne demande de code de votre part :

• trier en cliquant un en-tête : croissant, décroissant, aucun — sur cette colonne seule ; Maj+clic l'ajoute au tri après les autres (déjà dedans, la passe de croissant à décroissant, puis la retire), et chaque flèche porte alors son rang (1 décide, 2 départage…) ;
• filtrer rapidement par la zone de recherche, ou colonne par colonne par le bouton Filtres, qui affiche une ligne de saisie sous les en-têtes ;
• choisir les colonnes visibles par le bouton Colonnes ;
• redimensionner une colonne en tirant le bord de son en-tête ;
• réordonner les colonnes en faisant glisser leur en-tête ;
• figer ou masquer une colonne par le menu contextuel de son en-tête ;
• sélectionner une ligne, une plage (Maj) ou un ensemble (Ctrl) ;
• agir sur une ligne par son menu contextuel : copier, tout sélectionner, effacer la sélection, exporter en CSV — et les entrées que vous y ajoutez.

Toute modification de disposition remonte dans ue_layout_changed : largeurs, ordre, colonnes figées ou masquées. Conservez ce contenu, et rendez-le d'un seul appel à of_set_layout à la prochaine ouverture ; of_get_layout le relit à tout moment.

Au clavier — la grille est un seul arrêt de tabulation. Une fois atteinte, elle se parcourt entièrement au clavier :

La cellule focalisée est entourée d'un liseré à la couleur d'accent, et annoncée aux lecteurs d'écran par aria-activedescendant. Le focus survit au défilement : la grille étant virtualisée, il est tenu en mémoire et reposé après chaque rendu. Il disparaît en revanche si sa ligne sort de la vue par un tri ou un filtre.

⚠️ Le presse-papiers du navigateur peut être refusé dans une WebView hébergée. C'est pour cette raison que ue_copy vous remet le texte : posez-le vous-même avec ClipBoard(as_tsv) pour être certain du résultat.

Exemples #

Des comptes clients en quelques lignes #

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

Regrouper par statut, puis par ville #

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

Filtrer depuis votre code #

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

Trier sur plusieurs colonnes #

Le tri s'écrit comme celui d'un DataWindow : la première colonne décide, les suivantes départagent. L'utilisateur fait de même à la souris par Maj+clic sur les en-têtes ; un clic simple repart d'une seule colonne.

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

Ce que la grille lit dans le DataWindow #

of_from_datastore ne prend pas que les données : le texte d'en-tête de chaque colonne (<colonne>_t) devient son titre, son format d'affichage (Format, ou le masque d'un EditMask) s'applique, et une liste de codes — Values d'un Edit, d'une DDLB ou de boutons radio, DropDown DataWindow, CheckBox — montre la valeur affichée (Active) quand la ligne garde la donnée (A). On trie et on cherche sur ce qu'on voit ; une colonne à liste s'édite par une liste, et c'est la donnée qui revient.

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

Modifier sur place, enregistrer dans le DataStore #

La grille modifie, le DataStore garde la vérité : avec ib_write_back, chaque saisie y est écrite sur la ligne que la clé désigne (son RowID, retrouvé où elle est), typée par la colonne, avant ue_cell_edited — et la jauge suit. Une cellule modifiée garde un petit coin dans l'accent jusqu'à 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

Une colonne booléenne rendue éditable (TYPE_BOOL, ou une colonne CheckBox d'un DataWindow lue par of_from_datastore) montre une vraie case à cocher dans chaque cellule : un clic, Espace, Entrée ou F2 la retourne aussitôt — pas d'éditeur de texte, et un double-clic ne la retourne pas deux fois. La cellule reçoit la valeur de l'autre état — true/false, ou les valeurs ON/OFF de la CheckBox du DataWindow — par le même chemin qu'une saisie : véto ib_veto_edits / ue_cell_editing, puis ue_cell_edited, marque « modifiée » et ib_write_back. En lecture seule, une colonne booléenne garde sa coche ✓.

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

Une ligne dépliable, écrite depuis le 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")

Des pages plutôt qu'un défilement, et le total de tout #

Une fois paginée, la grille ne tient qu'une page : son pied totalise la page. Le total de tous les comptes, c'est le DataStore qui l'a.

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

Une source que la grille ne tient jamais entière #

Pour des centaines de milliers de lignes, la grille n'apprend que leur nombre et réclame celles qu'elle affiche. C'est ici que votre application lit la tranche demandée en base ; les numéros de ligne partent de 1, comme ceux du 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()

Exporter ce qui est affiché #

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

Vos entrées dans le menu de ligne #

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

Réagir à la sélection #

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

Retenir la disposition de l'utilisateur #

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

Bonnes pratiques #

• Encadrez la construction d'une grille par of_set_redraw(false) / of_set_redraw(true) : les colonnes et les lignes apparaissent d'un seul coup, sans clignotement.
• Appelez of_reset() avant de reconstruire une grille : sans lui, les colonnes déjà déclarées par of_add_column s'ajoutent aux nouvelles.
• of_from_datastore donne à chaque ligne son RowID pour clé : c'est lui qui voyage dans tous les events, et ids.GetRowFromRowId(Long(as_key)) retrouve la ligne même après un tri ou une suppression dans le DataStore. Les lignes que vous chargez vous-même en JSON portent une clé _k distincte.
• La grille modifie, votre DataStore enregistre : ue_cell_edited → SetItem, puis Update() quand l'utilisateur valide. Le composant ne fait ni Update(), ni impression.
• Au-delà de quelques dizaines de milliers de lignes, passez en mode fenêtré plutôt que de tout transférer : la mémoire et le temps d'ouverture s'en ressentent immédiatement.
• Dès que la grille pagine, accompagnez le total de page d'un of_supply_grand_totals : sans lui, l'utilisateur lit un total partiel là où il attend le total de tout.
• Réservez les cellules riches aux colonnes qui aident vraiment à lire : trois colonnes riches sur douze accrochent l'œil, douze sur douze le fatiguent.
• Pour analyser et croiser plutôt que lister, c'est crosstab qu'il vous faut.

Hérité du socle commun #

Ces membres existent sur tous les composants visuels — ils ne sont pas propres à celui-ci. Ils sont détaillés une seule fois, dans les chapitres transverses ; cette table dit seulement où les lire.

Deux aides ne sont pas héritées : of_icon et of_escape_markup vivent sur n_pbt_utils. Déclarez-en une — n_pbt_utils lnv_utils, rien à créer — et appelez-les dessus.

← Référence des composants · Sommaire du guide