crosstab — u_pbt_crosstab #

← Referencia de componentes · Índice de la guía

Tabla dinámica completa: áreas de filas / columnas / valores alimentadas desde un DataStore, agregaciones, filtros, formato condicional, agrupación de fechas, medidas calculadas y exportaciones CSV / Excel.

▶ Verlo en vivo — Aplicación de demostración, mosaico Crosstab: la vista previa, el código que lo genera y esta página, uno al lado del otro.

De un vistazo #

El principio #

Usted proporciona al componente un conjunto de datos plano — un DataStore, es decir, cualquier consulta ya escrita en su aplicación. Del resto se encarga la tabla dinámica: deduce la lista de campos y usted los reparte en cuatro áreas.

Todo el cálculo se realiza en el componente: una vez transmitidos los datos, reorganizar la tabla no provoca ninguna ida y vuelta a la base de datos ni a PowerBuilder.

Inicio rápido #

// event open de la ventana
datastore lds
lds = create datastore
lds.dataobject = "d_ventes"
lds.SetTransObject(SQLCA)
lds.Retrieve()

// 1. Transmitir los datos: los campos se deducen de las columnas
uo_croise.of_set_data(lds)

// 2. Repartir los campos en las areas
uo_croise.of_add_row_field(/*campo*/ "region")
uo_croise.of_add_col_field(/*campo*/ "annee")
uo_croise.of_add_value_field(/*campo*/ "montant", /*agregacion*/ uo_croise.AGG_SUM)

// 3. Presentar: formato de los importes y totales generales
uo_croise.of_set_value_format(/*campo*/ "montant", /*decimales*/ 0, /*miles*/ "locale", /*simbolo*/ "$", /*simbolo_delante*/ 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)
// El usuario quiere el detalle que hay detras de una cifra: abrir la lista correspondiente.
of_ouvrir_detail(as_row_tuple_json, as_col_tuple_json)

Constantes #

Las constantes de agregación se leen en el componente: uo_croise.AGG_SUM. Las de un campo (SHOW_*, CF_*) se leen en el handle del campo.

Propiedades #

Propiedades de un campo #

of_field (string as_field) devuelve el handle de un campo: usted lo obtiene una vez y luego gobierna el campo a través de sus propiedades. El handle se crea en la primera llamada y se reutiliza después.

Los valores de is_show y de is_conditional_formatting también están disponibles como constantes en el handle (SHOW_PCT_COL, CF_SCALE…).

n_pbt_crosstab_field lnv_champ

lnv_champ = uo_croise.of_field(/*campo*/ "montant")
lnv_champ.is_label = "Facturación"
lnv_champ.is_conditional_formatting = lnv_champ.CF_SCALE

⚠️ Cambio incompatible. Esta propiedad se llamaba is_cf: la abreviatura no decía nada en el punto de llamada. El nombre antiguo ya no existe: un código que lo utilice no compila. La sustitución es mecánica: is_cf → is_conditional_formatting, sin cambio de valores ni de comportamiento.

Métodos #

Alimentar y nombrar #

Construir la tabla #

Las agregaciones aceptadas por of_add_value_field las publica el componente como constantes: AGG_SUM (predeterminado), AGG_COUNT, AGG_DISTINCT_COUNT (recuento de valores distintos), AGG_AVG, AGG_MIN, AGG_MAX.

Totales y subtotales #

Filtrar #

Dar formato #

Fechas y campos calculados #

Una fórmula acepta los operadores + - * / ( ), números y campos entre corchetes. Una fórmula no válida dispara ue_calc_field_error — nada se bloquea.

Desplegar, memorizar, exportar #

Comunes #

Eventos #

Lo que el usuario puede hacer sin una línea de código #

La tabla está viva: es todo el interés del componente. Con el panel de campos visible (ib_field_list = true), el usuario puede:

• arrastrar un campo de un área a otra y reorganizar el cruce a voluntad;
• cambiar la agregación de una medida (suma, media, recuento…);
• filtrar los valores de un campo mediante una lista de casillas;
• plegar o desplegar un grupo de filas o de columnas;
• ordenar desde un encabezado;
• seleccionar y luego copiar un bloque de celdas.

