Skip to main content

Grid Controller

FdcGridController is the imperative runtime command surface for an attached grid. Use it when application UI outside the grid needs to change grid state—for example, a page-level button that focuses a column, clears filters, resets the layout, or opens a Pro detail row.

Dataset operations such as navigation, editing, validation, filtering, and persistence still belong to FdcDataSet. The grid controller is for grid presentation and interaction state.

Create and attach a controller​

Create the controller in widget state, pass it to the grid, and dispose it with the owning widget:

class CustomersPageState extends State<CustomersPage> {
  final gridController = FdcGridController();

  @override
  void dispose() {
    gridController.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return FdcGrid(
      controller: gridController,
      dataSet: customers,
      columns: const [
        FdcTextColumn<dynamic>(
          id: 'companyColumn',
          fieldName: 'company',
          label: 'Company',
        ),
      ],
    );
  }
}

A controller can issue commands only while it is attached to a live grid. Check isAttached when a command may run during initialization or teardown:

if (gridController.isAttached) {
  gridController.focusColumn('companyColumn');
}

Commands that require an attached grid throw a StateError when the controller is detached.

Focus and column visibility​

Columns should have stable id values when application code targets them by controller command.

gridController.focusColumn('companyColumn');
gridController.hideColumn('notesColumn');
gridController.showColumn('notesColumn');

focusColumn, hideColumn, and showColumn return bool so application code can detect whether the requested change was accepted by the current layout.

Filters​

await gridController.clearFilters();
gridController.showFilters();
await gridController.hideFilters();

clearFilters() removes grid-managed column filters and rebuilds the dataset view. showFilters() and hideFilters() control the header filter row at runtime.

hideFilters() is asynchronous because hiding the filter row can require a filter-state transition before the operation completes.

Sorting​

Clear grid-managed sorting and rebuild the dataset view:

await gridController.clearSorting();

Use the dataset sorting API for data-layer sorting logic that is independent of a particular grid instance.

Reset the layout​

await gridController.resetLayout();

Reset restores the grid's configured default layout. When Pro layout persistence is configured, reset also asks the persistence feature to delete the stored snapshot.

Community command summary​

CommandPurpose
isAttachedReports whether the controller is attached to a live grid.
focusColumn(id)Moves focus to a target column.
showColumn(id)Makes a target column visible.
hideColumn(id)Hides a target column.
clearFilters()Clears grid-managed filters.
showFilters()Shows the header filter row.
hideFilters()Hides the header filter row.
clearSorting()Clears grid-managed sorting.
resetLayout()Restores the configured default layout and removes persisted state when configured.
dispose()Detaches and permanently disposes the controller.

Pro controller extensions​

PRO

The Pro package extends the same FdcGridController with commands for layout state, detail rows, and range selection.

Layout state​

final state = gridController.captureLayout();

gridController.restoreLayout(state);

await gridController.saveLayout();
await gridController.saveNow();
final loaded = await gridController.loadLayout();

captureLayout() and restoreLayout() work with serializable FdcGridLayoutState values. saveLayout() and its saveNow() alias persist through the configured FdcGridLayoutPersistence callbacks. loadLayout() returns whether a persisted layout was loaded and restored.

Detail rows​

gridController.expandDetailRow();
gridController.expandDetailRow(rowIndex: 4);

gridController.collapseDetailRow();
gridController.collapseAllDetailRows();

When rowIndex is omitted, expand and collapse commands target the current row.

Range selection​

gridController.clearRangeSelection();

The method returns whether an active Pro range selection was present and cleared.