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
// Local variables
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(/*ads*/ 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_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)
// 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, de filtro, de fecha y de separador se leen en el componente: uo_crosstab.AGG_SUM. Las de un campo o de un valor (SHOW_*, CF_*) se leen en la clase de su handle: n_pbt_crosstab_field.CF_SCALE, n_pbt_crosstab_value.SHOW_PCT_GRAND. AGG_COUNT cuenta los valores no vacíos, como la Cuenta de Excel; AGG_COUNT_ROWS cuenta las filas, vacías incluidas.

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…). Fijados en el campo, is_show, is_conditional_formatting e is_format valen para todos sus valores del área Valores y para los que entren después — puestos antes de que el campo esté en Valores, se conservan, se releen tal cual y se aplican a su llegada. Para un solo valor (el mismo campo dos veces: el importe, y su parte del total), se usa el handle del valor, a continuación.

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

Propiedades de un valor #

of_value (integer ai_position) devuelve el handle de un valor del área Valores, por su posición (1 = el primero). Un campo puede estar allí dos veces — el importe, y su parte del total general — y cada valor tiene sus propios ajustes, que prevalecen sobre los de su campo. El handle designa una posición: tras of_remove_value, of_move_value, of_remove_field, of_remove_calc_measure, of_clear_layout u of_set_layout se libera — vuelva a pedir of_value. Sus constantes SHOW_* y CF_* son las de n_pbt_crosstab_field.

// Local variables
n_pbt_crosstab_value lnv_share, lnv_amount

// El importe dos veces en Valores : la suma, luego su parte del 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)

// Solo el segundo valor : su parte del total general, con su propia etiqueta
lnv_share = uo_crosstab.of_value(/*position*/ 2)
lnv_share.is_show = n_pbt_crosstab_value.SHOW_PCT_GRAND
lnv_share.is_label = "Parte de las ventas"

// El primer valor : dos decimales, los negativos en rojo
lnv_amount = uo_crosstab.of_value(/*position*/ 1)
lnv_amount.is_format = "#,##0.00"
lnv_amount.ib_negative_red = true

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 (el número de valores no vacíos, como la Cuenta de Excel), AGG_COUNT_ROWS (el número de filas, vacías incluidas), AGG_DISTINCT_COUNT (recuento de valores distintos, las celdas vacías se ignoran como en Excel), AGG_AVG, AGG_MIN, AGG_MAX. Una suma sin ningún valor es una celda vacía, no 0; una « diferencia respecto al anterior » en la que una de las dos celdas está vacía también está vacía. Los porcentajes se escriben como los escribe el idioma de visualización (57.9% en inglés, 57,9 % en francés).

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. El menú Opciones de la cuadrícula (el engranaje) ofrece los mismos cuatro interruptores, una entrada por eje: Fila de total general, Columna de total general, Subtotales de filas, Subtotales de columnas.

Filtrar #

Los valores que esperan of_set_member_filter y of_set_member_order son los que la cuadrícula guarda, no siempre los que muestra: en un campo derivado de una fecha, un mes se escribe "01"…"12", un trimestre "1"…"4", un año "2024"; un miembro fecha no agrupado se escribe yyyy-mm-dd. El usuario, por su parte, encuentra el filtro de etiqueta en el menú del chip de cualquier campo — texto, número o fecha.

Dar formato #

El formato de un valor se fija mediante una propiedad: of_field("amount").is_format = "$#,##0.00" para todos los valores de un campo, of_value(2).is_format para uno solo (véase Propiedades de un campo y Propiedades de un valor). Es un formato de visualización de PowerBuilder, leído por el motor de máscaras de la biblioteca; vacío, el valor toma el Format de la columna del DataWindow. Los negativos en rojo: of_value(n).ib_negative_red = true. El separador de miles de los valores sin formato sigue siendo is_thousands, la moneda del menú del chip is_currency_symbol.

Fechas y campos calculados #

Una fórmula acepta los operadores + - * / ( ), números (12, 0.5, .5, 1e3, siempre con punto) y campos entre corchetes; ^ no es un operador. 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, salvo la copia (que dispara ue_copy), 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. La construcción de la tabla se hace sin ratón — chips, menús, plegado y ordenació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. Seleccionar celdas y copiarlas (Ctrl+C) requiere hoy el ratón.

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

// 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(/*ads*/ 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_field(/*field*/ "avg_price").is_format = "$#,##0.00"

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

// 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*/ uo_crosstab.VALUEFILTER_TOP, /*a*/ 10, /*b*/ 0, /*measure_index*/ 1)

En un campo situado bajo otro, la clasificación se hace dentro de cada padre: la mejor ciudad de cada región, no la mejor ciudad del país. Los empates se quedan todos.

// Las ciudades bajo las regiones
uo_crosstab.of_add_row_field(/*field*/ "region")
uo_crosstab.of_add_row_field(/*field*/ "city")

// La mejor ciudad de cada region, sobre la primera medida
uo_crosstab.of_set_value_filter(/*field*/ "city", /*type*/ uo_crosstab.VALUEFILTER_TOP, /*a*/ 1, /*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)
// Local variables
long ll_rows[], ll_count, ll_i

// Las filas del DataStore detras de la cifra con doble clic
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)

// Nada que mostrar : ninguna fila, o una celda que no puede leerse ahora
if ll_count <= 0 then return

// Copiarlas en la lista de detalle : ids_sales es el DataStore dado 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

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