crosstab — u_pbt_crosstab #

← Riferimento dei componenti · Sommario della guida

Tabella crosstab completa: aree righe / colonne / valori alimentate da un DataStore, aggregazioni, filtri, formattazione condizionale, raggruppamento di date, misure calcolate ed esportazioni CSV / Excel.

▶ Vederlo dal vivo — Applicazione dimostrativa, riquadro Crosstab: l'anteprima, il codice che lo produce e questa pagina, affiancati.

In breve #

Il principio #

Lei fornisce al componente un insieme di dati piatto — un DataStore, quindi qualsiasi query già scritta nella sua applicazione. Al resto pensa il crosstab: ne deduce l'elenco dei campi e Lei li distribuisce in quattro aree.

Tutto il calcolo avviene nel componente: una volta trasmessi i dati, riorganizzare la tabella non provoca alcun viaggio di andata e ritorno verso il database né verso PowerBuilder.

Avvio rapido #

// event open della finestra
datastore lds
lds = create datastore
lds.dataobject = "d_sales"
lds.SetTransObject(SQLCA)
lds.Retrieve()

// 1. Trasmettere i dati: i campi sono dedotti dalle colonne
uo_crosstab.of_from_datastore(/*data*/ lds)

// 2. Distribuire i campi nelle aree
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. Presentare: formato degli importi e totali generali
uo_crosstab.of_set_value_format(/*field*/ "amount", /*decimals*/ 0, /*thousands*/ "locale", /*suffix*/ "$", /*symbol_before*/ true)
uo_crosstab.ib_row_grand_total = true
uo_crosstab.ib_col_grand_total = true

// event ue_cell_double_clicked di uo_crosstab: (string as_row_tuple_json, string as_col_tuple_json, integer ai_measure, double ad_value)
// L'utente vuole il dettaglio dietro una cifra: aprire l'elenco corrispondente.
of_open_detail(as_row_tuple_json, as_col_tuple_json)

Costanti #

Le costanti di aggregazione si leggono sul componente: uo_crosstab.AGG_SUM. Quelle di un campo (SHOW_*, CF_*) si leggono sull'handle del campo.

Proprietà #

Proprietà di un campo #

of_field (string as_field) restituisce l'handle di un campo: lo recupera una volta, poi pilota il campo attraverso le sue proprietà. L'handle viene creato alla prima chiamata e riutilizzato in seguito.

I valori di is_show e is_conditional_formatting sono disponibili anche come costanti sull'handle (SHOW_PCT_COL, CF_SCALE…). Posti prima che il campo sia in Valori, vengono conservati, riletti così come posti e applicati al suo arrivo.

// Local variables
n_pbt_crosstab_field lnv_field

// Il campo importo : la sua etichetta e una scala di colori
lnv_field = uo_crosstab.of_field(/*field*/ "amount")
lnv_field.is_label = "Fatturato"
lnv_field.is_conditional_formatting = lnv_field.CF_SCALE

⚠️ Modifica non retrocompatibile. Questa proprietà si chiamava is_cf: l'abbreviazione non diceva nulla nel punto di chiamata. Il vecchio nome non esiste più: un codice che lo utilizza non compila. La sostituzione è meccanica: is_cf → is_conditional_formatting, senza alcun cambiamento di valori né di comportamento.

Metodi #

Alimentare e denominare #

Costruire la tabella #

Le aggregazioni accettate da of_add_value_field sono esposte dal componente come costanti: AGG_SUM (predefinito), AGG_COUNT, AGG_DISTINCT_COUNT (conteggio di valori distinti, celle vuote ignorate come in Excel), AGG_AVG, AGG_MIN, AGG_MAX.

Totali e subtotali #

I totali si impostano tramite proprietà, descritte sopra: ib_row_grand_total e ib_col_grand_total per i totali generali, ib_row_subtotals e ib_col_subtotals per i subtotali, is_totals_position per la posizione della riga del totale generale.

Filtrare #

Formattare #

Date e campi calcolati #

Una formula accetta gli operatori + - * / ( ), numeri e campi tra parentesi quadre. Una formula non valida attiva ue_calc_field_error — nulla va in crash.

Espandere, memorizzare, esportare #

Comuni #

Event #

Che cosa può fare l'utente senza una riga di codice #

La tabella è viva: è tutto l'interesse del componente. Con il pannello dei campi visualizzato (ib_field_list = true), l'utente può:

• trascinare un campo da un'area all'altra e riorganizzare l'incrocio a piacimento;
• cambiare l'aggregazione di una misura (somma, media, conteggio…);
• filtrare i valori di un campo tramite un elenco con caselle di spunta;
• comprimere o espandere un gruppo di righe o di colonne;
• ordinare da un'intestazione;
• selezionare e poi copiare un blocco di celle, con le sue intestazioni perché un incolla in un foglio di calcolo dica che cosa sono le cifre (ib_copy_headers).

