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

// 1. Transmitir los datos: los campos se deducen de las columnas
uo_crosstab.of_from_datastore(/*data*/ lds)

// 2. Repartir los campos en las areas
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. Presentar: formato de los importes y totales generales
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)
// El usuario quiere el detalle que hay detras de una cifra: abrir la lista correspondiente.
of_open_detail(as_row_tuple_json, as_col_tuple_json)

Constantes #

Las constantes de agregación se leen en el componente: uo_crosstab.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…). Puestos antes de que el campo esté en Valores, se conservan, se releen tal cual y se aplican a su llegada.

// Local variables
n_pbt_crosstab_field lnv_field

// El campo importe : su etiqueta y una escala de colores
lnv_field = uo_crosstab.of_field(/*field*/ "amount")
lnv_field.is_label = "Facturación"
lnv_field.is_conditional_formatting = lnv_field.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, las celdas vacías se ignoran como en Excel), AGG_AVG, AGG_MIN, AGG_MAX.

Totales y subtotales #

Los totales se ajustan mediante propiedades, descritas más arriba: ib_row_grand_total y ib_col_grand_total para los totales generales, ib_row_subtotals y ib_col_subtotals para los subtotales, is_totals_position para la posición de la fila del total general.

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, con sus encabezados para que un pegado en una hoja de cálculo diga qué son las cifras (ib_copy_headers).

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í. Mayús+F10 o la tecla Menú también abren ese menú, y el foco sigue al campo recién movido, incluso a otra zona.

Ejemplos #

Un informe de ventas completo #

// Filas: region y luego ciudad dentro de cada region
uo_crosstab.of_clear_layout()
uo_crosstab.of_add_row_field(/*field*/ "region")
uo_crosstab.of_add_row_field(/*field*/ "city")

// Columnas: una por ano
uo_crosstab.of_add_col_field(/*field*/ "year")

// Celdas: el importe total
uo_crosstab.of_add_value_field(/*field*/ "amount", /*agg*/ uo_crosstab.AGG_SUM)

// Presentacion: importes legibles, subtotales y totales generales
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

// Colorear las celdas para detectar los importes altos de un vistazo
uo_crosstab.of_field(/*field*/ "amount").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_from_datastore.

// Primero los datos : los campos toman el nombre de las columnas
uo_crosstab.of_from_datastore(/*data*/ lds)

// Luego una etiqueta legible para cada campo
uo_crosstab.of_field(/*field*/ "region").is_label    = "Región"
uo_crosstab.of_field(/*field*/ "city").is_label     = "Ciudad"
uo_crosstab.of_field(/*field*/ "category").is_label = "Categoría"
uo_crosstab.of_field(/*field*/ "year").is_label     = "Año"
uo_crosstab.of_field(/*field*/ "amount").is_label   = "Facturación"
uo_crosstab.of_field(/*field*/ "quantity").is_label  = "Cantidad"

Analizar porcentajes en lugar de importes #

// Local variables
n_pbt_crosstab_field lnv_amount

// Partir de areas vacias y luego colocar los campos
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)

// Conservar solo dos categorias en pantalla (valores separados por una tabulacion)
uo_crosstab.of_set_member_filter(/*field*/ "category", /*values_tab*/ "Informatique~tMobilier")

// El campo importe, para ajustar como se muestra
lnv_amount = uo_crosstab.of_field(/*field*/ "amount")

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

// Una pequena barra en cada celda para comparar las partes de un vistazo
lnv_amount.is_conditional_formatting = lnv_amount.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.

// Partir de areas vacias y luego colocar los campos
uo_crosstab.of_clear_layout()
uo_crosstab.of_add_row_field(/*field*/ "region")

// Los dos totales que serviran de base al calculo
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)

// Precio medio = importe total dividido por la cantidad total
uo_crosstab.of_add_calc_measure(/*name*/ "avg_price", /*label*/ "Precio medio", /*formula*/ "[amount] / [quantity]")
uo_crosstab.of_set_value_format(/*field*/ "avg_price", /*decimals*/ 2, /*thousands*/ "locale", /*suffix*/ "$", /*symbol_before*/ true)

// Luego colocarla entre los valores como cualquier campo (el agregado no importa: una medida se calcula)
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)
// Formula no valida: avisar sin romper nada, la tabla sigue mostrandose.
uo_status.of_panel(/*key*/ "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 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")

// Despues cruzarlos como cualquier otro campo: ano en columnas, trimestre debajo
uo_crosstab.of_add_col_field(/*field*/ "sale_date__year")
uo_crosstab.of_add_col_field(/*field*/ "sale_date__quarter")

El ranking de las diez mejores regiones #

// Conservar solo las 10 regiones con el total mas alto sobre la primera medida
uo_crosstab.of_set_value_filter(/*field*/ "region", /*type*/ "top", /*a*/ 10, /*b*/ 0, /*measure_index*/ 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_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 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_crosstab.of_export_csv(/*path*/ "C:\exports\ventes.csv")

Ofrecer vistas guardadas #

// Local variables
string ls_view

// Guardar la vista actual : of_get_layout responde de inmediato
ls_view = uo_crosstab.of_get_layout()

// Conservar el contenido TAL CUAL : se reproduce sin transformacion.
of_save_view(is_current_view, ls_view)

// Mas tarde: reproducir una vista guardada
uo_crosstab.of_set_layout(/*state_json*/ of_read_view("Ventes par region"))

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

// event ue_cell_double_clicked de uo_crosstab: (string as_row_tuple_json, string as_col_tuple_json, integer ai_measure, 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_sales_detail lw_detail

// Abrir la ventana de detalle con el cruce como parametro
OpenWithParm(lw_detail, as_row_tuple_json + "|" + as_col_tuple_json)

Las dos tuplas y ai_measure forman la dirección de la celda: of_get_cell_value la vuelve a leer más tarde, tal como la tabla la muestra en ese 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 celda también se lee sin clic, por sus miembros: una tupla parcial designa un subtotal. Y of_remove_field quita un campo de todas sus áreas de una vez, filtros incluidos.

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

Buenas prácticas #

• Llame a of_from_datastore 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_from_datastore: 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