From ac294abb40483fc734e22833371d95cbb161ec87 Mon Sep 17 00:00:00 2001 From: Joe Malin Date: Tue, 16 Oct 2012 10:32:15 -0700 Subject: Revision to Notifications API guide Change-Id: I52229dfdff3649e03a1fbce91234c8b2a544502a --- .../guide/topics/ui/notifiers/notifications.jd | 128 +++++++++++++++++---- 1 file changed, 104 insertions(+), 24 deletions(-) diff --git a/docs/html/guide/topics/ui/notifiers/notifications.jd b/docs/html/guide/topics/ui/notifiers/notifications.jd index 2de62607ed0d..8026b7df57f3 100644 --- a/docs/html/guide/topics/ui/notifiers/notifications.jd +++ b/docs/html/guide/topics/ui/notifiers/notifications.jd @@ -18,6 +18,7 @@ page.title=Notifications
  • Notification actions
  • Creating a simple notification
  • Applying a big view style to a notification
    • +
  • Handling compatibility
  • Managing Notifications @@ -91,18 +92,36 @@ page.title=Notifications

    - Note: This guide refers to the + Note: Except where noted, this guide refers to the {@link android.support.v4.app.NotificationCompat.Builder NotificationCompat.Builder} class in the version 4 Support Library. - The class {@link android.app.Notification.Builder Notification.Builder} was added in API - level 11. + The class {@link android.app.Notification.Builder Notification.Builder} was added in Android + 3.0.

    Notification Display Elements

    - Notifications in the notification drawer appear in two main visual styles, normal view and - big view. + Notifications in the notification drawer can appear in one of two visual styles, depending on + the version and the state of the drawer: +

    +
    +
    + Normal view +
    +
    + The standard view of the notifications in the notification drawer. +
    +
    + Big view +
    +
    + A large view that's visible when the notification is expanded. Big view is part of the + expanded notification feature available as of Android 4.1. +
    +
    +

    + These styles are described in the following sections.

    Normal view

    @@ -139,7 +158,7 @@ page.title=Notifications

    A notification's big view appears only when the notification is expanded, which happens when the notification is at the top of the notification drawer, or when the user expands the - notification with a gesture. + notification with a gesture. Expanded notifications are available starting with Android 4.1.

    The following screenshot shows an inbox-style notification: @@ -246,10 +265,12 @@ page.title=Notifications

    A notification can provide multiple actions. You should always define the action that's - triggered when the user touches the notification; usually this action opens an + triggered when the user clicks the notification; usually this action opens an {@link android.app.Activity} in your application. You can also add buttons to the notification that perform additional actions such as snoozing an alarm or responding immediately to a text - message. + message; this feature is available as of Android 4.1. If you use additional action buttons, you + must also make their functionality available in an {@link android.app.Activity} in your app; see + the section Handling compatibility for more details.

    Inside a {@link android.app.Notification}, the action itself is defined by a @@ -257,22 +278,22 @@ page.title=Notifications an {@link android.app.Activity} in your application. To associate the {@link android.app.PendingIntent} with a gesture, call the appropriate method of {@link android.support.v4.app.NotificationCompat.Builder}. For example, if you want to start - {@link android.app.Activity} when the user touches the notification text in + {@link android.app.Activity} when the user clicks the notification text in the notification drawer, you add the {@link android.app.PendingIntent} by calling {@link android.support.v4.app.NotificationCompat.Builder#setContentIntent setContentIntent()}.

    - Starting an {@link android.app.Activity} when the user touches the notification is the most + Starting an {@link android.app.Activity} when the user clicks the notification is the most common action scenario. You can also start an {@link android.app.Activity} when the user - dismisses an {@link android.app.Activity}, and you can start an {@link android.app.Activity} - from an action button. To learn more, read the reference guide for + dismisses an {@link android.app.Activity}. In Android 4.1 and later, you can start an + {@link android.app.Activity} from an action button. To learn more, read the reference guide for {@link android.support.v4.app.NotificationCompat.Builder}.

    Creating a simple notification

    The following snippet illustrates a simple notification that specifies an activity to open when - the user touches the notification. Notice that the code creates a + the user clicks the notification. Notice that the code creates a {@link android.support.v4.app.TaskStackBuilder} object and uses it to create the {@link android.app.PendingIntent} for the action. This pattern is explained in more detail in the section @@ -316,6 +337,11 @@ mNotificationManager.notify(mId, mBuilder.build()); you want. Next, call {@link android.support.v4.app.NotificationCompat.Builder#setStyle Builder.setStyle()} with a big view style object as its argument.

    +

    + Remember that expanded notifications are not available on platforms prior to Android 4.1. To + learn how to handle notifications for Android 4.1 and for earlier platforms, read the + section Handling compatibility. +

    For example, the following code snippet demonstrates how to alter the notification created in the previous snippet to use the Inbox big view style: @@ -341,6 +367,47 @@ mBuilder.setStyle(inBoxStyle); ... // Issue the notification here. +

    Handling compatibility

    +

    + Not all notification features are available for a particular version, even though + the methods to set them are in the support library class + {@link android.support.v4.app.NotificationCompat.Builder NotificationCompat.Builder}. + For example, action buttons, which depend on expanded notifications, only appear on Android + 4.1 and higher, because expanded notifications themselves are only available on + Android 4.1 and higher. +

    +

    + To ensure the best compatibility, create notifications with + {@link android.support.v4.app.NotificationCompat NotificationCompat} and its subclasses, + particularly {@link android.support.v4.app.NotificationCompat.Builder + NotificationCompat.Builder}. In addition, follow this process when you implement a notification: +

    +
      +
    1. + Provide all of the notification's functionality to all users, regardless of the version + they're using. To do this, verify that all of the functionality is available from an + {@link android.app.Activity} in your app. You may want to add a new + {@link android.app.Activity} to do this. +

      + For example, if you want to use + {@link android.support.v4.app.NotificationCompat.Builder#addAction addAction()} to + provide a control that stops and starts media playback, first implement this + control in an {@link android.app.Activity} in your app. +

      +
      2. +
    2. + Ensure that all users can get to the functionality in the {@link android.app.Activity}, + by having it start when users click the notification. To do this, + create a {@link android.app.PendingIntent} for the {@link android.app.Activity}. Call + {@link android.support.v4.app.NotificationCompat.Builder#setContentIntent + setContentIntent()} to add the {@link android.app.PendingIntent} to the notification. +
      3. +
    3. + Now add the expanded notification features you want to use to the notification. Remember + that any functionality you add also has to be available in the {@link android.app.Activity} + that starts when users click the notification. +
      4. +

    Managing Notifications

    @@ -355,6 +422,10 @@ mBuilder.setStyle(inBoxStyle); "stacking" the notification; it's described in more detail in the Notifications Design guide.

    +

    + Note: This Gmail feature requires the "inbox" big view style, which is + part of the expanded notification feature available starting in Android 4.1. +

    The following section describes how to update notifications and also how to remove them.

    @@ -417,7 +488,7 @@ numMessages = 0; the notification can be cleared).
  • - The user touches the notification, and you called + The user clicks the notification, and you called {@link android.support.v4.app.NotificationCompat.Builder#setAutoCancel setAutoCancel()} when you created the notification.
    • @@ -452,7 +523,7 @@ numMessages = 0; start a fresh task, and provide the {@link android.app.PendingIntent} with a back stack that reproduces the application's normal Back behavior.

    - Notifications from the Gmail app demonstrate this. When you touch a notification for + Notifications from the Gmail app demonstrate this. When you click a notification for a single email message, you see the message itself. Touching Back takes you backwards through Gmail to the Home screen, just as if you had entered Gmail from the Home screen rather than entering it from a notification. @@ -489,7 +560,7 @@ numMessages = 0; Define your application's {@link android.app.Activity} hierarchy in the manifest.

    1. - Add support for API versions 15 and earlier. To do this, specify the parent of the + Add support for Android 4.0.3 and earlier. To do this, specify the parent of the {@link android.app.Activity} you're starting by adding a <meta-data> element as the child of the @@ -507,7 +578,7 @@ numMessages = 0;

    2. - Also add support for API versions 16 and later. To do this, add the + Also add support for Android 4.1 and later. To do this, add the android:parentActivityName attribute to the <activity> @@ -738,9 +809,14 @@ mNotificationManager.notify(id, builder.build()); {@link android.widget.ProgressBar} class.

      - To use a progress indicator, call - {@link android.support.v4.app.NotificationCompat.Builder#setProgress setProgress()}. The - determinate and indeterminate forms are described in the following sections. + To use a progress indicator on platforms starting with Android 4.0, call + {@link android.support.v4.app.NotificationCompat.Builder#setProgress setProgress()}. For + previous versions, you must create your own custom notification layout that + includes a {@link android.widget.ProgressBar} view. +

      +

      + The following sections describe how to display progress in a notification using + {@link android.support.v4.app.NotificationCompat.Builder#setProgress setProgress()}.

      Displaying a fixed-duration progress indicator

      @@ -871,6 +947,10 @@ mNotifyManager.notify(0, mBuilder.build()); Custom layout notifications are similar to normal notifications, but they're based on a {@link android.widget.RemoteViews} defined in a XML layout file.

      +

      + The height available for a custom notification layout depends on the notification view. Normal + view layouts are limited to 64 dp, and expanded view layouts are limited to 256 dp. +

      To define a custom notification layout, start by instantiating a {@link android.widget.RemoteViews} object that inflates an XML layout file. Then, @@ -911,8 +991,8 @@ mNotifyManager.notify(0, mBuilder.build());

      Using style resources for custom notification text

      Always use style resources for the text of a custom notification. The background color of the - notification can vary across different devices and platform versions, and using style resources - helps you account for this. Starting in API level 9, the system defined a style for the - standard notification layout text. If you use the same style in applications that target API - level 9 or higher, you'll ensure that your text is visible against the display background. + notification can vary across different devices and versions, and using style resources + helps you account for this. Starting in Android 2.3, the system defined a style for the + standard notification layout text. If you use the same style in applications that target Android + 2.3 or higher, you'll ensure that your text is visible against the display background.

      -- cgit v1.2.3-59-g8ed1b