crosstab — u_pbt_crosstab #

← Referência dos componentes · Índice do guia

Tabela dinâmica completa: zonas de linhas / colunas / valores alimentadas a partir de um DataStore, agregações, filtros, formatação condicional, agrupamento de datas, medidas calculadas e exportações CSV / Excel.

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

Em resumo #

O princípio #

O componente recebe um conjunto de dados plano — um DataStore, ou seja, qualquer consulta já escrita na aplicação. O crosstab trata do resto: deduz a lista dos campos, que devem ser distribuídos por quatro zonas.

Todo o cálculo é feito no componente: uma vez transmitidos os dados, reorganizar a tabela não desencadeia qualquer ida e volta à base de dados nem ao PowerBuilder.

Início rápido #

// event open de la fenetre
// Local variables
datastore lds
lds = create datastore
lds.dataobject = "d_sales"
lds.SetTransObject(SQLCA)
lds.Retrieve()

// 1. Transmitir os dados: os campos sao deduzidos das colunas
uo_crosstab.of_from_datastore(/*ads*/ lds)

// 2. Distribuir os campos pelas zonas
uo_crosstab.of_add_row_field(/*field*/ "region")
uo_crosstab.of_add_col_field(/*field*/ "year")
uo_crosstab.of_add_value_field(/*field*/ "amount", /*agg*/ uo_crosstab.AGG_SUM)

// 3. Apresentar: formato dos montantes e totais gerais
uo_crosstab.of_field(/*field*/ "amount").is_format = "$#,##0"
uo_crosstab.ib_row_grand_total = true
uo_crosstab.ib_col_grand_total = true

// event ue_cell_double_clicked de uo_crosstab : (string as_row_tuple_json, string as_col_tuple_json, integer ai_measure, double ad_value)
// O utilizador quer o detalhe por tras de um numero: abrir a lista correspondente.
of_open_detail(as_row_tuple_json, as_col_tuple_json)

Constantes #

As constantes de agregação, de filtro, de data e de separador leem-se no componente: uo_crosstab.AGG_SUM. As de um campo ou de um valor (SHOW_*, CF_*) leem-se na classe do seu handle: n_pbt_crosstab_field.CF_SCALE, n_pbt_crosstab_value.SHOW_PCT_GRAND. AGG_COUNT conta os valores não vazios, como a Contagem do Excel; AGG_COUNT_ROWS conta as linhas, vazias incluídas.

Propriedades #

Propriedades de um campo #

of_field (string as_field) devolve o handle de um campo: obtém-se uma vez e, a partir daí, o campo é controlado através das suas propriedades. O handle é criado na primeira chamada e reutilizado depois.

Os valores de is_show e de is_conditional_formatting estão também disponíveis como constantes no handle (SHOW_PCT_COL, CF_SCALE…). Definidos no campo, is_show, is_conditional_formatting e is_format valem para todos os seus valores da zona Valores e para os que lá entrarem depois — definidos antes de o campo estar em Valores, são guardados, relidos tal como definidos e aplicados à sua chegada. Para um só valor (o mesmo campo duas vezes: o montante, e a sua parte do total), usa-se o handle do valor, mais abaixo.

// Local variables
n_pbt_crosstab_field lnv_field

// O campo montante : a sua etiqueta e uma escala de cores
lnv_field = uo_crosstab.of_field(/*field*/ "amount")
lnv_field.is_label = "Volume de negócios"
lnv_field.is_conditional_formatting = lnv_field.CF_SCALE

⚠️ Alteração incompatível. Esta propriedade chamava-se is_cf: a abreviatura nada dizia no ponto de utilização. O nome antigo já não existe — um código que o utilize não compila. A substituição é mecânica: is_cf → is_conditional_formatting, sem alteração de valores nem de comportamento.

Propriedades de um valor #

