From 37cb8d75303a8f795ce66670761ca2263327563d Mon Sep 17 00:00:00 2001 From: Robert Ly Date: Thu, 8 May 2014 15:02:11 -0700 Subject: docs: fix some notification code for wear stacks Change-Id: Iea6b444480b161ab08a9ba02dbabb22773862cf0 --- .../html/guide/topics/resources/string-resource.jd | 107 ++++++++++++++++++++- docs/html/wear/images/notif_summary_framed.png | Bin 0 -> 39277 bytes docs/html/wear/notifications/stacks.jd | 90 ++++++++++++++--- 3 files changed, 178 insertions(+), 19 deletions(-) create mode 100644 docs/html/wear/images/notif_summary_framed.png (limited to 'docs/html') diff --git a/docs/html/guide/topics/resources/string-resource.jd b/docs/html/guide/topics/resources/string-resource.jd index 5a96ba1..e2326ec 100644 --- a/docs/html/guide/topics/resources/string-resource.jd +++ b/docs/html/guide/topics/resources/string-resource.jd @@ -20,9 +20,6 @@ your application with strings:

information about styling and formatting strings, see the section about Formatting and Styling.

- - -

String

A single string that can be referenced from the application or from other resource files (such @@ -433,7 +430,7 @@ java.lang.Object...)">format(res.getString(R.string.welcome_messages), usern -

Styling with HTML markup

+

Styling with HTML markup

You can add styling to your strings with HTML markup. For example:

@@ -497,5 +494,107 @@ java.lang.Object...)">format(res.getString(R.string.welcome_messages), escap
 CharSequence styledText = Html.fromHtml(text);
+

Styling with Spannables

+

+A {@link android.text.Spannable} is a text object that you can style with +typeface properties such as color and font weight. You use +{@link android.text.SpannableStringBuilder} to build +your text and then apply styles defined in the {@link android.text.style} +package to the text. +

+ +

You can use the following helper methods to set up much of the work +of creating spannable text:

+ +
+/**
+ * Returns a CharSequence that concatenates the specified array of CharSequence
+ * objects and then applies a list of zero or more tags to the entire range.
+ *
+ * @param content an array of character sequences to apply a style to
+ * @param tags the styled span objects to apply to the content
+ *        such as android.text.style.StyleSpan
+ *
+ */
+private static CharSequence apply(CharSequence[] content, Object... tags) {
+    SpannableStringBuilder text = new SpannableStringBuilder();
+    openTags(text, tags);
+    for (CharSequence item : content) {
+        text.append(item);
+    }
+    closeTags(text, tags);
+    return text;
+}
+
+/**
+ * Iterates over an array of tags and applies them to the beginning of the specified
+ * Spannable object so that future text appended to the text will have the styling
+ * applied to it. Do not call this method directly.
+ */
+private static void openTags(Spannable text, Object[] tags) {
+    for (Object tag : tags) {
+        text.setSpan(tag, 0, 0, Spannable.SPAN_MARK_MARK);
+    }
+}
+
+/**
+ * "Closes" the specified tags on a Spannable by updating the spans to be
+ * endpoint-exclusive so that future text appended to the end will not take
+ * on the same styling. Do not call this method directly.
+ */
+private static void closeTags(Spannable text, Object[] tags) {
+    int len = text.length();
+    for (Object tag : tags) {
+        if (len > 0) {
+            text.setSpan(tag, 0, len, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE);
+        } else {
+            text.removeSpan(tag);
+        }
+    }
+}
+
+

+The following bold, italic, and color +methods show you how to call the helper methods to apply +styles defined in the {@link android.text.style} package. You +can create similar methods to do other types of text styling. +

+ +
+/**
+ * Returns a CharSequence that applies boldface to the concatenation
+ * of the specified CharSequence objects.
+ */
+public static CharSequence bold(CharSequence... content) {
+    return apply(content, new StyleSpan(Typeface.BOLD));
+}
+
+/**
+ * Returns a CharSequence that applies italics to the concatenation
+ * of the specified CharSequence objects.
+ */
+public static CharSequence italic(CharSequence... content) {
+    return apply(content, new StyleSpan(Typeface.ITALIC));
+}
+
+/**
+ * Returns a CharSequence that applies a foreground color to the
+ * concatenation of the specified CharSequence objects.
+ */
+public static CharSequence color(int color, CharSequence... content) {
+    return apply(content, new ForegroundColorSpan(color));
+}
+
+

+Here's an example of how to chain these methods to create a character sequence +with different types of styling applied to individual words: +

