diff --git a/packages/flutter_widgets/example/ios/fastlane/report.xml b/packages/flutter_widgets/example/ios/fastlane/report.xml index 69eca3e6..b6e7bdcb 100644 --- a/packages/flutter_widgets/example/ios/fastlane/report.xml +++ b/packages/flutter_widgets/example/ios/fastlane/report.xml @@ -5,27 +5,27 @@ - + - + - + - + - + diff --git a/packages/flutter_widgets/example/pubspec.yaml b/packages/flutter_widgets/example/pubspec.yaml index 73d1c2f1..9b387e39 100644 --- a/packages/flutter_widgets/example/pubspec.yaml +++ b/packages/flutter_widgets/example/pubspec.yaml @@ -1,7 +1,7 @@ name: example description: A new Flutter project. publish_to: 'none' -version: 1.2.0 +version: 1.2.0+1 environment: sdk: ">=2.2.2 <3.0.0" 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 7a9e7e41..b77ef394 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 @@ -66,7 +66,11 @@ class ChannelListCore extends StatefulWidget { this.sort, this.pagination, this.channelListController, - }) : super(key: key); + }) : assert(errorBuilder != null), + assert(emptyBuilder != null), + assert(loadingBuilder != null), + assert(listBuilder != null), + super(key: key); /// A [ChannelListController] allows reloading and pagination. /// Use [ChannelListController.loadData] and [ChannelListController.paginateData] respectively for reloading and pagination. @@ -257,11 +261,14 @@ class _ChannelListCoreState extends State } } -/// Controller used for paginating data in [ChannelListCore] +/// Controller used for loading more data and controlling pagination in [ChannelListCore]. class ChannelListController { - /// Call this function to reload data + /// This function calls Stream's servers to load a list of channels. If there is existing data, + /// calling this function causes a reload. VoidCallback loadData; - /// Call this function to load further data + /// This function is used to load another page of data. Note, [loadData] should be + /// used to populate the initial page of data. Calling [paginateData] performs a query + /// to load subsequent pages. VoidCallback paginateData; } diff --git a/packages/stream_chat_flutter_core/lib/src/channels_bloc.dart b/packages/stream_chat_flutter_core/lib/src/channels_bloc.dart index 2eef0f8a..7009234b 100644 --- a/packages/stream_chat_flutter_core/lib/src/channels_bloc.dart +++ b/packages/stream_chat_flutter_core/lib/src/channels_bloc.dart @@ -3,10 +3,29 @@ import 'dart:async'; import 'package:flutter/material.dart'; import 'package:rxdart/rxdart.dart'; import 'package:stream_chat/stream_chat.dart'; +import 'package:stream_chat_flutter_core/src/channel_list_core.dart'; import 'package:stream_chat_flutter_core/src/stream_chat_core.dart'; /// Widget dedicated to the management of a channel list with pagination +/// [ChannelsBloc] is used together with [ChannelListCore] to manage a list of +/// [Channel]s with pagination, re-ordering, querying and other operations +/// associated with [Channel]s. +/// +/// [ChannelsBloc] can be access at anytime by using the static [of] method +/// using Flutter's [BuildContext]. +/// +/// API docs: https://getstream.io/chat/docs/flutter-dart/query_channels/ class ChannelsBloc extends StatefulWidget { + /// Creates a new [ChannelsBloc]. The parameter [child] must be supplied and not null. + const ChannelsBloc({ + Key key, + @required this.child, + this.lockChannelsOrder = false, + this.channelsComparator, + this.shouldAddChannel, + }) : assert(child != null), + super(key: key); + /// The widget child final Widget child; @@ -19,15 +38,6 @@ class ChannelsBloc extends StatefulWidget { /// Function used to evaluate if a channel should be added to the list when a message.new event is received final bool Function(Event) shouldAddChannel; - /// Instantiate a new ChannelsBloc - const ChannelsBloc({ - Key key, - this.child, - this.lockChannelsOrder = false, - this.channelsComparator, - this.shouldAddChannel, - }) : super(key: key); - @override ChannelsBlocState createState() => ChannelsBlocState(); @@ -45,7 +55,7 @@ class ChannelsBloc extends StatefulWidget { } } -/// The current state of the [ChannelsBloc] +/// The current state of the [ChannelsBloc]. class ChannelsBlocState extends State with AutomaticKeepAliveClientMixin { @override diff --git a/packages/stream_chat_flutter_core/lib/src/lazy_load_scroll_view.dart b/packages/stream_chat_flutter_core/lib/src/lazy_load_scroll_view.dart index d74c1d98..1820827f 100644 --- a/packages/stream_chat_flutter_core/lib/src/lazy_load_scroll_view.dart +++ b/packages/stream_chat_flutter_core/lib/src/lazy_load_scroll_view.dart @@ -3,9 +3,23 @@ import 'package:flutter/widgets.dart'; enum _LoadingStatus { LOADING, STABLE } -/// A widget that wraps a [Widget] and will trigger [onEndOfPage]/[onStartOfPage] when it -/// reaches the bottom/start of the list +/// Wrapper around a [Scrollable] which triggers [onEndOfPage]/[onStartOfPage] the Scrollable +/// reaches to the start or end of the view extent. class LazyLoadScrollView extends StatefulWidget { + /// Creates a new instance of [LazyLoadScrollView]. The parameter [child] must be + /// supplied and not null. + const LazyLoadScrollView({ + Key key, + @required this.child, + this.onStartOfPage, + this.onEndOfPage, + this.onPageScrollStart, + this.onPageScrollEnd, + this.onInBetweenOfPage, + this.scrollOffset = 100, + }) : assert(child != null), + super(key: key); + /// The [Widget] that this widget watches for changes on final Widget child; @@ -27,19 +41,6 @@ class LazyLoadScrollView extends StatefulWidget { /// The offset to take into account when triggering [onEndOfPage]/[onStartOfPage] in pixels final double scrollOffset; - /// Initiates a LazyLoadScrollView widget - const LazyLoadScrollView({ - Key key, - @required this.child, - this.onStartOfPage, - this.onEndOfPage, - this.onPageScrollStart, - this.onPageScrollEnd, - this.onInBetweenOfPage, - this.scrollOffset = 100, - }) : assert(child != null), - super(key: key); - @override State createState() => _LazyLoadScrollViewState(); } diff --git a/packages/stream_chat_flutter_core/lib/src/message_list_core.dart b/packages/stream_chat_flutter_core/lib/src/message_list_core.dart index b8d5c8da..64e8f255 100644 --- a/packages/stream_chat_flutter_core/lib/src/message_list_core.dart +++ b/packages/stream_chat_flutter_core/lib/src/message_list_core.dart @@ -53,20 +53,22 @@ import 'stream_channel.dart'; /// Make sure to have a [StreamChannel] ancestor in order to provide the information about the channels. /// The widget uses a [ListView.custom] to render the list of channels. /// -/// The widget components render the ui based on the first ancestor of type [StreamChatTheme]. -/// Modify it to change the widget appearance. class MessageListCore extends StatefulWidget { - /// Instantiate a new MessageListView + /// Instantiate a new [MessageListView]. MessageListCore({ Key key, - this.showScrollToBottom = true, - this.parentMessage, @required this.loadingBuilder, @required this.emptyBuilder, @required this.messageListBuilder, @required this.errorWidgetBuilder, + this.showScrollToBottom = true, + this.parentMessage, this.messageListController, - }) : super(key: key); + }) : assert(loadingBuilder != null), + assert(emptyBuilder != null), + assert(messageListBuilder != null), + assert(errorWidgetBuilder != null), + super(key: key); /// A [MessageListController] allows pagination. /// Use [ChannelListController.paginateData] pagination. @@ -89,7 +91,8 @@ class MessageListCore extends StatefulWidget { /// If true will show a scroll to bottom message when there are new messages and the scroll offset is not zero final bool showScrollToBottom; - /// Parent message in case of a thread + /// If the current message belongs to a `thread`, this property represents the + /// first message or the parent of the conversation. final Message parentMessage; @override diff --git a/packages/stream_chat_flutter_core/lib/src/message_search_bloc.dart b/packages/stream_chat_flutter_core/lib/src/message_search_bloc.dart index ca6a983d..6458bebf 100644 --- a/packages/stream_chat_flutter_core/lib/src/message_search_bloc.dart +++ b/packages/stream_chat_flutter_core/lib/src/message_search_bloc.dart @@ -4,16 +4,23 @@ import 'package:stream_chat/stream_chat.dart'; import 'stream_chat_core.dart'; -/// Widget dedicated to the management of a message list with pagination +/// [MessageSearchBloc] is used to manage a list of messages with pagination. +/// This class can be used to load messages, perform queries, etc. +/// +/// [MessageSearchBloc] can be access at anytime by using the static [of] method +/// using Flutter's [BuildContext]. +/// +// API docs: https://getstream.io/chat/docs/flutter-dart/send_message/ class MessageSearchBloc extends StatefulWidget { - /// The widget child - final Widget child; - /// Instantiate a new MessageSearchBloc const MessageSearchBloc({ Key key, @required this.child, - }) : super(key: key); + }) : assert(child != null), + super(key: key); + + /// The widget child + final Widget child; @override MessageSearchBlocState createState() => MessageSearchBlocState(); 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 1eefc3a0..e3d98426 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 @@ -32,7 +32,12 @@ import 'message_search_bloc.dart'; /// The widget uses a [ListView.separated] to render the list of messages. /// class MessageSearchListCore extends StatefulWidget { - /// Instantiate a new MessageSearchListView + /// Instantiate a new [MessageSearchListView]. + /// The following parameters must be supplied and not null: + /// * [emptyBuilder] + /// * [errorBuilder] + /// * [loadingBuilder] + /// * [childBuilder] const MessageSearchListCore({ Key key, @required this.emptyBuilder, @@ -45,7 +50,11 @@ class MessageSearchListCore extends StatefulWidget { this.paginationParams, this.messageFilters, this.messageSearchListController, - }) : super(key: key); + }) : assert(emptyBuilder != null), + assert(errorBuilder != null), + assert(loadingBuilder != null), + assert(childBuilder != null), + super(key: key); /// A [MessageSearchListController] allows reloading and pagination. /// Use [MessageSearchListController.loadData] and [MessageSearchListController.paginateData] respectively for reloading and pagination. diff --git a/packages/stream_chat_flutter_core/lib/src/stream_channel.dart b/packages/stream_chat_flutter_core/lib/src/stream_channel.dart index 85f7ecca..af5502ae 100644 --- a/packages/stream_chat_flutter_core/lib/src/stream_channel.dart +++ b/packages/stream_chat_flutter_core/lib/src/stream_channel.dart @@ -17,7 +17,8 @@ enum QueryDirection { /// /// Use [StreamChannel.of] to get the current [StreamChannelState] instance. class StreamChannel extends StatefulWidget { - // ignore: public_member_api_docs + /// Creates a new instance of [StreamChannel]. Both [child] and [client] must + /// be supplied and not null. const StreamChannel({ Key key, @required this.child, 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 737e80c1..e17fe708 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 @@ -34,6 +34,20 @@ typedef EventHandler = void Function(Event event); /// ``` /// class StreamChatCore extends StatefulWidget { + /// 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, + this.onBackgroundEventReceived, + this.backgroundKeepAlive = const Duration(minutes: 1), + }) : assert(client != null), + assert(child != null), + super(key: key); + /// Instance of Stream Chat Client containing information about the current /// application. final Client client; @@ -49,18 +63,6 @@ class StreamChatCore extends StatefulWidget { /// upon the [Event.type] final EventHandler onBackgroundEventReceived; - /// 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, - this.onBackgroundEventReceived, - this.backgroundKeepAlive = const Duration(minutes: 1), - }) : super(key: key); - @override StreamChatCoreState createState() => StreamChatCoreState(); 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 a9398d89..23140258 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 @@ -50,7 +50,6 @@ 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]. /// -/// The widget uses a [ListView.separated], [GridView.builder] to render the list, grid of channels. /// The parameters [listBuilder], [loadingBuilder], [emptyBuilder] and [errorBuilder] must all be supplied /// and not null. class UserListCore extends StatefulWidget { @@ -67,7 +66,11 @@ class UserListCore extends StatefulWidget { this.pagination, this.groupAlphabetically = false, this.userListController, - }) : super(key: key); + }) : assert(errorBuilder != null), + assert(emptyBuilder != null), + assert(loadingBuilder != null), + assert(listBuilder != null), + super(key: key); /// A [UserListController] allows reloading and pagination. /// Use [UserListController.loadData] and [UserListController.paginateData] respectively for reloading and pagination. 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 5ada9d90..19c4a026 100644 --- a/packages/stream_chat_flutter_core/lib/src/users_bloc.dart +++ b/packages/stream_chat_flutter_core/lib/src/users_bloc.dart @@ -5,15 +5,22 @@ import 'package:stream_chat/stream_chat.dart'; import 'stream_chat_core.dart'; /// Widget dedicated to the management of a users list with pagination. +/// +/// [UsersBloc] can be access at anytime by using the static [of] method +/// using Flutter's [BuildContext]. +/// +/// API docs: https://getstream.io/chat/docs/flutter-dart/init_and_users/ class UsersBloc extends StatefulWidget { - /// The widget child - final Widget child; - - /// Instantiate a new UsersBloc + /// Instantiate a new [UsersBloc]. The parameter [child] must be supplied and + /// not null. const UsersBloc({ Key key, @required this.child, - }) : super(key: key); + }) : assert(child != null), + super(key: key); + + /// The widget child + final Widget child; @override UsersBlocState createState() => UsersBlocState();