Ognuna di queste manipolazioni viene segnalata in ue_layout_changed: unita a of_get_layout / of_set_layout, permette di offrire ai suoi utenti delle « viste salvate ».

Da tastiera. Ognuno di questi gesti è raggiungibile senza mouse: Tab porta su un campo, su un triangolo di chiusura o su un'intestazione ordinabile, Invio o Spazio lo attiva. Su un campo si apre il suo menu — quello che porta Aggiungi alle righe / alle colonne / ai valori / ai filtri e Rimuovi: tutta la costruzione della tabella passa di lì. Maiusc+F10 o il tasto Menu aprono anche questo menu, e il focus segue il campo appena spostato, anche in un'altra zona.

Esempi #

Un rapporto vendite completo #

// Righe: regione, poi citta all'interno di ogni regione
uo_crosstab.of_clear_layout()
uo_crosstab.of_add_row_field(/*field*/ "region")
uo_crosstab.of_add_row_field(/*field*/ "city")

// Colonne: una per anno
uo_crosstab.of_add_col_field(/*field*/ "year")

// Celle: l'importo totale
uo_crosstab.of_add_value_field(/*field*/ "amount", /*agg*/ uo_crosstab.AGG_SUM)

// Presentazione: importi leggibili, subtotali e totali generali
uo_crosstab.of_set_value_format(/*field*/ "amount", /*decimals*/ 0, /*thousands*/ "locale", /*suffix*/ "$", /*symbol_before*/ true)
uo_crosstab.ib_row_subtotals = true
uo_crosstab.ib_row_grand_total = true
uo_crosstab.ib_col_grand_total = true

// Colorare le celle per individuare i grandi importi a colpo d'occhio
uo_crosstab.of_field(/*field*/ "amount").is_conditional_formatting = n_pbt_crosstab_field.CF_SCALE

Etichette leggibili #

Le sue colonne si chiamano spesso mt_ht o cd_reg. Le rinomini una volta per tutte, subito dopo of_from_datastore.

// Prima i dati : i campi prendono il nome delle colonne
uo_crosstab.of_from_datastore(/*data*/ lds)

// Poi un'etichetta leggibile per ogni campo
uo_crosstab.of_field(/*field*/ "region").is_label    = "Regione"
uo_crosstab.of_field(/*field*/ "city").is_label     = "Città"
uo_crosstab.of_field(/*field*/ "category").is_label = "Categoria"
uo_crosstab.of_field(/*field*/ "year").is_label     = "Anno"
uo_crosstab.of_field(/*field*/ "amount").is_label   = "Fatturato"
uo_crosstab.of_field(/*field*/ "quantity").is_label  = "Quantità"

Analizzare quote anziché importi #

// Local variables
n_pbt_crosstab_field lnv_amount

// Ripartire da aree vuote, poi collocare i campi
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)

// Tenere solo due categorie sullo schermo (valori separati da una tabulazione)
uo_crosstab.of_set_member_filter(/*field*/ "category", /*values_tab*/ "Informatique~tMobilier")

// Il campo importo, per regolarne la visualizzazione
lnv_amount = uo_crosstab.of_field(/*field*/ "amount")

// Mostrare la quota di ogni cella nel totale della sua colonna
lnv_amount.is_show = lnv_amount.SHOW_PCT_COL

// Una piccola barra in ogni cella per confrontare le quote a colpo d'occhio
lnv_amount.is_conditional_formatting = lnv_amount.CF_BARS

Una misura tutta sua: il prezzo medio #

Una misura calcolata si valuta sui totali di ogni cella, non riga per riga: è ciò che rende corretto un rapporto.

// Ripartire da aree vuote, poi collocare i campi
uo_crosstab.of_clear_layout()
uo_crosstab.of_add_row_field(/*field*/ "region")

// I due totali che serviranno da base al calcolo
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)

// Prezzo medio = importo totale diviso per la quantita totale
uo_crosstab.of_add_calc_measure(/*name*/ "avg_price", /*label*/ "Prezzo medio", /*formula*/ "[amount] / [quantity]")
uo_crosstab.of_set_value_format(/*field*/ "avg_price", /*decimals*/ 2, /*thousands*/ "locale", /*suffix*/ "$", /*symbol_before*/ true)

// Poi metterla tra i valori come qualsiasi campo (l'aggregato non conta: una misura si calcola)
uo_crosstab.of_add_value_field(/*field*/ "avg_price", /*agg*/ uo_crosstab.AGG_SUM)

// event ue_calc_field_error di uo_crosstab: (string as_field, string as_message)
// Formula non valida: avvisare senza rompere nulla, la tabella resta visualizzata.
uo_status.of_panel(/*key*/ "main").is_text = "Formula " + as_field + " : " + as_message