+ +
+// Create an italic "hello, " a red "world",
+// and bold the entire sequence.
+CharSequence text = bold(italic(res.getString(R.string.hello)),
+    color(Color.RED, res.getString(R.string.world)));
+
\ No newline at end of file diff --git a/docs/html/wear/images/notif_summary_framed.png b/docs/html/wear/images/notif_summary_framed.png new file mode 100644 index 0000000..17b1703 Binary files /dev/null and b/docs/html/wear/images/notif_summary_framed.png differ diff --git a/docs/html/wear/notifications/stacks.jd b/docs/html/wear/notifications/stacks.jd index 7f955f6..a2d34ce 100644 --- a/docs/html/wear/notifications/stacks.jd +++ b/docs/html/wear/notifications/stacks.jd @@ -2,8 +2,8 @@ page.title=Stacking Notifications @jd:body - - + +

When creating notifications for a handheld device, you should always aggregate similar notifications into a single summary notification. For example, if your app creates notifications @@ -29,20 +29,44 @@ Wear.

To create a stack, call -setGroup() for each notification you want in the stack, passing the same -group key. For example:

+setGroup() for each notification you want in the stack and specify a +group key. Then call notify() to send it to the wearable.

 final static String GROUP_KEY_EMAILS = "group_key_emails";
 
+// Build the notification and pass this builder to WearableNotifications.Builder
 NotificationCompat.Builder builder = new NotificationCompat.Builder(mContext)
-         .setContentTitle("New mail from " + sender)
-         .setContentText(subject)
+         .setContentTitle("New mail from " + sender1)
+         .setContentText(subject1)
          .setSmallIcon(R.drawable.new_mail);
 
-Notification notif = new WearableNotifications.Builder(builder)
+Notification notif1 = new WearableNotifications.Builder(builder)
          .setGroup(GROUP_KEY_EMAILS)
          .build();
+
+// Issue the notification
+NotificationManagerCompat notificationManager =
+        NotificationManagerCompat.from(this);
+notificationManager.notify(notificationId1, notif);
+
+ +

Later on, when you create another notification, specify +the same group key. When you call notify(), this notification appears +in the same stack as the previous notification, instead of as a new card:

+ +
+builder = new NotificationCompat.Builder(mContext)
+         .setContentTitle("New mail from " + sender2)
+         .setContentText(subject2)
+         .setSmallIcon(R.drawable.new_mail);
+
+// Use the same group as the previous notification
+Notification notif2 = new WearableNotifications.Builder(builder)
+         .setGroup(GROUP_KEY_EMAILS)
+         .build();
+
+notificationManager.notify(notificationId2, notif);

By default, notifications appear in the order in which you added them, with the most recent @@ -54,19 +78,55 @@ href="{@docRoot}reference/android/preview/support/wearable/notifications/Wearabl

Add a Summary Notification

+ +

It's important that you still provide a summary notification that appears on handheld devices. So in addition to adding each unique notification to the same stack group, also add a summary notification, but set its order position to be GROUP_ORDER_SUMMARY.

-
-Notification summaryNotification = new WearableNotifications.Builder(builder)
-         .setGroup(GROUP_KEY_EMAILS, WearableNotifications.GROUP_ORDER_SUMMARY)
-         .build();
-
+

This notification does not appear in your stack of notifications on the wearable, but +appears as the only notification on the handheld device.

-

This notification will not appear in your stack of notifications on the wearable, but -appears as the only notification on the handheld device. +

+Bitmap largeIcon = BitmapFactory.decodeResource(getResources(),
+        R.drawable.ic_large_icon);
+
+builder = new NotificationCompat.Builder(this)
+        .setSmallIcon(R.drawable.ic_small_icon)
+        .setLargeIcon(largeIcon);
+
+// Use the same group key and pass this builder to InboxStyle notification
+WearableNotifications.Builder wearableBuilder = new WearableNotifications
+        .Builder(builder)
+        .setGroup(GROUP_KEY_EMAILS,
+                WearableNotifications.GROUP_ORDER_SUMMARY);
+
+// Build the final notification to show on the handset
+Notification summaryNotification = new NotificationCompat.InboxStyle(
+        wearableBuilder.getCompatBuilder())
+        .addLine("Alex Faaborg   Check this out")
+        .addLine("Jeff Chang   Launch Party")
+        .setBigContentTitle("2 new messages")
+        .setSummaryText("johndoe@gmail.com")
+        .build();
+
+notificationManager.notify(notificationId3, summaryNotification);
+
+

+This notification uses {@link android.support.v4.app.NotificationCompat.InboxStyle}, +which gives you an easy way to create notifications for email or messaging apps. +You can use this style, another one defined in {@link android.support.v4.app.NotificationCompat}, +or no style for the summary notification. +

+ +

Tip: +To style the text like in the example screenshot, see +Styling +with HTML markup and +Styling +with Spannables. +

- + \ No newline at end of file -- cgit v1.1