datagrid — u_pbt_datagrid #

← Referencia de componentes · Índice de la guía

La cuadrícula moderna de un DataStore: columnas tipadas y celdas enriquecidas, ordenación, filtros, agrupación con subtotales, edición en el sitio, paginación, origen por ventana y exportación CSV — el DataWindow sigue siendo el dueño de sus datos.

▶ Verlo en vivo — Aplicación de demostración, mosaico Data grid: la vista previa, el código que lo genera y esta página, uno al lado del otro.

De un vistazo #

El posicionamiento #

El datagrid no sustituye a la DataWindow: es una capa de presentación que se coloca encima. Usted conserva su SQL, sus Retrieve(), sus Update(), sus impresiones — y gana una cuadrícula moderna para la visualización.

Cubre dos puntos ciegos de la cuadrícula DataWindow clásica:

• la escalabilidad — solo se dibujan realmente las filas visibles, el desplazamiento se mantiene fluido con decenas de miles de filas y el modo con ventana soporta cientos de miles de filas;
• las celdas enriquecidas — distintivo de estado coloreado, indicador, minigráfico, valoración con estrellas, avatar, etiquetas múltiples, botón de acción, enlace.

La conexión a la base de datos y la actualización quedan fuera del alcance: pertenecen a la DataWindow.

El DataStore de los ejemplos #

Todos los ejemplos de esta página — como los de la aplicación de demostración — parten del mismo DataStore de cuentas de clientes, una fila por cuenta: city, rep (el comercial), status, pipeline (un porcentaje), trend (siete cifras mensuales escritas "3,5,2,6,7,4,8"), revenue y rating (una nota sobre cinco). La cuadrícula se llama uo_grid en la ventana, el DataStore ids. Una fila cargada por of_from_datastore tiene como clave su RowID en el DataStore: no cambia cuando el DataStore ordena, filtra, inserta o elimina. Un evento se lo devuelve, e ids.GetRowFromRowId(Long(as_key)) es el número de la fila que designa ahora.

Un DataStore solo contiene valores simples, y basta para las celdas enriquecidas: un número es todo lo que necesitan un indicador (RENDERER_PROGRESS) y las estrellas (RENDERER_RATING), un nombre da un avatar, un texto "3,5,2,6" un minigráfico (RENDERER_SPARKLINE) igual que "vip, b2b" da etiquetas (RENDERER_TAGS); el color de una pastilla (RENDERER_CHIP) se da por valor con is_tones.

Inicio rápido #

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

Propiedades #

Propiedades de columna #

Cada columna es un objeto en sí misma, obtenido mediante of_column("identificador") — el handle se crea en el primer acceso y sigue siendo válido después.

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

Utilice siempre las constantes en lugar de las cadenas literales: el IDE las completa y una errata resulta imposible.

Las constantes se leen en el objeto que las lleva: u_pbt_datagrid.SELECT_MULTIPLE para una propiedad del componente, n_pbt_datagrid_column.PIN_START para una propiedad de columna.

Métodos #

Alimentar la cuadrícula #

Columnas #

Ordenación, filtro, presentación #

Selección, detalle, exportación #

Volúmenes muy grandes #

Comunes #

Eventos #

Lo que el usuario puede hacer sin una línea de código #

La cuadrícula incorpora su propia barra de herramientas y sus menús de encabezado. Nada de todo esto exige código por su parte:

• ordenar haciendo clic en un encabezado: ascendente, descendente, ninguno — solo por esa columna; Mayús+clic la añade a la ordenación tras las demás (si ya está, la pasa de ascendente a descendente y luego la quita), y cada flecha lleva entonces su rango (1 decide, 2 desempata…);
• filtrar rápidamente mediante la zona de búsqueda, o columna por columna mediante el botón Filtros, que muestra una fila de entrada bajo los encabezados;
• elegir las columnas visibles mediante el botón Columnas;
• redimensionar una columna arrastrando el borde de su encabezado;
• reordenar las columnas arrastrando su encabezado;
• fijar u ocultar una columna mediante el menú contextual de su encabezado;
• seleccionar una fila, un intervalo (Mayús) o un conjunto (Ctrl);
• actuar sobre una fila mediante su menú contextual: copiar, seleccionar todo, borrar la selección, exportar a CSV — y las entradas que usted le añada.

Cada cambio de disposición vuelve en ue_layout_changed: anchos, orden, columnas fijadas u ocultas. Consérvelo y devuélvalo con una sola llamada a of_set_layout en la próxima apertura; of_get_layout lo relee en cualquier momento.

Con el teclado — la cuadrícula es una única parada de tabulación. Una vez alcanzada, se recorre enteramente con el teclado:

