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
datastore lds
lds = create datastore
lds.dataobject = "d_ventes"
lds.SetTransObject(SQLCA)
lds.Retrieve()

// 1. Transmitir os dados: os campos sao deduzidos das colunas
uo_croise.of_set_data(lds)

// 2. Distribuir os campos pelas zonas
uo_croise.of_add_row_field(/*campo*/ "region")
uo_croise.of_add_col_field(/*campo*/ "annee")
uo_croise.of_add_value_field(/*campo*/ "montant", /*agregado*/ uo_croise.AGG_SUM)

// 3. Apresentar: formato dos montantes e totais gerais
uo_croise.of_set_value_format(/*campo*/ "montant", /*decimais*/ 0, /*milhares*/ "locale", /*simbolo*/ "$", /*simbolo_antes*/ true)
uo_croise.ib_row_grand_total = true
uo_croise.ib_col_grand_total = true

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

Constantes #

As constantes de agregação leem-se no componente: uo_croise.AGG_SUM. As de um campo (SHOW_*, CF_*) leem-se no handle do campo.

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…).

n_pbt_crosstab_field lnv_champ

lnv_champ = uo_croise.of_field(/*campo*/ "montant")
lnv_champ.is_label = "Volume de negócios"
lnv_champ.is_conditional_formatting = lnv_champ.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.

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, AGG_DISTINCT_COUNT (contagem de valores distintos), AGG_AVG, AGG_MIN, AGG_MAX.

Totais e subtotais #

Filtrar #

Formatar #

Datas e campos calculados #

Uma fórmula aceita os operadores + - * / ( ), números e campos entre parênteses retos. 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.

Cada uma destas manipulações é comunicada em ue_layout_changed: em conjunto com of_get_layout / of_set_layout, permite oferecer «vistas guardadas» aos utilizadores.

Com o teclado. Cada um destes gestos é alcançável sem rato: 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í.

Exemplos #

Um relatório de vendas completo #

// Linhas: regiao e depois cidade dentro de cada regiao
uo_croise.of_clear_layout()
uo_croise.of_add_row_field(/*campo*/ "region")
uo_croise.of_add_row_field(/*campo*/ "ville")

// Colunas: uma por ano
uo_croise.of_add_col_field(/*campo*/ "annee")

// Celulas: o montante total
uo_croise.of_add_value_field(/*campo*/ "montant", /*agregado*/ uo_croise.AGG_SUM)

// Apresentacao: montantes legiveis, subtotais e totais gerais
uo_croise.of_set_value_format(/*campo*/ "montant", /*decimais*/ 0, /*milhares*/ "locale", /*simbolo*/ "$", /*simbolo_antes*/ true)
uo_croise.ib_row_subtotals = true
uo_croise.ib_row_grand_total = true
uo_croise.ib_col_grand_total = true

// Colorir as celulas para identificar os grandes montantes num relance
uo_croise.of_field(/*campo*/ "montant").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_set_data.

uo_croise.of_set_data(lds)

uo_croise.of_field("region").is_label    = "Região"
uo_croise.of_field("ville").is_label     = "Cidade"
uo_croise.of_field("categorie").is_label = "Categoria"
uo_croise.of_field("annee").is_label     = "Ano"
uo_croise.of_field("montant").is_label   = "Volume de negócios"
uo_croise.of_field("quantite").is_label  = "Quantidade"

Analisar proporções em vez de montantes #

n_pbt_crosstab_field lnv_montant

uo_croise.of_clear_layout()
uo_croise.of_add_row_field(/*campo*/ "categorie")
uo_croise.of_add_col_field(/*campo*/ "annee")
uo_croise.of_add_value_field(/*campo*/ "montant", /*agregado*/ uo_croise.AGG_SUM)

// Manter apenas duas categorias no ecra (valores separados por uma tabulacao)
uo_croise.of_set_member_filter(/*campo*/ "categorie", /*valores*/ "Informatique~tMobilier")

lnv_montant = uo_croise.of_field(/*campo*/ "montant")

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

// Uma pequena barra em cada celula para comparar as proporcoes num relance
lnv_montant.is_conditional_formatting = lnv_montant.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.

uo_croise.of_clear_layout()
uo_croise.of_add_row_field(/*campo*/ "region")

// Os dois totais que vao servir de base ao calculo
uo_croise.of_add_value_field(/*campo*/ "montant",  /*agregado*/ uo_croise.AGG_SUM)
uo_croise.of_add_value_field(/*campo*/ "quantite", /*agregado*/ uo_croise.AGG_SUM)

// Preco medio = montante total dividido pela quantidade total
uo_croise.of_add_calc_measure(/*nome*/ "prix_moyen", /*etiqueta*/ "Preço médio", &
                              /*formula*/ "[montant] / [quantite]")
uo_croise.of_set_value_format(/*campo*/ "prix_moyen", /*decimais*/ 2, /*milhares*/ "locale", /*simbolo*/ "$", /*simbolo_antes*/ true)

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

// event ue_calc_field_error de uo_croise : (string as_field, string as_message)
// Formula invalida: avisar sem nada quebrar, a tabela permanece visivel.
uo_statut.of_item("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 date_vente
uo_croise.of_group_date_field(/*campo*/ "date_vente", /*nivel*/ "year")
uo_croise.of_group_date_field(/*campo*/ "date_vente", /*nivel*/ "quarter")
uo_croise.of_group_date_field(/*campo*/ "date_vente", /*nivel*/ "month")

// Depois cruza-los como qualquer outro campo: ano em colunas, trimestre por baixo
uo_croise.of_add_col_field("date_vente__year")
uo_croise.of_add_col_field("date_vente__quarter")

O ranking das dez melhores regiões #

// Manter apenas as 10 regioes com maior total na primeira medida
uo_croise.of_set_value_filter(/*campo*/ "region", /*tipo*/ "top", &
                              /*a*/ 10, /*b*/ 0, /*medida*/ 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_croise.of_export_xlsx("C:\temp\ventes.xlsx")

// event ue_xlsx_saved de uo_croise : (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_croise.of_export_csv(/*caminho*/ "C:\exports\ventes.csv")

Oferecer vistas guardadas #

string ls_vue

// Guardar a vista atual : of_get_layout responde de imediato
ls_vue = uo_croise.of_get_layout()

// Guardar o conteudo TAL COMO ESTA : reproduz-se sem transformacao.
of_enregistrer_vue(is_vue_courante, ls_vue)

// Mais tarde: repor uma vista guardada
uo_croise.of_set_layout(of_lire_vue("Ventes par region"))

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

// event ue_cell_double_clicked de uo_croise : (string as_row_tuple_json, string as_col_tuple_json, double ad_value)
// Os dois primeiros argumentos descrevem o cruzamento (que valores de linhas,
// que valores de colunas): o suficiente para reconstruir uma consulta de detalhe.
w_detail_ventes lw_detail

OpenWithParm(lw_detail, as_row_tuple_json + "|" + as_col_tuple_json)

Boas práticas #

• Chamar of_set_data 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_set_data: 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