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
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(/*data*/ 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_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 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 se lisent sur le composant : uo_crosstab.AGG_SUM. Celles d'un champ (SHOW_*, CF_*) se lisent sur le handle du champ.

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és avant que le champ soit en Valeurs, ils sont gardés, se relisent tels quels et s'appliquent à son arrivée.

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

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, AGG_DISTINCT_COUNT (comptage de valeurs distinctes, les cellules vides ignorées comme dans Excel), AGG_AVG, AGG_MIN, AGG_MAX.

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.

Filtrer #

Mettre en forme #

Dates et champs calculés #

Une formule accepte les opérateurs + - * / ( ), des nombres et des champs entre crochets. 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 remonte dans ue_layout_changed : couplé à of_get_layout / of_set_layout, cela permet d'offrir des « vues enregistrées » à vos utilisateurs.

Au clavier. Chacun de ces gestes est atteignable sans souris : 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.

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

// 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(/*data*/ 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_set_value_format(/*field*/ "avg_price", /*decimals*/ 2, /*thousands*/ "locale", /*suffix*/ "$", /*symbol_before*/ true)

// 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*/ "year")
uo_crosstab.of_group_date_field(/*field*/ "sale_date", /*part*/ "quarter")
uo_crosstab.of_group_date_field(/*field*/ "sale_date", /*part*/ "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*/ "top", /*a*/ 10, /*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)
// Les deux premiers arguments decrivent le croisement (quelles valeurs de lignes,
// quelles valeurs de colonnes) : de quoi reconstruire une requete de detail.
w_sales_detail lw_detail

// Ouvrir la fenetre de detail avec le croisement en parametre
OpenWithParm(lw_detail, as_row_tuple_json + "|" + as_col_tuple_json)

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