TListController<T, K> class

A powerful controller for managing list state and operations.

TListController provides comprehensive list management with:

Pagination: Client-side and server-side pagination
Selection: Single and multiple item selection
Expansion: Hierarchical item expansion/collapse
Search: Debounced search with filtering
Reordering: Drag-and-drop item reordering
Loading: Async data loading with error handling

Client-Side Usage

final controller = TListController<Product, int>(
  items: products,
  itemsPerPage: 10,
  itemKey: (product) => product.id,
  selectionMode: TSelectionMode.multiple,
);

// Use with TList
TList<Product, int>(
  controller: controller,
  itemBuilder: (context, item, index) {
    return ProductCard(product: item.data);
  },
)

Server-Side Usage

final controller = TListController<User, int>(
  itemsPerPage: 25,
  itemKey: (user) => user.id,
  onLoad: (options) async {
    final response = await api.getUsers(
      page: options.page,
      limit: options.itemsPerPage,
      search: options.search,
    );
    return TLoadResult(
       response.users,
       response.total,
    );
  },
);

With Selection

// Select items
controller.selectItem(product);
controller.selectAll();

// Get selected items
final selected = controller.selectedItems;
print('Selected: ${controller.selectedCount}');

With Search

controller.handleSearchChange('query');

Type parameters:

T: The type of items in the list
K: The type of the item key (must be String, int, double, num, or bool)

Constructors

TListController({List<T> items = const [], int itemsPerPage = 10, int? searchDelay, String search = '', TSelectionMode selectionMode = TSelectionMode.none, TExpansionMode expansionMode = TExpansionMode.none, TLoadListener<T>? onLoad, ItemKeyAccessor<T, K>? itemKey, ItemToString<T>? itemToString, ItemChildrenAccessor<T>? itemChildren, bool reorderable = false, void onReorder(int oldIndex, int newIndex)?, bool autoSelectFirst = false, bool autoExpandFirst = false, Iterable<K>? initialSelectedKeys, Iterable<K>? initialExpandedKeys, bool loading = false, bool hasMoreItems = true, bool loadOnSearchOnly = false, List<TFilterDef<T>>? filterDefs, Map<String, dynamic>? additional}): Creates a TListController.

Properties

