From 913652d864bb008b52170b7d0e06f2062e544dc9 Mon Sep 17 00:00:00 2001 From: reugenio Date: Sat, 27 Dec 2025 19:08:18 +0100 Subject: [PATCH] docs(TABLES_ARCHITECTURE): Update with FASE 4.5 - TableDataSource MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add TableDataSource interface documentation - Add adaptadores (MemoryDataSource, PagedDataSource) - Add drawRowsWithDataSource function docs - Update file structure with new datasource files - Add section 'Cómo Crear un Nuevo Tipo de Tabla' --- docs/TABLES_ARCHITECTURE.md | 90 +++++++++++++++++++++++++++++++------ 1 file changed, 76 insertions(+), 14 deletions(-) diff --git a/docs/TABLES_ARCHITECTURE.md b/docs/TABLES_ARCHITECTURE.md index 16ce34f..e7eb958 100644 --- a/docs/TABLES_ARCHITECTURE.md +++ b/docs/TABLES_ARCHITECTURE.md @@ -1,7 +1,7 @@ # Arquitectura de Tablas en zcatgui > **Documento de referencia definitivo** para entender, usar y extender los widgets de tabla. -> Actualizado: 2025-12-27 +> Actualizado: 2025-12-27 (FASE 4.5 completada - rendering unificado) --- @@ -49,20 +49,24 @@ zcatgui proporciona **dos widgets de tabla** que comparten lógica común: │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ table_core.zig │ │ │ │ │ │ -│ │ LÓGICA COMÚN (un solo lugar para modificar): │ │ +│ │ RENDERING UNIFICADO (FASE 4.5): │ │ +│ │ - drawRowsWithDataSource() [Dibuja filas con DataSource] │ │ +│ │ - drawStateIndicator() [Indicador estado fila] │ │ +│ │ - TableDataSource [Interface vtable] │ │ +│ │ - MemoryDataSource [Adaptador datos memoria] │ │ +│ │ - PagedDataSource [Adaptador datos paginados] │ │ +│ │ │ │ +│ │ LÓGICA COMÚN: │ │ │ │ - calculateNextCell() / calculatePrevCell() [Tab navigation] │ │ │ │ - toggleSort() [Ordenación] │ │ │ │ - handleEditingKeyboard() [Edición celda] │ │ │ │ - detectDoubleClick() [Doble-click] │ │ -│ │ - drawCellActiveIndicator() [Renderizado] │ │ -│ │ - drawEditingOverlay() [Overlay edición] │ │ │ │ - blendColor(), startsWithIgnoreCase() [Utilidades] │ │ │ │ │ │ │ │ TIPOS COMPARTIDOS: │ │ -│ │ - TabNavigateResult, CellPosition │ │ -│ │ - SortDirection, SortToggleResult │ │ -│ │ - TableColors, CellRenderInfo, EditState │ │ -│ │ - EditKeyboardResult, DoubleClickState │ │ +│ │ - RowState (normal/modified/new/deleted/error) │ │ +│ │ - TabNavigateResult, CellPosition, CellEditState │ │ +│ │ - DrawRowsConfig, RowRenderColors, ColumnRenderDef │ │ │ └─────────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────────┘ ``` @@ -73,19 +77,21 @@ zcatgui proporciona **dos widgets de tabla** que comparten lógica común: ``` src/widgets/ -├── table_core.zig # LÓGICA COMÚN - modificar aquí +├── table_core.zig # LÓGICA COMÚN + RENDERING UNIFICADO │ ├── advanced_table/ # Tabla con datos en memoria -│ ├── advanced_table.zig # Widget principal -│ ├── state.zig # Estado (usa table_core) +│ ├── advanced_table.zig # Widget principal (usa drawRowsWithDataSource) +│ ├── datasource.zig # MemoryDataSource (adaptador) +│ ├── state.zig # Estado (embeds CellEditState) │ ├── types.zig # Tipos específicos │ └── schema.zig # Definición de columnas │ └── virtual_advanced_table/ # Tabla con datos paginados - ├── virtual_advanced_table.zig # Widget principal - ├── state.zig # Estado (usa table_core) + ├── virtual_advanced_table.zig # Widget principal (usa drawRowsWithDataSource) + ├── paged_datasource.zig # PagedDataSource (adaptador) + ├── state.zig # Estado (embeds CellEditState) ├── types.zig # Tipos específicos - └── data_provider.zig # Interface para datos + └── data_provider.zig # Interface para datos BD ``` --- @@ -139,6 +145,62 @@ if (result.selection_changed) { --- +## TableDataSource: Rendering Unificado (FASE 4.5) + +A partir de la FASE 4.5, ambas tablas usan la misma función `drawRowsWithDataSource()` para renderizar filas. Esto se logra mediante el patrón **adaptador con vtable**. + +### Interface TableDataSource + +```zig +pub const TableDataSource = struct { + ptr: *anyopaque, + vtable: *const VTable, + + pub const VTable = struct { + getRowCount: *const fn (ptr: *anyopaque) usize, + getCellValueInto: *const fn (ptr: *anyopaque, row: usize, col: usize, buf: []u8) []const u8, + getRowId: *const fn (ptr: *anyopaque, row: usize) i64, + isCellEditable: *const fn (ptr: *anyopaque, row: usize, col: usize) bool, + invalidate: *const fn (ptr: *anyopaque) void, + getRowState: ?*const fn (ptr: *anyopaque, row: usize) RowState = null, + }; +}; +``` + +### Adaptadores + +| Adaptador | Tabla | Datos | +|-----------|-------|-------| +| `MemoryDataSource` | AdvancedTable | ArrayList en memoria | +| `PagedDataSource` | VirtualAdvancedTable | Ventana paginada | + +### Función de Rendering Unificada + +```zig +pub fn drawRowsWithDataSource( + ctx: *Context, + datasource: TableDataSource, + config: DrawRowsConfig, + cell_buffer: []u8, +) usize +``` + +**Características:** +- Dibuja filas con colores por estado (modified, new, deleted, error) +- Indicador de estado (columna izquierda con círculo de color) +- Celda activa con highlight +- Fila seleccionada con color diferenciado +- Bordes de fila opcionales + +### Cómo Crear un Nuevo Tipo de Tabla + +Si necesitas un tercer tipo de tabla (ej. streaming en tiempo real): + +1. Crear adaptador que implemente `TableDataSource.VTable` +2. El rendering ya está hecho - solo provees datos via `getCellValueInto()` + +--- + ## Cómo Extender la Funcionalidad ### Regla de Oro (Norma #7 DRY)