Analizzare per mese, trimestre o anno #

Una colonna data non si incrocia così com'è — ogni giorno formerebbe una riga a sé. Derivi prima il livello desiderato.

// Creare tre campi derivati dalla colonna sale_date
uo_crosstab.of_group_date_field(/*field*/ "sale_date", /*part*/ "year")
uo_crosstab.of_group_date_field(/*field*/ "sale_date", /*part*/ "quarter")
uo_crosstab.of_group_date_field(/*field*/ "sale_date", /*part*/ "month")

// Poi incrociarli come qualsiasi altro campo: anno in colonne, trimestre sotto
uo_crosstab.of_add_col_field(/*field*/ "sale_date__year")
uo_crosstab.of_add_col_field(/*field*/ "sale_date__quarter")

La classifica delle dieci migliori regioni #

// Tenere solo le 10 regioni con il totale piu alto sulla prima misura
uo_crosstab.of_set_value_filter(/*field*/ "region", /*type*/ "top", /*a*/ 10, /*b*/ 0, /*measure_index*/ 1)

Esportare #

L'esportazione riprende esattamente la vista corrente: stessi filtri, stessi totali, stessa formattazione.

// Verso Excel: il file viene scritto direttamente nel percorso indicato
uo_crosstab.of_export_xlsx(/*path*/ "C:\temp\ventes.xlsx")

// event ue_xlsx_saved di uo_crosstab: (string as_path, boolean ab_ok, string as_error)
// inv_notif = un n_pbt_toaster dichiarato come variabile d'istanza della finestra
if ab_ok then
    inv_notif.is_title = "Esportazione completata"
    inv_notif.is_text  = as_path
    inv_notif.is_kind  = inv_notif.KIND_SUCCESS
else
    inv_notif.is_title = "Esportazione impossibile"
    inv_notif.is_text  = as_error
    inv_notif.is_kind  = inv_notif.KIND_ERROR
end if
inv_notif.of_show()

// Verso CSV: un file, come per Excel; ue_csv_saved conferma
uo_crosstab.of_export_csv(/*path*/ "C:\exports\ventes.csv")

Offrire viste salvate #

// Local variables
string ls_view

// Salvare la vista corrente : of_get_layout risponde subito
ls_view = uo_crosstab.of_get_layout()

// Conservare il contenuto COSI COM E : si riproduce senza trasformazioni.
of_save_view(is_current_view, ls_view)

// Piu tardi: riprodurre una vista salvata
uo_crosstab.of_set_layout(/*state_json*/ of_read_view("Ventes par region"))

Scendere al dettaglio dietro una cifra #

// event ue_cell_double_clicked di uo_crosstab: (string as_row_tuple_json, string as_col_tuple_json, integer ai_measure, double ad_value)
// I primi due argomenti descrivono l'incrocio (quali valori di righe,
// quali valori di colonne): quanto basta per ricostruire una query di dettaglio.
w_sales_detail lw_detail

// Aprire la finestra di dettaglio con l'incrocio come parametro
OpenWithParm(lw_detail, as_row_tuple_json + "|" + as_col_tuple_json)

I due tuple e ai_measure formano l'indirizzo della cella: of_get_cell_value lo rilegge più tardi, così come la tabella lo mostra in quel 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

Una cella si legge anche senza clic, attraverso i suoi membri: un tuple parziale designa un subtotale. E of_remove_field toglie un campo da tutte le sue aree in un colpo solo, filtri compresi.

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

Buone pratiche #

• Chiami of_from_datastore una sola volta per insieme di dati: riorganizzare la tabella in seguito non costa nulla, ritrasmettere i dati costa caro.
• Imposti le etichette (of_field("...").is_label) subito dopo of_from_datastore: seguono il campo dappertutto, anche nel pannello dei campi e nelle esportazioni.
• Filtri lato SQL ciò che non è destinato a essere analizzato: il crosstab è rapido, ma un DataStore due volte più piccolo si apre due volte più in fretta.
• of_clear_layout() svuota le aree senza ritrasmettere i dati: è la chiamata giusta per proporre più analisi sulla stessa origine.
• Un campo data si incrocia sempre tramite of_group_date_field, mai direttamente.
• Lasci il pannello dei campi visibile sulle schermate di analisi, lo nasconda sui cruscotti fissi.

Ereditato dalla base comune #

Questi membri esistono su tutti i componenti visivi — non sono propri di questo. Sono descritti una sola volta, nei capitoli trasversali; questa tabella dice solo dove leggerli.

Due aiuti non sono ereditati: of_icon e of_escape_markup vivono su n_pbt_utils. Ne dichiari uno — n_pbt_utils lnv_utils, niente da creare — e li chiami su di esso.

← Riferimento dei componenti · Sommario della guida