Cada una de estas manipulaciones se notifica en ue_layout_changed: unido a of_get_layout / of_set_layout, esto permite ofrecer «vistas guardadas» a sus usuarios.

Con el teclado. Cada uno de esos gestos es alcanzable sin ratón: Tab lleva a un campo, a un triángulo de plegado o a un encabezado ordenable, Intro o Espacio lo dispara. Sobre un campo abre su menú — el que lleva Añadir a las filas / a las columnas / a los valores / a los filtros y Quitar: toda la construcción de la tabla pasa por ahí.

Ejemplos #

Un informe de ventas completo #

// Filas: region y luego ciudad dentro de cada region
uo_croise.of_clear_layout()
uo_croise.of_add_row_field(/*campo*/ "region")
uo_croise.of_add_row_field(/*campo*/ "ville")

// Columnas: una por ano
uo_croise.of_add_col_field(/*campo*/ "annee")

// Celdas: el importe total
uo_croise.of_add_value_field(/*campo*/ "montant", /*agregacion*/ uo_croise.AGG_SUM)

// Presentacion: importes legibles, subtotales y totales generales
uo_croise.of_set_value_format(/*campo*/ "montant", /*decimales*/ 0, /*miles*/ "locale", /*simbolo*/ "$", /*simbolo_delante*/ true)
uo_croise.ib_row_subtotals = true
uo_croise.ib_row_grand_total = true
uo_croise.ib_col_grand_total = true

// Colorear las celdas para detectar los importes altos de un vistazo
uo_croise.of_field(/*campo*/ "montant").is_conditional_formatting = n_pbt_crosstab_field.CF_SCALE

Etiquetas legibles #

Sus columnas suelen llamarse mt_ht o cd_reg. Cámbieles el nombre de una vez por todas, justo después de of_set_data.

uo_croise.of_set_data(lds)

uo_croise.of_field("region").is_label    = "Región"
uo_croise.of_field("ville").is_label     = "Ciudad"
uo_croise.of_field("categorie").is_label = "Categoría"
uo_croise.of_field("annee").is_label     = "Año"
uo_croise.of_field("montant").is_label   = "Facturación"
uo_croise.of_field("quantite").is_label  = "Cantidad"

Analizar porcentajes en lugar de importes #

n_pbt_crosstab_field lnv_montant

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

// Conservar solo dos categorias en pantalla (valores separados por una tabulacion)
uo_croise.of_set_member_filter(/*campo*/ "categorie", /*valores*/ "Informatique~tMobilier")

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

// Mostrar la parte de cada celda en el total de su columna
lnv_montant.is_show = lnv_montant.SHOW_PCT_COL

// Una pequena barra en cada celda para comparar las partes de un vistazo
lnv_montant.is_conditional_formatting = lnv_montant.CF_BARS

Una medida propia: el precio medio #

Una medida calculada se evalúa sobre los totales de cada celda, no fila a fila: eso es lo que hace correcto un ratio.

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

// Los dos totales que serviran de base al calculo
uo_croise.of_add_value_field(/*campo*/ "montant",  /*agregacion*/ uo_croise.AGG_SUM)
uo_croise.of_add_value_field(/*campo*/ "quantite", /*agregacion*/ uo_croise.AGG_SUM)

// Precio medio = importe total dividido por la cantidad total
uo_croise.of_add_calc_measure(/*nombre*/ "prix_moyen", /*etiqueta*/ "Precio medio", &
                              /*formula*/ "[montant] / [quantite]")
uo_croise.of_set_value_format(/*campo*/ "prix_moyen", /*decimales*/ 2, /*miles*/ "locale", /*simbolo*/ "$", /*simbolo_delante*/ true)

// Luego colocarla entre los valores como cualquier campo (el agregado no importa: una medida se calcula)
uo_croise.of_add_value_field(/*campo*/ "prix_moyen", /*agregado*/ uo_croise.AGG_SUM)

