crosstab — u_pbt_crosstab #

← Référence des composants · Sommaire du guide

Tableau croisé dynamique complet : zones lignes / colonnes / valeurs alimentées depuis un DataStore, agrégations, filtres, mise en forme conditionnelle, regroupement de dates, mesures calculées et exports CSV / Excel.

▶ Le voir en vrai — Application de démonstration, tuile Crosstab : l'aperçu, le code qui le produit et cette page, côte à côte.

En bref #

Le principe #

Vous fournissez au composant un jeu de données à plat — un DataStore, donc n'importe quelle requête déjà écrite dans votre application. Le crosstab s'occupe du reste : il en déduit la liste des champs, et vous les répartissez dans quatre zones.

Tout le calcul se fait dans le composant : une fois les données transmises, réarranger le tableau ne déclenche aucun aller-retour vers la base ni vers PowerBuilder.

Démarrage rapide #

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

// 1. Transmettre les donnees : les champs sont deduits des colonnes
uo_crosstab.of_from_datastore(/*ads*/ lds)

// 2. Repartir les champs dans les zones
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. Presenter : format des montants et totaux generaux
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)
// L'utilisateur veut le detail derriere un chiffre : ouvrir la liste correspondante.
of_open_detail(as_row_tuple_json, as_col_tuple_json)

Constantes #

Les constantes d'agrégation, de filtre, de date et de séparateur se lisent sur le composant : uo_crosstab.AGG_SUM. Celles d'un champ ou d'une valeur (SHOW_*, CF_*) se lisent sur la classe de sa poignée : n_pbt_crosstab_field.CF_SCALE, n_pbt_crosstab_value.SHOW_PCT_GRAND. AGG_COUNT compte les valeurs non vides, comme le Nombre d'Excel ; AGG_COUNT_ROWS compte les lignes, vides comprises.

Propriétés #

Propriétés d'un champ #

of_field (string as_field) renvoie le handle d'un champ : vous le récupérez une fois, puis vous pilotez le champ par ses propriétés. Le handle est créé au premier appel et réutilisé ensuite.

Les valeurs de is_show et is_conditional_formatting sont aussi disponibles en constantes sur le handle (SHOW_PCT_COL, CF_SCALE…). Posées sur le champ, is_show, is_conditional_formatting et is_format valent pour toutes ses valeurs de la zone Valeurs et pour celles qui y entrent ensuite — posées avant que le champ soit en Valeurs, elles sont gardées, se relisent telles quelles et s'appliquent à son arrivée. Pour une valeur seule (le même champ deux fois : le montant, et sa part du total), c'est la poignée de valeur, ci-dessous.

// Local variables
n_pbt_crosstab_field lnv_field

// Le champ Montant : son libelle et une echelle de couleurs
lnv_field = uo_crosstab.of_field(/*field*/ "amount")
lnv_field.is_label = "Chiffre d'affaires"
lnv_field.is_conditional_formatting = lnv_field.CF_SCALE

⚠️ Changement incompatible. Cette propriété s'appelait is_cf : l'abréviation ne disait rien au point d'appel. L'ancien nom n'existe plus — un code qui l'utilise ne compile pas. Le remplacement est mécanique : is_cf → is_conditional_formatting, sans changement de valeurs ni de comportement.

Propriétés d'une valeur #

of_value (integer ai_position) renvoie le handle d'une valeur de la zone Valeurs, par sa position (1 = la première). Un champ peut y être deux fois — le montant, et sa part du total général — et chaque valeur a ses réglages, qui passent devant ceux de son champ. Le handle désigne une position : après of_remove_value, of_move_value, of_remove_field, of_remove_calc_measure, of_clear_layout ou of_set_layout, il est libéré — redemandez of_value. Ses constantes SHOW_* et CF_* sont celles de n_pbt_crosstab_field.

// Local variables
n_pbt_crosstab_value lnv_share, lnv_amount

// Le montant deux fois en Valeurs : la somme, puis sa part du total general
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)

// La deuxieme valeur seule : sa part du total general, sous son propre libelle
lnv_share = uo_crosstab.of_value(/*position*/ 2)
lnv_share.is_show = n_pbt_crosstab_value.SHOW_PCT_GRAND
lnv_share.is_label = "Part des ventes"