activeFilterCount → int: The number of active advanced search / filter fields.
no setter
advancedSearch → Map<String, dynamic>?: Available on TListController<T, K>, provided by the TListControllerPagination extension
Current advanced search filters.
no setter
autoExpandFirst → bool: Whether to automatically expand the first item when items are loaded.
final
autoSelectFirst → bool: Whether to automatically select the first item when items are loaded.
final
canGoToNextPage → bool: Available on TListController<T, K>, provided by the TListControllerPagination extension
Whether there is a next page. For cursor pagination, checks hasMoreItems (from server's hasNextPage). For offset pagination, checks if page < totalPages.
no setter
canGoToPreviousPage → bool: Available on TListController<T, K>, provided by the TListControllerPagination extension
Whether there is a previous page. For cursor pagination, checks if there's cursor history. For offset pagination, checks if page > 1.
no setter
computedItemsPerPage → int: Available on TListController<T, K>, provided by the TListControllerPagination extension
The computed items per page (adjusted for last page).
no setter
currentCursor → String?: Available on TListController<T, K>, provided by the TListControllerPagination extension
Current cursor for cursor-based pagination.
no setter
cursorHistory → List<String>: Available on TListController<T, K>, provided by the TListControllerPagination extension
Cursor history stack for backward navigation.
no setter
displayItemKeys → List<K>: Keys of currently displayed items.
no setter
displayItems → List<TListItem<T, K>>: List of currently displayed items (paginated/filtered).
no setter
editingItemKey → K?: Available on TListController<T, K>, provided by the TListControllerDetailExpansion extension
Key of the item currently being edited.
no setter
expandable → bool: Available on TListController<T, K>, provided by the TListControllerExpansion extension
Whether tree node expansion is enabled.
no setter
expandedCount → int: Available on TListController<T, K>, provided by the TListControllerExpansion extension
The number of expanded tree items.
no setter
expandedDetailKey → K?: Available on TListController<T, K>, provided by the TListControllerDetailExpansion extension
Key of the currently expanded detail content item.
no setter
expandedItems → List<T>: Available on TListController<T, K>, provided by the TListControllerItems extension
List of expanded data items.
no setter
expandedKeys → UnmodifiableSetView<K>: The set of expanded tree parent item keys.
no setter
expansionInfo → String: Available on TListController<T, K>, provided by the TListControllerExpansion extension
Human-readable expansion information.
no setter
expansionMode → TExpansionMode: The expansion mode for hierarchical lists.
final
expansionTristate → bool?: Available on TListController<T, K>, provided by the TListControllerExpansion extension
Tristate expansion value (true/null/false).
no setter
filterDefs → List<TFilterDef<T>>?: Available filter field definitions associated with this controller.
no setter
flatItems → List<T>: Available on TListController<T, K>, provided by the TListControllerItems extension
Flat list of all item data values (across all levels).
no setter
hasError → bool: no setter
hasExpandedContent → bool: Available on TListController<T, K>, provided by the TListControllerDetailExpansion extension
Whether any row detail content is currently expanded.
no setter
hasExpansion → bool: Available on TListController<T, K>, provided by the TListControllerExpansion extension
Whether any tree items are expanded.
no setter
hashCode → int: The hash code for this object.
no setterinherited
hasListeners → bool: Whether any listeners are currently registered.
no setterinherited
hasMoreItems → bool: Available on TListController<T, K>, provided by the TListControllerPagination extension
Whether there are more items to load.
no setter
hasMultipleSelection → bool: Available on TListController<T, K>, provided by the TListControllerSelection extension
Whether multiple items are selected.
no setter
hasSelection → bool: Available on TListController<T, K>, provided by the TListControllerSelection extension
Whether any items are selected.
no setter
headerOrder → List<String>: Available on TListController<T, K>, provided by the TTableListControllerExt extension
The order of table headers/columns.
no setter
headerVisibility → Map<String, bool>: Available on TListController<T, K>, provided by the TTableListControllerExt extension
The visibility status of each table header/column.
no setter
isAllExpanded → bool: Available on TListController<T, K>, provided by the TListControllerExpansion extension
Whether all tree items are expanded.
no setter
isAllSelected → bool: Available on TListController<T, K>, provided by the TListControllerSelection extension
Whether all items are selected.
no setter
isCursorPagination → bool: Available on TListController<T, K>, provided by the TListControllerPagination extension

no setter
isEmpty → bool: Available on TListController<T, K>, provided by the TListControllerItems extension
Whether the display list is empty.
no setter
isFetching → bool: no setter
isFiltered → bool: Whether the list is currently filtered by search or advanced filters.
no setter
isFirstPage → bool: Available on TListController<T, K>, provided by the TListControllerPagination extension
Whether this is the first page.
no setter
isHierarchical → bool: no setter
isLastPage → bool: Available on TListController<T, K>, provided by the TListControllerPagination extension
Whether this is the last page.
no setter
isLoading → bool: no setter
isMultiSelect → bool: Available on TListController<T, K>, provided by the TListControllerSelection extension
Whether multiple selection is enabled.
no setter
isNotEmpty → bool: Available on TListController<T, K>, provided by the TListControllerItems extension
Whether the display list is not empty.
no setter
isServerSide → bool: Whether this controller uses server-side data loading.
final
itemChildren → ItemChildrenAccessor<T>?: Function to extract child items for hierarchical lists.
final
itemKey → ItemKeyAccessor<T, K>: Function to extract a unique key from an item.
final
itemsMap → Map<K, TListItem<T, K>>: Available on TListController<T, K>, provided by the TListControllerItems extension
Map of all items by key.
no setter
itemsPerPage → int: Available on TListController<T, K>, provided by the TListControllerPagination extension
The number of items per page.
no setter
itemToString → ItemToString<T>: Function to convert an item to a string for search filtering.
final
loadOnSearchOnly → bool: Whether to only load data when a search query is present.
final
localItems → List<T>: Available on TListController<T, K>, provided by the TListControllerItems extension
The items available for local pagination.
no setter
mounted → bool: no setter
nextCursor → String?: Available on TListController<T, K>, provided by the TListControllerPagination extension
Next cursor for cursor-based pagination.
no setter
onLoad → TLoadListener<T>?: Callback for loading data from a server.
final
onReorder → void Function(int oldIndex, int newIndex)?: Callback fired when items are reordered.
final
page → int: Available on TListController<T, K>, provided by the TListControllerPagination extension
The current page number (1-indexed).
no setter
pageEndedAt → int: Available on TListController<T, K>, provided by the TListControllerPagination extension
The ending index of the current page.
no setter
pageStartedAt → int: Available on TListController<T, K>, provided by the TListControllerPagination extension
The starting index of the current page.
no setter
paginationInfo → String: Available on TListController<T, K>, provided by the TListControllerPagination extension
Human-readable pagination information. For cursor pagination (when totalItems is 0 or unavailable), shows current page info. For offset pagination, shows range and total.
no setter
reorderable → bool: Whether items can be reordered.
final
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
selectable → bool: Available on TListController<T, K>, provided by the TListControllerSelection extension
Whether selection is enabled.
no setter
selectedCount → int: Available on TListController<T, K>, provided by the TListControllerSelection extension
The number of selected items.
no setter
selectedItems → List<T>: Available on TListController<T, K>, provided by the TListControllerItems extension
List of selected data items.
no setter
selectedKeys → UnmodifiableSetView<K>: The set of selected item keys.
no setter
selectionInfo → String: Available on TListController<T, K>, provided by the TListControllerSelection extension
Human-readable selection information.
no setter
selectionMode → TSelectionMode: The selection mode for the list.
final
selectionTristate → bool?: Available on TListController<T, K>, provided by the TListControllerSelection extension
Tristate selection value (true/null/false).
no setter
totalDisplayItems → int: Available on TListController<T, K>, provided by the TListControllerPagination extension
The number of items currently displayed.
no setter
totalItems → int: Available on TListController<T, K>, provided by the TListControllerPagination extension
The total number of items.
no setter
totalPages → int: Available on TListController<T, K>, provided by the TListControllerPagination extension
The total number of pages.
no setter
value ↔ TListState<T, K>: The current value stored in this notifier.
getter/setter pairinherited

Methods

addItem(T item, {K? parentKey, bool prepend = true}) → void: Available on TListController<T, K>, provided by the TListControllerItems extension
Adds a single item.
addItems(List<T> newItems, {K? parentKey, bool prepend = true}) → void: Available on TListController<T, K>, provided by the TListControllerItems extension
Adds multiple items.
addListener(VoidCallback listener) → void: Register a closure to be called when the object changes.
inherited
areDescendantsExpanded(K key) → bool: Available on TListController<T, K>, provided by the TListControllerExpansion extension
beginCreateItem({bool clearEditingItem = true}) → void: Available on TListController<T, K>, provided by the TListControllerActions extension
Puts the list into a state ready to create a new item.
beginEditItem(T item) → void: Available on TListController<T, K>, provided by the TListControllerActions extension
Puts the list into a state ready to edit an item.
beginEditItemKey(K key) → void: Available on TListController<T, K>, provided by the TListControllerActions extension
Puts the list into a state ready to edit an item key.
bindAsync(WidgetRef ref, ProviderListenable<AsyncValue<List<T>>> provider) → void: Available on TListController<T, K>, provided by the TListControllerRiverpod extension
bindAsyncMap<S>(WidgetRef ref, ProviderListenable<AsyncValue<S>> provider, {required List<T> map(S v)}) → void: Available on TListController<T, K>, provided by the TListControllerRiverpod extension
cancelCreateItem() → void: Available on TListController<T, K>, provided by the TListControllerActions extension
Cancels the create item state.
cancelEditItem() → void: Available on TListController<T, K>, provided by the TListControllerActions extension
Cancels the edit item state.
cancelPendingOperations() → void: Available on TListController<T, K>, provided by the TListControllerActions extension
Cancels all pending debouncer timers and network requests.
canExpand(K key) → bool: Available on TListController<T, K>, provided by the TListControllerExpansion extension
clear() → void: Available on TListController<T, K>, provided by the TListControllerItems extension
Clears all items and resets state.
clearAdditionalState() → void: Available on TListController<T, K>, provided by the TListControllerActions extension
Clears the additional state and notifies listeners.
clearAdvancedSearch() → void: Available on TListController<T, K>, provided by the TListControllerPagination extension
Clears all active advanced search / filter conditions.
clearError() → void: Available on TListController<T, K>, provided by the TListControllerActions extension
Clears any error state.
clearSelection() → void: Available on TListController<T, K>, provided by the TListControllerSelection extension
collapse(K key) → void: Available on TListController<T, K>, provided by the TListControllerExpansion extension
collapseAll() → void: Available on TListController<T, K>, provided by the TListControllerExpansion extension
collapseDescendants(K key) → void: Available on TListController<T, K>, provided by the TListControllerExpansion extension
collapseDetail() → void: Available on TListController<T, K>, provided by the TListControllerDetailExpansion extension
Collapses expanded detail content.
computeItemsPerPageOptions(List<int> options) → List<int>: Available on TListController<T, K>, provided by the TListControllerPagination extension
copyKeySet(Iterable<K> keys) → LinkedHashSet<K>
createEmptyKeySet() → LinkedHashSet<K>
deselect(K key) → void: Available on TListController<T, K>, provided by the TListControllerSelection extension
dispose() → void: Discards any resources used by the object.
override
expand(K key) → void: Available on TListController<T, K>, provided by the TListControllerExpansion extension
expandAll() → void: Available on TListController<T, K>, provided by the TListControllerExpansion extension
expandDescendants(K key) → void: Available on TListController<T, K>, provided by the TListControllerExpansion extension
expandDetail(K key, {Map<String, dynamic>? additional, bool clearEditingItem = true}) → void: Available on TListController<T, K>, provided by the TListControllerDetailExpansion extension
Expands detail content for a specific item key. Automatically clears any active edit item key, ensuring only one view/edit mode is active.
expandKeys(Iterable<K> keys) → void: Available on TListController<T, K>, provided by the TListControllerExpansion extension
getAncestorsOfKey(K key) → List<K>: Retrieves all ancestor item keys for a given item key in tree hierarchy.
getChildren(T item) → List<T>?: Safely retrieves child items for an item using itemChildren.
getDescendantsOfKey(K key) → Set<K>: Retrieves all descendant item keys for a given item key in tree hierarchy.
getItem(K key) → TListItem<T, K>?: Retrieves a TListItem by key, or null if not found.
getItems(Iterable<K> keys) → List<T>: Available on TListController<T, K>, provided by the TListControllerItems extension
Retrieves a list of items corresponding to the provided keys.
getOrRegisterItem(T item) → TListItem<T, K>: Available on TListController<T, K>, provided by the TListControllerItems extension
Safely retrieves an item from _itemsMap or registers it if not present.
goToFirstPage() → void: Available on TListController<T, K>, provided by the TListControllerPagination extension
goToLastPage() → void: Available on TListController<T, K>, provided by the TListControllerPagination extension
goToNextPage() → void: Available on TListController<T, K>, provided by the TListControllerPagination extension
goToPreviousPage() → void: Available on TListController<T, K>, provided by the TListControllerPagination extension
handleAdvancedSearchChange(Map<String, dynamic> filters) → void: Available on TListController<T, K>, provided by the TListControllerPagination extension
handleAsyncValue(AsyncValue<List<T>> next) → void: Available on TListController<T, K>, provided by the TListControllerRiverpod extension
handleAsyncValueMap<S>(AsyncValue<S> next, List<T> map(S v)) → void: Available on TListController<T, K>, provided by the TListControllerRiverpod extension
handleError(TListError error) → void: Available on TListController<T, K>, provided by the TListControllerActions extension
Sets an error state on the list.
handleFilterRulesChange(List<TFilterRule> rules, [List<TFilterDef<T>>? defs]) → void: Available on TListController<T, K>, provided by the TListControllerPagination extension
Applies a list of TFilterRule instances, converting them to JSON and updating advanced search.
handleItemsPerPageChange(int newItemsPerPage) → void: Available on TListController<T, K>, provided by the TListControllerPagination extension
handleLoadMore() → void: Available on TListController<T, K>, provided by the TListControllerPagination extension
handlePageChange(int newPage) → void: Available on TListController<T, K>, provided by the TListControllerPagination extension
handleRefresh() → void: Available on TListController<T, K>, provided by the TListControllerPagination extension
handleSearchChange(String search) → void: Available on TListController<T, K>, provided by the TListControllerPagination extension
handleSearchImmediate(String search) → void: Available on TListController<T, K>, provided by the TListControllerPagination extension
isDetailExpanded(K key) → bool: Available on TListController<T, K>, provided by the TListControllerDetailExpansion extension
isExpanded(K key) → bool: Available on TListController<T, K>, provided by the TListControllerExpansion extension
isSelected(K key) → bool: Available on TListController<T, K>, provided by the TListControllerSelection extension
itemFactory(T data, {K? parentKey, List<K>? childrenKeys, int level = 0}) → TListItem<T, K>: The single canonical factory for creating a TListItem from raw data.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
notifyListeners() → void: Call all the registered listeners.
inherited
registerItem(T item) → void: Available on TListController<T, K>, provided by the TListControllerItems extension
Registers an item in the items map if not already present.
removeItem(T item) → void: Available on TListController<T, K>, provided by the TListControllerItems extension
Removes a specific item.
removeItemByKey(K key) → void: Available on TListController<T, K>, provided by the TListControllerItems extension
Removes an item by key.
removeItems(List<T> items) → void: Available on TListController<T, K>, provided by the TListControllerItems extension
Removes multiple items.
removeItemsByKeys(Set<K> keys) → void: Available on TListController<T, K>, provided by the TListControllerItems extension
Removes multiple items by keys.
removeListener(VoidCallback listener) → void: Remove a previously registered closure from the list of closures that are notified when the object changes.
inherited
removeSelectedItems() → void: Available on TListController<T, K>, provided by the TListControllerItems extension
Removes all currently selected items.
reorder(int oldIndex, int newIndex) → void: Available on TListController<T, K>, provided by the TListControllerItems extension
Reorders items in the list.
select(K key) → void: Available on TListController<T, K>, provided by the TListControllerSelection extension
selectAll() → void: Available on TListController<T, K>, provided by the TListControllerSelection extension
selectKeys(Iterable<K> keys) → void: Available on TListController<T, K>, provided by the TListControllerSelection extension
setAdditionalState(String key, dynamic value) → void: Available on TListController<T, K>, provided by the TListControllerActions extension
Sets a value in the additional state and notifies listeners if it changed.
toggleContentKey(K key, {Map<String, dynamic>? additional}) → void: Available on TListController<T, K>, provided by the TListControllerDetailExpansion extension
Toggles detail content expansion for a specific item key.
toggleExpandAll() → void: Available on TListController<T, K>, provided by the TListControllerExpansion extension
toggleExpandDescendants(K key) → void: Available on TListController<T, K>, provided by the TListControllerExpansion extension
toggleExpansion(K key) → void: Available on TListController<T, K>, provided by the TListControllerExpansion extension
toggleSelectAll() → void: Available on TListController<T, K>, provided by the TListControllerSelection extension
toggleSelection(K key) → void: Available on TListController<T, K>, provided by the TListControllerSelection extension
toString() → String: A string representation of this object.
inherited
updateColumns(List<String> order, Map<String, bool> visibility) → void: Available on TListController<T, K>, provided by the TTableListControllerExt extension
Updates both header order and visibility reactively.
updateError(Object e, StackTrace st) → void: Available on TListController<T, K>, provided by the TListControllerActions extension
Helper to wrap exception and stacktrace into a TListError.
updateExpansionState(LinkedHashSet<K> expandedKeys) → void: Available on TListController<T, K>, provided by the TListControllerExpansion extension
updateFilterDefs(List<TFilterDef<T>>? defs) → void: Updates the filter field definitions and re-applies local pagination if active.
updateHeaderOrder(List<String> newOrder) → void: Available on TListController<T, K>, provided by the TTableListControllerExt extension
Updates the header order state reactively.
updateHeaderVisibility(String text, bool visible) → void: Available on TListController<T, K>, provided by the TTableListControllerExt extension
Updates the header visibility state reactively.
updateItem(T oldItem, T newItem) → void: Available on TListController<T, K>, provided by the TListControllerItems extension
Updates an existing item by value equality on its key.
updateItemByKey(K key, T newItem) → void: Available on TListController<T, K>, provided by the TListControllerItems extension
Updates an item by its key.
updateItems(List<T> items, {bool append = false}) → void: Available on TListController<T, K>, provided by the TListControllerItems extension
Updates the entire list of items.
updateLoading() → void: Available on TListController<T, K>, provided by the TListControllerActions extension
Puts the list into a loading state.
updateSelectionState(LinkedHashSet<K> newSelectedKeys) → void: Available on TListController<T, K>, provided by the TListControllerSelection extension
Replaces the entire selected key set with newSelectedKeys.
updateState({required String who, LinkedHashSet<K>? selectedKeys, LinkedHashSet<K>? expandedKeys, List<TListItem<T, K>>? displayItems, K? expandedDetailKey, bool clearExpandedDetail = false, K? editingItemKey, bool clearEditingItem = false, int? page, int? itemsPerPage, int? totalItems, bool? loading, bool? fetching, bool? hasMoreItems, bool? isCreatingItem, String? search, TSelectionMode? selectionMode, TExpansionMode? expansionMode, TListError? error, String? currentCursor, String? nextCursor, List<String>? cursorHistory, Map<String, dynamic>? advancedSearch, Map<String, dynamic>? additional}) → void

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Methods

defaultItemKey<T, K>(T item) → K

Constants

allowedKeyTypes → const List<Type>

TListController<T, K> class

Client-Side Usage

Server-Side Usage

With Selection

With Search

Constructors

Properties

Methods

Operators

Static Methods

Constants

list_controller library