Gitiles
Code Review Sign In
gerrit.omnirom.org / android_frameworks_base / 488230c3fec4fc55abc2ee1de7b8b51a4e89f9a5 / . / docs / html / wear / notifications / stacks.html
blob: e4f74a037b10c7328ade7ba61efd185be4fc35f8 [file] [log] [blame]
Scott Main50d7dc92014-03-18 05:13:12 -0700[diff] [blame]1<!DOCTYPE html>
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92<html>
93<head>
94
95
96<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
97<meta name="viewport" content="width=device-width" />
98
99<link rel="shortcut icon" type="image/x-icon" href="/favicon.ico" />
100<title>Stacking Notifications | Android Developers</title>
101
102<!-- STYLESHEETS -->
103<link rel="stylesheet"
104href="//fonts.googleapis.com/css?family=Roboto:light,regular,medium,thin,italic,mediumitalic,bold" title="roboto">
105<link href="/assets/css/default.css" rel="stylesheet" type="text/css">
106
107
108
109<!-- JAVASCRIPT -->
110<script src="//www.google.com/jsapi" type="text/javascript"></script>
111<script src="/assets/js/android_3p-bundle.js" type="text/javascript"></script>
112<script type="text/javascript">
113 var toRoot = "/";
114 var metaTags = [];
115 var devsite = false;
116</script>
117<script src="/assets/js/docs.js" type="text/javascript"></script>
118
119<script type="text/javascript">
120 var _gaq = _gaq || [];
121 _gaq.push(['_setAccount', 'UA-5831155-1']);
122 _gaq.push(['_trackPageview']);
123
124 (function() {
125 var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
126 ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
127 var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
128 })();
129</script>
130</head>
131
132<body class="gc-documentation
133 " itemscope itemtype="http://schema.org/Article">
134
135
136
137<a name="top"></a>
138
139 <!-- Header -->
140 <div id="header">
141 <div class="wrap" id="header-wrap">
142 <div class="col-3 logo-wear">
143 <a href="/wear/index.html">
144 <img src="/wear/images/android-wear.png" height="16" alt="Android Wear" />
145 </a>
146 </div>
147
148
149 <div class="col-8" style="margin:0"><h1 style="margin:1px 0 0 20px;padding:0;line-height:16px;
150 color:#666;font-weight:100;font-size:24px;">Developer Preview</h1></div>
151
152
153 <!-- New Search -->
154 <div class="menu-container">
155 <div class="moremenu">
156 <div id="more-btn"></div>
157 </div>
158 <div class="morehover" id="moremenu">
159 <div class="top"></div>
160 <div class="mid">
161 <div class="header">Links</div>
162 <ul>
163 <li><a href="https://play.google.com/apps/publish/">Google Play Developer Console</a></li>
164 <li><a href="http://android-developers.blogspot.com/">Android Developers Blog</a></li>
165 <li><a href="/about/index.html">About Android</a></li>
166 </ul>
167 <div class="header">Android Sites</div>
168 <ul>
169 <li><a href="http://www.android.com">Android.com</a></li>
170 <li class="active"><a>Android Developers</a></li>
171 <li><a href="http://source.android.com">Android Open Source Project</a></li>
172 </ul>
173
174
175
176 <div class="header">Language</div>
177 <div id="language" class="locales">
178 <select name="language" onChange="changeLangPref(this.value, true)">
179 <option value="en">English</option>
180 <option value="es">Español</option>
181 <option value="ja">日本語</option>
182 <option value="ko">한국어</option>
183 <option value="ru">Русский</option>
184 <option value="zh-cn">中文 (中国)</option>
185 <option value="zh-tw">中文 (台灣)</option>
186 </select>
187 </div>
188 <script type="text/javascript">
189 <!--
190 loadLangPref();
191 //-->
192 </script>
193
194
195
196
197 <br class="clearfix" />
198 </div><!-- end mid -->
199 <div class="bottom"></div>
200 </div><!-- end morehover -->
201
202 <div class="search" id="search-container">
203 <div class="search-inner">
204 <div id="search-btn"></div>
205 <div class="left"></div>
206 <form onsubmit="return submit_search()">
207 <input id="search_autocomplete" type="text" value="" autocomplete="off" name="q"
208onfocus="search_focus_changed(this, true)" onblur="search_focus_changed(this, false)"
209onkeydown="return search_changed(event, true, '/')"
210onkeyup="return search_changed(event, false, '/')" />
211 </form>
212 <div class="right"></div>
213 <a class="close hide">close</a>
214 <div class="left"></div>
215 <div class="right"></div>
216 </div>
217 </div><!-- end search -->
218
219 <div class="search_filtered_wrapper reference">
220 <div class="suggest-card reference no-display">
221 <ul class="search_filtered">
222 </ul>
223 </div>
224 </div>
225
226 <div class="search_filtered_wrapper docs">
227 <div class="suggest-card dummy no-display">&nbsp;</div>
228 <div class="suggest-card develop no-display">
229 <ul class="search_filtered">
230 </ul>
231 <div class="child-card guides no-display">
232 </div>
233 <div class="child-card training no-display">
234 </div>
235 <div class="child-card samples no-display">
236 </div>
237 </div>
238 <div class="suggest-card design no-display">
239 <ul class="search_filtered">
240 </ul>
241 </div>
242 <div class="suggest-card distribute no-display">
243 <ul class="search_filtered">
244 </ul>
245 </div>
246 </div><!-- end search_filtered_wrapper -->
247
248 </div>
249 <!-- end menu_container -->
250
251
252 </div><!-- end header-wrap -->
253 </div>
254 <!-- /Header -->
255
256
257 <div id="searchResults" class="wrap" style="display:none;">
258 <h2 id="searchTitle">Results</h2>
259 <div id="leftSearchControl" class="search-control">Loading...</div>
260 </div>
261
262
263
264
265
266 <div class="wrap clearfix" id="body-content">
267 <div class="col-4" id="side-nav" itemscope itemtype="http://schema.org/SiteNavigationElement">
268 <div id="devdoc-nav" class="scroll-pane">
269<a class="totop" href="#top" data-g-event="left-nav-top">to top</a>
270
271<ul id="nav">
272
273 <li class="nav-section">
274 <div class="nav-section-header empty"><a href="/wear/preview/start.html">Get Started
275 </a></div>
276 </li>
277
278 <li class="nav-section">
279 <div class="nav-section-header empty"><a href="/wear/design/user-interface.html">UI Overview
280 </a></div>
281 </li>
282
283 <li class="nav-section">
284 <div class="nav-section-header empty"><a href="/wear/design/index.html">Design Principles
285 </a></div>
286 </li>
287
288 <li class="nav-section">
289 <div class="nav-section-header empty"><a href="/wear/notifications/creating.html">Creating Notifications for Android Wear
290 </a></div>
291 </li>
292
293 <li class="nav-section">
294 <div class="nav-section-header empty"><a href="/wear/notifications/remote-input.html">Receiving Voice Input from a Notification
295 </a></div>
296 </li>
297
298 <li class="nav-section">
299 <div class="nav-section-header empty"><a href="/wear/notifications/pages.html">Adding Pages to a Notification
300 </a></div>
301 </li>
302
303 <li class="nav-section">
304 <div class="nav-section-header empty"><a href="/wear/notifications/stacks.html">Stacking Notifications
305 </a></div>
306 </li>
307
308 <li class="nav-section">
309 <div class="nav-section-header"><a href="/reference/android/preview/support/package-summary.html">Notification Reference</a></div>
310 <ul class="tree-list-children">
311<li class="nav-section">
312<div class="nav-section-header-ref"><span class="tree-list-subtitle package" title="android.preview.support.v4.app">android.preview.support.v4.app</span></div>
313 <ul>
314<li><a href="/reference/android/preview/support/v4/app/NotificationManagerCompat.html">NotificationManagerCompat</a></li>
315 </ul>
316</li>
317
318<li class="nav-section">
319<div class="nav-section-header-ref"><span class="tree-list-subtitle package" title="android.preview.support.wearable.notifications">android.preview.support.wearable.notifications</span></div>
320<ul>
321
322<li><a href="/reference/android/preview/support/wearable/notifications/RemoteInput.html">RemoteInput</a></li>
323<li><a href="/reference/android/preview/support/wearable/notifications/RemoteInput.Builder.html" >RemoteInput.Builder</a></li>
324
325<li><a href="/reference/android/preview/support/wearable/notifications/WearableNotifications.html">WearableNotifications</a></li>
326
327<li><a href="/reference/android/preview/support/wearable/notifications/WearableNotifications.Action.html">WearableNotifications.Action</a></li>
328
329<li><a href="/reference/android/preview/support/wearable/notifications/WearableNotifications.Action.Builder.html">WearableNotifications.Action.Builder</a></li>
330
331<li><a href="/reference/android/preview/support/wearable/notifications/WearableNotifications.Builder.html">WearableNotifications.Builder</a></li>
332 </ul>
333 </li>
334</ul>
335</li>
336
337
338
339 <li class="nav-section">
340 <div class="nav-section-header empty"><a href="/wear/license.html">License Agreement</a></div>
341 </li>
342
343
344</ul>
345
346
347
348 </div>
349 </div> <!-- end side-nav -->
350 <script>
351 $(document).ready(function() {
352 scrollIntoView("devdoc-nav");
353 });
354 </script>
355
356
357
358
359<div class="col-12" id="doc-col" >
360
361
362
363
364
365 <h1 itemprop="name" >Stacking Notifications</h1>
366
367
368
369
370
371
372 <div id="jd-content">
373
374
375 <div class="jd-descr" itemprop="articleBody">
376 <img src="/wear/images/11_bundles_B.png" height="200" width="169" style="float:right;margin:0 0 20px 40px" />
377<img src="/wear/images/11_bundles_A.png" height="200" width="169" style="float:right;margin:0 0 20px 40px" />
378
Scott Maina32c4372014-03-19 11:51:05 -0700[diff] [blame]379<p>When creating notifications for a handheld device, you should always aggregate similar
380notifications into a single summary notification. For example, if your app creates notifications
381for received messages, you should not show more than one notification
382on a handheld device&mdash;when more than one is message is received, use a single notification
383to provide a summary such as "2 new messages."</p>
Scott Main50d7dc92014-03-18 05:13:12 -0700[diff] [blame]384
Scott Maina32c4372014-03-19 11:51:05 -0700[diff] [blame]385<p>However, a summary notification is less useful on an Android wearable because users
386are not able to read details from each message on the wearable (they must open your app on the
387handheld to view more information). So for the wearable device, you should
388group all the notifications together in a stack. The stack of notifications appears as a single
389card, which users can expand to view the details from each notification separately. The new
390<a href="/reference/android/preview/support/wearable/notifications/WearableNotifications.Builder.html#setGroup(java.lang.String, int)">
391<code>setGroup()</code></a> method makes this possible while allowing you to still provide
392only one summary notification on the handheld device.</p>
Scott Main50d7dc92014-03-18 05:13:12 -0700[diff] [blame]393
394<p>For details about designing notification stacks, see the
395<a href="/wear/design/index.html#NotificationStacks">Design Principles of Android
396Wear</a>.</p>
397
398
399<h2 id="AddGroup">Add Each Notification to a Group</h2>
400
401<p>To create a stack, call <a
402href="/reference/android/preview/support/wearable/notifications/WearableNotifications.Builder.html#setGroup(java.lang.String, int)">
403<code>setGroup()</code></a> for each notification you want in the stack, passing the same
404group key. For example:</p>
405
406<pre style="clear:right">
407final static String GROUP_KEY_EMAILS = "group_key_emails";
408
409NotificationCompat.Builder builder = new NotificationCompat.Builder(mContext)
410 .setContentTitle("New mail from " + sender)
411 .setContentText(subject)
412 .setSmallIcon(R.drawable.new_mail);
413
414Notification notif = new WearableNotifications.Builder(builder)
415 .setGroup(GROUP_KEY_EMAILS)
416 .build();
417</pre>
418
419<p>By default, notifications appear in the order in which you added them, with the most recent
420 notification visible at the top. You can define a specific position in the group
421 by passing an order position as the second parameter for <a
422href="/reference/android/preview/support/wearable/notifications/WearableNotifications.Builder.html#setGroup(java.lang.String, int)">
423<code>setGroup()</code></a>.</p>
424
425
426<h2 id="AddSummary">Add a Summary Notification</h2>
427
Scott Maina32c4372014-03-19 11:51:05 -0700[diff] [blame]428<p>It's important that you still provide a summary notification that appears on handheld devices.
429So in addition to adding each unique notification to the same stack group, also add a summary
430notification, but set its order position to be <a
431href="/reference/android/preview/support/wearable/notifications/WearableNotifications.html#GROUP_ORDER_SUMMARY"><code>GROUP_ORDER_SUMMARY</code></a>.</p>
Scott Main50d7dc92014-03-18 05:13:12 -0700[diff] [blame]432
433<pre>
434Notification summaryNotification = new WearableNotifications.Builder(builder)
435 .setGroup(GROUP_KEY_EMAILS, WearableNotifications.GROUP_ORDER_SUMMARY)
436 .build();
437</pre>
438
Scott Maina32c4372014-03-19 11:51:05 -0700[diff] [blame]439<p>This notification will not appear in your stack of notifications on the wearable, but
440appears as the only notification on the handheld device.
Scott Main50d7dc92014-03-18 05:13:12 -0700[diff] [blame]441
442</body>
443</html>
444
445 </div>
446
447 <div class="content-footer layout-content-row"
448 itemscope itemtype="http://schema.org/SiteNavigationElement">
449 <div class="layout-content-col col-9" style="padding-top:4px">
450
451 <div class="g-plusone" data-size="medium"></div>
452
453 </div>
454
455 <div class="paging-links layout-content-col col-4">
456
457 </div>
458
459 </div>
460
461
462
463
464 </div> <!-- end jd-content -->
465
466<div id="footer" class="wrap" >
467
468
469 <div id="copyright">
470
471 Except as noted, this content is
472 licensed under <a href="http://creativecommons.org/licenses/by/2.5/">
473 Creative Commons Attribution 2.5</a>. For details and
474 restrictions, see the <a href="/license.html">Content
475 License</a>.
476 </div>
477
478
479 <div id="footerlinks">
480
481 <p>
482 <a href="/about/index.html">About Android</a>&nbsp;&nbsp;|&nbsp;
483 <a href="/legal.html">Legal</a>&nbsp;&nbsp;|&nbsp;
484 <a href="/support.html">Support</a>
485 </p>
486 </div>
487
488</div> <!-- end footer -->
489</div><!-- end doc-content -->
490
491</div> <!-- end body-content -->
492
493
494
495
496
497
498<!-- Start of Tag -->
499<script type="text/javascript">
500var axel = Math.random() + "";
501var a = axel * 10000000000000;
502document.write('<iframe src="https://2507573.fls.doubleclick.net/activityi;src=2507573;type=other026;cat=googl348;ord=' + a + '?" width="1" height="1" frameborder="0" style="display:none"></iframe>');
503</script>
504<noscript>
505<iframe src="https://2507573.fls.doubleclick.net/activityi;src=2507573;type=other026;cat=googl348;ord=1?" width="1" height="1" frameborder="0" style="display:none"></iframe>
506</noscript>
507<!-- End of Tag -->
508</body>
509</html>
510
511
512