azlistview

To react to user interaction on the IndexBar, implement the IndexBarDragListener and use its dragDetails stream. This allows you to sync the index bar's state with your main list.

IndexBarDragDetails provides the following information:

• action: An integer representing the drag state:
  • 0: actionDown (Touch started)
  • 1: actionUp (Touch released)
  • 2: actionUpdate (Dragging/Moving)
  • 3: actionEnd (Drag finished)
  • 4: actionCancel (Drag cancelled)
• index: The current integer index being touched.
• tag: The string label (e.g., 'A') at the current index.
• localPositionY / globalPositionY: The vertical position of the touch.

// 1. Create the listener
final IndexBarDragListener dragListener = IndexBarDragListener.create();

// 2. Add a listener to the dragDetails ValueListenable
dragListener.dragDetails.addListener(() {
  final details = dragListener.dragDetails.value;
  print('Current tag: ${details.tag}, Action: ${details.action}');
});

// 3. Pass it to the IndexBar
IndexBar(
  indexBarDragListener: dragListener,
  // ... other properties
)

The IndexBar widget provides a vertical list of characters (or custom data) that users can drag to navigate through a list. It supports custom styling, index hints (popups showing the current character), and drag event listening.

Key features:

• Custom Data: Pass a List<String> to data to define the index labels.
• Index Hint: A popup widget that appears during dragging. You can customize its appearance via indexHintBuilder or options.
• Drag Listening: Use IndexBarDragNotifier to listen to drag actions and respond to index changes.
• Styling: Extensive customization via IndexBarOptions for colors, decorations, and text styles.

IndexBar(
  data: ['A', 'B', 'C', 'D'],
  indexHintBuilder: (context, tag) {
    return Text(tag, style: TextStyle(fontSize: 24));
  },
  options: IndexBarOptions(
    hapticFeedback: true,
    indexHintDecoration: BoxDecoration(
      color: Colors.black87,
      borderRadius: BorderRadius.circular(6),
    ),
  ),
)

The AzListView widget is the primary entry point for creating a list with sticky headers (suspension views) and an index bar for quick navigation. It requires a list of data implementing ISuspensionBean, the total item count, and an item builder.

Key Parameters

• data: A List<ISuspensionBean> containing the data items. Each bean must provide a suspension tag via getSuspensionTag().
• itemCount: The total number of items in the list.
• itemBuilder: A function to build the list items.
• susItemBuilder: (Optional) A function to build the sticky suspension header widget.
• itemScrollController: (Optional) An ItemScrollController to programmatically jump or scroll to specific items.
• itemPositionsListener: (Optional) An ItemPositionsListener to track the position of items as they are laid out.
• indexBarOptions: Configuration for the index bar, such as item decoration.

AzListView(
  data: myDataList, // List<ISuspensionBean>
  itemCount: myDataList.length,
  itemBuilder: (context, index) {
    return ListTile(title: Text(myDataList[index].name));
  },
  susItemBuilder: (context, index) {
    return Container(
      color: Colors.grey,
      child: Text(myDataList[index].getSuspensionTag()),
    );
  },
)

The SuspensionUtil class provides static helper methods to process lists of ISuspensionBean objects for use with the list view components.

• sortListBySuspensionTag(List<ISuspensionBean>? list): Sorts the list based on the tags returned by getSuspensionTag(). It handles special characters like @ and # to ensure they appear at the start/end as intended.
• getTagIndexList(List<ISuspensionBean>? list): Extracts a unique list of all tags present in the list, which is typically used to build the side index bar.
• setShowSuspensionStatus(List<ISuspensionBean>? list): Iterates through the list and updates the isShowSuspension property of each item. This is necessary to tell the UI which items in the list are currently the active headers.

// 1. Sort the list
SuspensionUtil.sortListBySuspensionTag(myList);

// 2. Get the tags for the side index bar
List<String> tags = SuspensionUtil.getTagIndexList(myList);

// 3. Update the suspension status for rendering
SuspensionUtil.setShowSuspensionStatus(myList);