// La premiere valeur : deux decimales, les negatifs en rouge
lnv_amount = uo_crosstab.of_value(/*position*/ 1)
lnv_amount.is_format = "#,##0.00"
lnv_amount.ib_negative_red = true

Méthodes #

Alimenter et nommer #

Construire le tableau #

Les agrégations acceptées par of_add_value_field sont portées par le composant en constantes : AGG_SUM (défaut), AGG_COUNT (le nombre de valeurs non vides, comme le Nombre d'Excel), AGG_COUNT_ROWS (le nombre de lignes, vides comprises), AGG_DISTINCT_COUNT (comptage de valeurs distinctes, les cellules vides ignorées comme dans Excel), AGG_AVG, AGG_MIN, AGG_MAX. Une somme sans aucune valeur est une cellule vide, pas 0 ; une « différence avec la précédente » dont l'une des deux cellules est vide est vide aussi. Les pourcentages s'écrivent selon la langue d'affichage (57.9% en anglais, 57,9 % en français).

Totaux et sous-totaux #

Les totaux se règlent par propriétés, décrites plus haut : ib_row_grand_total et ib_col_grand_total pour les totaux généraux, ib_row_subtotals et ib_col_subtotals pour les sous-totaux, is_totals_position pour la place de la ligne de total général. Le menu Options de la grille (la roue dentée) offre les mêmes quatre interrupteurs, une entrée par axe : Ligne de total général, Colonne de total général, Sous-totaux des lignes, Sous-totaux des colonnes.

Filtrer #

Les valeurs que of_set_member_filter et of_set_member_order attendent sont celles que la grille garde, pas toujours celles qu'elle affiche : sur un champ dérivé d'une date, un mois s'écrit "01"…"12", un trimestre "1"…"4", une année "2024" ; un membre date non groupé s'écrit yyyy-mm-dd. L'utilisateur, lui, trouve le filtre de libellé dans le menu de la puce de tout champ — texte, nombre ou date.

Mettre en forme #

Le format d'une valeur se pose par propriété : of_field("amount").is_format = "$#,##0.00" pour toutes les valeurs d'un champ, of_value(2).is_format pour une seule (voir Propriétés d'un champ et Propriétés d'une valeur). C'est un format d'affichage PowerBuilder, lu par le moteur de masques de la bibliothèque ; vide, la valeur prend le Format de la colonne du DataWindow. Les négatifs en rouge : of_value(n).ib_negative_red = true. Le séparateur de milliers des valeurs sans format reste is_thousands, la devise du menu de la puce is_currency_symbol.

Dates et champs calculés #

Une formule accepte les opérateurs + - * / ( ), des nombres (12, 0.5, .5, 1e3, toujours avec un point) et des champs entre crochets ; ^ n'est pas un opérateur. Une formule invalide déclenche ue_calc_field_error — rien ne plante.

Déplier, mémoriser, exporter #

Communes #

Événements #

Ce que l'utilisateur peut faire sans une ligne de code #

Le tableau est vivant : c'est tout l'intérêt du composant. Avec le panneau de champs affiché (ib_field_list = true), l'utilisateur peut :

• faire glisser un champ d'une zone à l'autre, et réarranger le croisement à volonté ;
• changer l'agrégation d'une mesure (somme, moyenne, comptage…) ;
• filtrer les valeurs d'un champ par une liste à cocher ;
• replier ou déplier un groupe de lignes ou de colonnes ;
• trier sur un en-tête ;
• sélectionner puis copier un bloc de cellules, avec ses en-têtes pour qu'un collage dans un tableur dise ce que sont les chiffres (ib_copy_headers).

Chacune de ces manipulations, la copie mise à part (elle lève ue_copy), remonte dans ue_layout_changed : couplé à of_get_layout / of_set_layout, cela permet d'offrir des « vues enregistrées » à vos utilisateurs.

Au clavier. La construction du tableau se fait sans souris — puces, menus, replis et tris : Tab amène sur un champ, un triangle de repli ou un en-tête triable, Entrée ou Espace le déclenche. Sur un champ, cela ouvre son menu — celui qui porte Ajouter aux lignes / aux colonnes / aux valeurs / aux filtres et Retirer : toute la construction du tableau passe par là. Maj+F10 ou la touche Menu ouvrent aussi ce menu, et le focus suit le champ qu'on vient de déplacer, même dans une autre zone. Sélectionner des cellules et les copier (Ctrl+C) demandent la souris aujourd'hui.

Exemples #

Un rapport de ventes complet #

// Lignes : region, puis ville a l'interieur de chaque region
uo_crosstab.of_clear_layout()
uo_crosstab.of_add_row_field(/*field*/ "region")
uo_crosstab.of_add_row_field(/*field*/ "city")

// Colonnes : une par annee
uo_crosstab.of_add_col_field(/*field*/ "year")

// Cellules : le montant total
uo_crosstab.of_add_value_field(/*field*/ "amount", /*agg*/ uo_crosstab.AGG_SUM)

// Presentation : montants lisibles, sous-totaux et totaux generaux
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

// Colorer les cellules pour reperer les gros montants d'un coup d'oeil
uo_crosstab.of_field(/*field*/ "amount").is_conditional_formatting = n_pbt_crosstab_field.CF_SCALE

Des libellés lisibles #

Vos colonnes s'appellent souvent mt_ht ou cd_reg. Renommez-les une fois pour toutes, juste après of_from_datastore.

// Les donnees d'abord : les champs prennent le nom des colonnes
uo_crosstab.of_from_datastore(/*ads*/ lds)

// Puis un libelle lisible pour chaque champ
uo_crosstab.of_field(/*field*/ "region").is_label    = "Region"
uo_crosstab.of_field(/*field*/ "city").is_label     = "Ville"
uo_crosstab.of_field(/*field*/ "category").is_label = "Categorie"
uo_crosstab.of_field(/*field*/ "year").is_label     = "Annee"
uo_crosstab.of_field(/*field*/ "amount").is_label   = "Chiffre d'affaires"
uo_crosstab.of_field(/*field*/ "quantity").is_label  = "Quantite"

Analyser des parts plutôt que des montants #

// Local variables
n_pbt_crosstab_field lnv_amount

// Repartir de zones vides, puis placer les champs
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)