// event ue_calc_field_error de uo_croise: (string as_field, string as_message)
// Formula no valida: avisar sin romper nada, la tabla sigue mostrandose.
uo_statut.of_item("main").is_text = "Fórmula " + as_field + " : " + as_message

Analizar por mes, trimestre o año #

Una columna de fecha no se cruza tal cual — cada día formaría su propia fila. Derive primero el nivel deseado.

// Crear tres campos derivados de la columna date_vente
uo_croise.of_group_date_field(/*campo*/ "date_vente", /*nivel*/ "year")
uo_croise.of_group_date_field(/*campo*/ "date_vente", /*nivel*/ "quarter")
uo_croise.of_group_date_field(/*campo*/ "date_vente", /*nivel*/ "month")

// Despues cruzarlos como cualquier otro campo: ano en columnas, trimestre debajo
uo_croise.of_add_col_field("date_vente__year")
uo_croise.of_add_col_field("date_vente__quarter")

El ranking de las diez mejores regiones #

// Conservar solo las 10 regiones con el total mas alto sobre la primera medida
uo_croise.of_set_value_filter(/*campo*/ "region", /*tipo*/ "top", &
                              /*a*/ 10, /*b*/ 0, /*medida*/ 1)

Exportar #

La exportación reproduce exactamente la vista actual: los mismos filtros, los mismos totales, el mismo formato.

// Hacia Excel: el archivo se escribe directamente en la ruta indicada
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 declarado como variable de instancia de la ventana
if ab_ok then
    inv_notif.is_title = "Exportación finalizada"
    inv_notif.is_text  = as_path
    inv_notif.is_kind  = inv_notif.KIND_SUCCESS
else
    inv_notif.is_title = "Exportación imposible"
    inv_notif.is_text  = as_error
    inv_notif.is_kind  = inv_notif.KIND_ERROR
end if
inv_notif.of_show()

// Hacia CSV: un archivo, como para Excel; ue_csv_saved confirma
uo_croise.of_export_csv(/*ruta*/ "C:\exports\ventes.csv")

Ofrecer vistas guardadas #

string ls_vue

// Guardar la vista actual : of_get_layout responde de inmediato
ls_vue = uo_croise.of_get_layout()

// Conservar el contenido TAL CUAL : se reproduce sin transformacion.
of_enregistrer_vue(is_vue_courante, ls_vue)

// Mas tarde: reproducir una vista guardada
uo_croise.of_set_layout(of_lire_vue("Ventes par region"))

Bajar al detalle que hay detrás de una cifra #

// event ue_cell_double_clicked de uo_croise: (string as_row_tuple_json, string as_col_tuple_json, double ad_value)
// Los dos primeros argumentos describen el cruce (que valores de filas,
// que valores de columnas): lo suficiente para reconstruir una consulta de detalle.
w_detail_ventes lw_detail

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

Buenas prácticas #

• Llame a of_set_data una sola vez por conjunto de datos: reorganizar la tabla después no cuesta nada, retransmitir los datos sale caro.
• Ponga las etiquetas (of_field("...").is_label) justo después de of_set_data: siguen al campo a todas partes, incluidos el panel de campos y las exportaciones.
• Filtre en el lado SQL lo que no está destinado a ser analizado: la tabla dinámica es rápida, pero un DataStore la mitad de grande se abre el doble de rápido.
• of_clear_layout() vacía las áreas sin retransmitir los datos: es la llamada adecuada para proponer varios análisis sobre la misma fuente.
• Un campo de fecha se cruza siempre mediante of_group_date_field, nunca directamente.
• Deje el panel de campos visible en las pantallas de análisis y ocúltelo en los cuadros de mando fijos.

Heredado de la base común #

Estos miembros existen en todos los componentes visuales — no son propios de este. Se detallan una sola vez, en los capítulos transversales; esta tabla solo dice dónde leerlos.

Dos ayudas no se heredan: of_icon y of_escape_markup viven en n_pbt_utils. Declare uno — n_pbt_utils lnv_utils, nada que crear — y llámelas sobre él.

← Referencia de componentes · Índice de la guía