TrinaGrid

Switching from uniform to variable row heights changes how the underlying list renders:

• Uniform Heights: Uses ListView.builder with itemExtent, which is highly efficient for large datasets.
• Variable Heights: Uses ListView.builder without itemExtent, requiring more complex scroll calculations and potentially reducing performance.

Mitigation Strategies:

• Set heights at creation time whenever possible.
• Limit the number of variable-height rows.
• For very large datasets, consider implementing lazy height calculation or keeping most rows at a uniform height.

Column Movement

• If a column is moved outside its group, it is removed from that group.
• If all columns are removed from a group, the group is automatically removed.
• Moving columns between groups updates the group structure automatically.

Column Hiding

• If all columns in a group are hidden, the group is not displayed.
• When a hidden column is shown again, it returns to its original group.

Column Resizing

• Resizing a column affects only that specific column.
• The group width automatically adjusts to accommodate the total width of its constituent columns.

TrinaGrid supports two levels of rendering customization:

1. Column-level rendering: Applied via TrinaColumn to all cells within that specific column.
2. Cell-level rendering: Applied via the renderer property on a TrinaCell instance to customize a specific individual cell.

Precedence Rule: When both are defined, the cell-level renderer takes precedence over the column-level renderer.

// Column-level renderer (applies to all cells in the column)
TrinaColumn(
  title: 'Status',
  field: 'status',
  type: TrinaColumnType.text(),
  renderer: (rendererContext) {
    return Text(rendererContext.cell.value.toString());
  },
)

// Cell-level renderer (applies only to this specific cell)
TrinaCell(
  value: 'Completed',
  renderer: (rendererContext) {
    return Container(color: Colors.green, child: Text(rendererContext.cell.value.toString()));
  },
)

TrinaGrid supports three resizing behaviors via the TrinaResizeMode enum. You can set this in the TrinaGridConfiguration using the columnSize property.

• TrinaResizeMode.none: Disables column resizing. Users cannot drag column edges.
• TrinaResizeMode.normal: (Default) Resizing a column only changes its own width. Other columns remain unchanged, which may increase the total grid width.
• TrinaResizeMode.pushAndPull: Resizing a column causes neighboring columns to adjust their widths to maintain the overall grid width. Expanding one column shrinks others, and vice versa.

TrinaGrid(
  columns: columns,
  rows: rows,
  configuration: const TrinaGridConfiguration(
    columnSize: TrinaGridColumnSizeConfig(
      resizeMode: TrinaResizeMode.pushAndPull,
    ),
  ),
)

The TrinaGridStateManager provides methods to control the grid programmatically (e.g., for sorting, selection, or row manipulation). You should capture the instance from the onLoaded event of the TrinaGrid widget.

late TrinaGridStateManager stateManager;

// In your TrinaGrid widget:
onLoaded: (TrinaGridOnLoadedEvent event) {
  stateManager = event.stateManager;
},

You can specify how much of the grid is covered by the loading indicator using the TrinaGridLoadingLevel enum. This allows you to target specific areas of the grid during asynchronous operations.

• TrinaGridLoadingLevel.grid: Covers the entire grid area (default).
• TrinaGridLoadingLevel.body: Covers only the body area of the grid.
• TrinaGridLoadingLevel.row: Covers only the row area of the grid.

Context menus in TrinaGrid are integrated with several core column management features. Depending on your configuration, the context menu provides direct access to:

• Column Freezing: Options to freeze or unfreeze columns.
• Column Resizing: If both enableContextMenu and enableDropToResize are enabled, the context menu icon can be used as a handle to drag and resize columns.
• Column Filtering: Access to filtering options (requires enableFilterMenuItem to be true).
• Column Visibility: Options to hide columns or manage overall column visibility.

Instead of using TrinaRow.data, you can store metadata in columns that are not visible to the user by setting the hide property to true in TrinaColumn.

Pros/Cons:

• Hidden Columns: Data is stored within the standard row.cells structure and is part of the grid's cell model. Accessible via row.cells['column_id'].
• TrinaRow.data: Cleaner for complex objects or metadata that doesn't map to a specific grid column.

TrinaColumn(
  title: 'Original Name',
  field: 'original_name',
  type: TrinaColumnType.text(),
  hide: true,  // Column won't be rendered
)

TrinaGrid includes built-in logic to ensure the grid remains usable when freezing columns:

1. Space Preservation: The grid ensures there is always enough space for non-frozen (scrollable) columns to be visible.
2. Automatic Unfreezing: If the width of the middle (non-frozen) columns becomes too narrow due to frozen columns taking up space, the frozen columns will be automatically released (unfrozen).
3. Validation: The limitToggleFrozenColumn method is used internally to check if there is sufficient space before allowing a new column to be frozen.