diff --git a/packages/stream_chat_flutter_core/lib/src/channel_list_core.dart b/packages/stream_chat_flutter_core/lib/src/channel_list_core.dart index d2fd53c7..d60292d1 100644 --- a/packages/stream_chat_flutter_core/lib/src/channel_list_core.dart +++ b/packages/stream_chat_flutter_core/lib/src/channel_list_core.dart @@ -11,6 +11,7 @@ import 'stream_chat_core.dart'; /// [ChannelListCore] is a simplified class that allows fetching a list of channels while exposing UI builders. /// A [ChannelListController] is used to reload and paginate data. /// +/// /// ```dart /// class ChannelListPage extends StatelessWidget { /// @override @@ -50,20 +51,19 @@ import 'stream_chat_core.dart'; /// } /// ``` /// -/// /// Make sure to have a [StreamChatCore] ancestor in order to provide the information about the channels. class ChannelListCore extends StatefulWidget { /// Instantiate a new ChannelListView ChannelListCore({ Key key, - this.filter, - this.options, - this.sort, - this.pagination, @required this.errorBuilder, @required this.emptyBuilder, @required this.loadingBuilder, @required this.listBuilder, + this.filter, + this.options, + this.sort, + this.pagination, this.channelListController, }) : super(key: key); diff --git a/packages/stream_chat_flutter_core/lib/src/message_search_list_core.dart b/packages/stream_chat_flutter_core/lib/src/message_search_list_core.dart index e5ff9527..cfdfb0ae 100644 --- a/packages/stream_chat_flutter_core/lib/src/message_search_list_core.dart +++ b/packages/stream_chat_flutter_core/lib/src/message_search_list_core.dart @@ -27,25 +27,22 @@ import 'message_search_bloc.dart'; /// } /// ``` /// -/// /// Make sure to have a [MessageSearchBloc] ancestor in order to provide the information about the messages. /// The widget uses a [ListView.separated] to render the list of messages. /// -/// The widget components render the ui based on the first ancestor of type [StreamChatTheme]. -/// Modify it to change the widget appearance. class MessageSearchListCore extends StatefulWidget { /// Instantiate a new MessageSearchListView const MessageSearchListCore({ Key key, + @required this.emptyBuilder, + @required this.errorBuilder, + @required this.loadingBuilder, + @required this.childBuilder, this.messageQuery, this.filters, this.sortOptions, this.paginationParams, this.messageFilters, - @required this.emptyBuilder, - @required this.errorBuilder, - @required this.loadingBuilder, - @required this.childBuilder, this.messageSearchListController, }) : super(key: key); diff --git a/packages/stream_chat_flutter_core/lib/src/stream_chat_core.dart b/packages/stream_chat_flutter_core/lib/src/stream_chat_core.dart index 73f5eb61..3d23eb08 100644 --- a/packages/stream_chat_flutter_core/lib/src/stream_chat_core.dart +++ b/packages/stream_chat_flutter_core/lib/src/stream_chat_core.dart @@ -4,8 +4,14 @@ import 'package:flutter/foundation.dart'; import 'package:flutter/material.dart'; import 'package:stream_chat/stream_chat.dart'; -/// Widget used to provide information about the chat to the widget tree +/// Widget used to provide information about the chat to the widget tree. +/// This Widget is used to react to life cycle changes and system updates. +/// When the app goes into the background, the websocket connection is kept alive +/// for two minutes before being terminated. /// +/// Conversely, when app is resumed or restarted, a new connection is initiated. +/// +/// ```dart /// class MyApp extends StatelessWidget { /// final Client client; /// @@ -15,7 +21,7 @@ import 'package:stream_chat/stream_chat.dart'; /// Widget build(BuildContext context) { /// return MaterialApp( /// home: Container( -/// child: StreamChat( +/// child: StreamChatCore( /// client: client, /// child: ChannelListPage(), /// ), @@ -23,22 +29,25 @@ import 'package:stream_chat/stream_chat.dart'; /// ); /// } /// } +/// ``` /// -/// Use [StreamChatCore.of] to get the current [StreamChatCoreState] instance. class StreamChatCore extends StatefulWidget { - // ignore: public_member_api_docs + /// Instance of Stream Chat Client containing information about the current + /// application. final Client client; - // ignore: public_member_api_docs + + /// Widget descendant. final Widget child; - // ignore: public_member_api_docs + /// Constructor used for creating a new instance of [StreamChatCore]. + /// + /// [StreamChatCore] is a stateful widget which reacts to system events and updates + /// Stream's connection status accordingly. StreamChatCore({ Key key, @required this.client, @required this.child, - }) : super( - key: key, - ); + }) : super(key: key); @override StreamChatCoreState createState() => StreamChatCoreState(); @@ -58,11 +67,12 @@ class StreamChatCore extends StatefulWidget { } } -/// The current state of the StreamChat widget +/// State class associated with [StreamChatCore]. class StreamChatCoreState extends State with WidgetsBindingObserver { - // ignore: public_member_api_docs + /// Initialized client used throughout the application. Client get client => widget.client; + Timer _disconnectTimer; @override diff --git a/packages/stream_chat_flutter_core/lib/src/user_list_core.dart b/packages/stream_chat_flutter_core/lib/src/user_list_core.dart index e323591f..a9398d89 100644 --- a/packages/stream_chat_flutter_core/lib/src/user_list_core.dart +++ b/packages/stream_chat_flutter_core/lib/src/user_list_core.dart @@ -47,25 +47,25 @@ import 'package:stream_chat_flutter_core/src/users_bloc.dart'; /// } /// ``` /// +/// [UsersBloc] must be the ancestor of this widget. This is necessary since +/// [UserListCore] depends on functionality contained within [UsersBloc]. /// -/// Make sure to have a [UsersBloc] ancestor in order to provide the information about the users. /// The widget uses a [ListView.separated], [GridView.builder] to render the list, grid of channels. -/// -/// The widget components render the ui based on the first ancestor of type [StreamChatTheme]. -/// Modify it to change the widget appearance. +/// The parameters [listBuilder], [loadingBuilder], [emptyBuilder] and [errorBuilder] must all be supplied +/// and not null. class UserListCore extends StatefulWidget { - /// Instantiate a new UserListView + /// Instantiate a new [UserListCore] const UserListCore({ Key key, + @required this.errorBuilder, + @required this.emptyBuilder, + @required this.loadingBuilder, + @required this.listBuilder, this.filter, this.options, this.sort, this.pagination, this.groupAlphabetically = false, - @required this.errorBuilder, - @required this.emptyBuilder, - @required this.loadingBuilder, - @required this.listBuilder, this.userListController, }) : super(key: key); @@ -138,9 +138,9 @@ class _UserListCoreState extends State @override Widget build(BuildContext context) { - final usersBloc = UsersBloc.of(context); + final _usersBloc = UsersBloc.of(context); - return _buildListView(usersBloc); + return _buildListView(_usersBloc); } bool get isListAlreadySorted => @@ -207,9 +207,9 @@ class _UserListCoreState extends State } void loadData() { - final usersBloc = UsersBloc.of(context); + final _usersBloc = UsersBloc.of(context); - usersBloc.queryUsers( + _usersBloc.queryUsers( filter: widget.filter, sort: widget.sort, pagination: widget.pagination, @@ -218,13 +218,13 @@ class _UserListCoreState extends State } void paginateData() { - final usersBloc = UsersBloc.of(context); + final _usersBloc = UsersBloc.of(context); - usersBloc.queryUsers( + _usersBloc.queryUsers( filter: widget.filter, sort: widget.sort, pagination: widget.pagination.copyWith( - offset: usersBloc.users?.length ?? 0, + offset: _usersBloc.users?.length ?? 0, ), options: widget.options, ); @@ -249,7 +249,9 @@ class _UserListCoreState extends State } } -// ignore: public_member_api_docs +/// Represents an item in a the user stream list. +/// Header items are prefixed with the key `HEADER` While users are prefixed with +/// `USER`. abstract class ListItem { // ignore: public_member_api_docs String get key { diff --git a/packages/stream_chat_flutter_core/lib/src/users_bloc.dart b/packages/stream_chat_flutter_core/lib/src/users_bloc.dart index 489461ef..5ada9d90 100644 --- a/packages/stream_chat_flutter_core/lib/src/users_bloc.dart +++ b/packages/stream_chat_flutter_core/lib/src/users_bloc.dart @@ -4,7 +4,7 @@ import 'package:stream_chat/stream_chat.dart'; import 'stream_chat_core.dart'; -/// Widget dedicated to the management of a users list with pagination +/// Widget dedicated to the management of a users list with pagination. class UsersBloc extends StatefulWidget { /// The widget child final Widget child; @@ -49,7 +49,9 @@ class UsersBlocState extends State /// The stream notifying the state of queryUsers call Stream get queryUsersLoading => _queryUsersLoadingController.stream; - /// Calls [Client.queryUsers] updating [queryUsersLoading] stream + /// The Query Users method allows you to search for users and see if they are + /// online/offline. + /// [API Reference](https://getstream.io/chat/docs/flutter-dart/query_users/?language=dart) Future queryUsers({ Map filter, List sort,