datagrid — u_pbt_datagrid #

← Referência dos componentes · Índice do guia

A grelha moderna de um DataStore: colunas tipadas e células ricas, ordenação, filtros, agrupamento com subtotais, edição no próprio sítio, paginação, origem por janela e exportação CSV — o DataWindow continua a ser o dono dos seus dados.

▶ Ver ao vivo — Aplicação de demonstração, mosaico Data grid: a pré-visualização, o código que o produz e esta página, lado a lado.

Em resumo #

O posicionamento #

O datagrid não é um substituto da DataWindow: é uma camada de apresentação que se coloca por cima. O SQL, os Retrieve(), os Update() e as impressões mantêm-se — e ganha-se uma grelha moderna para a visualização.

Visa dois pontos cegos da grelha DataWindow clássica:

• a escalabilidade — apenas as linhas visíveis são efetivamente desenhadas, o deslocamento mantém-se fluido em dezenas de milhares de linhas, e o modo por janela suporta centenas de milhares de linhas;
• as células ricas — marca de estado colorida, barra de progresso, minicurva, classificação por estrelas, avatar, múltiplas etiquetas, botão de ação, ligação.

A ligação à base de dados e a atualização permanecem fora do âmbito: pertencem à DataWindow.

O DataStore dos exemplos #

Todos os exemplos desta página — como os da aplicação de demonstração — partem do mesmo DataStore de contas de clientes, uma linha por conta: city, rep (o comercial), status, pipeline (uma percentagem), trend (sete valores mensais escritos "3,5,2,6,7,4,8"), revenue e rating (uma nota em cinco). A grelha chama-se uo_grid na janela, o DataStore ids. Uma linha carregada por of_from_datastore tem como chave o seu RowID no DataStore: não muda quando o DataStore ordena, filtra, insere ou elimina. Um evento devolve-lho, e ids.GetRowFromRowId(Long(as_key)) é o número da linha que designa agora.

Um DataStore só contém valores simples, e isso chega para as células ricas: um número é tudo o que um indicador (RENDERER_PROGRESS) e as estrelas (RENDERER_RATING) precisam, um nome dá um avatar, um texto "3,5,2,6" um minigráfico (RENDERER_SPARKLINE) tal como "vip, b2b" dá etiquetas (RENDERER_TAGS); a cor de uma pastilha (RENDERER_CHIP) dá-se por valor com is_tones.

Início 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)))

Propriedades #

Propriedades de coluna #

Cada coluna é um objeto por direito próprio, obtido por of_column("identificador") — o handle é criado no primeiro acesso e permanece válido a seguir.

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

Devem utilizar-se sempre as constantes em vez das cadeias literais: o IDE completa-as e um erro de escrita torna-se impossível.

As constantes leem-se no objeto que as transporta: u_pbt_datagrid.SELECT_MULTIPLE para uma propriedade do componente, n_pbt_datagrid_column.PIN_START para uma propriedade de coluna.

Métodos #

Alimentar a grelha #

Colunas #

Ordenação, filtro, apresentação #

Seleção, detalhe, exportação #

Volumes muito grandes #

Comuns #

Eventos #

O que o utilizador pode fazer sem uma linha de código #

A grelha integra a sua própria barra de ferramentas e os seus menus de cabeçalho. Nada disto exige código da sua parte:

• ordenar clicando num cabeçalho: crescente, decrescente, nenhum — só por essa coluna; Shift+clique acrescenta-a à ordenação depois das outras (se já lá está, passa-a de crescente a decrescente e depois retira-a), e cada seta mostra então a sua ordem (1 decide, 2 desempata…);
• filtrar rapidamente pela zona de pesquisa, ou coluna a coluna pelo botão Filtros, que apresenta uma linha de introdução sob os cabeçalhos;
• escolher as colunas visíveis pelo botão Colunas;
• redimensionar uma coluna arrastando a margem do respetivo cabeçalho;
• reordenar as colunas arrastando o respetivo cabeçalho;
• fixar ou ocultar uma coluna através do menu de contexto do respetivo cabeçalho;
• selecionar uma linha, um intervalo (Shift) ou um conjunto (Ctrl);
• agir sobre uma linha através do respetivo menu de contexto: copiar, selecionar tudo, limpar a seleção, exportar para CSV — e as entradas que lhe acrescentar.

Cada alteração da disposição volta em ue_layout_changed: larguras, ordem, colunas fixadas ou ocultas. Guarde-a e devolva-a com uma única chamada a of_set_layout na próxima abertura; of_get_layout relê-a a qualquer momento.

No teclado — a grelha é uma única paragem de tabulação. Uma vez alcançada, percorre-se inteiramente pelo teclado:

A célula com o foco é contornada por um filete da cor de destaque e anunciada aos leitores de ecrã através de aria-activedescendant. O foco sobrevive ao deslocamento: sendo a grelha virtualizada, é mantido em memória e reposto após cada renderização. Desaparece, no entanto, se a sua linha sair da vista por uma ordenação ou um filtro.

⚠️ A área de transferência do navegador pode ser recusada numa WebView alojada. É por isso que ue_copy lhe devolve o texto: coloque-o você mesmo com ClipBoard(as_tsv) para ter a certeza do resultado.

Exemplos #

Contas de clientes em poucas linhas #

// 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 e depois por cidade #

// 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 a partir do seu 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 várias colunas #

A ordenação escreve-se como a de um DataWindow: a primeira coluna decide, as seguintes desempatam. O utilizador faz o mesmo com o rato com Shift+clique nos cabeçalhos; um clique simples recomeça a partir de uma só coluna.

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

O que a grelha lê na DataWindow #

of_from_datastore não leva só os dados: o texto de cabeçalho de cada coluna (<coluna>_t) torna-se o seu título, o seu formato de apresentação (Format, ou a máscara de um EditMask) aplica-se, e uma tabela de códigos — os Values de um Edit, de uma DDLB ou de botões de opção, uma DropDown DataWindow, uma CheckBox — mostra o valor apresentado (Active) enquanto a linha mantém o dado (A). Ordena-se e pesquisa-se sobre o que se vê; uma coluna com tabela de códigos edita-se através de uma lista, e volta o dado.

// 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 no próprio sítio, gravar no DataStore #

A grelha edita, o DataStore guarda a verdade: com ib_write_back, cada introdução é escrita nele na linha que a chave designa (o seu RowID, encontrado onde está), tipada pela coluna, antes de ue_cell_edited — e o indicador acompanha. Uma célula modificada mantém um pequeno canto na cor de destaque até 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

Uma coluna booleana tornada editável (TYPE_BOOL, ou uma coluna CheckBox de um DataWindow lida por of_from_datastore) mostra uma verdadeira caixa de verificação em cada célula: um clique, Espaço, Enter ou F2 inverte-a de imediato — sem editor de texto, e um duplo clique não a inverte duas vezes. A célula recebe o valor do outro estado — true/false, ou os valores ON/OFF da CheckBox do DataWindow — pelo mesmo caminho que uma introdução: veto ib_veto_edits / ue_cell_editing, depois ue_cell_edited, marca «modificada» e ib_write_back. Só de leitura, uma coluna booleana mantém o seu visto ✓.

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

Uma linha expansível, escrita a partir do 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 em vez de um deslocamento, e o total de tudo #

Uma vez paginada, a grelha só contém uma página: o seu rodapé totaliza a página. O total de todas as contas é o DataStore que o tem.

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

Uma origem que a grelha nunca contém inteira #

Para centenas de milhares de linhas, a grelha só conhece o seu número e pede as que mostra. É aqui que a sua aplicação lê da base de dados a fatia pedida; os números de linha começam em 1, como os do 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 o que é mostrado #

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

As suas entradas no menu de linha #

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

Reagir à seleção #

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

Lembrar a disposição do utilizador #

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

Boas práticas #

• Enquadre a construção de uma grelha com of_set_redraw(false) / of_set_redraw(true): as colunas e as linhas aparecem de uma só vez, sem cintilação.
• Chame of_reset() antes de reconstruir uma grelha: sem ele, as colunas já declaradas por of_add_column acrescentam-se às novas.
• of_from_datastore dá a cada linha o seu RowID como chave: é ele que viaja em todos os eventos, e ids.GetRowFromRowId(Long(as_key)) encontra a linha mesmo após uma ordenação ou uma eliminação no DataStore. As linhas que carrega em JSON levam uma chave _k distinta.
• A grelha edita, o seu DataStore grava: ue_cell_edited → SetItem, depois Update() quando o utilizador confirma. O componente não faz nem Update() nem impressão.
• Para além de algumas dezenas de milhares de linhas, é preferível passar ao modo por janela em vez de transferir tudo: a memória e o tempo de abertura ressentem-se de imediato.
• Assim que a grelha pagina, acompanhe o total de página com um of_supply_grand_totals: sem ele, o utilizador lê um total parcial onde espera o total de tudo.
• Reserve as células ricas para as colunas que ajudam realmente a ler: três colunas ricas em doze prendem o olhar, doze em doze cansam-no.
• Para analisar e cruzar em vez de listar, o adequado é crosstab.

Herdado da base comum #

Estes membros existem em todos os componentes visuais — não são próprios deste. São detalhados uma só vez, nos capítulos transversais; esta tabela apenas diz onde os ler.

Duas ajudas não são herdadas: of_icon e of_escape_markup vivem em n_pbt_utils. Declare um — n_pbt_utils lnv_utils, nada a criar — e chame-as nele.

← Referência dos componentes · Índice do guia