// Ne garder que deux categories a l'ecran (valeurs separees par une tabulation)
uo_crosstab.of_set_member_filter(/*field*/ "category", /*values_tab*/ "Informatique~tMobilier")

// Le champ Montant, pour regler son affichage
lnv_amount = uo_crosstab.of_field(/*field*/ "amount")

// Afficher la part de chaque cellule dans le total de sa colonne
lnv_amount.is_show = lnv_amount.SHOW_PCT_COL

// Une petite barre dans chaque cellule pour comparer les parts d'un regard
lnv_amount.is_conditional_formatting = lnv_amount.CF_BARS

Une mesure à vous : le prix moyen #

Une mesure calculée s'évalue sur les totaux de chaque cellule, pas ligne à ligne : c'est ce qui rend un ratio juste.

// Repartir de zones vides, puis placer les champs
uo_crosstab.of_clear_layout()
uo_crosstab.of_add_row_field(/*field*/ "region")

// Les deux totaux qui vont servir de base au calcul
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)

// Prix moyen = montant total divise par quantite totale
uo_crosstab.of_add_calc_measure(/*name*/ "avg_price", /*label*/ "Prix moyen", /*formula*/ "[amount] / [quantity]")
uo_crosstab.of_field(/*field*/ "avg_price").is_format = "$#,##0.00"

// Puis la placer parmi les valeurs comme n'importe quel champ (l'agregat ne compte pas : une mesure se calcule)
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)
// Formule invalide : prevenir sans rien casser, le tableau reste affiche.
uo_status.of_panel(/*key*/ "main").is_text = "Formule " + as_field + " : " + as_message

Analyser par mois, trimestre ou année #

Une colonne de date ne se croise pas telle quelle — chaque jour ferait sa propre ligne. Dérivez d'abord le niveau voulu.

// Creer trois champs derives de la colonne 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)

// Puis les croiser comme n'importe quel champ : annee en colonnes, trimestre en dessous
uo_crosstab.of_add_col_field(/*field*/ "sale_date__year")
uo_crosstab.of_add_col_field(/*field*/ "sale_date__quarter")