of_value (integer ai_position) devolve o handle de um valor da zona Valores, pela sua posição (1 = o primeiro). Um campo pode lá estar duas vezes — o montante, e a sua parte do total geral — e cada valor tem as suas definições, que prevalecem sobre as do seu campo. O handle designa uma posição: após of_remove_value, of_move_value, of_remove_field, of_remove_calc_measure, of_clear_layout ou of_set_layout é libertado — peça of_value de novo. As suas constantes SHOW_* e CF_* são as de n_pbt_crosstab_field.

// Local variables
n_pbt_crosstab_value lnv_share, lnv_amount

// O montante duas vezes em Valores : a soma, depois a sua parte do total geral
uo_crosstab.of_add_value_field(/*field*/ "amount", /*agg*/ uo_crosstab.AGG_SUM)
uo_crosstab.of_add_value_field(/*field*/ "amount", /*agg*/ uo_crosstab.AGG_SUM)

// So o segundo valor : a sua parte do total geral, com a sua propria etiqueta
lnv_share = uo_crosstab.of_value(/*position*/ 2)
lnv_share.is_show = n_pbt_crosstab_value.SHOW_PCT_GRAND
lnv_share.is_label = "Parte das vendas"

// O primeiro valor : duas casas decimais, os negativos a vermelho
lnv_amount = uo_crosstab.of_value(/*position*/ 1)
lnv_amount.is_format = "#,##0.00"
lnv_amount.ib_negative_red = true

Métodos #

Alimentar e nomear #

Construir a tabela #

As agregações aceites por of_add_value_field são disponibilizadas pelo componente sob a forma de constantes: AGG_SUM (predefinição), AGG_COUNT (o número de valores não vazios, como a Contagem do Excel), AGG_COUNT_ROWS (o número de linhas, vazias incluídas), AGG_DISTINCT_COUNT (contagem de valores distintos, as células vazias são ignoradas como no Excel), AGG_AVG, AGG_MIN, AGG_MAX. Uma soma sem qualquer valor é uma célula vazia, não 0; uma « diferença face ao anterior » em que uma das duas células está vazia também é vazia. As percentagens escrevem-se como a língua de apresentação as escreve (57.9% em inglês, 57,9 % em francês).

Totais e subtotais #

Os totais definem-se através de propriedades, descritas acima: ib_row_grand_total e ib_col_grand_total para os totais gerais, ib_row_subtotals e ib_col_subtotals para os subtotais, is_totals_position para a posição da linha de total geral. O menu Opções da grelha (a roda dentada) oferece os mesmos quatro interruptores, uma entrada por eixo: Linha do total geral, Coluna do total geral, Subtotais das linhas, Subtotais das colunas.

Filtrar #

Os valores que of_set_member_filter e of_set_member_order esperam são os que a grelha guarda, nem sempre os que apresenta: num campo derivado de uma data, um mês escreve-se "01"…"12", um trimestre "1"…"4", um ano "2024"; um membro de data não agrupado escreve-se yyyy-mm-dd. O utilizador, por seu lado, encontra o filtro de etiqueta no menu do chip de qualquer campo — texto, número ou data.

Formatar #

O formato de um valor define-se através de uma propriedade: of_field("amount").is_format = "$#,##0.00" para todos os valores de um campo, of_value(2).is_format para um só (ver Propriedades de um campo e Propriedades de um valor). É um formato de apresentação PowerBuilder, lido pelo motor de máscaras da biblioteca; vazio, o valor recebe o Format da coluna do DataWindow. Os negativos a vermelho: of_value(n).ib_negative_red = true. O separador de milhares dos valores sem formato continua a ser is_thousands, a moeda do menu do chip is_currency_symbol.

Datas e campos calculados #

Uma fórmula aceita os operadores + - * / ( ), números (12, 0.5, .5, 1e3, sempre com ponto) e campos entre parênteses retos; ^ não é um operador. Uma fórmula inválida desencadeia ue_calc_field_error — nada falha.

Expandir, memorizar, exportar #

Comuns #

Eventos #

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

A tabela é viva: é esse todo o interesse do componente. Com o painel de campos visível (ib_field_list = true), o utilizador pode:

• arrastar um campo de uma zona para outra e reorganizar o cruzamento à vontade;
• alterar a agregação de uma medida (soma, média, contagem…);
• filtrar os valores de um campo através de uma lista de seleção;
• recolher ou expandir um grupo de linhas ou de colunas;
• ordenar através de um cabeçalho;
• selecionar e depois copiar um bloco de células, com os seus cabeçalhos para que uma colagem numa folha de cálculo diga o que são os valores (ib_copy_headers).

Cada uma destas manipulações, exceto a cópia (que desencadeia ue_copy), é comunicada em ue_layout_changed: em conjunto com of_get_layout / of_set_layout, permite oferecer «vistas guardadas» aos utilizadores.

Com o teclado. A construção da tabela faz-se sem rato — chips, menus, dobragem e ordenação: Tab leva a um campo, a um triângulo de dobragem ou a um cabeçalho ordenável, Enter ou Espaço aciona-o. Num campo abre o respetivo menu — aquele que tem Adicionar às linhas / às colunas / aos valores / aos filtros e Remover: toda a construção da tabela passa por aí. Shift+F10 ou a tecla Menu também abrem esse menu, e o foco segue o campo acabado de mover, mesmo para outra zona. Selecionar células e copiá-las (Ctrl+C) exige hoje o rato.

Exemplos #

Um relatório de vendas completo #

// Linhas: regiao e depois cidade dentro de cada regiao
uo_crosstab.of_clear_layout()
uo_crosstab.of_add_row_field(/*field*/ "region")
uo_crosstab.of_add_row_field(/*field*/ "city")

// Colunas: uma por ano
uo_crosstab.of_add_col_field(/*field*/ "year")

// Celulas: o montante total
uo_crosstab.of_add_value_field(/*field*/ "amount", /*agg*/ uo_crosstab.AGG_SUM)

// Apresentacao: montantes legiveis, subtotais e totais gerais
uo_crosstab.of_field(/*field*/ "amount").is_format = "$#,##0"
uo_crosstab.ib_row_subtotals = true
uo_crosstab.ib_row_grand_total = true
uo_crosstab.ib_col_grand_total = true

// Colorir as celulas para identificar os grandes montantes num relance
uo_crosstab.of_field(/*field*/ "amount").is_conditional_formatting = n_pbt_crosstab_field.CF_SCALE

Etiquetas legíveis #

As colunas chamam-se muitas vezes mt_ht ou cd_reg. Devem ser renomeadas de uma vez por todas, logo a seguir a of_from_datastore.

// Primeiro os dados : os campos tomam o nome das colunas
uo_crosstab.of_from_datastore(/*ads*/ lds)

// Depois uma etiqueta legivel para cada campo
uo_crosstab.of_field(/*field*/ "region").is_label    = "Região"
uo_crosstab.of_field(/*field*/ "city").is_label     = "Cidade"
uo_crosstab.of_field(/*field*/ "category").is_label = "Categoria"
uo_crosstab.of_field(/*field*/ "year").is_label     = "Ano"
uo_crosstab.of_field(/*field*/ "amount").is_label   = "Volume de negócios"
uo_crosstab.of_field(/*field*/ "quantity").is_label  = "Quantidade"

Analisar proporções em vez de montantes #

// Local variables
n_pbt_crosstab_field lnv_amount

// Partir de zonas vazias e depois colocar os campos
uo_crosstab.of_clear_layout()
uo_crosstab.of_add_row_field(/*field*/ "category")
uo_crosstab.of_add_col_field(/*field*/ "year")
uo_crosstab.of_add_value_field(/*field*/ "amount", /*agg*/ uo_crosstab.AGG_SUM)

// Manter apenas duas categorias no ecra (valores separados por uma tabulacao)
uo_crosstab.of_set_member_filter(/*field*/ "category", /*values_tab*/ "Informatique~tMobilier")

// O campo montante, para definir como e apresentado
lnv_amount = uo_crosstab.of_field(/*field*/ "amount")

// Mostrar a proporcao de cada celula no total da sua coluna
lnv_amount.is_show = lnv_amount.SHOW_PCT_COL

