Skip to content

Bring projects, wikis, and teams together with AI. AppFlowy is the AI collaborative workspace where you achieve more without losing control of your data. The leading open source Notion alternative.

chore: update doc

appflowy8f5569a01212
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<AFBoardContent> createState() => _AFBoardContentState();
+ State<_AppFlolwyBoardContent> createState() => _AppFlowyBoardContentState();
}
-class _AFBoardContentState extends State<AFBoardContent> {
+class _AppFlowyBoardContentState extends State<_AppFlolwyBoardContent> {
final GlobalKey _boardContentKey =
- GlobalKey(debugLabel: '$AFBoardContent overlay key');
+ GlobalKey(debugLabel: '$_AppFlolwyBoardContent overlay key');
late BoardOverlayEntry _overlayEntry;
final Map<String, GlobalObjectKey> _reorderFlexKeys = {};
@@ -263,7 +255,7 @@ class _AFBoardContentState extends State<AFBoardContent> {
value: widget.dataController.getGroupController(columnData.id),
child: Consumer<AFBoardGroupDataController>(
builder: (context, value, child) {
- final boardColumn = AppFlowyBoardGroupWidget(
+ final boardColumn = AppFlowyBoardGroup(
reorderFlexKey: reorderFlexKey,
// key: PageStorageKey<String>(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<String, GlobalKey> groupKeys = {};
final Map<String, DraggingState> groupDragStates = {};
final Map<String, Map<String, GlobalObjectKey>> 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<AppFlowyBoardGroupWidget> createState() =>
- _AppFlowyBoardGroupWidgetState();
+ State<AppFlowyBoardGroup> createState() => _AppFlowyBoardGroupState();
}
-class _AppFlowyBoardGroupWidgetState extends State<AppFlowyBoardGroupWidget> {
+class _AppFlowyBoardGroupState extends State<AppFlowyBoardGroup> {
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<AppFlowyBoardGroupData> _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<AppFlowyBoardGroupData> get groupDatas =>
UnmodifiableListView(_groupDatas);
+ /// Returns list of group id
List<String> 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<AppFlowyBoardGroupData> 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<String> 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,