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
// Local variables
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(/*ads*/ 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_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 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, di filtro, di data e di separatore si leggono sul componente: uo_crosstab.AGG_SUM. Quelle di un campo o di un valore (SHOW_*, CF_*) si leggono sulla classe del suo handle: n_pbt_crosstab_field.CF_SCALE, n_pbt_crosstab_value.SHOW_PCT_GRAND. AGG_COUNT conta i valori non vuoti, come il Conteggio di Excel; AGG_COUNT_ROWS conta le righe, comprese quelle vuote.

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 sul campo, is_show, is_conditional_formatting e is_format valgono per tutti i suoi valori dell'area Valori e per quelli che vi entrano dopo — posti prima che il campo sia in Valori, vengono conservati, riletti così come posti e applicati al suo arrivo. Per un solo valore (lo stesso campo due volte: l'importo, e la sua quota del totale), si usa l'handle del valore, qui sotto.

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

Proprietà di un valore #

of_value (integer ai_position) restituisce l'handle di un valore dell'area Valori, tramite la sua posizione (1 = il primo). Un campo può starvi due volte — l'importo, e la sua quota del totale generale — e ogni valore ha le sue impostazioni, che prevalgono su quelle del suo campo. L'handle designa una posizione: dopo of_remove_value, of_move_value, of_remove_field, of_remove_calc_measure, of_clear_layout o of_set_layout viene rilasciato — richieda of_value. Le sue costanti SHOW_* e CF_* sono quelle di n_pbt_crosstab_field.

// Local variables
n_pbt_crosstab_value lnv_share, lnv_amount

// L'importo due volte in Valori : la somma, poi la sua quota del totale generale
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)

// Solo il secondo valore : la sua quota del totale generale, con la propria etichetta
lnv_share = uo_crosstab.of_value(/*position*/ 2)
lnv_share.is_show = n_pbt_crosstab_value.SHOW_PCT_GRAND
lnv_share.is_label = "Quota delle vendite"

// Il primo valore : due decimali, i negativi in rosso
lnv_amount = uo_crosstab.of_value(/*position*/ 1)
lnv_amount.is_format = "#,##0.00"
lnv_amount.ib_negative_red = true

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 (il numero di valori non vuoti, come il Conteggio di Excel), AGG_COUNT_ROWS (il numero di righe, comprese quelle vuote), AGG_DISTINCT_COUNT (conteggio di valori distinti, celle vuote ignorate come in Excel), AGG_AVG, AGG_MIN, AGG_MAX. Una somma senza alcun valore è una cella vuota, non 0; uno « scarto rispetto al precedente » in cui una delle due celle è vuota è vuoto anch'esso. Le percentuali si scrivono come le scrive la lingua di visualizzazione (57.9% in inglese, 57,9 % in francese).

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. Il menu Opzioni della griglia (l'ingranaggio) offre gli stessi quattro interruttori, una voce per asse: Riga del totale generale, Colonna del totale generale, Subtotali delle righe, Subtotali delle colonne.

Filtrare #

I valori che of_set_member_filter e of_set_member_order attendono sono quelli che la griglia conserva, non sempre quelli che mostra: su un campo derivato da una data, un mese si scrive "01"…"12", un trimestre "1"…"4", un anno "2024"; un membro data non raggruppato si scrive yyyy-mm-dd. L'utente, da parte sua, trova il filtro di etichetta nel menu del chip di ogni campo — testo, numero o data.

Formattare #

Il formato di un valore si imposta tramite una proprietà: of_field("amount").is_format = "$#,##0.00" per tutti i valori di un campo, of_value(2).is_format per uno solo (vedere Proprietà di un campo e Proprietà di un valore). È un formato di visualizzazione PowerBuilder, letto dal motore di maschere della libreria; vuoto, il valore prende il Format della colonna del DataWindow. I negativi in rosso: of_value(n).ib_negative_red = true. Il separatore delle migliaia dei valori senza formato resta is_thousands, la valuta del menu del chip is_currency_symbol.

Date e campi calcolati #

Una formula accetta gli operatori + - * / ( ), numeri (12, 0.5, .5, 1e3, sempre con il punto) e campi tra parentesi quadre; ^ non è un operatore. 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, tranne la copia (che attiva ue_copy), 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. La costruzione della tabella si fa senza mouse — chip, menu, compressione e ordinamento: 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. Selezionare delle celle e copiarle (Ctrl+C) richiede oggi il mouse.

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

// 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(/*ads*/ 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_field(/*field*/ "avg_price").is_format = "$#,##0.00"

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

// 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*/ uo_crosstab.VALUEFILTER_TOP, /*a*/ 10, /*b*/ 0, /*measure_index*/ 1)

Su un campo posto sotto un altro, la classifica si fa all'interno di ciascun genitore: la città migliore di ogni regione, non la città migliore del paese. I pari merito restano tutti.

// Le citta sotto le regioni
uo_crosstab.of_add_row_field(/*field*/ "region")
uo_crosstab.of_add_row_field(/*field*/ "city")

// La citta migliore di ogni regione, sulla prima misura
uo_crosstab.of_set_value_filter(/*field*/ "city", /*type*/ uo_crosstab.VALUEFILTER_TOP, /*a*/ 1, /*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)
// Local variables
long ll_rows[], ll_count, ll_i

// Le righe del DataStore dietro la cifra cliccata due volte
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)

// Niente da mostrare : nessuna riga, o una cella non leggibile ora
if ll_count <= 0 then return

// Copiarle nell'elenco di dettaglio : ids_sales e il DataStore dato 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

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