// Uma pequena barra em cada celula para comparar as proporcoes num relance
lnv_amount.is_conditional_formatting = lnv_amount.CF_BARS

Uma medida à medida: o preço médio #

Uma medida calculada é avaliada sobre os totais de cada célula, e não linha a linha: é isso que torna um rácio correto.

// Partir de zonas vazias e depois colocar os campos
uo_crosstab.of_clear_layout()
uo_crosstab.of_add_row_field(/*field*/ "region")

// Os dois totais que vao servir de base ao calculo
uo_crosstab.of_add_value_field(/*field*/ "amount",  /*agg*/ uo_crosstab.AGG_SUM)
uo_crosstab.of_add_value_field(/*field*/ "quantity", /*agg*/ uo_crosstab.AGG_SUM)

// Preco medio = montante total dividido pela quantidade total
uo_crosstab.of_add_calc_measure(/*name*/ "avg_price", /*label*/ "Preço médio", /*formula*/ "[amount] / [quantity]")
uo_crosstab.of_field(/*field*/ "avg_price").is_format = "$#,##0.00"

// Depois coloca-la entre os valores como qualquer campo (o agregado nao conta: uma medida calcula-se)
uo_crosstab.of_add_value_field(/*field*/ "avg_price", /*agg*/ uo_crosstab.AGG_SUM)

// event ue_calc_field_error de uo_crosstab : (string as_field, string as_message)
// Formula invalida: avisar sem nada quebrar, a tabela permanece visivel.
uo_status.of_panel(/*key*/ "main").is_text = "Fórmula " + as_field + " : " + as_message

Analisar por mês, trimestre ou ano #

Uma coluna de data não se cruza tal como está — cada dia daria origem à sua própria linha. É necessário derivar primeiro o nível pretendido.

// Criar tres campos derivados da coluna sale_date
uo_crosstab.of_group_date_field(/*field*/ "sale_date", /*part*/ uo_crosstab.DATE_YEAR)
uo_crosstab.of_group_date_field(/*field*/ "sale_date", /*part*/ uo_crosstab.DATE_QUARTER)
uo_crosstab.of_group_date_field(/*field*/ "sale_date", /*part*/ uo_crosstab.DATE_MONTH)

// Depois cruza-los como qualquer outro campo: ano em colunas, trimestre por baixo
uo_crosstab.of_add_col_field(/*field*/ "sale_date__year")
uo_crosstab.of_add_col_field(/*field*/ "sale_date__quarter")

O ranking das dez melhores regiões #

// Manter apenas as 10 regioes com maior total na primeira medida
uo_crosstab.of_set_value_filter(/*field*/ "region", /*type*/ uo_crosstab.VALUEFILTER_TOP, /*a*/ 10, /*b*/ 0, /*measure_index*/ 1)

Num campo colocado sob outro, a classificação faz-se dentro de cada pai: a melhor cidade de cada região, não a melhor cidade do país. Os empates ficam todos.

// As cidades sob as regioes
uo_crosstab.of_add_row_field(/*field*/ "region")
uo_crosstab.of_add_row_field(/*field*/ "city")

// A melhor cidade de cada regiao, na primeira medida
uo_crosstab.of_set_value_filter(/*field*/ "city", /*type*/ uo_crosstab.VALUEFILTER_TOP, /*a*/ 1, /*b*/ 0, /*measure_index*/ 1)

Exportar #

A exportação reproduz exatamente a vista em curso: os mesmos filtros, os mesmos totais, a mesma formatação.

// Para Excel: o ficheiro e escrito diretamente no caminho indicado
uo_crosstab.of_export_xlsx(/*path*/ "C:\temp\ventes.xlsx")

// event ue_xlsx_saved de uo_crosstab : (string as_path, boolean ab_ok, string as_error)
// inv_notif = um n_pbt_toaster declarado como variavel de instancia da window
if ab_ok then
    inv_notif.is_title = "Exportação concluída"
    inv_notif.is_text  = as_path
    inv_notif.is_kind  = inv_notif.KIND_SUCCESS
