From 8f5569a0121237458da0b878062121b94b1f86dc Mon Sep 17 00:00:00 2001 From: appflowy Date: Tue, 6 Sep 2022 10:52:32 +0800 Subject: [PATCH] chore: update doc --- .../appflowy_board/lib/src/widgets/board.dart | 26 +++---- .../widgets/board_column/board_column.dart | 13 ++-- .../lib/src/widgets/board_data.dart | 68 ++++++++++++++++++- .../reorder_phantom/phantom_controller.dart | 4 +- 4 files changed, 82 insertions(+), 29 deletions(-) diff --git a/frontend/app_flowy/packages/appflowy_board/lib/src/widgets/board.dart b/frontend/app_flowy/packages/appflowy_board/lib/src/widgets/board.dart index 7ed69db822..7e98653848 100644 --- a/frontend/app_flowy/packages/appflowy_board/lib/src/widgets/board.dart +++ b/frontend/app_flowy/packages/appflowy_board/lib/src/widgets/board.dart @@ -110,7 +110,7 @@ class AppFlowyBoard extends StatelessWidget { scrollManager!._groupState = _groupState; } - return AFBoardContent( + return _AppFlolwyBoardContent( config: config, dataController: dataController, scrollController: scrollController, @@ -131,7 +131,7 @@ class AppFlowyBoard extends StatelessWidget { } } -class AFBoardContent extends StatefulWidget { +class _AppFlolwyBoardContent extends StatefulWidget { final ScrollController? scrollController; final OnDragStarted? onDragStarted; final OnReorder onReorder; @@ -143,21 +143,13 @@ class AFBoardContent extends StatefulWidget { final BoxConstraints columnConstraints; final AFBoardScrollManager? scrollManager; final BoardGroupsState columnsState; - - /// final AppFlowyBoardCardBuilder cardBuilder; - - /// final AppFlowyBoardHeaderBuilder? headerBuilder; - - /// final AppFlowyBoardFooterBuilder? footerBuilder; - final OverlapDragTargetDelegate delegate; - final BoardPhantomController phantomController; - const AFBoardContent({ + const _AppFlolwyBoardContent({ required this.config, required this.onReorder, required this.delegate, @@ -178,12 +170,12 @@ class AFBoardContent extends StatefulWidget { super(key: key); @override - State createState() => _AFBoardContentState(); + State<_AppFlolwyBoardContent> createState() => _AppFlowyBoardContentState(); } -class _AFBoardContentState extends State { +class _AppFlowyBoardContentState extends State<_AppFlolwyBoardContent> { final GlobalKey _boardContentKey = - GlobalKey(debugLabel: '$AFBoardContent overlay key'); + GlobalKey(debugLabel: '$_AppFlolwyBoardContent overlay key'); late BoardOverlayEntry _overlayEntry; final Map _reorderFlexKeys = {}; @@ -263,7 +255,7 @@ class _AFBoardContentState extends State { value: widget.dataController.getGroupController(columnData.id), child: Consumer( builder: (context, value, child) { - final boardColumn = AppFlowyBoardGroupWidget( + final boardColumn = AppFlowyBoardGroup( reorderFlexKey: reorderFlexKey, // key: PageStorageKey(columnData.id), margin: _marginFromIndex(columnIndex), @@ -351,12 +343,12 @@ class BoardGroupContext { class BoardGroupsState extends DraggingStateStorage with ReorderDragTargetIndexKeyStorage { - /// Quick access to the [AppFlowyBoardGroupWidget] + /// Quick access to the [AppFlowyBoardGroup] final Map groupKeys = {}; final Map groupDragStates = {}; final Map> groupDragDragTargets = {}; - void addGroup(String groupId, AppFlowyBoardGroupWidget groupWidget) { + void addGroup(String groupId, AppFlowyBoardGroup groupWidget) { groupKeys[groupId] = groupWidget.reorderFlexKey; } diff --git a/frontend/app_flowy/packages/appflowy_board/lib/src/widgets/board_column/board_column.dart b/frontend/app_flowy/packages/appflowy_board/lib/src/widgets/board_column/board_column.dart index 9723f97807..62e6da9bc5 100644 --- a/frontend/app_flowy/packages/appflowy_board/lib/src/widgets/board_column/board_column.dart +++ b/frontend/app_flowy/packages/appflowy_board/lib/src/widgets/board_column/board_column.dart @@ -60,9 +60,9 @@ abstract class AppFlowyBoardGroupDataDataSource extends ReoderFlexDataSource { } } -/// [AppFlowyBoardGroupWidget] represents the column of the Board. +/// [AppFlowyBoardGroup] represents the group of the Board. /// -class AppFlowyBoardGroupWidget extends StatefulWidget { +class AppFlowyBoardGroup extends StatefulWidget { final AppFlowyBoardGroupDataDataSource dataSource; final ScrollController? scrollController; final ReorderFlexConfig config; @@ -94,7 +94,7 @@ class AppFlowyBoardGroupWidget extends StatefulWidget { final GlobalObjectKey reorderFlexKey; - const AppFlowyBoardGroupWidget({ + const AppFlowyBoardGroup({ Key? key, required this.reorderFlexKey, this.headerBuilder, @@ -116,13 +116,12 @@ class AppFlowyBoardGroupWidget extends StatefulWidget { super(key: key); @override - State createState() => - _AppFlowyBoardGroupWidgetState(); + State createState() => _AppFlowyBoardGroupState(); } -class _AppFlowyBoardGroupWidgetState extends State { +class _AppFlowyBoardGroupState extends State { final GlobalKey _columnOverlayKey = - GlobalKey(debugLabel: '$AppFlowyBoardGroupWidget overlay key'); + GlobalKey(debugLabel: '$AppFlowyBoardGroup overlay key'); late BoardOverlayEntry _overlayEntry; @override diff --git a/frontend/app_flowy/packages/appflowy_board/lib/src/widgets/board_data.dart b/frontend/app_flowy/packages/appflowy_board/lib/src/widgets/board_data.dart index 7cd5642791..db23dd845d 100644 --- a/frontend/app_flowy/packages/appflowy_board/lib/src/widgets/board_data.dart +++ b/frontend/app_flowy/packages/appflowy_board/lib/src/widgets/board_data.dart @@ -28,16 +28,42 @@ typedef OnMoveGroupItemToGroup = void Function( int toIndex, ); +/// A controller for [AppFlowyBoard] widget. +/// +/// A [AppFlowyBoardDataController] can be used to provide an initial value of +/// the board by calling [addGroup] method with the passed in parameter +/// [AppFlowyBoardGroupData]. A [AppFlowyBoardGroupData] represents one +/// group data. Whenever the user modifies the board, this controller will +/// update the corresponding group data. +/// +/// Also, you can register the callbacks that receive the changes. +/// [onMoveGroup] will get called when moving the group from one position to +/// another. +/// +/// [onMoveGroupItem] will get called when moving the group's items. +/// +/// [onMoveGroupItemToGroup] will get called when moving the group's item from +/// one group to another group. class AppFlowyBoardDataController extends ChangeNotifier with EquatableMixin, BoardPhantomControllerDelegate, ReoderFlexDataSource { final List _groupDatas = []; + + /// [onMoveGroup] will get called when moving the group from one position to + /// another. final OnMoveGroup? onMoveGroup; + + /// [onMoveGroupItem] will get called when moving the group's items. final OnMoveGroupItem? onMoveGroupItem; + + /// [onMoveGroupItemToGroup] will get called when moving the group's item from + /// one group to another group. final OnMoveGroupItemToGroup? onMoveGroupItemToGroup; + /// Returns the unmodifiable list of [AppFlowyBoardGroupData] UnmodifiableListView get groupDatas => UnmodifiableListView(_groupDatas); + /// Returns list of group id List get groupIds => _groupDatas.map((groupData) => groupData.id).toList(); @@ -50,6 +76,10 @@ class AppFlowyBoardDataController extends ChangeNotifier this.onMoveGroupItemToGroup, }); + /// Adds a new group to the end of the current group list. + /// + /// If you don't want to notify the listener after adding a new group, the + /// [notify] should set to false. Default value is true. void addGroup(AppFlowyBoardGroupData groupData, {bool notify = true}) { if (_groupControllers[groupData.id] != null) return; @@ -59,6 +89,10 @@ class AppFlowyBoardDataController extends ChangeNotifier if (notify) notifyListeners(); } + /// Adds a list of groups to the end of the current group list. + /// + /// If you don't want to notify the listener after adding the groups, the + /// [notify] should set to false. Default value is true. void addGroups(List groups, {bool notify = true}) { for (final column in groups) { addGroup(column, notify: false); @@ -67,6 +101,10 @@ class AppFlowyBoardDataController extends ChangeNotifier if (groups.isNotEmpty && notify) notifyListeners(); } + /// Removes the group with id [groupId] + /// + /// If you don't want to notify the listener after removing the group, the + /// [notify] should set to false. Default value is true. void removeGroup(String groupId, {bool notify = true}) { final index = _groupDatas.indexWhere((group) => group.id == groupId); if (index == -1) { @@ -82,6 +120,10 @@ class AppFlowyBoardDataController extends ChangeNotifier } } + /// Removes a list of groups + /// + /// If you don't want to notify the listener after removing the groups, the + /// [notify] should set to false. Default value is true. void removeGroups(List groupIds, {bool notify = true}) { for (final groupId in groupIds) { removeGroup(groupId, notify: false); @@ -90,12 +132,16 @@ class AppFlowyBoardDataController extends ChangeNotifier if (groupIds.isNotEmpty && notify) notifyListeners(); } + /// Remove all the groups controller. + /// This method should get called when you want to remove all the current + /// groups or get ready to reinitialize the [AppFlowyBoard]. void clear() { _groupDatas.clear(); _groupControllers.clear(); notifyListeners(); } + /// Returns the [AFBoardGroupDataController] with id [groupId]. AFBoardGroupDataController? getGroupController(String groupId) { final groupController = _groupControllers[groupId]; if (groupController == null) { @@ -105,6 +151,11 @@ class AppFlowyBoardDataController extends ChangeNotifier return groupController; } + /// Moves the group controller from [fromIndex] to [toIndex] and notify the + /// listeners. + /// + /// If you don't want to notify the listener after moving the group, the + /// [notify] should set to false. Default value is true. void moveGroup(int fromIndex, int toIndex, {bool notify = true}) { final toGroupData = _groupDatas[toIndex]; final fromGroupData = _groupDatas.removeAt(fromIndex); @@ -114,31 +165,42 @@ class AppFlowyBoardDataController extends ChangeNotifier if (notify) notifyListeners(); } + /// Moves the group's item from [fromIndex] to [toIndex] + /// If the group with id [groupId] is not exist, this method will do nothing. void moveGroupItem(String groupId, int fromIndex, int toIndex) { if (getGroupController(groupId)?.move(fromIndex, toIndex) ?? false) { onMoveGroupItem?.call(groupId, fromIndex, toIndex); } } + /// Adds the [AppFlowyGroupItem] to the end of the group + /// If the group with id [groupId] is not exist, this method will do nothing. void addGroupItem(String groupId, AppFlowyGroupItem item) { getGroupController(groupId)?.add(item); } + /// Inserts the [AppFlowyGroupItem] at [index] in the group + /// It will do nothing if the group with id [groupId] is not exist void insertGroupItem(String groupId, int index, AppFlowyGroupItem item) { getGroupController(groupId)?.insert(index, item); } + /// Removes the item with id [itemId] from the group + /// It will do nothing if the group with id [groupId] is not exist void removeGroupItem(String groupId, String itemId) { getGroupController(groupId)?.removeWhere((item) => item.id == itemId); } + /// Replaces or inserts the [AppFlowyGroupItem] to the end of the group. + /// If the group with id [groupId] is not exist, this method will do nothing. void updateGroupItem(String groupId, AppFlowyGroupItem item) { getGroupController(groupId)?.replaceOrInsertItem(item); } + /// Swap the @override @protected - void swapGroupItem( + void moveGroupItemToAnotherGroup( String fromGroupId, int fromGroupIndex, String toGroupId, @@ -146,12 +208,12 @@ class AppFlowyBoardDataController extends ChangeNotifier ) { final fromGroupController = getGroupController(fromGroupId)!; final toGroupController = getGroupController(toGroupId)!; - final item = fromGroupController.removeAt(fromGroupIndex); + final fromGroupItem = fromGroupController.removeAt(fromGroupIndex); if (toGroupController.items.length > toGroupIndex) { assert(toGroupController.items[toGroupIndex] is PhantomGroupItem); } - toGroupController.replace(toGroupIndex, item); + toGroupController.replace(toGroupIndex, fromGroupItem); onMoveGroupItemToGroup?.call( fromGroupId, fromGroupIndex, diff --git a/frontend/app_flowy/packages/appflowy_board/lib/src/widgets/reorder_phantom/phantom_controller.dart b/frontend/app_flowy/packages/appflowy_board/lib/src/widgets/reorder_phantom/phantom_controller.dart index f7b06a73fd..0d505461ed 100644 --- a/frontend/app_flowy/packages/appflowy_board/lib/src/widgets/reorder_phantom/phantom_controller.dart +++ b/frontend/app_flowy/packages/appflowy_board/lib/src/widgets/reorder_phantom/phantom_controller.dart @@ -27,7 +27,7 @@ abstract class BoardPhantomControllerDelegate { /// [dragTargetIndex] the index of the dragTarget void updatePhantom(String groupId, int newIndex); - void swapGroupItem( + void moveGroupItemToAnotherGroup( String fromGroupId, int fromGroupIndex, String toGroupId, @@ -79,7 +79,7 @@ class BoardPhantomController extends OverlapDragTargetDelegate } if (phantomRecord!.toGroupId == groupId) { - delegate.swapGroupItem( + delegate.moveGroupItemToAnotherGroup( fromGroupId, phantomRecord!.fromGroupIndex, toGroupId,