La celda con el foco está rodeada por un filete del color de acento y se anuncia a los lectores de pantalla mediante aria-activedescendant. El foco sobrevive al desplazamiento: al estar la cuadrícula virtualizada, se mantiene en memoria y se vuelve a colocar tras cada renderizado. En cambio, desaparece si su fila sale de la vista por una ordenación o un filtro.

⚠️ El portapapeles del navegador puede ser rechazado en una WebView alojada. Por eso ue_copy le devuelve el texto: colóquelo usted mismo con ClipBoard(as_tsv) para estar seguro del resultado.

Ejemplos #

Cuentas de clientes en pocas líneas #

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

Agrupar por estado y luego por ciudad #

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

Filtrar desde su código #

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

Ordenar por varias columnas #

La ordenación se escribe como la de un DataWindow: la primera columna decide, las siguientes desempatan. El usuario hace lo mismo con el ratón con Mayús+clic en los encabezados; un clic simple vuelve a empezar desde una sola columna.

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

Lo que la cuadrícula lee en la DataWindow #

of_from_datastore no toma solo los datos: el texto de encabezado de cada columna (<columna>_t) se convierte en su título, su formato de visualización (Format, o la máscara de un EditMask) se aplica, y una tabla de códigos — los Values de un Edit, de una DDLB o de botones de opción, una DropDown DataWindow, una CheckBox — muestra el valor visible (Active) mientras la fila conserva el dato (A). Se ordena y se busca sobre lo que se ve; una columna con tabla de códigos se edita mediante una lista, y vuelve el 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)

Editar en el sitio, guardar en el DataStore #

La cuadrícula edita, el DataStore guarda la verdad: con ib_write_back, cada entrada se escribe en él en la fila que la clave designa (su RowID, encontrado donde está), tipada por la columna, antes de ue_cell_edited — y el indicador lo sigue. Una celda modificada conserva una pequeña esquina en el color de acento hasta 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 columna booleana hecha editable (TYPE_BOOL, o una columna CheckBox de un DataWindow leída por of_from_datastore) muestra una verdadera casilla de verificación en cada celda: un clic, Espacio, Intro o F2 la invierte al instante — sin editor de texto, y un doble clic no la invierte dos veces. La celda recibe el valor del otro estado — true/false, o los valores ON/OFF de la CheckBox del DataWindow — por el mismo camino que una entrada: veto ib_veto_edits / ue_cell_editing, luego ue_cell_edited, marca «modificada» e ib_write_back. En solo lectura, una columna booleana conserva su marca ✓.

// 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 fila desplegable, escrita desde el 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")

Páginas en lugar de un desplazamiento, y el total de todo #

Una vez paginada, la cuadrícula solo contiene una página: su pie totaliza la página. El total de todas las cuentas lo tiene el 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())

Un origen que la cuadrícula nunca tiene entero #

Para cientos de miles de filas, la cuadrícula solo conoce su número y pide las que muestra. Es aquí donde su aplicación lee de la base el tramo pedido; los números de fila empiezan en 1, como los 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()

Exportar lo que se muestra #

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

Sus propias entradas en el menú de fila #

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

Reaccionar a la selección #

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

Recordar la disposición del usuario #

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

Buenas prácticas #

• Enmarque la construcción de una cuadrícula con of_set_redraw(false) / of_set_redraw(true): las columnas y las filas aparecen de una sola vez, sin parpadeo.
• Llame a of_reset() antes de reconstruir una cuadrícula: sin él, las columnas ya declaradas por of_add_column se añaden a las nuevas.
• of_from_datastore da a cada fila su RowID como clave: es él el que viaja en todos los eventos, e ids.GetRowFromRowId(Long(as_key)) encuentra la fila incluso tras una ordenación o una eliminación en el DataStore. Las filas que usted carga en JSON llevan una clave _k distinta.
• La cuadrícula edita, su DataStore guarda: ue_cell_edited → SetItem, y luego Update() cuando el usuario confirma. El componente no hace ni Update() ni impresión.
• Más allá de algunas decenas de miles de filas, pase al modo con ventana en lugar de transferirlo todo: la memoria y el tiempo de apertura lo notan de inmediato.
• En cuanto la cuadrícula pagina, acompañe el total de página con un of_supply_grand_totals: sin él, el usuario lee un total parcial allí donde espera el total de todo.
• Reserve las celdas enriquecidas para las columnas que realmente ayudan a leer: tres columnas enriquecidas de doce captan la mirada, doce de doce la fatigan.
• Para analizar y cruzar en lugar de listar, es crosstab lo que necesita.

Heredado de la base común #

Estos miembros existen en todos los componentes visuales — no son propios de este. Se detallan una sola vez, en los capítulos transversales; esta tabla solo dice dónde leerlos.

Dos ayudas no se heredan: of_icon y of_escape_markup viven en n_pbt_utils. Declare uno — n_pbt_utils lnv_utils, nada que crear — y llámelas sobre él.

← Referencia de componentes · Índice de la guía