From 748071ff40d5a29a823ed767af924d29b2c77309 Mon Sep 17 00:00:00 2001 From: Michael Bui <25263378+MaikuB@users.noreply.github.com> Date: Sat, 22 Feb 2020 14:42:59 +1100 Subject: [PATCH] documentation updates (#490) --- flutter_local_notifications/CHANGELOG.md | 83 +++++++++++++--- flutter_local_notifications/README.md | 16 ++-- .../example/lib/main.dart | 7 +- .../flutter_local_notifications_plugin.dart | 47 ++++++--- .../platform_flutter_local_notifications.dart | 6 ++ .../src/platform_specifics/android/enums.dart | 16 ++-- .../android/initialization_settings.dart | 4 +- .../platform_specifics/android/message.dart | 14 ++- .../android/notification_details.dart | 95 +++++++++++++------ .../platform_specifics/android/person.dart | 14 +-- .../styles/big_picture_style_information.dart | 18 ++-- .../styles/big_text_style_information.dart | 6 +- .../styles/default_style_information.dart | 6 +- .../styles/inbox_style_information.dart | 8 +- .../styles/messaging_style_information.dart | 9 +- .../ios/initialization_settings.dart | 34 +++++-- .../ios/notification_details.dart | 17 +++- .../lib/src/typedefs.dart | 6 +- .../lib/src/types.dart | 16 +++- flutter_local_notifications/pubspec.yaml | 2 +- 20 files changed, 295 insertions(+), 129 deletions(-) diff --git a/flutter_local_notifications/CHANGELOG.md b/flutter_local_notifications/CHANGELOG.md index 5ace9978b..3cea91ea5 100644 --- a/flutter_local_notifications/CHANGELOG.md +++ b/flutter_local_notifications/CHANGELOG.md @@ -1,36 +1,50 @@ +# [1.1.7] + +* [iOS] Added `requestPermissions()` method to `IOSFlutterLocalNotificationsPlugin` class. This can be used to request notification permissions separately from plugin initialisation. To facilitate this the `IOSFlutterLocalNotificationsPlugin` and `AndroidFlutterLocalNotificationsPlugin` now expose a static `instance` property that can be used obtain the platform-specific implementation of the plugin so that platform-specific methods can be used. Thanks to the PR from [Dariusz Łuksza](https://github.com/dluksza) +* Updated documentation to clarify that `getNotificationAppLaunchDetails()` is intended to be used more on if a notification from this plugin triggered launch an application +* Updated API docs for consistency and to better follow the guidelines on effective Dart documentation. + # [1.1.6] + * [iOS] Added ability to set badge number. Thanks to PR from [FelixYew](https://github.com/FelixYew) * Fixed a spelling mistake in the 1.1.5+1 changelog entry # [1.1.5+1] + * No functional changes. Fixed a reported formatting issue. * Mention removal of named constructor argument in 1.1.0 changelog entry * Add API docs to `FlutterLocalNotificationsPlugin.private()` on how it could be used for testing * Update notes on testing to mention that the `FlutterLocalNotificationsPlugin.private()` named constructor may be of use # [1.1.5] + * [Android] minor optimisation on scheduling related code so that `Gson` instance is reused instead of being rebuilt each time * Changed plugin to require 1.12.3+hotfix.5 or greater since pub has issues resolving 1.12.3+hotfix.6 * Updated changelog entry for version 1.1.4 to mention removal of upper bound constraint on Flutter SDK requirement # [1.1.4] + * Support v2 Android embedding. Note that there is currently a [known issue](https://github.com/flutter/flutter/issues/49365) in the Flutter SDK that will cause `onSelectNotification` to fire twice on Android. The fix is in the master channel but hasn't rolled out to other channels. Subscribe to the issue for updates. * Require Flutter SDK 1.12.3+hotfix.6 or greater. Maximum SDK restraint has also been removed # [1.1.3] + * Expose `NotificationAppLaunchDetails` via main plugin * Retroactively updated changelog for 1.1.0 to indicate breaking change on moving to using platform interface * Made plugin methods be a no-op to fix issue with version 1.1.0 where test code involving the plugin would fail when running on an environment that is neither Android or iOS # [1.1.2] + * Passing a null notification id now throws an `ArgumentError`. Thanks to PR from [talmor_guy](https://github.com/talmor-guy) * Slight tweak to message displayed with by `ArgumentError` when notification id is not within range of a 32-bit integer # [1.1.1] + * [Android] Added ability to specify timeout duration of notification * [Android] Added ability to specify the notification category # [1.1.0] + * **BREAKING CHANGE** Updated plugin to make use of `flutter_local_notifications_platform_interface` version 1.0.1. This allows for platform-specific implementations of the platform interface to now be accessible. Note that the plugin will check which platform the plugin is running on. *Note*: this may have inadvertently broke some tests for users as the plugin now checks which platform the plugin is executing code on and would throw an `UnimplementedError` since neither iOS or Android can be detected. Another issue is that `NotificationAppLaunchDetails` was no longer exposed via the main plugin. Please upgrade to 1.1.3 to have both of these issues fixed * **BREAKING CHANGE** Plugin callbacks are no longer publicly accessible @@ -38,26 +52,33 @@ * **BREAKING CHANGE** `MethodChannel` argument has been removed from the named constructor that was visible for testing purposes # [1.0.0] + * **BREAKING CHANGE** [iOS] Added checks to ensure callbacks are only invoked for notifications originating from the plugin to improve compatibility with other notification plugins. * [Android] Bump Gradle plugin to 3.5.3 # [0.9.1+3] + * Include notes in getting started section to emphasise that the steps in the integration guide for each platform needs to be done. * Move information in the readme on configuring resources to keep on Android. # [0.9.1+2] + * Update link to repository due to restructuring. # [0.9.1+1] + * Update readme with Swift example code on cancelling local notifications using the deprecated `UILocalNotification` iOS APIs when trying to prevent local notifications from appearing in the scenario where user has uninstalled the app whilst there are pending notification requests, reinstalled the app and ran it again. # [0.9.1] + * Add support for media notification. This currently only supports showing the specified image as album artwork. Thanks to PR by [gianlucaparadise](https://github.com/gianlucaparadise) # [0.9.0+1] + * Fix readme where Objective-C was written twice # [0.9.0] + * [Android] Add ability to customise visibility of a notification on the lockscreen. Thanks to PR by [gianlucaparadise](https://github.com/gianlucaparadise) * [Android] Bumped compile and target SDK to 29 * **BREAKING CHANGE** [iOS] Plugin no longer registers as a `UNUserNotificationCenterDelegate`. This is to enable compatibility with other plugins that display notifications. Developers must now do this themselves. Refer to the updated iOS integration section for more info on this @@ -67,19 +88,24 @@ * Migrate the plugin to the pubspec platforms manifest # [0.8.4+3] + * Update example to fix issue [372](https://github.com/MaikuB/flutter_local_notifications/issues/372) around app not firing `onSelectNotification` having switched to using streams and initialising the app in the `main` function. # [0.8.4+2] + * Add note to readme that plugin initialisation be done as part of showing the first page of the app. # [0.8.4+1] + * Fix typo in readme. Thanks to PR submitted by [Michael Arndt](https://github.com/MeneDev) * Updated API docs and example around initializing the plugin to make it clearer that `initialize` should only be called once on app startup. # [0.8.4] + * [iOS] Fix issue [336](https://github.com/MaikuB/flutter_local_notifications/issues/336) where a native crash occurred after creating a notification with a null body # [0.8.3] + * [Android] Changed intents to use the `FLAG_UPDATE_CURRENT` flag instead of `FLAG_CANCEL_CURRENT` as alarms weren't being cleared out properly when updating or cancel a notification. Thanks to [WJQ](https://github.com/jjs1015) for submitting the PR to address the cancellation issue # [0.8.2+1] @@ -87,96 +113,120 @@ * Update readme around approach used to develop the plugin # [0.8.2] + * [iOS] Fix issue [295](https://github.com/MaikuB/flutter_local_notifications/issues/295) where `onSelectNotification` callback wasn't trigger when a notification had been tapped on whilst the app was terminated # [0.8.1+1] + * Update comment in example around grouped notifications to clarify that the summary notification ia required for all versions of Android * Update email address in pubspec.yaml # [0.8.1] + * [iOS] Accepted PR from [Josh Burton](https://github.com/athornz) that improves ability for plugin to work in multiple isolate by moving state to instance variables * [iOS] Add a guard to prevent a scenario from happening where it may still be possible for the `onDidReceiveLocalNotification` callback to trigger on iOS 10+ * Minor update to readme on raising issues and correction on payload information # [0.8.0] + * Added an optional parameter named `androidAllowWhileIdle` to `schedule` method. This will allow notifications to still display at the specified time when the Android device is in an low-power idle mode. * **BREAKING CHANGE** Bump minimum Flutter version to 1.5.0 * **BREAKING CHANGE** Update Flutter dependencies # [0.7.1+3] + * Fix build status badge # [0.7.1+2] + * Started adding Cirrus CI configuration and include CI status badge as part of readme # [0.7.1+1] + * Updated readme to include information about OS limits related to scheduled notifications # [0.7.1] + * [Android] Added ability to specify the "ticker" text. Thanks to PR submitted by [Zhang Jing](https://github.com/byrdkm17) * Spelling mistake fixes in readme. Thanks to PR submitted by [Wanbok (Wayne) Choi](https://github.com/wanbok) # [0.7.0] + * **BREAKING CHANGE** [Android] Updated to Gradle 5.1.1 and Android Gradle plugin has been updated to 3.4.0 (aligns with Android Studio 3.4 release). Example app has also been updated to Gradle 5.1.1. Apps will need to update to use the plugin. Please see [here](https://developer.android.com/studio/releases/gradle-plugin) for more information if you need help on updating * [Android] Add ability to specify the LED colour of the notification. Updated example app to show this can be done. Note that for Android 8.0+ (i.e. API 26+) that this is tied to the notification channel # [0.6.1] + * [Android/iOS] Added `pendingNotificationRequests` method. This will return a list of pending notification requests that have been scheduled to be shown in the future. Updated example app to include sample code for calling the method * [Android] Fix an issue where scheduling a notification (recurring or otherwise) with the same id as another notification that was scheduled with the same id would result in both being stored in shared preferences. The shared preferences were used to reschedule notifications on reboot and shouldn't affect the functionality of displaying the notifications * Updated plugin methods to return `Future` instead of `Future` as per Dart guidelines -* Updated README to mention known issue with scheduling notifications and daylight savings +* Updated readme to mention known issue with scheduling notifications and daylight savings * Refactored widgets in example app # [0.6.0] + * **BREAKING CHANGE** [Android] Updated Gradle plugin to 3.3.2 * **BREAKING CHANGE** [Android] Changed to store the name of drawable specified as the small icon to be used for Android notifications instead of the resource ID. This should fix the scenario where an app could be updated and the resource IDs got change and cause scheduled notifications to not appear. Believe this fix should retroactively apply for notifications scheduled with an icon specified but won't apply to those that were scheduled to use the default icon specified via the `initialize` method. This is due to the fact the name of the default icon wasn't being cached in previous ones but this has now changed so it's cached in shared preferences from this version onwards # [0.5.2] + * Fix for when multiple isolates use the plugin. Thanks to PR submitted by [xtelinco](https://github.com/xtelinco) * Added the `channelAction` field to the `AndroidNotificationDetails` class. This provides options for managing notification channels on Android. Default behaviour is to create the notification channel if it doesn't exist (which was what it it use to do). Another option is to update the details of the notification channel. Example app has been updated to demonstrate how to update a notification channel when sending a notification # [0.5.1+2] -* Highlight note on migrating to AndroidX more in README + +* Highlight note on migrating to AndroidX more in readme # [0.5.1+1] -* README corrections and add information on migrating to AndroidX + +* Readme corrections and add information on migrating to AndroidX # [0.5.1] -* Updated gradle plugin of example app to 3.3.1 + +* Updated Gradle plugin of example app to 3.3.1 * Added support for messaging style notifications on Android as requested in issue [159](https://github.com/MaikuB/flutter_local_notifications/issues/159). See example app for some sample code # [0.5.0] + * **BREAKING CHANGE** Migrated to use AndroidX as the Android support libraries are deprecated. There shouldn't be any functional changes. Developers may require migrating their apps to support this following [this guide](https://developer.android.com/jetpack/androidx/migrate). This addresses issue [162](https://github.com/MaikuB/flutter_local_notifications/issues/162). Thanks to [Jeff Scaturro](https://github.com/JeffScaturro) for submitting the PR for this work. Note that if you don't want to migrate your app to use AndroidX yet then you may need to pin dependencies to a specific version # [0.4.5] + * Fix issue [160](https://github.com/MaikuB/flutter_local_notifications/issues/160) so that notifications created with the `schedule` on Android will appear at the exact date and time they are scheduled # [0.4.4+2] -* Fix CHANGELOG + +* Fix changelog # [0.4.4+1] + * **BREAKING CHANGE** Fix naming of `onDidReceiveLocalNotification` property in the `IOSInitializationSettings` class (was previously named `onDidReceiveLocalNotificationCallback` by accident) # [0.4.4] + * **BREAKING CHANGE** removed `registerUNNotificationCenterDelegate` argument for the `IOSInitializationSettings` class as it wasn't actually used. * Plugin can now handle `didReceiveLocalNotification` delegate method in iOS and allow developers to handle the associated callback in Flutter. Added a `onDidReceiveLocalNotificationCallback` argument to the `IOSInitializationSettings` class to enable this and updated the sample code to demonstrate the usage. This should resolve issue [14](https://github.com/MaikuB/flutter_local_notifications/issues/14). # [0.4.3] + * Merged PR from Aine LLC (ganessaa) to fix issue [140](https://github.com/MaikuB/flutter_local_notifications/issues/140) where scheduled notifications were shown immediately on iOS versions before 10. Note that this issue is likely related to an [known issue in the Flutter engine](https://github.com/flutter/flutter/issues/21313) that may require switching channels to be addressed as the fix isn't on the stable channel yet. * [Android] Provide a way to hide the large icon when showing an expanded big picture notification via the `hideExpandedLargeIcon` flag within thr `BigPictureStyleInformation` class. This provides a solution for issue [136](https://github.com/MaikuB/flutter_local_notifications/issues/136). Updated the example to demonstrate * Merged PR from (riccardoratta) so that sample code is coloured in GitHub to improve readability. # [0.4.2+1] + * Update changelog to indicate when `MessageHandler` typedef got renamed (in 0.4.1) as raised in issue [132](https://github.com/MaikuB/flutter_local_notifications/issues/132) # [0.4.2] + * **BREAKING CHANGE** Fix issue [127](https://github.com/MaikuB/flutter_local_notifications/issues/127) by changing plugin to Android Support Library version 27.1.1, compile and target SDK version to 27 due to issues Flutter has with API 28. # [0.4.1+1] * Remove unused code in example app # [0.4.1] + * **BREAKING CHANGE** renamed the `selectNotification` callback exposed by the `initialize` function to `onSelectNotification` * **BREAKING CHANGE** renamed the `MessageHandler` typedef to `SelectNotificationCallback` * **BREAKING CHANGE** updated plugin to Android Support Library version 28.0, compile and target SDK version to 28 @@ -185,41 +235,50 @@ * Updated version of the http dependency for used by the example app # [0.4.0] + * [Android] Fix issue [112](https://github.com/MaikuB/flutter_local_notifications/issues/112) where big picture notifications wouldn't show # [0.3.9] + * [Android] Added ability to show progress notifications and updated example app to demonstrate how to display them # [0.3.8] + * Added `getNotificationAppLaunchDetails()` method that could be used to determine if the app was launched via notification (raised in issue [99](https://github.com/MaikuB/flutter_local_notifications/issues/99)) -* Added documentation around ProGuard configuration to Android Integration section of the README +* Added documentation around ProGuard configuration to Android Integration section of the readme ## [0.3.7] + * [Android] Fix issue [88](https://github.com/MaikuB/flutter_local_notifications/issues/88) where cancelled notifications could reappear on reboot. ## [0.3.6] + * [Android] Add mapping to the setOnlyAlertOnce method [83](https://github.com/MaikuB/flutter_local_notifications/issues/83). Allows the sound, vibrate and ticker to be played if the notification is not already showing * [Android] Add mapping to setShowBadge for notification channels that controls if notifications posted to channel can appear as application icon badges in a Launcher ## [0.3.5] + * [Android] Will now throw a PlatformException with a more friendly error message on the Flutter side when a specified resource hasn't been found e.g. when specifying the icon for the notification * Fix overflow rendering issue in the example app ## [0.3.4] + * [Android] Fix issue [71](https://github.com/MaikuB/flutter_local_notifications/issues/71) where the wrong time on when the notification occurred is being displayed. **BREAKING CHANGE** this involves changing it the receiver for displaying a scheduled notification will only build the notification prior to displaying it. There is a fix applied to existing scheduled notifications in this release that will be eventually be removed as going forward all scheduled notifications will work as just described * [Android] Fix an issue with serialising and deserialising the notifications so that additional style types (big picture and inbox) would be recognised. This affected scheduled notifications where upon rebooting the device, the plugin would need to reschedule the notifications using information saved in shared preferences. ## [0.3.3] + * [iOS] Fixes issue [61](https://github.com/MaikuB/flutter_local_notifications/issues/61) where the `showDailyAtTime` and `showWeeklyAtDayAndTime` methods may not show notifications that should appear the next day. Thanks to [Jeff Scaturro](https://github.com/JeffScaturro) for submitting the PR to fix this. ## [0.3.2] -* No functional changes. Updated the README around raising issues, recurring Android notifications on Android and a fix in the getting started section (thanks to [ebeem](https://github.com/ebeem) for spotting that). + +* No functional changes. Updated the readme around raising issues, recurring Android notifications on Android and a fix in the getting started section (thanks to [ebeem](https://github.com/ebeem) for spotting that). ## [0.3.1] * No functional changes in this release but removed a class that is no longer used due to changes in 0.3.0 -* Updated README information the example app and configuring Android notification icons -* Changelog is now in reverse chronological order so details about the most recent release are at the top +* Updated readme information the example app and configuring Android notification icons +* changelog is now in reverse chronological order so details about the most recent release are at the top * Additional comments in the example's main.dart file to refer to downloading the complete example app project from GitHub ## [0.3.0] @@ -242,7 +301,7 @@ ## [0.2.8] -* Update dev dependencies required for flutter test to run. This is due to a breaking change in Flutter. See https://github.com/flutter/flutter/wiki/Changelog +* Update dev dependencies required for flutter test to run. This is due to a breaking change in Flutter. See https://github.com/flutter/flutter/wiki/changelog ## [0.2.7] @@ -347,7 +406,7 @@ ## [0.0.4] -* Updated README +* Updated readme ## [0.0.3] @@ -355,7 +414,7 @@ ## [0.0.2] -* README fixes +* Readme fixes ## [0.0.1] diff --git a/flutter_local_notifications/README.md b/flutter_local_notifications/README.md index 5cb44becb..27e5b1fa4 100644 --- a/flutter_local_notifications/README.md +++ b/flutter_local_notifications/README.md @@ -39,7 +39,7 @@ A cross platform plugin for displaying local notifications. * [Android] Group notifications * [Android] Show progress notifications * [Android] Configure notification visibility on the lockscreen -* [iOS] Delay requesting notification permission +* [iOS] Request notification permissions when needed (e.g. in response to user turning on a setting) * [iOS] Customise the permissions to be requested around displaying notifications Note that this plugin aims to provide abstractions for all platforms as opposed to having methods that only work on specific platforms. However, each method allows passing in "platform-specifics" that contains data that is specific for customising notifications on each platform. This approach means that some scenarios may not be covered by the plugin. Developers can either fork or maintain their code for showing notifications in these situations. Note that the plugin still under development so expect the API surface to change over time. @@ -79,7 +79,7 @@ var initializationSettingsIOS = IOSInitializationSettings( onDidReceiveLocalNotification: onDidReceiveLocalNotification); var initializationSettings = InitializationSettings( initializationSettingsAndroid, initializationSettingsIOS); -flutterLocalNotificationsPlugin.initialize(initializationSettings, +await flutterLocalNotificationsPlugin.initialize(initializationSettings, onSelectNotification: onSelectNotification); ``` @@ -101,15 +101,15 @@ In the real world, this payload could represent the id of the item you want to d *Notes around initialisation*: if the app had been launched by tapping on a notification created by this plugin, calling `initialize` is what will trigger the `onSelectNotification` to trigger to handle the notification that the user tapped on. An alternative to handling the "launch notification" is to call the `getNotificationAppLaunchDetails` method that is available in the plugin. This could be used, for example, to change the home route of the app for deep-linking. Calling `initialize` will still cause the `onSelectNotification` callback to fire for the launch notification. It will be up to developers to ensure that they don't process the same notification twice (e.g. by storing and comparing the notification id). -### [iOS only] Requesting notification permission +### [iOS only] Requesting notification permissions -By default this plugin will request notification permission when it is initialized. `IOSInitializationSettings` have three named parameters: +By default this plugin will request notification permissions when it is initialised. `IOSInitializationSettings` have three named parameters: 1. `requestSoundPermission`, 1. `requestBadgePermission`, 1. `requestAlertPermission` that control this behaviour. -If you want to delay permission request, set all of the above to false. +If you want to request permissions at a later point in your application, set all of the above to false. ```dart FlutterLocalNotificationsPlugin flutterLocalNotificationsPlugin = new FlutterLocalNotificationsPlugin(); @@ -123,11 +123,11 @@ var initializationSettingsIOS = new IOSInitializationSettings( ); var initializationSettings = new InitializationSettings( initializationSettingsAndroid, initializationSettingsIOS); -flutterLocalNotificationsPlugin.initialize(initializationSettings, +await flutterLocalNotificationsPlugin.initialize(initializationSettings, onSelectNotification: onSelectNotification); ``` -Then later call `requestPermissions` method with desired permissions. +Then call `requestPermissions` method with desired permissions at the appropriate point in your application ```dart var result = await IOSFlutterLocalNotificationsPlugin.instance?.requestPermissions( @@ -306,7 +306,7 @@ await flutterLocalNotificationsPlugin.cancelAll(); ``` -### Get details on if the app was launched via a notification +### Get details on if the app was launched via a notification created by this plugin ```dart var notificationAppLaunchDetails = diff --git a/flutter_local_notifications/example/lib/main.dart b/flutter_local_notifications/example/lib/main.dart index dc98ffb57..7e35328f0 100644 --- a/flutter_local_notifications/example/lib/main.dart +++ b/flutter_local_notifications/example/lib/main.dart @@ -45,6 +45,8 @@ Future main() async { // await flutterLocalNotificationsPlugin.getNotificationAppLaunchDetails(); var initializationSettingsAndroid = AndroidInitializationSettings('app_icon'); + // Note: permissions aren't requested here just to demonstrate that can be done later using the `requestPermissions()` method + // of the `IOSFlutterLocalNotificationsPlugin` class var initializationSettingsIOS = IOSInitializationSettings( requestAlertPermission: false, requestBadgePermission: false, @@ -56,13 +58,14 @@ Future main() async { }); var initializationSettings = InitializationSettings( initializationSettingsAndroid, initializationSettingsIOS); - await flutterLocalNotificationsPlugin.initialize(initializationSettings, - onSelectNotification: (String payload) async { + var initialised = await flutterLocalNotificationsPlugin.initialize( + initializationSettings, onSelectNotification: (String payload) async { if (payload != null) { debugPrint('notification payload: ' + payload); } selectNotificationSubject.add(payload); }); + print('initialised: $initialised'); runApp( MaterialApp( home: HomePage(), diff --git a/flutter_local_notifications/lib/src/flutter_local_notifications_plugin.dart b/flutter_local_notifications/lib/src/flutter_local_notifications_plugin.dart index 8f729a110..ba164a8d8 100644 --- a/flutter_local_notifications/lib/src/flutter_local_notifications_plugin.dart +++ b/flutter_local_notifications/lib/src/flutter_local_notifications_plugin.dart @@ -11,13 +11,15 @@ import 'platform_flutter_local_notifications.dart'; import 'typedefs.dart'; import 'types.dart'; -/// `FlutterLocalNotificationsPlugin` allows applications to display a local notification. +/// Provides cross-platform functionality for displaying local notifications. +/// /// The plugin will check the platform that is running on to use the appropriate platform-specific /// implementation of the plugin. The plugin methods will be a no-op when the platform can't be detected. class FlutterLocalNotificationsPlugin { factory FlutterLocalNotificationsPlugin() => _instance; /// Used internally for creating the appropriate platform-specific implementation of the plugin. + /// /// This can be used for tests as well. For example, the following code /// /// ``` @@ -42,12 +44,21 @@ class FlutterLocalNotificationsPlugin { final Platform _platform; - /// Initializes the plugin. Call this method on application before using the plugin further. - /// This should only be done once. When a notification created by this plugin was used to launch the app, - /// calling `initialize` is what will trigger to the `onSelectNotification` callback to be fire. + /// Initializes the plugin. + /// + /// Call this method on application before using the plugin further. This should only be done once. When a notification + /// created by this plugin was used to launch the app, calling `initialize` is what will trigger to the `onSelectNotification` + /// callback to be fire. + /// + /// Will return a [bool] value to indicate if initialization succeeded. On iOS this is dependent on if permissions have been + /// granted to show notification When running in environment that is neither Android and iOS (e.g. when running tests), + /// this will be a no-op and return true. /// - /// Will return a [bool] value to indicate if initialization succeeded. When running in environment that is - /// neither Android and iOS (e.g. when running tests), this will be a no-op and return true. + /// Note that on iOS, initialisation may also request notification permissions where users will see a permissions prompt. + /// This may be fine in cases where it's acceptable to do this when the application runs for the first time. However, if your application + /// needs to do this at a later point in time, set the [IOSInitializationSettings.requestAlertPermission], + /// [IOSInitializationSettings.requestBadgePermission] and [IOSInitializationSettings.requestSoundPermission] values to false. + /// [requestPermissions] can then be called to request permissions when needed. Future initialize(InitializationSettings initializationSettings, {SelectNotificationCallback onSelectNotification}) async { if (_platform.isAndroid) { @@ -64,9 +75,9 @@ class FlutterLocalNotificationsPlugin { return true; } - /// Returns info on if a notification had been used to launch the application. - /// An example of how this could be used is to change the initial route of your application when it starts up. + /// Returns info on if a notification created from this plugin had been used to launch the application. /// + /// An example of how this could be used is to change the initial route of your application when it starts up. /// If the plugin isn't running on either Android or iOS then it defaults to indicate that a notification wasn't /// used to launch the app. Future getNotificationAppLaunchDetails() async { @@ -85,7 +96,7 @@ class FlutterLocalNotificationsPlugin { } } - /// Show a notification with an optional payload that will be passed back to the app when a notification is tapped + /// Show a notification with an optional payload that will be passed back to the app when a notification is tapped. Future show(int id, String title, String body, NotificationDetails notificationDetails, {String payload}) async { @@ -105,17 +116,22 @@ class FlutterLocalNotificationsPlugin { } } - /// Cancel/remove the notification with the specified id. This applies to notifications that have been scheduled and those that have already been presented. + /// Cancel/remove the notification with the specified id. + /// + /// This applies to notifications that have been scheduled and those that have already been presented. Future cancel(int id) async { await FlutterLocalNotificationsPlatform.instance?.cancel(id); } - /// Cancels/removes all notifications. This applies to notifications that have been scheduled and those that have already been presented. + /// Cancels/removes all notifications. + /// + /// This applies to notifications that have been scheduled and those that have already been presented. Future cancelAll() async { await FlutterLocalNotificationsPlatform.instance?.cancelAll(); } - /// Schedules a notification to be shown at the specified time with an optional payload that is passed through when a notification is tapped + /// Schedules a notification to be shown at the specified time with an optional payload that is passed through when a notification is tapped. + /// /// The [androidAllowWhileIdle] parameter is Android-specific and determines if the notification should still be shown at the specified time /// even when in a low-power idle mode. Future schedule(int id, String title, String body, @@ -136,6 +152,7 @@ class FlutterLocalNotificationsPlugin { } /// Periodically show a notification using the specified interval. + /// /// For example, specifying a hourly interval means the first time the notification will be an hour after the method has been called and then every hour after that. Future periodicallyShow(int id, String title, String body, RepeatInterval repeatInterval, NotificationDetails notificationDetails, @@ -157,7 +174,7 @@ class FlutterLocalNotificationsPlugin { } } - /// Shows a notification on a daily interval at the specified time + /// Shows a notification on a daily interval at the specified time. Future showDailyAtTime(int id, String title, String body, Time notificationTime, NotificationDetails notificationDetails, {String payload}) async { @@ -176,7 +193,7 @@ class FlutterLocalNotificationsPlugin { } } - /// Shows a notification on a daily interval at the specified time + /// Shows a notification on a daily interval at the specified time. Future showWeeklyAtDayAndTime(int id, String title, String body, Day day, Time notificationTime, NotificationDetails notificationDetails, {String payload}) async { @@ -195,7 +212,7 @@ class FlutterLocalNotificationsPlugin { } } - /// Returns a list of notifications pending to be delivered/shown + /// Returns a list of notifications pending to be delivered/shown. Future> pendingNotificationRequests() { return FlutterLocalNotificationsPlatform.instance ?.pendingNotificationRequests(); diff --git a/flutter_local_notifications/lib/src/platform_flutter_local_notifications.dart b/flutter_local_notifications/lib/src/platform_flutter_local_notifications.dart index 163b2478d..a1ceea48a 100644 --- a/flutter_local_notifications/lib/src/platform_flutter_local_notifications.dart +++ b/flutter_local_notifications/lib/src/platform_flutter_local_notifications.dart @@ -198,6 +198,12 @@ class IOSFlutterLocalNotificationsPlugin /// Initializes the plugin. Call this method on application before using the plugin further. /// This should only be done once. When a notification created by this plugin was used to launch the app, /// calling `initialize` is what will trigger to the `onSelectNotification` callback to be fire. + /// + /// Initialisation may also request notification permissions where users will see a permissions prompt. This may be fine + /// in cases where it's acceptable to do this when the application runs for the first time. However, if your application + /// needs to do this at a later point in time, set the [IOSInitializationSettings.requestAlertPermission], + /// [IOSInitializationSettings.requestBadgePermission] and [IOSInitializationSettings.requestSoundPermission] values to false. + /// [requestPermissions] can then be called to request permissions when needed. Future initialize(IOSInitializationSettings initializationSettings, {SelectNotificationCallback onSelectNotification}) async { _onSelectNotification = onSelectNotification; diff --git a/flutter_local_notifications/lib/src/platform_specifics/android/enums.dart b/flutter_local_notifications/lib/src/platform_specifics/android/enums.dart index 07ec6d7d8..7b6a0b270 100644 --- a/flutter_local_notifications/lib/src/platform_specifics/android/enums.dart +++ b/flutter_local_notifications/lib/src/platform_specifics/android/enums.dart @@ -1,10 +1,10 @@ /// Specifies the source for a bitmap used by Android notifications. enum BitmapSource { Drawable, FilePath } -/// Specifies the source for icons +/// Specifies the source for icons. enum IconSource { Drawable, FilePath, ContentUri } -/// The available notification styles on Android +/// The available notification styles on Android. enum AndroidNotificationStyle { Default, BigPicture, @@ -15,11 +15,13 @@ enum AndroidNotificationStyle { } /// The available actions for managing notification channels. -/// [CreateIfNotExists]: will create a channel if it doesn't exist -/// [Update]: will update the details of an existing channel. Note that some details can not be changed once a channel has been created +/// +/// [CreateIfNotExists]: will create a channel if it doesn't exist. +/// [Update]: will update the details of an existing channel. Note that some details can not be changed once a channel has been created. enum AndroidNotificationChannelAction { CreateIfNotExists, Update } /// The available importance levels for Android notifications. +/// /// Required for Android 8.0+ class Importance { static const Unspecified = Importance(-1000); @@ -37,7 +39,7 @@ class Importance { const Importance(this.value); } -/// Priority for notifications on Android 7.1 and lower +/// Priority for notifications on Android 7.1 and lower. class Priority { static const Min = Priority(-2); static const Low = Priority(-1); @@ -52,10 +54,10 @@ class Priority { const Priority(this.value); } -/// The available alert behaviours for grouped notifications +/// The available alert behaviours for grouped notifications. enum GroupAlertBehavior { All, Summary, Children } -/// Defines the notification visibility on the lockscreen +/// Defines the notification visibility on the lockscreen. enum NotificationVisibility { /// Show this notification on all lockscreens, but conceal sensitive or private information on secure lockscreens. Private, diff --git a/flutter_local_notifications/lib/src/platform_specifics/android/initialization_settings.dart b/flutter_local_notifications/lib/src/platform_specifics/android/initialization_settings.dart index de4111e91..63f28726d 100644 --- a/flutter_local_notifications/lib/src/platform_specifics/android/initialization_settings.dart +++ b/flutter_local_notifications/lib/src/platform_specifics/android/initialization_settings.dart @@ -1,6 +1,6 @@ -/// Plugin initialization settings for Android +/// Plugin initialization settings for Android. class AndroidInitializationSettings { - /// Sets the default icon for notifications + /// Sets the default icon for notifications. final String defaultIcon; const AndroidInitializationSettings(this.defaultIcon); diff --git a/flutter_local_notifications/lib/src/platform_specifics/android/message.dart b/flutter_local_notifications/lib/src/platform_specifics/android/message.dart index dfbd5ff3c..72ce60a4a 100644 --- a/flutter_local_notifications/lib/src/platform_specifics/android/message.dart +++ b/flutter_local_notifications/lib/src/platform_specifics/android/message.dart @@ -1,20 +1,24 @@ import 'person.dart'; -/// Represents a message used in Android messaging style notifications +/// Represents a message used in Android messaging style notifications. class Message { /// The message text final String text; - /// Time at which the message arrived. Note that this is eventually converted to milliseconds since epoch as required by Android + /// Time at which the message arrived. + /// + /// Note that this is eventually converted to milliseconds since epoch as required by Android. final DateTime timestamp; - /// Person that sent this message + /// Person that sent this message. final Person person; - /// MIME type for this message context when the [dataUri] is provided + /// MIME type for this message context when the [dataUri] is provided. final String dataMimeType; - /// Uri containing the content. The original text will be used if the content or MIME type isn't supported + /// Uri containing the content. + /// + /// The original text will be used if the content or MIME type isn't supported final String dataUri; Message(this.text, this.timestamp, this.person, diff --git a/flutter_local_notifications/lib/src/platform_specifics/android/notification_details.dart b/flutter_local_notifications/lib/src/platform_specifics/android/notification_details.dart index bc1cffc73..1218f5dda 100644 --- a/flutter_local_notifications/lib/src/platform_specifics/android/notification_details.dart +++ b/flutter_local_notifications/lib/src/platform_specifics/android/notification_details.dart @@ -5,102 +5,136 @@ import 'enums.dart'; import 'styles/style_information.dart'; import 'styles/default_style_information.dart'; -/// Configures the notification on Android +/// Configures the notification on Android. class AndroidNotificationDetails { - /// The icon that should be used when displaying the notification. When not specified, this will use the default icon that has been configured. + /// The icon that should be used when displaying the notification. + /// + /// When not specified, this will use the default icon that has been configured. final String icon; - /// The channel's id. Required for Android 8.0+ + /// The channel's id. + /// + /// Required for Android 8.0+. final String channelId; - /// The channel's name. Required for Android 8.0+ + /// The channel's name. + /// + /// Required for Android 8.0+. final String channelName; - /// The channel's description. Required for Android 8.0+ + /// The channel's description. + /// + /// Required for Android 8.0+. final String channelDescription; /// Whether notifications posted to this channel can appear as application icon badges in a Launcher final bool channelShowBadge; - /// The importance of the notification + /// The importance of the notification. Importance importance; /// The priority of the notification Priority priority; - /// Indicates if a sound should be played when the notification is displayed. For Android 8.0+, this is tied to the specified channel cannot be changed afterward the channel has been created for the first time. + /// Indicates if a sound should be played when the notification is displayed. + /// + /// For Android 8.0+, this is tied to the specified channel cannot be changed afterward the channel has been created for the first time. bool playSound; - /// The sound to play for the notification. Requires setting [playSound] to true for it to work. If [playSound] is set to true but this is not specified then the default sound is played. For Android 8.0+, this is tied to the specified channel cannot be changed afterward the channel has been created for the first time. + /// The sound to play for the notification. + /// + /// Requires setting [playSound] to true for it to work. + /// If [playSound] is set to true but this is not specified then the default sound is played. + /// For Android 8.0+, this is tied to the specified channel cannot be changed afterward the channel has been created for the first time. String sound; - /// Indicates if vibration should be enabled when the notification is displayed. For Android 8.0+, this is tied to the specified channel cannot be changed afterward the channel has been created for the first time. + /// Indicates if vibration should be enabled when the notification is displayed. + /// + /// For Android 8.0+, this is tied to the specified channel cannot be changed afterward the channel has been created for the first time. bool enableVibration; - /// Indicates if lights should be enabled when the notification is displayed. For Android 8.0+, this is tied to the specified channel cannot be changed afterward the channel has been created for the first time. + /// Indicates if lights should be enabled when the notification is displayed. + /// + /// For Android 8.0+, this is tied to the specified channel cannot be changed afterward the channel has been created for the first time. bool enableLights; - /// The vibration pattern. Requires setting [enableVibration] to true for it to work. For Android 8.0+, this is tied to the specified channel cannot be changed afterward the channel has been created for the first time. + /// Configures the vibration pattern. + /// + /// Requires setting [enableVibration] to true for it to work. + /// For Android 8.0+, this is tied to the specified channel cannot be changed afterward the channel has been created for the first time. Int64List vibrationPattern; - /// Defines the notification style + /// Defines the notification style. AndroidNotificationStyle style; - /// Contains extra information for the specified notification [style] + /// Contains extra information for the specified notification [style]. StyleInformation styleInformation; - /// Specifies the group that this notification belongs to. For Android 7.0+ (API level 24) + /// Specifies the group that this notification belongs to. + /// + /// For Android 7.0+ (API level 24) String groupKey; - /// Specifies if this notification will function as the summary for grouped notifications + /// Specifies if this notification will function as the summary for grouped notifications. bool setAsGroupSummary; - /// Sets the group alert behavior for this notification. Default is AlertAll. See https://developer.android.com/reference/android/support/v4/app/NotificationCompat.Builder.html#setGroupAlertBehavior(int) + /// Sets the group alert behavior for this notification. + /// + /// Default is AlertAll. + /// See https://developer.android.com/reference/android/support/v4/app/NotificationCompat.Builder.html#setGroupAlertBehavior(int) for more details. GroupAlertBehavior groupAlertBehavior; - /// Specifies if the notification should automatically dismissed upon tapping on it + /// Specifies if the notification should automatically dismissed upon tapping on it. bool autoCancel; /// Specifies if the notification will be "ongoing". bool ongoing; - /// Sets the color + /// Sets the color. Color color; /// Specifics the large icon to use. This will be either the name of the drawable of an actual file path based on the value of [largeIconBitmapSource]. String largeIcon; - /// Specifies the source for the large icon + /// Specifies the source for the large icon. BitmapSource largeIconBitmapSource; /// Specifies if you would only like the sound, vibrate and ticker to be played if the notification is not already showing. bool onlyAlertOnce; - /// Specifies if the notification will be used to show progress + /// Specifies if the notification will be used to show progress. bool showProgress; - /// The maximum progress value + /// The maximum progress value. int maxProgress; - /// The current progress value + /// The current progress value. int progress; - /// Specifies if an indeterminate progress bar will be shown + /// Specifies if an indeterminate progress bar will be shown. bool indeterminate; - /// Sets the light color of the notification. For Android 8.0+, this is tied to the specified channel cannot be changed afterward the channel has been created for the first time. + /// Sets the light color of the notification. + /// + /// For Android 8.0+, this is tied to the specified channel cannot be changed afterward the channel has been created for the first time. Color ledColor; - /// Sets how long the light colour will remain on. Not applicable for Android 8.0+ + /// Sets how long the light colour will remain on. + /// + /// Not applicable for Android 8.0+ int ledOnMs; - /// Sets how long the light colour will remain off. Not applicable for Android 8.0+ + /// Sets how long the light colour will remain off. + /// + /// Not applicable for Android 8.0+ int ledOffMs; - /// Set the "ticker" text which is sent to accessibility services + /// Set the "ticker" text which is sent to accessibility services. String ticker; - /// The action to take for managing notification channels. Defaults to creating the notification channel using the provided details if it doesn't exist + /// The action to take for managing notification channels. + /// + /// Defaults to creating the notification channel using the provided details if it doesn't exist AndroidNotificationChannelAction channelAction; /// Defines the notification visibility on the lockscreen @@ -109,8 +143,9 @@ class AndroidNotificationDetails { /// The duration in milliseconds after which the notification will be cancelled if it hasn't already int timeoutAfter; - /// The notification category. Refer to Android notification API documentation at https://developer.android.com/reference/androidx/core/app/NotificationCompat.html#constants_2 - /// for the available categories + /// The notification category. + /// + /// Refer to Android notification API documentation at https://developer.android.com/reference/androidx/core/app/NotificationCompat.html#constants_2 for the available categories String category; AndroidNotificationDetails( diff --git a/flutter_local_notifications/lib/src/platform_specifics/android/person.dart b/flutter_local_notifications/lib/src/platform_specifics/android/person.dart index 24bba1314..823c584a8 100644 --- a/flutter_local_notifications/lib/src/platform_specifics/android/person.dart +++ b/flutter_local_notifications/lib/src/platform_specifics/android/person.dart @@ -1,26 +1,26 @@ import 'enums.dart'; -/// Details of a person e.g. someone who sent a message +/// Details of a person e.g. someone who sent a message. class Person { /// Whether or not this person represents a machine rather than a human. final bool bot; - /// Icon for this person + /// Icon for this person. final String icon; - /// Determines how the icon should be interpreted/resolved e.g. as a drawable + /// Determines how the icon should be interpreted/resolved e.g. as a drawable. final IconSource iconSource; - /// Whether or not this is an important person + /// Whether or not this is an important person. final bool important; - /// Unique identifier for this person + /// Unique identifier for this person. final String key; - /// Name of this person + /// Name of this person. final String name; - /// Uri for this person + /// Uri for this person. final String uri; Person( diff --git a/flutter_local_notifications/lib/src/platform_specifics/android/styles/big_picture_style_information.dart b/flutter_local_notifications/lib/src/platform_specifics/android/styles/big_picture_style_information.dart index 740fb9a1f..c2a19b3e5 100644 --- a/flutter_local_notifications/lib/src/platform_specifics/android/styles/big_picture_style_information.dart +++ b/flutter_local_notifications/lib/src/platform_specifics/android/styles/big_picture_style_information.dart @@ -1,7 +1,7 @@ import 'default_style_information.dart'; import '../enums.dart'; -/// Used to pass the content for an Android notification displayed using the big picture style +/// Used to pass the content for an Android notification displayed using the big picture style. class BigPictureStyleInformation extends DefaultStyleInformation { /// Overrides ContentTitle in the big form of the template. final String contentTitle; @@ -9,25 +9,29 @@ class BigPictureStyleInformation extends DefaultStyleInformation { /// Set the first line of text after the detail section in the big form of the template. final String summaryText; - /// Specifies if the overridden ContentTitle should have formatting applies through HTML markup + /// Specifies if the overridden ContentTitle should have formatting applies through HTML markup. final bool htmlFormatContentTitle; /// Specifies if formatting should be applied to the first line of text after the detail section in the big form of the template. final bool htmlFormatSummaryText; - /// Path the bitmap that will override the large icon when the big notification is shown. This will be either the name of the drawable of an actual file path based on the value of [largeIconBitmapSource]. + /// Path the bitmap that will override the large icon when the big notification is shown. + /// + /// This will be either the name of the drawable of an actual file path based on the value of [largeIconBitmapSource]. final String largeIcon; - /// Specifics the source for bitmap that will override the large icon specified in this style + /// Specifics the source for bitmap that will override the large icon specified in this style. final BitmapSource largeIconBitmapSource; - /// Path to the bitmap to be used as the payload for the BigPicture notification. This will be either the name of the drawable of an actual file path based on the value of [bigPictureBitmapSource]. + /// Path to the bitmap to be used as the payload for the BigPicture notification. + /// + /// This will be either the name of the drawable of an actual file path based on the value of [bigPictureBitmapSource]. final String bigPicture; - /// Specifies the source for the bitmap to be used as the payload for the BigPicture notification + /// Specifies the source for the bitmap to be used as the payload for the BigPicture notification. final BitmapSource bigPictureBitmapSource; - /// Hides the large icon when showing the expanded notification + /// Hides the large icon when showing the expanded notification. final bool hideExpandedLargeIcon; BigPictureStyleInformation(this.bigPicture, this.bigPictureBitmapSource, diff --git a/flutter_local_notifications/lib/src/platform_specifics/android/styles/big_text_style_information.dart b/flutter_local_notifications/lib/src/platform_specifics/android/styles/big_text_style_information.dart index 9d89262aa..523f672ad 100644 --- a/flutter_local_notifications/lib/src/platform_specifics/android/styles/big_text_style_information.dart +++ b/flutter_local_notifications/lib/src/platform_specifics/android/styles/big_text_style_information.dart @@ -1,6 +1,6 @@ import 'default_style_information.dart'; -/// Used to pass the content for an Android notification displayed using the big text style +/// Used to pass the content for an Android notification displayed using the big text style. class BigTextStyleInformation extends DefaultStyleInformation { /// Provide the longer text to be displayed in the big form of the template in place of the content text. final String bigText; @@ -11,10 +11,10 @@ class BigTextStyleInformation extends DefaultStyleInformation { /// Set the first line of text after the detail section in the big form of the template. final String summaryText; - /// Specifies if formatting should be applied to the longer text through HTML markup + /// Specifies if formatting should be applied to the longer text through HTML markup. final bool htmlFormatBigText; - /// Specifies if the overridden ContentTitle should have formatting applies through HTML markup + /// Specifies if the overridden ContentTitle should have formatting applies through HTML markup. final bool htmlFormatContentTitle; /// Specifies if formatting should be applied to the first line of text after the detail section in the big form of the template. diff --git a/flutter_local_notifications/lib/src/platform_specifics/android/styles/default_style_information.dart b/flutter_local_notifications/lib/src/platform_specifics/android/styles/default_style_information.dart index 8ef34b56a..a1573337a 100644 --- a/flutter_local_notifications/lib/src/platform_specifics/android/styles/default_style_information.dart +++ b/flutter_local_notifications/lib/src/platform_specifics/android/styles/default_style_information.dart @@ -1,11 +1,11 @@ import 'style_information.dart'; -/// The default Android notification style +/// The default Android notification style. class DefaultStyleInformation extends StyleInformation { - /// Specifies if formatting should be applied to the content through HTML markup + /// Specifies if formatting should be applied to the content through HTML markup. bool htmlFormatContent; - /// Specifies if formatting should be applied to the title through HTML markup + /// Specifies if formatting should be applied to the title through HTML markup. bool htmlFormatTitle; DefaultStyleInformation(this.htmlFormatContent, this.htmlFormatTitle) diff --git a/flutter_local_notifications/lib/src/platform_specifics/android/styles/inbox_style_information.dart b/flutter_local_notifications/lib/src/platform_specifics/android/styles/inbox_style_information.dart index 0aaba1f1b..c347644bb 100644 --- a/flutter_local_notifications/lib/src/platform_specifics/android/styles/inbox_style_information.dart +++ b/flutter_local_notifications/lib/src/platform_specifics/android/styles/inbox_style_information.dart @@ -1,6 +1,6 @@ import 'default_style_information.dart'; -/// Used to pass the content for an Android notification displayed using the inbox style +/// Used to pass the content for an Android notification displayed using the inbox style. class InboxStyleInformation extends DefaultStyleInformation { /// Overrides ContentTitle in the big form of the template. final String contentTitle; @@ -8,13 +8,13 @@ class InboxStyleInformation extends DefaultStyleInformation { /// Set the first line of text after the detail section in the big form of the template. final String summaryText; - /// The lines that form part of the digest section for inbox-style notifications + /// The lines that form part of the digest section for inbox-style notifications. List lines; - /// Specifies if the lines should have formatting applied through HTML markup + /// Specifies if the lines should have formatting applied through HTML markup. final bool htmlFormatLines; - /// Specifies if the overridden ContentTitle should have formatting applied through HTML markup + /// Specifies if the overridden ContentTitle should have formatting applied through HTML markup. final bool htmlFormatContentTitle; /// Specifies if formatting should be applied to the first line of text after the detail section in the big form of the template. diff --git a/flutter_local_notifications/lib/src/platform_specifics/android/styles/messaging_style_information.dart b/flutter_local_notifications/lib/src/platform_specifics/android/styles/messaging_style_information.dart index 53b166a59..cb1585e43 100644 --- a/flutter_local_notifications/lib/src/platform_specifics/android/styles/messaging_style_information.dart +++ b/flutter_local_notifications/lib/src/platform_specifics/android/styles/messaging_style_information.dart @@ -2,19 +2,20 @@ import 'default_style_information.dart'; import '../person.dart'; import '../message.dart'; -/// Used to pass the content for an Android notification displayed using the messaging style +/// Used to pass the content for an Android notification displayed using the messaging style. class MessagingStyleInformation extends DefaultStyleInformation { - /// The person displayed for any messages that are sent by the user + /// The person displayed for any messages that are sent by the user. final Person person; - /// The title to be displayed on this conversation + /// The title to be displayed on this conversation. final String conversationTitle; - /// Whether this conversation notification represents a group + /// Whether this conversation notification represents a group. final bool groupConversation; /// Messages to be displayed by this notification final List messages; + MessagingStyleInformation(this.person, {this.conversationTitle, this.groupConversation, diff --git a/flutter_local_notifications/lib/src/platform_specifics/ios/initialization_settings.dart b/flutter_local_notifications/lib/src/platform_specifics/ios/initialization_settings.dart index 052992806..ac15fb066 100644 --- a/flutter_local_notifications/lib/src/platform_specifics/ios/initialization_settings.dart +++ b/flutter_local_notifications/lib/src/platform_specifics/ios/initialization_settings.dart @@ -1,26 +1,44 @@ import '../../typedefs.dart'; -/// Plugin initialization settings for iOS +/// Plugin initialization settings for iOS. class IOSInitializationSettings { - /// Request permission to display an alert. Default value is true. + /// Request permission to display an alert. + /// + /// Default value is true. final bool requestAlertPermission; - /// Request permission to play a sound. Default value is true. + /// Request permission to play a sound. + /// + /// Default value is true. final bool requestSoundPermission; - /// Request permission to badge app icon. Default value is true. + /// Request permission to badge app icon. + /// + /// Default value is true. final bool requestBadgePermission; - /// Default setting that indiciates an alert should be displayed when a notification is triggered while app is in the foreground. Default value is true. iOS 10+ only + /// Configures the default setting on if an alert should be displayed when a notification is triggered while app is in the foreground. + /// + /// Default value is true. + /// Applicable to iOS 10 and above. + final bool defaultPresentAlert; - /// Default setting that indiciates if a sound should be played when a notification is triggered while app is in the foreground. Default value is true. iOS 10+ only + /// Configures the default setting on if a sound should be played when a notification is triggered while app is in the foreground by default. + /// + /// Default value is true. + /// Applicable to iOS 10 and above. final bool defaultPresentSound; - /// Default setting that indicates if a badge value should be applied when a notification is triggered while app is in the foreground. Default value is true. iOS 10+ only + /// Configures the default setting on if a badge value should be applied when a notification is triggered while app is in the foreground by default. + /// + /// Default value is true. + /// Applicable to iOS 10 and above. final bool defaultPresentBadge; - /// Callback for handling when a notification is triggered while the app is in the foreground. Applicable to iOS versions < 10 only + /// Callback for handling when a notification is triggered while the app is in the foreground. + /// + /// Applicable to iOS versions below 10. final DidReceiveLocalNotificationCallback onDidReceiveLocalNotification; const IOSInitializationSettings( diff --git a/flutter_local_notifications/lib/src/platform_specifics/ios/notification_details.dart b/flutter_local_notifications/lib/src/platform_specifics/ios/notification_details.dart index 90234da71..c36335b3b 100644 --- a/flutter_local_notifications/lib/src/platform_specifics/ios/notification_details.dart +++ b/flutter_local_notifications/lib/src/platform_specifics/ios/notification_details.dart @@ -1,18 +1,27 @@ /// Configures the notification details on iOS. class IOSNotificationDetails { - // Display an alert when the notification is triggered while app is in the foreground. iOS 10+ only + /// Display an alert when the notification is triggered while app is in the foreground. + /// + /// Applicable to iOS 10 and above. final bool presentAlert; - /// Play a sound when the notification is triggered while app is in the foreground. iOS 10+ only + /// Play a sound when the notification is triggered while app is in the foreground. + /// + /// Applicable to iOS 10 and above. final bool presentSound; - /// Apply the badge value when the notification is triggered while app is in the foreground. iOS 10+ only + /// Apply the badge value when the notification is triggered while app is in the foreground. + /// + /// Applicable to iOS 10 and above. final bool presentBadge; - /// Specifies the name of the file to play for the notification. Requires setting [presentSound] to true. If [presentSound] is set to true but [sound] isn't specified then it will use the default notification sound. + /// Specifies the name of the file to play for the notification. + /// + /// Requires setting [presentSound] to true. If [presentSound] is set to true but [sound] isn't specified then it will use the default notification sound. final String sound; /// Specify the number to display as the app icon's badge when the notification arrives. + /// /// Specify the number 0 to remove the current badge, if present. Greater than 0 to display a badge with that number. /// Specify null to leave the current badge unchanged. final int badgeNumber; diff --git a/flutter_local_notifications/lib/src/typedefs.dart b/flutter_local_notifications/lib/src/typedefs.dart index 94baa6579..675009089 100644 --- a/flutter_local_notifications/lib/src/typedefs.dart +++ b/flutter_local_notifications/lib/src/typedefs.dart @@ -1,8 +1,10 @@ import 'dart:async'; -/// Signature of callback passed to [initialize]. Callback triggered when user taps on a notification +/// Signature of callback passed to [initialize] that is triggered when user taps on a notification. typedef SelectNotificationCallback = Future Function(String payload); -// Signature of the callback that is triggered when a notification is shown whilst the app is in the foreground. Applicable to iOS versions < 10 only +/// Signature of the callback that is triggered when a notification is shown whilst the app is in the foreground. +/// +/// Applicable to iOS versions below 10. typedef DidReceiveLocalNotificationCallback = Future Function( int id, String title, String body, String payload); diff --git a/flutter_local_notifications/lib/src/types.dart b/flutter_local_notifications/lib/src/types.dart index 6eef3086a..e1e3789bc 100644 --- a/flutter_local_notifications/lib/src/types.dart +++ b/flutter_local_notifications/lib/src/types.dart @@ -1,4 +1,4 @@ -/// The days of the week +/// The days of the week. class Day { static const Sunday = Day(1); static const Monday = Day(2); @@ -16,15 +16,21 @@ class Day { const Day(this.value); } -/// Used for specifying a time in 24 hour format +/// Used for specifying a time in 24 hour format. class Time { - /// The hour component of the time. Accepted range is 0 to 23 inclusive + /// The hour component of the time. + /// + /// Accepted range is 0 to 23 inclusive. final int hour; - /// The minutes component of the time. Accepted range is 0 to 59 inclusive + /// The minutes component of the time. + /// + /// Accepted range is 0 to 59 inclusive. final int minute; - /// The seconds component of the time. Accepted range is 0 to 59 inclusive + /// The seconds component of the time. + /// + /// Accepted range is 0 to 59 inclusive. final int second; Time([this.hour = 0, this.minute = 0, this.second = 0]) { diff --git a/flutter_local_notifications/pubspec.yaml b/flutter_local_notifications/pubspec.yaml index 3b3097b11..ebe2f0055 100644 --- a/flutter_local_notifications/pubspec.yaml +++ b/flutter_local_notifications/pubspec.yaml @@ -1,6 +1,6 @@ name: flutter_local_notifications description: A cross platform plugin for displaying and scheduling local notifications for Flutter applications with the ability to customise for each platform. -version: 1.1.6 +version: 1.1.7 homepage: https://github.com/MaikuB/flutter_local_notifications/tree/master/flutter_local_notifications dependencies: