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(
      items: response.users,
      totalItems: response.total,
    );
  },
);

With Selection

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

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

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)

See also:

Inheritance
Available extensions

Constructors

TListController({List<T> items = const [], int itemsPerPage = 0, String search = '', int? searchDelay, TSelectionMode selectionMode = TSelectionMode.none, TExpansionMode expansionMode = TExpansionMode.none, TLoadListener<T>? onLoad, ItemKeyAccessor<T, K>? itemKey, ItemToString<T>? itemToString, ListItemFactory<T, K>? itemFactory, ItemChildrenAccessor<T>? itemChildren, bool reorderable = false, void onReorder(int oldIndex, int newIndex)?})
Creates a list controller.

Properties

canGoToNextPage → bool

Available on TListController<T, K>, provided by the TListControllerPagination extension

Whether there is a next page.
no setter
canGoToPreviousPage → bool

Available on TListController<T, K>, provided by the TListControllerPagination extension

Whether there is a previous page.
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
expandable → bool

Available on TListController<T, K>, provided by the TListControllerExpansion extension

Whether expansion is enabled.
no setter
expandedCount → int

Available on TListController<T, K>, provided by the TListControllerExpansion extension

The number of expanded items.
no setter
expandedItems → List<T>

Available on TListController<T, K>, provided by the TListControllerExpansion extension

The list of expanded items.
no setter
expandedKeys → LinkedHashSet<K>

Available on TListController<T, K>, provided by the TListControllerExpansion extension

The set of expanded 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
flatItems → List<T>

Available on TListController<T, K>, provided by the TListControllerItems extension

List of all items (flattened).
no setter
hasError → bool
no setter
hasExpansion → bool

Available on TListController<T, K>, provided by the TListControllerExpansion extension

Whether any 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
hasMultipleExpansion → bool

Available on TListController<T, K>, provided by the TListControllerExpansion extension

Whether multiple items are expanded.
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
isAllExpanded → bool

Available on TListController<T, K>, provided by the TListControllerExpansion extension

Whether all items are expanded.
no setter
isAllSelected → bool

Available on TListController<T, K>, provided by the TListControllerSelection extension

Whether all items are selected.
no setter
isEmpty → bool

Available on TListController<T, K>, provided by the TListControllerItems extension

Whether the display list is empty.
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
isSomeExpanded → bool

Available on TListController<T, K>, provided by the TListControllerExpansion extension

Whether some (but not all) items are expanded.
no setter
isSomeSelected → bool

Available on TListController<T, K>, provided by the TListControllerSelection extension

Whether some (but not all) items are selected.
no setter
itemChildren → ItemChildrenAccessor<T>?
Function to extract child items for hierarchical lists.
final
itemFactory → ListItemFactory<T, K>
Factory function to create list items.
final
itemKey → ItemKeyAccessor<T, K>
Function to extract a unique key from an item.
final
itemsMap → Map<K, T>

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
listItemKeys → List<K>

Available on TListController<T, K>, provided by the TListControllerItems extension

Keys of currently displayed items.
no setter
listItems → List<TListItem<T, K>>

Available on TListController<T, K>, provided by the TListControllerItems extension

List of currently displayed items (paginated/filtered).
no setter
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
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.
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 TListControllerSelection extension

The list of selected items.
no setter
selectedKeys → LinkedHashSet<K>

Available on TListController<T, K>, provided by the TListControllerSelection extension

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, [bool prepend = true]) → void

Available on TListController<T, K>, provided by the TListControllerItems extension

