docs(TABLES_ARCHITECTURE): Update with FASE 4.5 - TableDataSource
- 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'
This commit is contained in:
parent
08ffcdbac5
commit
913652d864
1 changed files with 76 additions and 14 deletions
|
|
@ -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)
|
||||
|
|
|
|||
Loading…
Reference in a new issue