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
|
# Arquitectura de Tablas en zcatgui
|
||||||
|
|
||||||
> **Documento de referencia definitivo** para entender, usar y extender los widgets de tabla.
|
> **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 │ │
|
│ │ 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] │ │
|
│ │ - calculateNextCell() / calculatePrevCell() [Tab navigation] │ │
|
||||||
│ │ - toggleSort() [Ordenación] │ │
|
│ │ - toggleSort() [Ordenación] │ │
|
||||||
│ │ - handleEditingKeyboard() [Edición celda] │ │
|
│ │ - handleEditingKeyboard() [Edición celda] │ │
|
||||||
│ │ - detectDoubleClick() [Doble-click] │ │
|
│ │ - detectDoubleClick() [Doble-click] │ │
|
||||||
│ │ - drawCellActiveIndicator() [Renderizado] │ │
|
|
||||||
│ │ - drawEditingOverlay() [Overlay edición] │ │
|
|
||||||
│ │ - blendColor(), startsWithIgnoreCase() [Utilidades] │ │
|
│ │ - blendColor(), startsWithIgnoreCase() [Utilidades] │ │
|
||||||
│ │ │ │
|
│ │ │ │
|
||||||
│ │ TIPOS COMPARTIDOS: │ │
|
│ │ TIPOS COMPARTIDOS: │ │
|
||||||
│ │ - TabNavigateResult, CellPosition │ │
|
│ │ - RowState (normal/modified/new/deleted/error) │ │
|
||||||
│ │ - SortDirection, SortToggleResult │ │
|
│ │ - TabNavigateResult, CellPosition, CellEditState │ │
|
||||||
│ │ - TableColors, CellRenderInfo, EditState │ │
|
│ │ - DrawRowsConfig, RowRenderColors, ColumnRenderDef │ │
|
||||||
│ │ - EditKeyboardResult, DoubleClickState │ │
|
|
||||||
│ └─────────────────────────────────────────────────────────────────┘ │
|
│ └─────────────────────────────────────────────────────────────────┘ │
|
||||||
└─────────────────────────────────────────────────────────────────────────┘
|
└─────────────────────────────────────────────────────────────────────────┘
|
||||||
```
|
```
|
||||||
|
|
@ -73,19 +77,21 @@ zcatgui proporciona **dos widgets de tabla** que comparten lógica común:
|
||||||
|
|
||||||
```
|
```
|
||||||
src/widgets/
|
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/ # Tabla con datos en memoria
|
||||||
│ ├── advanced_table.zig # Widget principal
|
│ ├── advanced_table.zig # Widget principal (usa drawRowsWithDataSource)
|
||||||
│ ├── state.zig # Estado (usa table_core)
|
│ ├── datasource.zig # MemoryDataSource (adaptador)
|
||||||
|
│ ├── state.zig # Estado (embeds CellEditState)
|
||||||
│ ├── types.zig # Tipos específicos
|
│ ├── types.zig # Tipos específicos
|
||||||
│ └── schema.zig # Definición de columnas
|
│ └── schema.zig # Definición de columnas
|
||||||
│
|
│
|
||||||
└── virtual_advanced_table/ # Tabla con datos paginados
|
└── virtual_advanced_table/ # Tabla con datos paginados
|
||||||
├── virtual_advanced_table.zig # Widget principal
|
├── virtual_advanced_table.zig # Widget principal (usa drawRowsWithDataSource)
|
||||||
├── state.zig # Estado (usa table_core)
|
├── paged_datasource.zig # PagedDataSource (adaptador)
|
||||||
|
├── state.zig # Estado (embeds CellEditState)
|
||||||
├── types.zig # Tipos específicos
|
├── 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
|
## Cómo Extender la Funcionalidad
|
||||||
|
|
||||||
### Regla de Oro (Norma #7 DRY)
|
### Regla de Oro (Norma #7 DRY)
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue