SmartSearchController<T, K> class

Controller for managing search state and connecting to SmartPaginationCubit.

This controller handles:

  • Debounced search input
  • Search query state management
  • Connection to pagination cubit for data fetching
  • Overlay visibility state
  • Keyboard navigation (up/down arrows)
  • Focus state persistence
  • Selected item state (for showSelected mode)
  • Key-based selection with automatic data synchronization

The controller supports two generic types:

  • T: The data type of items (e.g., Product, User)
  • K: The key type used for identification (e.g., String, int)

Example with key-based selection:

final searchController = SmartSearchController<Product, String>(
  cubit: productsCubit,
  searchRequestBuilder: (query) => PaginationRequest(
    page: 1,
    pageSize: 20,
    searchQuery: query,
  ),
  keyExtractor: (product) => product.sku,
  selectedKey: 'SKU-001',
  selectedKeyLabelBuilder: (key) => 'Product: $key',
);

Example without key (uses item equality):

final searchController = SmartSearchController<Product, Product>(
  cubit: productsCubit,
  searchRequestBuilder: (query) => PaginationRequest(...),
  initialSelectedValue: someProduct,
);
Inheritance

Constructors

SmartSearchController({required SmartPaginationCubit<T> cubit, required PaginationRequest searchRequestBuilder(String query), SmartSearchConfig config = const SmartSearchConfig(), ValueChanged<T>? onItemSelected, ValueChanged<K>? onKeySelected, T? initialSelectedValue, K? selectedKey, K keyExtractor(T item)?, String selectedKeyLabelBuilder(K key)?})

Properties

config → SmartSearchConfig
The current search configuration.
no setter
cubit → SmartPaginationCubit<T>
The connected pagination cubit.
no setter
focusedIndex → int
The index of the currently focused item (-1 if none).
no setter
focusedItem → T?
Returns the currently focused item, or null if none.
no setter
focusNode → FocusNode
The focus node for the search field.
no setter
hasFocus → bool
Whether the search field has focus.
no setter
hashCode → int
The hash code for this object.
no setterinherited
hasItemFocus → bool
Whether an item is currently focused.
no setter
hasListeners → bool
Whether any listeners are currently registered.
no setterinherited
hasOverlayValue → bool
Whether a custom overlay value is set.
no setter
hasPendingKey → bool
Whether there's a pending key that hasn't been resolved yet.
no setter
hasSelectedItem → bool
Whether an item is currently selected.
no setter
hasSelectedKey → bool
Whether a key is currently selected.
no setter
hasText → bool
Whether the search field has text.
no setter
isFocused → bool
Alias for hasFocus for consistency.
no setter
isOverlayVisible → bool
Whether the overlay is currently visible.
no setter
isSearching → bool
Whether a search is currently in progress.
no setter
keyExtractor → K Function(T item)?
The key extractor function.
no setter
onItemSelected ← ValueChanged<T>?
Sets the item selection callback.
no getter
onKeySelected ← ValueChanged<K>?
Sets the key selection callback.
no getter
overlayValue → Object?
The custom value passed when overlay was shown. Use this to determine overlay content type.
no setter
query → String
The current search query text.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
selectedItem → T?
The currently selected item (for showSelected mode).
no setter
selectedKey → K?
The currently selected key.
no setter
selectedKeyLabel → String?
Returns the display label for the selected key when item is not loaded. Returns null if no pending key or no label builder provided.
no setter
textController → TextEditingController
The text editing controller for the search field.
no setter

Methods

addListener(VoidCallback listener) → void
Register a closure to be called when the object changes.
inherited
clearItemFocus() → void
Clears the item focus (sets to -1).
clearOverlayValue() → void
Clears the overlay value.
clearSearch() → void
Clears the search text and resets the query.
clearSelection({bool requestFocus = true}) → void
Clears the selected item and shows the search box. Optionally requests focus on the search field.
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
getKeyLabel(K key) → String
Returns the display label for a specific key.
getOverlayValue<V>() → V?
Gets the overlay value cast to a specific type. Returns null if the value is not of the expected type.
handleKeyEvent(KeyEvent event) → bool
Handles keyboard events for navigation. Returns true if the event was handled.
hideOverlay({bool clearValue = true}) → void
Hides the search overlay.
moveToFirstItem() → void
Moves focus to the first item.
moveToLastItem() → void
Moves focus to the last item.
moveToNextItem() → bool
Moves focus to the next item in the list. Returns true if focus was moved, false if at the end.
moveToPreviousItem() → bool
Moves focus to the previous item in the list. Returns true if focus was moved, false if at the beginning.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
notifyListeners() → void
Call all the registered listeners.
inherited
removeListener(VoidCallback listener) → void
Remove a previously registered closure from the list of closures that are notified when the object changes.
inherited
requestFocus() → void
Requests focus on the search field.
searchNow() → void
Triggers an immediate search with the current text.
selectByKey(K key) → void
Selects an item by its key. If the item is already loaded, it will be selected immediately. Otherwise, the key will be stored as pending and resolved when data loads.
selectFocusedItem() → T?
Selects the currently focused item. Returns the item if one was focused and selected, null otherwise.
selectItem(T item) → void
Selects an item from the search results. This will store the selected item, hide the overlay, call the onItemSelected callback, and optionally clear the search.
setFocusedIndex(int index) → void
Sets focus to a specific index.
setOverlayValue(Object? value) → void
Sets the overlay value without showing the overlay.
setSearchText(String text) → void
Sets the search text programmatically.
setSelectedItem(T? item) → void
Sets the selected item programmatically.
setSelectedKey(K? key) → void
Sets the selected key programmatically. This will try to resolve to an item if data is loaded.
showOverlay({Object? value}) → void
Shows the search overlay with an optional value.
toggleOverlay({Object? value}) → void
Toggles the overlay visibility with an optional value.
toString() → String
A string representation of this object.
inherited
unfocus() → void
Removes focus from the search field.

Operators

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