advanced_grouped_list 1.0.3

advanced_grouped_list: ^1.0.3 copied to clipboard

Acknowledgements

This package is originally based on the excellent work from Dimibe/sticky_grouped_list (which has not been updated for over a year) and also incorporates changes from th8m0z/sticky_grouped_list. We would like to express our sincere respect and gratitude to the original authors and contributors of these repositories.

Key Features and Enhancements Added in This Package:

• Added onGroupChanged callback to StickyGroupedListView for tracking group changes during scrolling.
• groupSeparatorBuilder is now an optional parameter, allowing for more flexible usage.
• Extended ItemPositionsListener with topItemIndex and lastItemIndex support for advanced scroll tracking.
• Improved performance.
• Variable item and group separator heights now supported.

A ListView in which list items can be grouped to sections. Based on scrollable_positioned_list, which enables programatically scrolling of the list.

Features #

• Easy creation of chat-like interfaces.
• List items can be separated in groups.
• For the groups an individual header can be set.
• Sticky headers with floating option.
• All fields from ScrollablePositionedList available.

Getting Started #

Add the package to your pubspec.yaml:

advanced_grouped_list: ^1.0.3

In your dart file, import the library:

import 'package:advanced_grouped_list/advanced_grouped_list.dart';

Create a AdvancedGroupedListView Widget:

 final GroupedItemScrollController itemScrollController = GroupedItemScrollController();
 final ItemPositionsListener itemPositionsListener = ItemPositionsListener.create();

 AdvancedGroupedListView<dynamic, String>(
   elements: _elements,
   // groupBy is now optional
   // You can omit it if you don't need group headers
   groupBy: (dynamic element) => element['group'],
   // groupSeparatorBuilder is now optional
   // You can omit it if you don't need group headers
   groupSeparatorBuilder: (dynamic element) => Text(element['group']),
   itemBuilder: (context, dynamic element) => Text(element['name']),
   itemComparator: (e1, e2) => e1['name'].compareTo(e2['name']), // optional
   elementIdentifier: (element) => element.name, // optional - see below for usage
   itemScrollController: itemScrollController, // optional
   itemPositionsListener: itemPositionsListener, // optional
   order: AdvancedGroupedListOrder.ASC, // optional
   // New: onGroupChanged callback
   onGroupChanged: (group) {
     // Called when the top visible group changes
     print('Current group: $group');
   },
 );

If you are using the GroupedItemScrollController you can scroll or jump to an specific position in the list programatically:

1. By using the index, which will scroll to the element at position [index]:

  itemScrollController.scrollTo(index: 4, duration: Duration(seconds: 2));
  itemScrollController.jumpTo(index: 4);

2. By using a pre defined element identifier. The identifier is defined by a Function which takes one element and returns a unique identifier of any type. The methods scrollToElement and jumpToElement can be used to jump to an element by providing the elements identifier instead of the index:

  final GroupedItemScrollController itemScrollController = GroupedItemScrollController();

  AdvancedGroupedListView<dynamic, String>(
    elements: _elements,
    elementIdentifier: (element) => element.name
    itemScrollController: itemScrollController, 
    [...]
  );

  itemScrollController.scrollToElement(identifier: 'item-1', duration: Duration(seconds: 2));
  itemScrollController.jumpToElement(identifier: 'item-2');

Example: Using topItemIndex and lastItemIndex with minVisibility

final topIndex = itemPositionsListener.topItemIndex();
final lastIndex = itemPositionsListener.lastItemIndex(minVisibility: 0.5); // consider as visible if at least 50% of the item is visible on the screen

Parameters: #

GroupedItemScrollController.srollTo() and GroupedItemScrollController.jumpTo() automatically set the alignment so that the item is fully visible aligned under the group header. Both methods take automaticAlignment as an additional optional parameter which needs to be set to true if alignment is specified.

Also the fields from ScrollablePositionedList.builder can be used.

Highlight - Chat Dialog #

Easy creation of chat-like dialogs. Just set the option reverse to true and the option order to AdvancedGroupedListOrder.DESC. A full example can be found in the examples. The list will be scrolled to the end in the initial state and therefore scrolling will be against redeaing direction.

Used packages: #