else
    inv_notif.is_title = "Exportação impossível"
    inv_notif.is_text  = as_error
    inv_notif.is_kind  = inv_notif.KIND_ERROR
end if
inv_notif.of_show()

// Para CSV: um ficheiro, como para o Excel; ue_csv_saved confirma
uo_crosstab.of_export_csv(/*path*/ "C:\exports\ventes.csv")

Oferecer vistas guardadas #

// Local variables
string ls_view

// Guardar a vista atual : of_get_layout responde de imediato
ls_view = uo_crosstab.of_get_layout()

// Guardar o conteudo TAL COMO ESTA : reproduz-se sem transformacao.
of_save_view(is_current_view, ls_view)

// Mais tarde: repor uma vista guardada
uo_crosstab.of_set_layout(/*state_json*/ of_read_view("Ventes par region"))

Descer ao detalhe por trás de um número #

// event ue_cell_double_clicked de uo_crosstab : (string as_row_tuple_json, string as_col_tuple_json, integer ai_measure, double ad_value)
// Local variables
long ll_rows[], ll_count, ll_i

// As linhas do DataStore por tras do numero com duplo clique
ll_count = uo_crosstab.of_get_cell_rows(/*row_tuple_json*/ as_row_tuple_json, /*col_tuple_json*/ as_col_tuple_json, /*rows*/ ll_rows)

// Nada a mostrar : nenhuma linha, ou uma celula que nao pode ser lida agora
if ll_count <= 0 then return

// Copia-las para a lista de detalhe : ids_sales e o DataStore dado a of_from_datastore
dw_detail.Reset()
for ll_i = 1 to ll_count
	ids_sales.RowsCopy(ll_rows[ll_i], ll_rows[ll_i], Primary!, dw_detail, dw_detail.RowCount() + 1, Primary!)
next

Os dois tuplos e ai_measure formam o endereço da célula: of_get_cell_value volta a lê-lo mais tarde, tal como a tabela o apresenta nesse momento.

// ue_cell_double_clicked event of uo_crosstab : the address of the cell, read again later
// Local variables
double ld_value

// Read the cell again from its address : 0 when it exists
if uo_crosstab.of_get_cell_value(/*row_tuple_json*/ as_row_tuple_json, /*col_tuple_json*/ as_col_tuple_json, /*measure*/ ai_measure, /*value*/ ld_value) = 0 then

	// ld_value is what the cell shows ; NULL for an empty cell
end if

Uma célula também se lê sem clique, pelos seus membros: um tuplo parcial designa um subtotal. E of_remove_field retira um campo de todas as suas zonas de uma só vez, filtros incluídos.

// The sales of Nord in 2025, first measure of Values
// Local variables
double ld_north

// A partial address : the region and the year, no other member
uo_crosstab.of_get_cell_value(/*row_tuple_json*/ '{"region":"Nord"}', /*col_tuple_json*/ '{"year":"2025"}', /*measure*/ 1, /*value*/ ld_north)

// Take the year out of the table, filters included
uo_crosstab.of_remove_field(/*field*/ "year")

Boas práticas #

• Chamar of_from_datastore uma única vez por conjunto de dados: reorganizar a tabela em seguida não tem custo, retransmitir os dados é dispendioso.
• Colocar as etiquetas (of_field("...").is_label) logo a seguir a of_from_datastore: acompanham o campo em toda a parte, incluindo no painel de campos e nas exportações.
• Filtrar do lado do SQL aquilo que não se destina a ser analisado: o crosstab é rápido, mas um DataStore duas vezes mais pequeno abre-se duas vezes mais depressa.
• of_clear_layout() esvazia as zonas sem retransmitir os dados: é a chamada indicada para propor várias análises sobre a mesma origem.
• Um campo de data cruza-se sempre através de of_group_date_field, nunca diretamente.
• O painel de campos deve permanecer visível nos ecrãs de análise e ser ocultado nos painéis de bordo fixos.

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