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_ventes"
lds.SetTransObject(SQLCA)
lds.Retrieve()

// 1. Transmettre les donnees : les champs sont deduits des colonnes
uo_croise.of_set_data(lds)

// 2. Repartir les champs dans les zones
uo_croise.of_add_row_field(/*champ*/ "region")
uo_croise.of_add_col_field(/*champ*/ "annee")
uo_croise.of_add_value_field(/*champ*/ "montant", /*agregat*/ uo_croise.AGG_SUM)

// 3. Presenter : format des montants et totaux generaux
uo_croise.of_set_value_format(/*champ*/ "montant", /*decimales*/ 0, /*milliers*/ "locale", /*symbole*/ "$", /*symbole_avant*/ 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)
// L'utilisateur veut le detail derriere un chiffre : ouvrir la liste correspondante.
of_ouvrir_detail(as_row_tuple_json, as_col_tuple_json)

Constantes #

Les constantes d'agrégation se lisent sur le composant : uo_croise.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…).

n_pbt_crosstab_field lnv_champ

lnv_champ = uo_croise.of_field(/*champ*/ "montant")
lnv_champ.is_label = "Chiffre d'affaires"
lnv_champ.is_conditional_formatting = lnv_champ.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), AGG_AVG, AGG_MIN, AGG_MAX.

Totaux et sous-totaux #

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.

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

Exemples #

Un rapport de ventes complet #

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

// Colonnes : une par annee
uo_croise.of_add_col_field(/*champ*/ "annee")

// Cellules : le montant total
uo_croise.of_add_value_field(/*champ*/ "montant", /*agregat*/ uo_croise.AGG_SUM)

// Presentation : montants lisibles, sous-totaux et totaux generaux
uo_croise.of_set_value_format(/*champ*/ "montant", /*decimales*/ 0, /*milliers*/ "locale", /*symbole*/ "$", /*symbole_avant*/ true)
uo_croise.ib_row_subtotals = true
uo_croise.ib_row_grand_total = true
uo_croise.ib_col_grand_total = true

// Colorer les cellules pour reperer les gros montants d'un coup d'oeil
uo_croise.of_field(/*champ*/ "montant").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_set_data.

uo_croise.of_set_data(lds)

uo_croise.of_field("region").is_label    = "Region"
uo_croise.of_field("ville").is_label     = "Ville"
uo_croise.of_field("categorie").is_label = "Categorie"
uo_croise.of_field("annee").is_label     = "Annee"
uo_croise.of_field("montant").is_label   = "Chiffre d'affaires"
uo_croise.of_field("quantite").is_label  = "Quantite"

Analyser des parts plutôt que des montants #

n_pbt_crosstab_field lnv_montant

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

// Ne garder que deux categories a l'ecran (valeurs separees par une tabulation)
uo_croise.of_set_member_filter(/*champ*/ "categorie", /*valeurs*/ "Informatique~tMobilier")

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

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

// Une petite barre dans chaque cellule pour comparer les parts d'un regard
lnv_montant.is_conditional_formatting = lnv_montant.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.

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

// Les deux totaux qui vont servir de base au calcul
uo_croise.of_add_value_field(/*champ*/ "montant",  /*agregat*/ uo_croise.AGG_SUM)
uo_croise.of_add_value_field(/*champ*/ "quantite", /*agregat*/ uo_croise.AGG_SUM)

// Prix moyen = montant total divise par quantite totale
uo_croise.of_add_calc_measure(/*nom*/ "prix_moyen", /*libelle*/ "Prix moyen", &
                              /*formule*/ "[montant] / [quantite]")
uo_croise.of_set_value_format(/*champ*/ "prix_moyen", /*decimales*/ 2, /*milliers*/ "locale", /*symbole*/ "$", /*symbole_avant*/ true)

// Puis la placer parmi les valeurs comme n'importe quel champ (l'agregat ne compte pas : une mesure se calcule)
uo_croise.of_add_value_field(/*champ*/ "prix_moyen", /*agregat*/ uo_croise.AGG_SUM)

// event ue_calc_field_error de uo_croise : (string as_field, string as_message)
// Formule invalide : prevenir sans rien casser, le tableau reste affiche.
uo_statut.of_item("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 date_vente
uo_croise.of_group_date_field(/*champ*/ "date_vente", /*niveau*/ "year")
uo_croise.of_group_date_field(/*champ*/ "date_vente", /*niveau*/ "quarter")
uo_croise.of_group_date_field(/*champ*/ "date_vente", /*niveau*/ "month")

// Puis les croiser comme n'importe quel champ : annee en colonnes, trimestre en dessous
uo_croise.of_add_col_field("date_vente__year")
uo_croise.of_add_col_field("date_vente__quarter")

Le palmarès des dix meilleures régions #

// Ne garder que les 10 regions au plus fort total sur la premiere mesure
uo_croise.of_set_value_filter(/*champ*/ "region", /*type*/ "top", &
                              /*a*/ 10, /*b*/ 0, /*mesure*/ 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_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 = 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_croise.of_export_csv(/*chemin*/ "C:\exports\ventes.csv")

Offrir des vues enregistrées #

string ls_vue

// Enregistrer la vue courante : of_get_layout la rend tout de suite
ls_vue = uo_croise.of_get_layout()

// Conserver le contenu TEL QUEL : il se rejoue sans transformation.
of_enregistrer_vue(is_vue_courante, ls_vue)

// Plus tard : rejouer une vue enregistree
uo_croise.of_set_layout(of_lire_vue("Ventes par region"))

Descendre au détail derrière un chiffre #

// event ue_cell_double_clicked de uo_croise : (string as_row_tuple_json, string as_col_tuple_json, 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_detail_ventes lw_detail

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

Bonnes pratiques #

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