DataSet State

FdcDataSetState describes the current lifecycle and editing state of a dataset.

States

State	Meaning
closed	No active records are open
browse	Records are open with no active edit operation
edit	The current record is being edited
insert	A new record is being inserted or appended
loading	Data is being loaded
applyingUpdates	Posted changes are being applied through an adapter

Read the current state through:

final state = dataSet.state;

Typical lifecycle

A local dataset commonly follows:

closed
  ↓ loadRows()
browse
  ↓ edit()
edit
  ↓ post() or cancel()
browse

A new record follows:

browse
  ↓ append() or insert()
insert
  ↓ post() or cancel()
browse

An adapter-backed dataset additionally uses loading and may use applyingUpdates during persistence.

Prefer intent-oriented properties where possible

When you need to know whether a dataset is open, use:

if (dataSet.isOpen) {
  // The dataset is not closed.
}

To check whether records are visible:

if (!dataSet.isEmpty) {
  // A current record can be navigated and read.
}

To check for pending persistent changes:

if (dataSet.hasUpdates) {
  // Cached changes are waiting to be applied or cancelled.
}

Direct state checks are best when behavior specifically depends on an edit or insert lifecycle phase.

Observe state transitions

Use onStateChanged when application behavior must react to dataset state transitions:

final dataSet = FdcDataSet(
  fields: fields,
  onStateChanged: (dataSet, previousState, currentState) {
    debugPrint('$previousState → $currentState');
  },
);

The callback runs synchronously when the state value changes. The dataset has already entered currentState when the callback is invoked.

Do not duplicate dataset state in widgets

A common anti-pattern is copying dataset state into independent booleans such as:

bool isEditing = false;

and then manually trying to keep that value synchronized with grid edits, editor commits, cancel operations, and navigation.

Prefer observing the dataset itself. FdcDataSet is a ChangeNotifier, and data-aware FDC components already coordinate through it.

Busy work is separate from lifecycle state

Dataset lifecycle state tells you whether the dataset is closed, browsing, editing, loading, or applying. Longer-running work and progress reporting are exposed separately through the dataset work API.

This separation allows UI code to represent operation progress without overloading edit-state logic.

Next: Editing Lifecycle