Le palmarès des dix meilleures régions #

// Ne garder que les 10 regions au plus fort total sur la premiere mesure
uo_crosstab.of_set_value_filter(/*field*/ "region", /*type*/ uo_crosstab.VALUEFILTER_TOP, /*a*/ 10, /*b*/ 0, /*measure_index*/ 1)

Sur un champ placé sous un autre, le classement se fait à l'intérieur de chaque parent : la meilleure ville de chaque région, pas la meilleure ville du pays. Les ex-aequo restent tous.

// Les villes sous les regions
uo_crosstab.of_add_row_field(/*field*/ "region")
uo_crosstab.of_add_row_field(/*field*/ "city")

// La meilleure ville de chaque region, sur la premiere mesure
uo_crosstab.of_set_value_filter(/*field*/ "city", /*type*/ uo_crosstab.VALUEFILTER_TOP, /*a*/ 1, /*b*/ 0, /*measure_index*/ 1)

Exporter #

L'export reprend exactement la vue en cours : mêmes filtres, mêmes totaux, même mise en forme.

// Vers Excel : le fichier est ecrit directement au chemin indique
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 = un n_pbt_toaster declare en variable d'instance de la fenetre
if ab_ok then
    inv_notif.is_title = "Export termine"
    inv_notif.is_text  = as_path
    inv_notif.is_kind  = inv_notif.KIND_SUCCESS
else
    inv_notif.is_title = "Export impossible"
    inv_notif.is_text  = as_error
    inv_notif.is_kind  = inv_notif.KIND_ERROR
end if
inv_notif.of_show()

// Vers CSV : un fichier, comme pour Excel ; ue_csv_saved confirme
uo_crosstab.of_export_csv(/*path*/ "C:\exports\ventes.csv")

Offrir des vues enregistrées #

// Local variables
string ls_view

// Enregistrer la vue courante : of_get_layout la rend tout de suite
ls_view = uo_crosstab.of_get_layout()

// Conserver le contenu TEL QUEL : il se rejoue sans transformation.
of_save_view(is_current_view, ls_view)

// Plus tard : rejouer une vue enregistree
uo_crosstab.of_set_layout(/*state_json*/ of_read_view("Ventes par region"))

Descendre au détail derrière un chiffre #

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

// Les lignes du DataStore derriere le chiffre double-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)

// Rien a montrer : aucune ligne, ou une cellule illisible maintenant
if ll_count <= 0 then return

// Les copier dans la liste de detail : ids_sales est le DataStore donne 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

Les deux tuples et ai_measure forment l'adresse de la cellule : of_get_cell_value la relit plus tard, telle que le tableau l'affiche à ce moment-là.

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

Une cellule se lit aussi sans clic, par ses membres : un tuple partiel désigne un sous-total. Et of_remove_field retire un champ de toutes ses zones d'un coup, filtres compris.

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

Bonnes pratiques #

• Appelez of_from_datastore une seule fois par jeu de données : réarranger le tableau ensuite ne coûte rien, retransmettre les données coûte cher.
• Posez les libellés (of_field("...").is_label) juste après of_from_datastore : ils suivent le champ partout, y compris dans le panneau de champs et dans les exports.
• Filtrez côté SQL ce qui n'a pas vocation à être analysé : le crosstab est rapide, mais un DataStore deux fois plus petit s'ouvre deux fois plus vite.
• of_clear_layout() vide les zones sans retransmettre les données : c'est le bon appel pour proposer plusieurs analyses sur la même source.
• Un champ date se croise toujours via of_group_date_field, jamais directement.
• Laissez le panneau de champs visible sur les écrans d'analyse, masquez-le sur les tableaux de bord figés.

Hérité du socle commun #

Ces membres existent sur tous les composants visuels — ils ne sont pas propres à celui-ci. Ils sont détaillés une seule fois, dans les chapitres transverses ; cette table dit seulement où les lire.

Deux aides ne sont pas héritées : of_icon et of_escape_markup vivent sur n_pbt_utils. Déclarez-en une — n_pbt_utils lnv_utils, rien à créer — et appelez-les dessus.

← Référence des composants · Sommaire du guide