[flutter_local_notifications] Feature: Android - Add useAlarmClock mode to ScheduleMode (#1997)

* Add alarmClock mode to ScheduleMode

Allowing exact alarm even in low power mode

* Address PR CR

* Address PR CR: Add example of using AlarmClock

* update text for alarm clock example for consistency and casing

---------

Co-authored-by: Michael Bui <[email protected]>

Author: iballan

flutter_local_notifications/android/src/main/java/com/dexterous/flutterlocalnotifications/FlutterLocalNotificationsPlugin.java

@@ -680,6 +680,9 @@ private static void setupAlarm(
         checkCanScheduleExactAlarms(alarmManager);
         AlarmManagerCompat.setExact(
             alarmManager, AlarmManager.RTC_WAKEUP, epochMilli, pendingIntent);
+      } else if (notificationDetails.scheduleMode.useAlarmClock()) {
+        AlarmManagerCompat.setAlarmClock(
+                alarmManager, epochMilli, pendingIntent, pendingIntent);
       } else {
         alarmManager.set(AlarmManager.RTC_WAKEUP, epochMilli, pendingIntent);
       }
@@ -695,6 +698,9 @@ private static void setupAllowWhileIdleAlarm(
       checkCanScheduleExactAlarms(alarmManager);
       AlarmManagerCompat.setExactAndAllowWhileIdle(
           alarmManager, AlarmManager.RTC_WAKEUP, epochMilli, pendingIntent);
+    } else if (notificationDetails.scheduleMode.useAlarmClock()) {
+      AlarmManagerCompat.setAlarmClock(
+              alarmManager, epochMilli, pendingIntent, pendingIntent);
     } else {
       AlarmManagerCompat.setAndAllowWhileIdle(
           alarmManager, AlarmManager.RTC_WAKEUP, epochMilli, pendingIntent);

flutter_local_notifications/android/src/main/java/com/dexterous/flutterlocalnotifications/models/ScheduleMode.java

@@ -8,6 +8,7 @@
 
 @Keep
 public enum ScheduleMode {
+  alarmClock,
   exact,
   exactAllowWhileIdle,
   inexact,
@@ -21,6 +22,10 @@ public boolean useExactAlarm() {
     return this == exact || this == exactAllowWhileIdle;
   }
 
+  public boolean useAlarmClock() {
+    return this == alarmClock;
+  }
+
   public static class Deserializer implements JsonDeserializer<ScheduleMode> {
     @Override
     public ScheduleMode deserialize(

flutter_local_notifications/example/lib/main.dart

@@ -434,6 +434,14 @@ class _HomePageState extends State<HomePage> {
                         await _zonedScheduleNotification();
                       },
                     ),
+                    PaddedElevatedButton(
+                      buttonText:
+                          'Schedule notification to appear in 5 seconds '
+                          'based on local time zone using alarm clock',
+                      onPressed: () async {
+                        await _zonedScheduleAlarmClockNotification();
+                      },
+                    ),
                     PaddedElevatedButton(
                       buttonText: 'Repeat notification every minute',
                       onPressed: () async {
@@ -1383,6 +1391,21 @@ class _HomePageState extends State<HomePage> {
             UILocalNotificationDateInterpretation.absoluteTime);
   }
 
+  Future<void> _zonedScheduleAlarmClockNotification() async {
+    await flutterLocalNotificationsPlugin.zonedSchedule(
+        123,
+        'scheduled alarm clock title',
+        'scheduled alarm clock body',
+        tz.TZDateTime.now(tz.local).add(const Duration(seconds: 5)),
+        const NotificationDetails(
+            android: AndroidNotificationDetails(
+                'alarm_clock_channel', 'Alarm Clock Channel',
+                channelDescription: 'Alarm Clock Notification')),
+        androidScheduleMode: AndroidScheduleMode.alarmClock,
+        uiLocalNotificationDateInterpretation:
+            UILocalNotificationDateInterpretation.absoluteTime);
+  }
+
   Future<void> _showNotificationWithNoSound() async {
     const AndroidNotificationDetails androidNotificationDetails =
         AndroidNotificationDetails('silent channel id', 'silent channel name',

flutter_local_notifications/lib/src/platform_specifics/android/schedule_mode.dart

@@ -3,6 +3,11 @@
 /// This leverages the use of alarms to schedule notifications as described
 /// at https://developer.android.com/training/scheduling/alarms
 enum AndroidScheduleMode {
+  /// Used to specify that the notification should be scheduled to be shown at
+  /// the exact time specified AND will execute whilst device is in
+  /// low-power idle mode. Requires SCHEDULE_EXACT_ALARM permission.
+  alarmClock,
+
   /// Used to specify that the notification should be scheduled to be shown at
   /// the exact time specified but may not execute whilst device is in
   /// low-power idle mode.