Adds a single item.
addItems(List<T> newItems, {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
cancelPendingOperations() → void
clear() → void

Available on TListController<T, K>, provided by the TListControllerItems extension

Clears all items and resets state.
clearError() → void
clearSelection() → void

Available on TListController<T, K>, provided by the TListControllerSelection extension

collapseAll() → void

Available on TListController<T, K>, provided by the TListControllerExpansion extension

collapseItem(T item) → void

Available on TListController<T, K>, provided by the TListControllerExpansion extension

collapseItemKey(K key) → void

Available on TListController<T, K>, provided by the TListControllerExpansion extension

computeItemsPerPageOptions(List<int> options) → List<int>

Available on TListController<T, K>, provided by the TListControllerPagination extension

deselectItem(T item) → void

Available on TListController<T, K>, provided by the TListControllerSelection extension

deselectItemKey(K key) → void

Available on TListController<T, K>, provided by the TListControllerSelection extension

dispose() → void
Discards any resources used by the object. After this is called, the object is not in a usable state and should be discarded (calls to addListener will throw after the object is disposed).
override
expandAll() → void

Available on TListController<T, K>, provided by the TListControllerExpansion extension

expandItem(T item) → void

Available on TListController<T, K>, provided by the TListControllerExpansion extension

expandItemKey(K key) → void

Available on TListController<T, K>, provided by the TListControllerExpansion extension

expandItemKeys(Iterable<K> keys) → void

Available on TListController<T, K>, provided by the TListControllerExpansion extension

expandItems(Iterable<T> items) → void

Available on TListController<T, K>, provided by the TListControllerExpansion extension

getItemsFromKeys(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.
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

handleError(TListError error) → void
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

isItemExpanded(T item) → void

Available on TListController<T, K>, provided by the TListControllerExpansion extension

isItemKeyExpanded(K key) → bool

Available on TListController<T, K>, provided by the TListControllerExpansion extension

isItemKeySelected(K key) → bool

Available on TListController<T, K>, provided by the TListControllerSelection extension

isItemSelected(T item) → void

Available on TListController<T, K>, provided by the TListControllerSelection extension

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
notifyListeners() → void
Call all the registered listeners.
inherited
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.
selectAll() → void

Available on TListController<T, K>, provided by the TListControllerSelection extension

selectItem(T item) → void

Available on TListController<T, K>, provided by the TListControllerSelection extension

selectItemKey(K key) → void

Available on TListController<T, K>, provided by the TListControllerSelection extension

selectItemKeys(Iterable<K> keys) → void

Available on TListController<T, K>, provided by the TListControllerSelection extension

selectItems(Iterable<T> items) → void

Available on TListController<T, K>, provided by the TListControllerSelection extension

toggleExpandAll() → void

Available on TListController<T, K>, provided by the TListControllerExpansion extension

toggleExpansion(T item) → void

Available on TListController<T, K>, provided by the TListControllerExpansion extension

toggleExpansionByKey(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(T item) → void

Available on TListController<T, K>, provided by the TListControllerSelection extension

toggleSelectionByKey(K key) → void

Available on TListController<T, K>, provided by the TListControllerSelection extension

toString() → String
A string representation of this object.
inherited
updateExpansionState(LinkedHashSet<K> expandedKeys) → void

Available on TListController<T, K>, provided by the TListControllerExpansion extension

updateItem(T oldItem, T item) → void

Available on TListController<T, K>, provided by the TListControllerItems extension

Updates an existing item.
updateItemByKey(K key, T item) → void

Available on TListController<T, K>, provided by the TListControllerItems extension

Updates an item by its key.
updateItems(List<T> items) → void

Available on TListController<T, K>, provided by the TListControllerItems extension

Updates the entire list of items.
updateSelectionState(LinkedHashSet<K> selectedKeys, {String who = ''}) → void

Available on TListController<T, K>, provided by the TListControllerSelection extension

updateState({required String who, LinkedHashSet<K>? selectedKeys, LinkedHashSet<K>? expandedKeys, List<TListItem<T, K>>? displayItems, int? page, int? itemsPerPage, int? totalItems, bool? loading, bool? hasMoreItems, String? search, TSelectionMode? selectionMode, TExpansionMode? expansionMode, TListError? error}) → void

Operators

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

Constants

allowedKeyTypes → const List<Type>