From 6ceca588a268ed8fef4b32df278ca7567e608510 Mon Sep 17 00:00:00 2001 From: Dianne Hackborn Date: Tue, 10 Jan 2012 15:24:26 -0800 Subject: [PATCH] Update notification documentation to follow current guidelines. The documentation is now consistent with the current UI guidelines for handling notifications, and includes complete sample code showing the correct way to do this. Change-Id: I68f0afc62c2af164c3205535e62093679e2a256a --- core/java/android/app/Notification.java | 9 +- .../ui_guidelines/activity_task_design.jd | 115 ++------------- .../topics/ui/notifiers/notifications.jd | 133 ++++++++++++++++++ 3 files changed, 154 insertions(+), 103 deletions(-) diff --git a/core/java/android/app/Notification.java b/core/java/android/app/Notification.java index f5add25162c41..d569e20714635 100644 --- a/core/java/android/app/Notification.java +++ b/core/java/android/app/Notification.java @@ -113,7 +113,10 @@ public class Notification implements Parcelable * {@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK} flag, which requires * that you take care of task management as described in the * Tasks and Back - * Stack document. + * Stack document. In particular, make sure to read the notification section + * Handling + * Notifications for the correct ways to launch an application from a + * notification. */ public PendingIntent contentIntent; @@ -765,7 +768,9 @@ public class Notification implements Parcelable * Supply a {@link PendingIntent} to send when the notification is clicked. * If you do not supply an intent, you can now add PendingIntents to individual * views to be launched when clicked by calling {@link RemoteViews#setOnClickPendingIntent - * RemoteViews.setOnClickPendingIntent(int,PendingIntent)}. + * RemoteViews.setOnClickPendingIntent(int,PendingIntent)}. Be sure to + * read {@link Notification#contentIntent Notification.contentIntent} for + * how to correctly use this. */ public Builder setContentIntent(PendingIntent intent) { mContentIntent = intent; diff --git a/docs/html/guide/practices/ui_guidelines/activity_task_design.jd b/docs/html/guide/practices/ui_guidelines/activity_task_design.jd index 31ad466dc0b31..5faa7ece8502e 100644 --- a/docs/html/guide/practices/ui_guidelines/activity_task_design.jd +++ b/docs/html/guide/practices/ui_guidelines/activity_task_design.jd @@ -40,7 +40,7 @@ parent.link=index.html
  • Handle case where no activity matches
  • Consider how to launch your activities
  • Allow activities to add to current task
    • -
  • Notifications should let user easily get back
    • +
  • Notifications and App Widgets should provide consistent back behavior
  • Use the notification system
  • Don't take over BACK key unless you absolutely need to
    • @@ -1063,110 +1063,23 @@ MAIN and

    -

    Notifications should let the user easily get back to the previous activity

    +

    Notifications and App Widgets should provide consistent back behavior

    - Applications that are in the background or not running can have - services that send out notifications to the user letting them know about - events of interest. Two examples are Calendar, which can send out notifications of - upcoming events, and Email, which can send out notifications when new - messages arrive. One of the user interface guidelines is that when the - user is in activity A, gets a notification for activity B and - picks that notification, when they press the BACK key, they should - go back to activity A.  + Notifications and app widgets are two common ways that a user can launch + your app through something besides its main icon in Launcher. You must + take care when implementing these so that the user has a consistent experience + with the back button, not causing surprises in where they return to or the + state the application ends up in.

    - The following scenario shows how the activity stack should work - when the user responds to a notification. -

    - -
      -
    1. - User is creating a new event in Calendar. They realize they - need to copy part of an email message into this event -
      2. -
    2. - The user chooses Home > Gmail -
      3. -
    3. - While in Gmail, they receive a notification from Calendar for an upcoming meeting -
      4. -
    4. - So they choose that notification, which takes them to a - dedicated Calendar activity that displays brief details of the - upcoming meeting -
      5. -
    5. - The user chooses this short notice to view further details -
      6. -
    6. - When done viewing the event, the user presses the BACK - key. They should be taken to Gmail, which is where they were - when they took the notification -
      7. -
    - -

    -This behavior doesn't necessarily happen by default. -

    - -

    -Notifications generally happen primarily in one of two ways: -

    - - - -

    - There are other ways to handle notifications, such as bringing the - activity to the foreground, set to display specific data, such as - displaying the text message thread for the person who just sent a - new text message. + The + Handling + Notifications section of the developer guide's + Status Bar Notifications + documentation provides an overview of how to write code to correctly handle + notification. This dicussion applies equally to handling interactions with + app widgets.

    diff --git a/docs/html/guide/topics/ui/notifiers/notifications.jd b/docs/html/guide/topics/ui/notifiers/notifications.jd index 7bc1cde3ff367..1b01c6112fcd5 100644 --- a/docs/html/guide/topics/ui/notifiers/notifications.jd +++ b/docs/html/guide/topics/ui/notifiers/notifications.jd @@ -16,6 +16,7 @@ user clicks it

    In this document

    1. The Basics
      2. +
    2. Responding to Notifications
    3. Managing your Notifications
    4. Creating a Notification
        @@ -123,6 +124,138 @@ mNotificationManager.notify(HELLO_ID, notification);
      +

      Responding to Notifications

      + +

      A central part of the user's experience with a notification revolves around +how it interacts with the application's UI flow. You must implement +this correctly to provide a consistent user experience within your app.

      + +

      Two typical examples of notifications are provided by Calendar, which can send out +notifications of upcoming events, and Email, which can send out notifications +when new messages arrive. These represent the two recommended patterns for handling +notifications: either launching into an activity that is separate from the +main application, or launching an entirely new instance of the application +showing the appropriate point for the notification.

      + +

      The following scenario shows how the activity stack should work +in these two typical notification flows, first handling a Calendar notification: +

      + +
        +
      1. User is creating a new event in Calendar. They realize they + need to copy part of an email message into this event. +
        2. +
      2. + The user chooses Home > Email. +
        3. +
      3. + While in Email, they receive a notification from Calendar for an upcoming + meeting. +
        4. +
      4. + So they choose that notification, which takes them to a + dedicated Calendar activity that displays brief details of the + upcoming meeting. +
        5. +
      5. + The user has seen enough to know they have a meeting coming up, + so they press the BACK button. They are now returned to Email, which + is where they were when they took the notification. +
        6. +
      + +

      Handling an Email notification:

      + +
        +
      1. + The user is currently in Email composing a message, and needs to + check a date in their calendar. +
        2. +
      2. + The user chooses Home > Calendar. +
        3. +
      3. + While in Calendar, they receive a notification from Email about a new + message. +
        4. +
      4. + They select the notification, which brings them to Email with the message + details displayed. This has replaced what they were previously doing + (writing an e-mail), but that message is still saved in their drafts. +
        5. +
      5. + The user presses BACK once to go to the message list (the typical flow in the + Email app), and press BACK again to return to Calendar as they left it. +
        6. +
      + +

      In an Email style of notification, the UI launched by the notification +shows the main application in a state representing that notification. +For example, when the Email application comes to the foreground from its +notification, it displays either the conversion list or a specific +conversation depending on whether there are multiple or only one new +email. To achieve this, we want to completely replace whatever current +state the application is in with a new activity stack representing the +new notification state.

      + +

      The following code illustrates how to show this kind of notification. Of +most interest is the makeMessageIntentStack() method, which constructs +an array of intents representing the app's new activity stack for this state. +(If you are using fragments, you may need to initialize your fragment and +app state so that pressing BACK will switch the UI back to its parent state.) +The core of this is the {@link android.content.Intent#makeRestartActivityTask +Intent.makeRestartActivityTask()} method, which constructs the root activity +of the stack with the appropriate flags, such as +{@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TASK Intent.FLAG_ACTIVITY_CLEAR_TASK}.

      + +{@sample development/samples/ApiDemos/src/com/example/android/apis/app/IncomingMessage.java + app_notification} + +

      In a Calendar style of notification, the UI launched by the notification +is a dedicated activity that is not part of the normal application flow. +For example, when the user receives a Calendar notification, choosing that +notification starts a special activity that displays a list +of upcoming calendar events — this view is available only +from the notification, not through the Calendar's normal user +interface.

      + +

      The code for posting this type of notification is very straight-forward; it +is like the above, but the {@link android.app.PendingIntent} is for just a single +activity, our dedicated notification activity.

      + +{@sample development/samples/ApiDemos/src/com/example/android/apis/app/IncomingMessage.java + interstitial_notification} + +

      This is not enough, however. Normally Android considers all activities within +an application to be part of that application's UI flow, so simply launching the +activity like this can cause it to be mixed with your normal application back stack +in undesired ways. To make it behave correctly, in the manifest declaration +for the activity the attributes +android:launchMode="singleInstance" and +android:excludeFromRecents="true" +must be set. The full activity declaration for this sample is:

      + +{@sample development/samples/ApiDemos/AndroidManifest.xml interstitial_affinity} + +

      Because of the use of singleInstance, you must be careful about launching +any other activities from this one. These activities will be launched +in their own task, and care must be taken to make sure this interacts +well with the current state of your application's task. This is essentially +the same as switching to the main application as described for the Email style +notification shown before. Given the makeMessageIntentStack() +method previously shown, handling a click here would look something like this:

      + +{@sample development/samples/ApiDemos/src/com/example/android/apis/app/IncomingMessageInterstitial.java + app_launch} + +

      If you don't want to use the singleInstance launch mode for +this activity, an alternative approach is to use android:taskAffinity="". +This tells Android that the activity should not be treated as part of the +main application flow, so it will not get mixed together with that. All of the +other issues discussed here do still apply, though this would allow you to start +additional activities that are part of this notification task instead of switching +to and replacing the main application task.

      +

      Managing your Notifications

      The {@link android.app.NotificationManager} is a system service that manages all