blob: 89e73e6e57e5429316da37f1cc0feb99010afc6d [file] [log] [blame]
The Android Open Source Project9066cfe2009-03-03 19:31:44 -08001/*
2 * Copyright (C) 2007 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.app;
18
The Android Open Source Project9066cfe2009-03-03 19:31:44 -080019import android.content.Context;
20import android.content.Intent;
Daniel Sandler9f7936a2012-05-21 16:14:28 -040021import android.content.res.Resources;
Joe Onoratoef1e7762010-09-17 18:38:38 -040022import android.graphics.Bitmap;
Jeff Sharkey098d5802012-04-26 17:30:34 -070023import android.media.AudioManager;
The Android Open Source Project9066cfe2009-03-03 19:31:44 -080024import android.net.Uri;
Daniel Sandlerdcbaf662013-04-26 16:23:09 -040025import android.os.BadParcelableException;
Daniel Sandler2561b0b2012-02-13 21:04:12 -050026import android.os.Bundle;
The Android Open Source Project9066cfe2009-03-03 19:31:44 -080027import android.os.Parcel;
28import android.os.Parcelable;
Daniel Sandlera2985ed2012-04-03 16:42:00 -040029import android.os.SystemClock;
Jeff Sharkey6d515712012-09-20 16:06:08 -070030import android.os.UserHandle;
The Android Open Source Project9066cfe2009-03-03 19:31:44 -080031import android.text.TextUtils;
Daniel Sandlerdcbaf662013-04-26 16:23:09 -040032import android.util.Log;
Daniel Sandler9f7936a2012-05-21 16:14:28 -040033import android.util.TypedValue;
Joe Onorato8595a3d2010-11-19 18:12:07 -080034import android.view.View;
Jeff Sharkey1c400132011-08-05 14:50:13 -070035import android.widget.ProgressBar;
The Android Open Source Project9066cfe2009-03-03 19:31:44 -080036import android.widget.RemoteViews;
37
Griff Hazen959591e2014-05-15 22:26:18 -070038import com.android.internal.R;
39
Andy Stadler110988c2010-12-03 14:29:16 -080040import java.text.NumberFormat;
Daniel Sandler2561b0b2012-02-13 21:04:12 -050041import java.util.ArrayList;
Joe Onorato561d3852010-11-20 18:09:34 -080042
The Android Open Source Project9066cfe2009-03-03 19:31:44 -080043/**
44 * A class that represents how a persistent notification is to be presented to
45 * the user using the {@link android.app.NotificationManager}.
46 *
Joe Onoratocb109a02011-01-18 17:57:41 -080047 * <p>The {@link Notification.Builder Notification.Builder} has been added to make it
48 * easier to construct Notifications.</p>
49 *
Joe Fernandez558459f2011-10-13 16:47:36 -070050 * <div class="special reference">
51 * <h3>Developer Guides</h3>
52 * <p>For a guide to creating notifications, read the
53 * <a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Status Bar Notifications</a>
54 * developer guide.</p>
55 * </div>
The Android Open Source Project9066cfe2009-03-03 19:31:44 -080056 */
57public class Notification implements Parcelable
58{
Daniel Sandlerdcbaf662013-04-26 16:23:09 -040059 private static final String TAG = "Notification";
60
The Android Open Source Project9066cfe2009-03-03 19:31:44 -080061 /**
62 * Use all default values (where applicable).
63 */
64 public static final int DEFAULT_ALL = ~0;
Daniel Sandler2561b0b2012-02-13 21:04:12 -050065
The Android Open Source Project9066cfe2009-03-03 19:31:44 -080066 /**
67 * Use the default notification sound. This will ignore any given
68 * {@link #sound}.
Daniel Sandler2561b0b2012-02-13 21:04:12 -050069 *
70
The Android Open Source Project9066cfe2009-03-03 19:31:44 -080071 * @see #defaults
Daniel Sandler2561b0b2012-02-13 21:04:12 -050072 */
73
The Android Open Source Project9066cfe2009-03-03 19:31:44 -080074 public static final int DEFAULT_SOUND = 1;
75
76 /**
77 * Use the default notification vibrate. This will ignore any given
Daniel Sandler2561b0b2012-02-13 21:04:12 -050078 * {@link #vibrate}. Using phone vibration requires the
Scott Mainb8b36452009-04-26 15:50:49 -070079 * {@link android.Manifest.permission#VIBRATE VIBRATE} permission.
Daniel Sandler2561b0b2012-02-13 21:04:12 -050080 *
The Android Open Source Project9066cfe2009-03-03 19:31:44 -080081 * @see #defaults
Daniel Sandler2561b0b2012-02-13 21:04:12 -050082 */
83
The Android Open Source Project9066cfe2009-03-03 19:31:44 -080084 public static final int DEFAULT_VIBRATE = 2;
Daniel Sandler2561b0b2012-02-13 21:04:12 -050085
The Android Open Source Project9066cfe2009-03-03 19:31:44 -080086 /**
87 * Use the default notification lights. This will ignore the
88 * {@link #FLAG_SHOW_LIGHTS} bit, and {@link #ledARGB}, {@link #ledOffMS}, or
89 * {@link #ledOnMS}.
Daniel Sandler2561b0b2012-02-13 21:04:12 -050090 *
The Android Open Source Project9066cfe2009-03-03 19:31:44 -080091 * @see #defaults
Daniel Sandler2561b0b2012-02-13 21:04:12 -050092 */
93
The Android Open Source Project9066cfe2009-03-03 19:31:44 -080094 public static final int DEFAULT_LIGHTS = 4;
Daniel Sandler2561b0b2012-02-13 21:04:12 -050095
The Android Open Source Project9066cfe2009-03-03 19:31:44 -080096 /**
Daniel Sandler2561b0b2012-02-13 21:04:12 -050097 * A timestamp related to this notification, in milliseconds since the epoch.
Joe Malin8d40d042012-11-05 11:36:40 -080098 *
Daniel Sandler2561b0b2012-02-13 21:04:12 -050099 * Default value: {@link System#currentTimeMillis() Now}.
100 *
101 * Choose a timestamp that will be most relevant to the user. For most finite events, this
102 * corresponds to the time the event happened (or will happen, in the case of events that have
103 * yet to occur but about which the user is being informed). Indefinite events should be
Joe Malin8d40d042012-11-05 11:36:40 -0800104 * timestamped according to when the activity began.
105 *
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500106 * Some examples:
Joe Malin8d40d042012-11-05 11:36:40 -0800107 *
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500108 * <ul>
109 * <li>Notification of a new chat message should be stamped when the message was received.</li>
110 * <li>Notification of an ongoing file download (with a progress bar, for example) should be stamped when the download started.</li>
111 * <li>Notification of a completed file download should be stamped when the download finished.</li>
112 * <li>Notification of an upcoming meeting should be stamped with the time the meeting will begin (that is, in the future).</li>
113 * <li>Notification of an ongoing stopwatch (increasing timer) should be stamped with the watch's start time.
114 * <li>Notification of an ongoing countdown timer should be stamped with the timer's end time.
Joe Malin8d40d042012-11-05 11:36:40 -0800115 * </ul>
116 *
The Android Open Source Project9066cfe2009-03-03 19:31:44 -0800117 */
118 public long when;
119
120 /**
121 * The resource id of a drawable to use as the icon in the status bar.
Daniel Sandlerd952dae2011-02-07 16:33:36 -0500122 * This is required; notifications with an invalid icon resource will not be shown.
The Android Open Source Project9066cfe2009-03-03 19:31:44 -0800123 */
124 public int icon;
125
126 /**
Joe Onorato46439ce2010-11-19 13:56:21 -0800127 * If the icon in the status bar is to have more than one level, you can set this. Otherwise,
128 * leave it at its default value of 0.
129 *
130 * @see android.widget.ImageView#setImageLevel
Griff Hazen959591e2014-05-15 22:26:18 -0700131 * @see android.graphics.drawable.Drawable#setLevel
Joe Onorato46439ce2010-11-19 13:56:21 -0800132 */
133 public int iconLevel;
134
135 /**
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500136 * The number of events that this notification represents. For example, in a new mail
137 * notification, this could be the number of unread messages.
Joe Malin8d40d042012-11-05 11:36:40 -0800138 *
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500139 * The system may or may not use this field to modify the appearance of the notification. For
140 * example, before {@link android.os.Build.VERSION_CODES#HONEYCOMB}, this number was
141 * superimposed over the icon in the status bar. Starting with
142 * {@link android.os.Build.VERSION_CODES#HONEYCOMB}, the template used by
143 * {@link Notification.Builder} has displayed the number in the expanded notification view.
Joe Malin8d40d042012-11-05 11:36:40 -0800144 *
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500145 * If the number is 0 or negative, it is never shown.
The Android Open Source Project9066cfe2009-03-03 19:31:44 -0800146 */
147 public int number;
148
149 /**
150 * The intent to execute when the expanded status entry is clicked. If
151 * this is an activity, it must include the
152 * {@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK} flag, which requires
Scott Main7aee61f2011-02-08 11:25:01 -0800153 * that you take care of task management as described in the
154 * <a href="{@docRoot}guide/topics/fundamentals/tasks-and-back-stack.html">Tasks and Back
Dianne Hackborn6ceca582012-01-10 15:24:26 -0800155 * Stack</a> document. In particular, make sure to read the notification section
156 * <a href="{@docRoot}guide/topics/ui/notifiers/notifications.html#HandlingNotifications">Handling
157 * Notifications</a> for the correct ways to launch an application from a
158 * notification.
The Android Open Source Project9066cfe2009-03-03 19:31:44 -0800159 */
160 public PendingIntent contentIntent;
161
162 /**
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500163 * The intent to execute when the notification is explicitly dismissed by the user, either with
164 * the "Clear All" button or by swiping it away individually.
165 *
166 * This probably shouldn't be launching an activity since several of those will be sent
167 * at the same time.
The Android Open Source Project9066cfe2009-03-03 19:31:44 -0800168 */
169 public PendingIntent deleteIntent;
170
171 /**
Dianne Hackborn170bae72010-09-03 15:14:28 -0700172 * An intent to launch instead of posting the notification to the status bar.
Joe Onoratocb109a02011-01-18 17:57:41 -0800173 *
174 * @see Notification.Builder#setFullScreenIntent
Daniel Sandlere46cbd32010-06-17 10:35:26 -0400175 */
176 public PendingIntent fullScreenIntent;
177
178 /**
The Android Open Source Project9066cfe2009-03-03 19:31:44 -0800179 * Text to scroll across the screen when this item is added to
Joe Onoratoef1e7762010-09-17 18:38:38 -0400180 * the status bar on large and smaller devices.
181 *
Joe Onorato46439ce2010-11-19 13:56:21 -0800182 * @see #tickerView
The Android Open Source Project9066cfe2009-03-03 19:31:44 -0800183 */
184 public CharSequence tickerText;
185
186 /**
Joe Onorato46439ce2010-11-19 13:56:21 -0800187 * The view to show as the ticker in the status bar when the notification
188 * is posted.
Joe Onoratoef1e7762010-09-17 18:38:38 -0400189 */
Joe Onorato46439ce2010-11-19 13:56:21 -0800190 public RemoteViews tickerView;
Joe Onoratoef1e7762010-09-17 18:38:38 -0400191
192 /**
Daniel Sandlere46cbd32010-06-17 10:35:26 -0400193 * The view that will represent this notification in the expanded status bar.
The Android Open Source Project9066cfe2009-03-03 19:31:44 -0800194 */
195 public RemoteViews contentView;
196
Daniel Sandlera0a938c2012-03-15 08:42:37 -0400197 /**
Daniel Sandler4dfbe832012-04-11 14:51:46 -0400198 * A large-format version of {@link #contentView}, giving the Notification an
Daniel Sandlerf3b73432012-03-27 15:01:25 -0400199 * opportunity to show more detail. The system UI may choose to show this
200 * instead of the normal content view at its discretion.
Daniel Sandlerf3b73432012-03-27 15:01:25 -0400201 */
202 public RemoteViews bigContentView;
203
204 /**
Joe Onorato46439ce2010-11-19 13:56:21 -0800205 * The bitmap that may escape the bounds of the panel and bar.
The Android Open Source Project9066cfe2009-03-03 19:31:44 -0800206 */
Joe Onorato46439ce2010-11-19 13:56:21 -0800207 public Bitmap largeIcon;
The Android Open Source Project9066cfe2009-03-03 19:31:44 -0800208
209 /**
210 * The sound to play.
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500211 *
The Android Open Source Project9066cfe2009-03-03 19:31:44 -0800212 * <p>
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500213 * To play the default notification sound, see {@link #defaults}.
The Android Open Source Project9066cfe2009-03-03 19:31:44 -0800214 * </p>
215 */
216 public Uri sound;
217
218 /**
219 * Use this constant as the value for audioStreamType to request that
220 * the default stream type for notifications be used. Currently the
Jeff Sharkey098d5802012-04-26 17:30:34 -0700221 * default stream type is {@link AudioManager#STREAM_NOTIFICATION}.
The Android Open Source Project9066cfe2009-03-03 19:31:44 -0800222 */
223 public static final int STREAM_DEFAULT = -1;
224
225 /**
226 * The audio stream type to use when playing the sound.
227 * Should be one of the STREAM_ constants from
228 * {@link android.media.AudioManager}.
229 */
230 public int audioStreamType = STREAM_DEFAULT;
231
The Android Open Source Project9066cfe2009-03-03 19:31:44 -0800232 /**
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500233 * The pattern with which to vibrate.
234 *
The Android Open Source Project9066cfe2009-03-03 19:31:44 -0800235 * <p>
236 * To vibrate the default pattern, see {@link #defaults}.
237 * </p>
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500238 *
The Android Open Source Project9066cfe2009-03-03 19:31:44 -0800239 * @see android.os.Vibrator#vibrate(long[],int)
240 */
241 public long[] vibrate;
242
243 /**
244 * The color of the led. The hardware will do its best approximation.
245 *
246 * @see #FLAG_SHOW_LIGHTS
247 * @see #flags
248 */
249 public int ledARGB;
250
251 /**
252 * The number of milliseconds for the LED to be on while it's flashing.
253 * The hardware will do its best approximation.
254 *
255 * @see #FLAG_SHOW_LIGHTS
256 * @see #flags
257 */
258 public int ledOnMS;
259
260 /**
261 * The number of milliseconds for the LED to be off while it's flashing.
262 * The hardware will do its best approximation.
263 *
264 * @see #FLAG_SHOW_LIGHTS
265 * @see #flags
266 */
267 public int ledOffMS;
268
269 /**
270 * Specifies which values should be taken from the defaults.
271 * <p>
272 * To set, OR the desired from {@link #DEFAULT_SOUND},
273 * {@link #DEFAULT_VIBRATE}, {@link #DEFAULT_LIGHTS}. For all default
274 * values, use {@link #DEFAULT_ALL}.
275 * </p>
276 */
277 public int defaults;
278
The Android Open Source Project9066cfe2009-03-03 19:31:44 -0800279 /**
280 * Bit to be bitwise-ored into the {@link #flags} field that should be
281 * set if you want the LED on for this notification.
282 * <ul>
283 * <li>To turn the LED off, pass 0 in the alpha channel for colorARGB
284 * or 0 for both ledOnMS and ledOffMS.</li>
285 * <li>To turn the LED on, pass 1 for ledOnMS and 0 for ledOffMS.</li>
286 * <li>To flash the LED, pass the number of milliseconds that it should
287 * be on and off to ledOnMS and ledOffMS.</li>
288 * </ul>
289 * <p>
290 * Since hardware varies, you are not guaranteed that any of the values
291 * you pass are honored exactly. Use the system defaults (TODO) if possible
292 * because they will be set to values that work on any given hardware.
293 * <p>
294 * The alpha channel must be set for forward compatibility.
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500295 *
The Android Open Source Project9066cfe2009-03-03 19:31:44 -0800296 */
297 public static final int FLAG_SHOW_LIGHTS = 0x00000001;
298
299 /**
300 * Bit to be bitwise-ored into the {@link #flags} field that should be
301 * set if this notification is in reference to something that is ongoing,
302 * like a phone call. It should not be set if this notification is in
303 * reference to something that happened at a particular point in time,
304 * like a missed phone call.
305 */
306 public static final int FLAG_ONGOING_EVENT = 0x00000002;
307
308 /**
309 * Bit to be bitwise-ored into the {@link #flags} field that if set,
Scott Mainb8b36452009-04-26 15:50:49 -0700310 * the audio will be repeated until the notification is
311 * cancelled or the notification window is opened.
The Android Open Source Project9066cfe2009-03-03 19:31:44 -0800312 */
313 public static final int FLAG_INSISTENT = 0x00000004;
314
315 /**
316 * Bit to be bitwise-ored into the {@link #flags} field that should be
Griff Hazen293977b2014-04-28 08:37:20 -0700317 * set if you would only like the sound, vibrate and ticker to be played
318 * if the notification was not already showing.
The Android Open Source Project9066cfe2009-03-03 19:31:44 -0800319 */
320 public static final int FLAG_ONLY_ALERT_ONCE = 0x00000008;
321
322 /**
323 * Bit to be bitwise-ored into the {@link #flags} field that should be
324 * set if the notification should be canceled when it is clicked by the
Daniel Sandler8aa9ae62012-12-04 23:31:47 -0500325 * user.
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500326
The Android Open Source Project9066cfe2009-03-03 19:31:44 -0800327 */
328 public static final int FLAG_AUTO_CANCEL = 0x00000010;
329
330 /**
331 * Bit to be bitwise-ored into the {@link #flags} field that should be
332 * set if the notification should not be canceled when the user clicks
333 * the Clear all button.
334 */
335 public static final int FLAG_NO_CLEAR = 0x00000020;
336
Dianne Hackbornd8a43f62009-08-17 23:33:56 -0700337 /**
338 * Bit to be bitwise-ored into the {@link #flags} field that should be
339 * set if this notification represents a currently running service. This
340 * will normally be set for you by {@link Service#startForeground}.
341 */
342 public static final int FLAG_FOREGROUND_SERVICE = 0x00000040;
343
Daniel Sandlere46cbd32010-06-17 10:35:26 -0400344 /**
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500345 * Obsolete flag indicating high-priority notifications; use the priority field instead.
Joe Malin8d40d042012-11-05 11:36:40 -0800346 *
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500347 * @deprecated Use {@link #priority} with a positive value.
Daniel Sandlere46cbd32010-06-17 10:35:26 -0400348 */
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500349 public static final int FLAG_HIGH_PRIORITY = 0x00000080;
Daniel Sandlere46cbd32010-06-17 10:35:26 -0400350
Griff Hazendfcb0802014-02-11 12:00:00 -0800351 /**
352 * Bit to be bitswise-ored into the {@link #flags} field that should be
353 * set if this notification is relevant to the current device only
354 * and it is not recommended that it bridge to other devices.
355 */
356 public static final int FLAG_LOCAL_ONLY = 0x00000100;
357
The Android Open Source Project9066cfe2009-03-03 19:31:44 -0800358 public int flags;
359
360 /**
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500361 * Default notification {@link #priority}. If your application does not prioritize its own
362 * notifications, use this value for all notifications.
363 */
364 public static final int PRIORITY_DEFAULT = 0;
365
366 /**
367 * Lower {@link #priority}, for items that are less important. The UI may choose to show these
368 * items smaller, or at a different position in the list, compared with your app's
369 * {@link #PRIORITY_DEFAULT} items.
370 */
371 public static final int PRIORITY_LOW = -1;
372
373 /**
374 * Lowest {@link #priority}; these items might not be shown to the user except under special
375 * circumstances, such as detailed notification logs.
376 */
377 public static final int PRIORITY_MIN = -2;
378
379 /**
380 * Higher {@link #priority}, for more important notifications or alerts. The UI may choose to
381 * show these items larger, or at a different position in notification lists, compared with
382 * your app's {@link #PRIORITY_DEFAULT} items.
383 */
384 public static final int PRIORITY_HIGH = 1;
385
386 /**
387 * Highest {@link #priority}, for your application's most important items that require the
388 * user's prompt attention or input.
389 */
390 public static final int PRIORITY_MAX = 2;
391
392 /**
393 * Relative priority for this notification.
Joe Malin8d40d042012-11-05 11:36:40 -0800394 *
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500395 * Priority is an indication of how much of the user's valuable attention should be consumed by
396 * this notification. Low-priority notifications may be hidden from the user in certain
397 * situations, while the user might be interrupted for a higher-priority notification. The
Daniel Sandler6738eee2012-11-16 12:03:32 -0500398 * system will make a determination about how to interpret this priority when presenting
399 * the notification.
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500400 */
401 public int priority;
Joe Malin8d40d042012-11-05 11:36:40 -0800402
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500403 /**
John Spurlockcf44a122014-03-24 11:02:36 -0400404 * Notification category: incoming call (voice or video) or similar synchronous communication request.
Griff Hazened0c87e2014-05-05 15:15:12 -0700405 * @hide
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500406 */
John Spurlockcf44a122014-03-24 11:02:36 -0400407 public static final String CATEGORY_CALL = "call";
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500408
409 /**
John Spurlockcf44a122014-03-24 11:02:36 -0400410 * Notification category: incoming direct message (SMS, instant message, etc.).
Griff Hazened0c87e2014-05-05 15:15:12 -0700411 * @hide
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500412 */
John Spurlockcf44a122014-03-24 11:02:36 -0400413 public static final String CATEGORY_MESSAGE = "msg";
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500414
415 /**
John Spurlockcf44a122014-03-24 11:02:36 -0400416 * Notification category: asynchronous bulk message (email).
Griff Hazened0c87e2014-05-05 15:15:12 -0700417 * @hide
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500418 */
John Spurlockcf44a122014-03-24 11:02:36 -0400419 public static final String CATEGORY_EMAIL = "email";
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500420
421 /**
John Spurlockcf44a122014-03-24 11:02:36 -0400422 * Notification category: calendar event.
Griff Hazened0c87e2014-05-05 15:15:12 -0700423 * @hide
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500424 */
John Spurlockcf44a122014-03-24 11:02:36 -0400425 public static final String CATEGORY_EVENT = "event";
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500426
427 /**
John Spurlockcf44a122014-03-24 11:02:36 -0400428 * Notification category: promotion or advertisement.
Griff Hazened0c87e2014-05-05 15:15:12 -0700429 * @hide
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500430 */
John Spurlockcf44a122014-03-24 11:02:36 -0400431 public static final String CATEGORY_PROMO = "promo";
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500432
433 /**
John Spurlockcf44a122014-03-24 11:02:36 -0400434 * Notification category: alarm or timer.
Griff Hazened0c87e2014-05-05 15:15:12 -0700435 * @hide
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500436 */
John Spurlockcf44a122014-03-24 11:02:36 -0400437 public static final String CATEGORY_ALARM = "alarm";
438
439 /**
440 * Notification category: progress of a long-running background operation.
Griff Hazened0c87e2014-05-05 15:15:12 -0700441 * @hide
John Spurlockcf44a122014-03-24 11:02:36 -0400442 */
443 public static final String CATEGORY_PROGRESS = "progress";
444
445 /**
446 * Notification category: social network or sharing update.
Griff Hazened0c87e2014-05-05 15:15:12 -0700447 * @hide
John Spurlockcf44a122014-03-24 11:02:36 -0400448 */
449 public static final String CATEGORY_SOCIAL = "social";
450
451 /**
452 * Notification category: error in background operation or authentication status.
Griff Hazened0c87e2014-05-05 15:15:12 -0700453 * @hide
John Spurlockcf44a122014-03-24 11:02:36 -0400454 */
455 public static final String CATEGORY_ERROR = "err";
456
457 /**
458 * Notification category: media transport control for playback.
Griff Hazened0c87e2014-05-05 15:15:12 -0700459 * @hide
John Spurlockcf44a122014-03-24 11:02:36 -0400460 */
461 public static final String CATEGORY_TRANSPORT = "transport";
462
463 /**
464 * Notification category: system or device status update. Reserved for system use.
Griff Hazened0c87e2014-05-05 15:15:12 -0700465 * @hide
John Spurlockcf44a122014-03-24 11:02:36 -0400466 */
467 public static final String CATEGORY_SYSTEM = "sys";
468
469 /**
470 * Notification category: indication of running background service.
Griff Hazened0c87e2014-05-05 15:15:12 -0700471 * @hide
John Spurlockcf44a122014-03-24 11:02:36 -0400472 */
473 public static final String CATEGORY_SERVICE = "service";
474
475 /**
476 * Notification category: a specific, timely recommendation for a single thing.
477 * For example, a news app might want to recommend a news story it believes the user will
478 * want to read next.
Griff Hazened0c87e2014-05-05 15:15:12 -0700479 * @hide
John Spurlockcf44a122014-03-24 11:02:36 -0400480 */
481 public static final String CATEGORY_RECOMMENDATION = "recommendation";
482
483 /**
484 * Notification category: ongoing information about device or contextual status.
Griff Hazened0c87e2014-05-05 15:15:12 -0700485 * @hide
John Spurlockcf44a122014-03-24 11:02:36 -0400486 */
487 public static final String CATEGORY_STATUS = "status";
488
489 /**
490 * One of the predefined notification categories (see the <code>CATEGORY_*</code> constants)
491 * that best describes this Notification. May be used by the system for ranking and filtering.
Griff Hazened0c87e2014-05-05 15:15:12 -0700492 * @hide
John Spurlockcf44a122014-03-24 11:02:36 -0400493 */
494 public String category;
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500495
496 /**
Daniel Sandlerf45564e2013-04-15 15:05:08 -0400497 * Additional semantic data to be carried around with this Notification.
Daniel Sandlercf1d39b2013-09-23 13:35:35 -0400498 * <p>
499 * The extras keys defined here are intended to capture the original inputs to {@link Builder}
500 * APIs, and are intended to be used by
501 * {@link android.service.notification.NotificationListenerService} implementations to extract
502 * detailed information from notification objects.
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500503 */
Daniel Sandlerf45564e2013-04-15 15:05:08 -0400504 public Bundle extras = new Bundle();
505
Daniel Sandlercf1d39b2013-09-23 13:35:35 -0400506 /**
507 * {@link #extras} key: this is the title of the notification,
508 * as supplied to {@link Builder#setContentTitle(CharSequence)}.
509 */
Daniel Sandlerbe6e7e02013-02-01 17:49:11 -0500510 public static final String EXTRA_TITLE = "android.title";
Daniel Sandlercf1d39b2013-09-23 13:35:35 -0400511
512 /**
513 * {@link #extras} key: this is the title of the notification when shown in expanded form,
514 * e.g. as supplied to {@link BigTextStyle#setBigContentTitle(CharSequence)}.
515 */
Daniel Sandlerf45564e2013-04-15 15:05:08 -0400516 public static final String EXTRA_TITLE_BIG = EXTRA_TITLE + ".big";
Daniel Sandlercf1d39b2013-09-23 13:35:35 -0400517
518 /**
519 * {@link #extras} key: this is the main text payload, as supplied to
520 * {@link Builder#setContentText(CharSequence)}.
521 */
Daniel Sandlerbe6e7e02013-02-01 17:49:11 -0500522 public static final String EXTRA_TEXT = "android.text";
Daniel Sandlercf1d39b2013-09-23 13:35:35 -0400523
524 /**
525 * {@link #extras} key: this is a third line of text, as supplied to
526 * {@link Builder#setSubText(CharSequence)}.
527 */
Daniel Sandlerf45564e2013-04-15 15:05:08 -0400528 public static final String EXTRA_SUB_TEXT = "android.subText";
Daniel Sandlercf1d39b2013-09-23 13:35:35 -0400529
530 /**
531 * {@link #extras} key: this is a small piece of additional text as supplied to
532 * {@link Builder#setContentInfo(CharSequence)}.
533 */
Daniel Sandlerf45564e2013-04-15 15:05:08 -0400534 public static final String EXTRA_INFO_TEXT = "android.infoText";
Daniel Sandlercf1d39b2013-09-23 13:35:35 -0400535
536 /**
537 * {@link #extras} key: this is a line of summary information intended to be shown
538 * alongside expanded notifications, as supplied to (e.g.)
539 * {@link BigTextStyle#setSummaryText(CharSequence)}.
540 */
Daniel Sandlerf45564e2013-04-15 15:05:08 -0400541 public static final String EXTRA_SUMMARY_TEXT = "android.summaryText";
Daniel Sandlercf1d39b2013-09-23 13:35:35 -0400542
543 /**
544 * {@link #extras} key: this is the resource ID of the notification's main small icon, as
545 * supplied to {@link Builder#setSmallIcon(int)}.
546 */
Daniel Sandlerbe6e7e02013-02-01 17:49:11 -0500547 public static final String EXTRA_SMALL_ICON = "android.icon";
Daniel Sandlercf1d39b2013-09-23 13:35:35 -0400548
549 /**
550 * {@link #extras} key: this is a bitmap to be used instead of the small icon when showing the
551 * notification payload, as
552 * supplied to {@link Builder#setLargeIcon(android.graphics.Bitmap)}.
553 */
Daniel Sandlerf45564e2013-04-15 15:05:08 -0400554 public static final String EXTRA_LARGE_ICON = "android.largeIcon";
Daniel Sandlercf1d39b2013-09-23 13:35:35 -0400555
556 /**
557 * {@link #extras} key: this is a bitmap to be used instead of the one from
558 * {@link Builder#setLargeIcon(android.graphics.Bitmap)} when the notification is
559 * shown in its expanded form, as supplied to
560 * {@link BigPictureStyle#bigLargeIcon(android.graphics.Bitmap)}.
561 */
Daniel Sandlerf45564e2013-04-15 15:05:08 -0400562 public static final String EXTRA_LARGE_ICON_BIG = EXTRA_LARGE_ICON + ".big";
Daniel Sandlercf1d39b2013-09-23 13:35:35 -0400563
564 /**
565 * {@link #extras} key: this is the progress value supplied to
566 * {@link Builder#setProgress(int, int, boolean)}.
567 */
Daniel Sandlerf45564e2013-04-15 15:05:08 -0400568 public static final String EXTRA_PROGRESS = "android.progress";
Daniel Sandlercf1d39b2013-09-23 13:35:35 -0400569
570 /**
571 * {@link #extras} key: this is the maximum value supplied to
572 * {@link Builder#setProgress(int, int, boolean)}.
573 */
Daniel Sandlerf45564e2013-04-15 15:05:08 -0400574 public static final String EXTRA_PROGRESS_MAX = "android.progressMax";
Daniel Sandlercf1d39b2013-09-23 13:35:35 -0400575
576 /**
577 * {@link #extras} key: whether the progress bar is indeterminate, supplied to
578 * {@link Builder#setProgress(int, int, boolean)}.
579 */
Daniel Sandlerf45564e2013-04-15 15:05:08 -0400580 public static final String EXTRA_PROGRESS_INDETERMINATE = "android.progressIndeterminate";
Daniel Sandlercf1d39b2013-09-23 13:35:35 -0400581
582 /**
583 * {@link #extras} key: whether {@link #when} should be shown as a count-up timer (specifically
584 * a {@link android.widget.Chronometer}) instead of a timestamp, as supplied to
585 * {@link Builder#setUsesChronometer(boolean)}.
586 */
Daniel Sandlerf45564e2013-04-15 15:05:08 -0400587 public static final String EXTRA_SHOW_CHRONOMETER = "android.showChronometer";
Daniel Sandlercf1d39b2013-09-23 13:35:35 -0400588
589 /**
590 * {@link #extras} key: whether {@link #when} should be shown,
591 * as supplied to {@link Builder#setShowWhen(boolean)}.
592 */
Daniel Sandlerf45564e2013-04-15 15:05:08 -0400593 public static final String EXTRA_SHOW_WHEN = "android.showWhen";
Daniel Sandlercf1d39b2013-09-23 13:35:35 -0400594
595 /**
596 * {@link #extras} key: this is a bitmap to be shown in {@link BigPictureStyle} expanded
597 * notifications, supplied to {@link BigPictureStyle#bigPicture(android.graphics.Bitmap)}.
598 */
Daniel Sandlerf45564e2013-04-15 15:05:08 -0400599 public static final String EXTRA_PICTURE = "android.picture";
Daniel Sandlercf1d39b2013-09-23 13:35:35 -0400600
601 /**
602 * {@link #extras} key: An array of CharSequences to show in {@link InboxStyle} expanded
603 * notifications, each of which was supplied to {@link InboxStyle#addLine(CharSequence)}.
604 */
Daniel Sandlerf45564e2013-04-15 15:05:08 -0400605 public static final String EXTRA_TEXT_LINES = "android.textLines";
606
Daniel Sandlercf1d39b2013-09-23 13:35:35 -0400607 /**
608 * {@link #extras} key: An array of people that this notification relates to, specified
609 * by contacts provider contact URI.
610 */
Daniel Sandlerf45564e2013-04-15 15:05:08 -0400611 public static final String EXTRA_PEOPLE = "android.people";
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500612
613 /**
Scott Greenwald9a05b312013-06-28 00:37:54 -0400614 * @hide
615 * Extra added by NotificationManagerService to indicate whether a NotificationScorer
616 * modified the Notifications's score.
617 */
618 public static final String EXTRA_SCORE_MODIFIED = "android.scoreModified";
619
620 /**
Daniel Sandlercf1d39b2013-09-23 13:35:35 -0400621 * Not used.
Chris Wren51c75102013-07-16 20:49:17 -0400622 * @hide
623 */
624 public static final String EXTRA_AS_HEADS_UP = "headsup";
625
626 /**
John Spurlockcf44a122014-03-24 11:02:36 -0400627 * Allow certain system-generated notifications to appear before the device is provisioned.
628 * Only available to notifications coming from the android package.
629 * @hide
630 */
631 public static final String EXTRA_ALLOW_DURING_SETUP = "android.allowDuringSetup";
632
633 /**
Daniel Sandlercf1d39b2013-09-23 13:35:35 -0400634 * Value for {@link #EXTRA_AS_HEADS_UP}.
Chris Wren51c75102013-07-16 20:49:17 -0400635 * @hide
636 */
637 public static final int HEADS_UP_NEVER = 0;
638
639 /**
Daniel Sandlercf1d39b2013-09-23 13:35:35 -0400640 * Default value for {@link #EXTRA_AS_HEADS_UP}.
Chris Wren51c75102013-07-16 20:49:17 -0400641 * @hide
642 */
643 public static final int HEADS_UP_ALLOWED = 1;
644
645 /**
Daniel Sandlercf1d39b2013-09-23 13:35:35 -0400646 * Value for {@link #EXTRA_AS_HEADS_UP}.
Chris Wren51c75102013-07-16 20:49:17 -0400647 * @hide
648 */
649 public static final int HEADS_UP_REQUESTED = 2;
650
651 /**
Daniel Sandlercf1d39b2013-09-23 13:35:35 -0400652 * Structure to encapsulate a named action that can be shown as part of this notification.
653 * It must include an icon, a label, and a {@link PendingIntent} to be fired when the action is
654 * selected by the user.
655 * <p>
Griff Hazen959591e2014-05-15 22:26:18 -0700656 * Apps should use {@link Notification.Builder#addAction(int, CharSequence, PendingIntent)}
657 * or {@link Notification.Builder#addAction(Notification.Action)}
658 * to attach actions.
Daniel Sandlera0a938c2012-03-15 08:42:37 -0400659 */
Daniel Sandlerea2a3172013-02-20 22:24:20 -0500660 public static class Action implements Parcelable {
Griff Hazen959591e2014-05-15 22:26:18 -0700661 private final Bundle mExtras;
662
Daniel Sandlercf1d39b2013-09-23 13:35:35 -0400663 /**
664 * Small icon representing the action.
665 */
Daniel Sandlera0a938c2012-03-15 08:42:37 -0400666 public int icon;
Daniel Sandlercf1d39b2013-09-23 13:35:35 -0400667 /**
668 * Title of the action.
669 */
Daniel Sandlera0a938c2012-03-15 08:42:37 -0400670 public CharSequence title;
Daniel Sandlercf1d39b2013-09-23 13:35:35 -0400671 /**
672 * Intent to send when the user invokes this action. May be null, in which case the action
673 * may be rendered in a disabled presentation by the system UI.
674 */
Daniel Sandlera0a938c2012-03-15 08:42:37 -0400675 public PendingIntent actionIntent;
Griff Hazen959591e2014-05-15 22:26:18 -0700676
Daniel Sandlera0a938c2012-03-15 08:42:37 -0400677 private Action(Parcel in) {
678 icon = in.readInt();
679 title = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(in);
680 if (in.readInt() == 1) {
681 actionIntent = PendingIntent.CREATOR.createFromParcel(in);
682 }
Griff Hazen959591e2014-05-15 22:26:18 -0700683 mExtras = in.readBundle();
Daniel Sandlera0a938c2012-03-15 08:42:37 -0400684 }
Daniel Sandlercf1d39b2013-09-23 13:35:35 -0400685 /**
Griff Hazen959591e2014-05-15 22:26:18 -0700686 * Use {@link Notification.Builder#addAction(int, CharSequence, PendingIntent)}.
Daniel Sandlercf1d39b2013-09-23 13:35:35 -0400687 */
688 public Action(int icon, CharSequence title, PendingIntent intent) {
Griff Hazen959591e2014-05-15 22:26:18 -0700689 this(icon, title, intent, new Bundle());
690 }
691
692 private Action(int icon, CharSequence title, PendingIntent intent, Bundle extras) {
Daniel Sandlercf1d39b2013-09-23 13:35:35 -0400693 this.icon = icon;
694 this.title = title;
695 this.actionIntent = intent;
Griff Hazen959591e2014-05-15 22:26:18 -0700696 this.mExtras = extras != null ? extras : new Bundle();
697 }
698
699 /**
700 * Get additional metadata carried around with this Action.
701 */
702 public Bundle getExtras() {
703 return mExtras;
704 }
705
706 /**
707 * Builder class for {@link Action} objects.
708 */
709 public static class Builder {
710 private final int mIcon;
711 private final CharSequence mTitle;
712 private final PendingIntent mIntent;
713 private final Bundle mExtras;
714
715 /**
716 * Construct a new builder for {@link Action} object.
717 * @param icon icon to show for this action
718 * @param title the title of the action
719 * @param intent the {@link PendingIntent} to fire when users trigger this action
720 */
721 public Builder(int icon, CharSequence title, PendingIntent intent) {
722 this(icon, title, intent, new Bundle());
723 }
724
725 /**
726 * Construct a new builder for {@link Action} object using the fields from an
727 * {@link Action}.
728 * @param action the action to read fields from.
729 */
730 public Builder(Action action) {
731 this(action.icon, action.title, action.actionIntent, new Bundle(action.mExtras));
732 }
733
734 private Builder(int icon, CharSequence title, PendingIntent intent, Bundle extras) {
735 mIcon = icon;
736 mTitle = title;
737 mIntent = intent;
738 mExtras = extras;
739 }
740
741 /**
742 * Merge additional metadata into this builder.
743 *
744 * <p>Values within the Bundle will replace existing extras values in this Builder.
745 *
746 * @see Notification.Action#extras
747 */
748 public Builder addExtras(Bundle extras) {
749 if (extras != null) {
750 mExtras.putAll(extras);
751 }
752 return this;
753 }
754
755 /**
756 * Get the metadata Bundle used by this Builder.
757 *
758 * <p>The returned Bundle is shared with this Builder.
759 */
760 public Bundle getExtras() {
761 return mExtras;
762 }
763
764 /**
765 * Combine all of the options that have been set and return a new {@link Action}
766 * object.
767 * @return the built action
768 */
769 public Action build() {
770 return new Action(mIcon, mTitle, mIntent, mExtras);
771 }
Daniel Sandlera0a938c2012-03-15 08:42:37 -0400772 }
Daniel Sandlercf1d39b2013-09-23 13:35:35 -0400773
Daniel Sandlera0a938c2012-03-15 08:42:37 -0400774 @Override
775 public Action clone() {
776 return new Action(
777 this.icon,
Daniel Sandlercf1d39b2013-09-23 13:35:35 -0400778 this.title,
Griff Hazen959591e2014-05-15 22:26:18 -0700779 this.actionIntent, // safe to alias
780 new Bundle(this.mExtras));
Daniel Sandlera0a938c2012-03-15 08:42:37 -0400781 }
782 @Override
783 public int describeContents() {
784 return 0;
785 }
786 @Override
787 public void writeToParcel(Parcel out, int flags) {
788 out.writeInt(icon);
789 TextUtils.writeToParcel(title, out, flags);
790 if (actionIntent != null) {
791 out.writeInt(1);
792 actionIntent.writeToParcel(out, flags);
793 } else {
794 out.writeInt(0);
795 }
Griff Hazen959591e2014-05-15 22:26:18 -0700796 out.writeBundle(mExtras);
Daniel Sandlera0a938c2012-03-15 08:42:37 -0400797 }
Griff Hazen959591e2014-05-15 22:26:18 -0700798 public static final Parcelable.Creator<Action> CREATOR =
799 new Parcelable.Creator<Action>() {
Daniel Sandlera0a938c2012-03-15 08:42:37 -0400800 public Action createFromParcel(Parcel in) {
801 return new Action(in);
802 }
803 public Action[] newArray(int size) {
804 return new Action[size];
805 }
806 };
807 }
808
Daniel Sandlercf1d39b2013-09-23 13:35:35 -0400809 /**
810 * Array of all {@link Action} structures attached to this notification by
811 * {@link Builder#addAction(int, CharSequence, PendingIntent)}. Mostly useful for instances of
812 * {@link android.service.notification.NotificationListenerService} that provide an alternative
813 * interface for invoking actions.
814 */
Daniel Sandlerea2a3172013-02-20 22:24:20 -0500815 public Action[] actions;
Daniel Sandlera0a938c2012-03-15 08:42:37 -0400816
817 /**
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500818 * Constructs a Notification object with default values.
Joe Onorato46439ce2010-11-19 13:56:21 -0800819 * You might want to consider using {@link Builder} instead.
The Android Open Source Project9066cfe2009-03-03 19:31:44 -0800820 */
821 public Notification()
822 {
823 this.when = System.currentTimeMillis();
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500824 this.priority = PRIORITY_DEFAULT;
The Android Open Source Project9066cfe2009-03-03 19:31:44 -0800825 }
826
827 /**
The Android Open Source Project9066cfe2009-03-03 19:31:44 -0800828 * @hide
829 */
830 public Notification(Context context, int icon, CharSequence tickerText, long when,
831 CharSequence contentTitle, CharSequence contentText, Intent contentIntent)
832 {
833 this.when = when;
834 this.icon = icon;
835 this.tickerText = tickerText;
836 setLatestEventInfo(context, contentTitle, contentText,
837 PendingIntent.getActivity(context, 0, contentIntent, 0));
838 }
839
840 /**
841 * Constructs a Notification object with the information needed to
842 * have a status bar icon without the standard expanded view.
843 *
844 * @param icon The resource id of the icon to put in the status bar.
845 * @param tickerText The text that flows by in the status bar when the notification first
846 * activates.
847 * @param when The time to show in the time field. In the System.currentTimeMillis
848 * timebase.
Joe Onorato46439ce2010-11-19 13:56:21 -0800849 *
850 * @deprecated Use {@link Builder} instead.
The Android Open Source Project9066cfe2009-03-03 19:31:44 -0800851 */
Joe Onorato46439ce2010-11-19 13:56:21 -0800852 @Deprecated
The Android Open Source Project9066cfe2009-03-03 19:31:44 -0800853 public Notification(int icon, CharSequence tickerText, long when)
854 {
855 this.icon = icon;
856 this.tickerText = tickerText;
857 this.when = when;
858 }
859
860 /**
861 * Unflatten the notification from a parcel.
862 */
863 public Notification(Parcel parcel)
864 {
865 int version = parcel.readInt();
866
867 when = parcel.readLong();
868 icon = parcel.readInt();
869 number = parcel.readInt();
870 if (parcel.readInt() != 0) {
871 contentIntent = PendingIntent.CREATOR.createFromParcel(parcel);
872 }
873 if (parcel.readInt() != 0) {
874 deleteIntent = PendingIntent.CREATOR.createFromParcel(parcel);
875 }
876 if (parcel.readInt() != 0) {
877 tickerText = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(parcel);
878 }
879 if (parcel.readInt() != 0) {
Joe Onorato46439ce2010-11-19 13:56:21 -0800880 tickerView = RemoteViews.CREATOR.createFromParcel(parcel);
Joe Onoratoef1e7762010-09-17 18:38:38 -0400881 }
882 if (parcel.readInt() != 0) {
The Android Open Source Project9066cfe2009-03-03 19:31:44 -0800883 contentView = RemoteViews.CREATOR.createFromParcel(parcel);
884 }
Joe Onorato561d3852010-11-20 18:09:34 -0800885 if (parcel.readInt() != 0) {
886 largeIcon = Bitmap.CREATOR.createFromParcel(parcel);
887 }
The Android Open Source Project9066cfe2009-03-03 19:31:44 -0800888 defaults = parcel.readInt();
889 flags = parcel.readInt();
890 if (parcel.readInt() != 0) {
891 sound = Uri.CREATOR.createFromParcel(parcel);
892 }
893
894 audioStreamType = parcel.readInt();
895 vibrate = parcel.createLongArray();
896 ledARGB = parcel.readInt();
897 ledOnMS = parcel.readInt();
898 ledOffMS = parcel.readInt();
899 iconLevel = parcel.readInt();
Daniel Sandlere46cbd32010-06-17 10:35:26 -0400900
901 if (parcel.readInt() != 0) {
902 fullScreenIntent = PendingIntent.CREATOR.createFromParcel(parcel);
903 }
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500904
905 priority = parcel.readInt();
Daniel Sandlera0a938c2012-03-15 08:42:37 -0400906
John Spurlockcf44a122014-03-24 11:02:36 -0400907 category = parcel.readString();
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500908
Daniel Sandlerbe6e7e02013-02-01 17:49:11 -0500909 extras = parcel.readBundle(); // may be null
Daniel Sandlera0a938c2012-03-15 08:42:37 -0400910
Daniel Sandlerbe6e7e02013-02-01 17:49:11 -0500911 actions = parcel.createTypedArray(Action.CREATOR); // may be null
912
Daniel Sandlera0a938c2012-03-15 08:42:37 -0400913 if (parcel.readInt() != 0) {
Daniel Sandlerf3b73432012-03-27 15:01:25 -0400914 bigContentView = RemoteViews.CREATOR.createFromParcel(parcel);
915 }
The Android Open Source Project9066cfe2009-03-03 19:31:44 -0800916 }
917
Andy Stadler110988c2010-12-03 14:29:16 -0800918 @Override
Joe Onorato18e69df2010-05-17 22:26:12 -0700919 public Notification clone() {
920 Notification that = new Notification();
Daniel Sandler1a497d32013-04-18 14:52:45 -0400921 cloneInto(that, true);
Daniel Sandlerbe6e7e02013-02-01 17:49:11 -0500922 return that;
923 }
Joe Onorato18e69df2010-05-17 22:26:12 -0700924
Daniel Sandler1a497d32013-04-18 14:52:45 -0400925 /**
926 * Copy all (or if heavy is false, all except Bitmaps and RemoteViews) members
927 * of this into that.
928 * @hide
929 */
930 public void cloneInto(Notification that, boolean heavy) {
Joe Onorato18e69df2010-05-17 22:26:12 -0700931 that.when = this.when;
932 that.icon = this.icon;
933 that.number = this.number;
934
935 // PendingIntents are global, so there's no reason (or way) to clone them.
936 that.contentIntent = this.contentIntent;
937 that.deleteIntent = this.deleteIntent;
Daniel Sandlere46cbd32010-06-17 10:35:26 -0400938 that.fullScreenIntent = this.fullScreenIntent;
Joe Onorato18e69df2010-05-17 22:26:12 -0700939
940 if (this.tickerText != null) {
941 that.tickerText = this.tickerText.toString();
942 }
Daniel Sandler1a497d32013-04-18 14:52:45 -0400943 if (heavy && this.tickerView != null) {
Joe Onorato46439ce2010-11-19 13:56:21 -0800944 that.tickerView = this.tickerView.clone();
Joe Onoratoef1e7762010-09-17 18:38:38 -0400945 }
Daniel Sandler1a497d32013-04-18 14:52:45 -0400946 if (heavy && this.contentView != null) {
Joe Onorato18e69df2010-05-17 22:26:12 -0700947 that.contentView = this.contentView.clone();
948 }
Daniel Sandler1a497d32013-04-18 14:52:45 -0400949 if (heavy && this.largeIcon != null) {
Joe Onorato561d3852010-11-20 18:09:34 -0800950 that.largeIcon = Bitmap.createBitmap(this.largeIcon);
951 }
Jozef BABJAKa8b91832011-02-22 08:05:08 +0100952 that.iconLevel = this.iconLevel;
Joe Onorato18e69df2010-05-17 22:26:12 -0700953 that.sound = this.sound; // android.net.Uri is immutable
954 that.audioStreamType = this.audioStreamType;
955
956 final long[] vibrate = this.vibrate;
957 if (vibrate != null) {
958 final int N = vibrate.length;
959 final long[] vib = that.vibrate = new long[N];
960 System.arraycopy(vibrate, 0, vib, 0, N);
961 }
962
963 that.ledARGB = this.ledARGB;
964 that.ledOnMS = this.ledOnMS;
965 that.ledOffMS = this.ledOffMS;
966 that.defaults = this.defaults;
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500967
Joe Onorato18e69df2010-05-17 22:26:12 -0700968 that.flags = this.flags;
969
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500970 that.priority = this.priority;
Joe Malin8d40d042012-11-05 11:36:40 -0800971
John Spurlockcf44a122014-03-24 11:02:36 -0400972 that.category = this.category;
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500973
974 if (this.extras != null) {
Daniel Sandlerdcbaf662013-04-26 16:23:09 -0400975 try {
976 that.extras = new Bundle(this.extras);
977 // will unparcel
978 that.extras.size();
979 } catch (BadParcelableException e) {
980 Log.e(TAG, "could not unparcel extras from notification: " + this, e);
981 that.extras = null;
982 }
Daniel Sandler2561b0b2012-02-13 21:04:12 -0500983 }
984
Daniel Sandlerbe6e7e02013-02-01 17:49:11 -0500985 if (this.actions != null) {
986 that.actions = new Action[this.actions.length];
987 for(int i=0; i<this.actions.length; i++) {
988 that.actions[i] = this.actions[i].clone();
989 }
Daniel Sandlera0a938c2012-03-15 08:42:37 -0400990 }
Daniel Sandlerbe6e7e02013-02-01 17:49:11 -0500991
Daniel Sandler1a497d32013-04-18 14:52:45 -0400992 if (heavy && this.bigContentView != null) {
Daniel Sandlerf3b73432012-03-27 15:01:25 -0400993 that.bigContentView = this.bigContentView.clone();
994 }
Daniel Sandler1a497d32013-04-18 14:52:45 -0400995
996 if (!heavy) {
997 that.lightenPayload(); // will clean out extras
998 }
999 }
1000
1001 /**
1002 * Removes heavyweight parts of the Notification object for archival or for sending to
1003 * listeners when the full contents are not necessary.
1004 * @hide
1005 */
1006 public final void lightenPayload() {
1007 tickerView = null;
1008 contentView = null;
1009 bigContentView = null;
1010 largeIcon = null;
1011 if (extras != null) {
1012 extras.remove(Notification.EXTRA_LARGE_ICON);
1013 extras.remove(Notification.EXTRA_LARGE_ICON_BIG);
1014 extras.remove(Notification.EXTRA_PICTURE);
1015 }
Joe Onorato18e69df2010-05-17 22:26:12 -07001016 }
1017
Daniel Sandlerdcbaf662013-04-26 16:23:09 -04001018 /**
1019 * Make sure this CharSequence is safe to put into a bundle, which basically
1020 * means it had better not be some custom Parcelable implementation.
1021 * @hide
1022 */
1023 public static CharSequence safeCharSequence(CharSequence cs) {
1024 if (cs instanceof Parcelable) {
1025 Log.e(TAG, "warning: " + cs.getClass().getCanonicalName()
1026 + " instance is a custom Parcelable and not allowed in Notification");
1027 return cs.toString();
1028 }
1029
1030 return cs;
1031 }
1032
The Android Open Source Project9066cfe2009-03-03 19:31:44 -08001033 public int describeContents() {
1034 return 0;
1035 }
1036
1037 /**
1038 * Flatten this notification from a parcel.
1039 */
1040 public void writeToParcel(Parcel parcel, int flags)
1041 {
1042 parcel.writeInt(1);
1043
1044 parcel.writeLong(when);
1045 parcel.writeInt(icon);
1046 parcel.writeInt(number);
1047 if (contentIntent != null) {
1048 parcel.writeInt(1);
1049 contentIntent.writeToParcel(parcel, 0);
1050 } else {
1051 parcel.writeInt(0);
1052 }
1053 if (deleteIntent != null) {
1054 parcel.writeInt(1);
1055 deleteIntent.writeToParcel(parcel, 0);
1056 } else {
1057 parcel.writeInt(0);
1058 }
1059 if (tickerText != null) {
1060 parcel.writeInt(1);
1061 TextUtils.writeToParcel(tickerText, parcel, flags);
1062 } else {
1063 parcel.writeInt(0);
1064 }
Joe Onorato46439ce2010-11-19 13:56:21 -08001065 if (tickerView != null) {
Joe Onoratoef1e7762010-09-17 18:38:38 -04001066 parcel.writeInt(1);
Joe Onorato46439ce2010-11-19 13:56:21 -08001067 tickerView.writeToParcel(parcel, 0);
Joe Onoratoef1e7762010-09-17 18:38:38 -04001068 } else {
1069 parcel.writeInt(0);
1070 }
The Android Open Source Project9066cfe2009-03-03 19:31:44 -08001071 if (contentView != null) {
1072 parcel.writeInt(1);
1073 contentView.writeToParcel(parcel, 0);
1074 } else {
1075 parcel.writeInt(0);
1076 }
Joe Onorato561d3852010-11-20 18:09:34 -08001077 if (largeIcon != null) {
1078 parcel.writeInt(1);
1079 largeIcon.writeToParcel(parcel, 0);
1080 } else {
1081 parcel.writeInt(0);
1082 }
The Android Open Source Project9066cfe2009-03-03 19:31:44 -08001083
1084 parcel.writeInt(defaults);
1085 parcel.writeInt(this.flags);
1086
1087 if (sound != null) {
1088 parcel.writeInt(1);
1089 sound.writeToParcel(parcel, 0);
1090 } else {
1091 parcel.writeInt(0);
1092 }
1093 parcel.writeInt(audioStreamType);
1094 parcel.writeLongArray(vibrate);
1095 parcel.writeInt(ledARGB);
1096 parcel.writeInt(ledOnMS);
1097 parcel.writeInt(ledOffMS);
1098 parcel.writeInt(iconLevel);
Daniel Sandlere46cbd32010-06-17 10:35:26 -04001099
1100 if (fullScreenIntent != null) {
1101 parcel.writeInt(1);
1102 fullScreenIntent.writeToParcel(parcel, 0);
1103 } else {
1104 parcel.writeInt(0);
1105 }
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001106
1107 parcel.writeInt(priority);
Joe Malin8d40d042012-11-05 11:36:40 -08001108
John Spurlockcf44a122014-03-24 11:02:36 -04001109 parcel.writeString(category);
Joe Malin8d40d042012-11-05 11:36:40 -08001110
Daniel Sandlerbe6e7e02013-02-01 17:49:11 -05001111 parcel.writeBundle(extras); // null ok
Daniel Sandlera0a938c2012-03-15 08:42:37 -04001112
Daniel Sandlerbe6e7e02013-02-01 17:49:11 -05001113 parcel.writeTypedArray(actions, 0); // null ok
Daniel Sandlera0a938c2012-03-15 08:42:37 -04001114
Daniel Sandlerf3b73432012-03-27 15:01:25 -04001115 if (bigContentView != null) {
1116 parcel.writeInt(1);
1117 bigContentView.writeToParcel(parcel, 0);
1118 } else {
1119 parcel.writeInt(0);
1120 }
The Android Open Source Project9066cfe2009-03-03 19:31:44 -08001121 }
1122
1123 /**
1124 * Parcelable.Creator that instantiates Notification objects
1125 */
1126 public static final Parcelable.Creator<Notification> CREATOR
1127 = new Parcelable.Creator<Notification>()
1128 {
1129 public Notification createFromParcel(Parcel parcel)
1130 {
1131 return new Notification(parcel);
1132 }
1133
1134 public Notification[] newArray(int size)
1135 {
1136 return new Notification[size];
1137 }
1138 };
1139
1140 /**
1141 * Sets the {@link #contentView} field to be a view with the standard "Latest Event"
1142 * layout.
1143 *
1144 * <p>Uses the {@link #icon} and {@link #when} fields to set the icon and time fields
1145 * in the view.</p>
1146 * @param context The context for your application / activity.
1147 * @param contentTitle The title that goes in the expanded entry.
1148 * @param contentText The text that goes in the expanded entry.
1149 * @param contentIntent The intent to launch when the user clicks the expanded notification.
1150 * If this is an activity, it must include the
1151 * {@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK} flag, which requires
Scott Main7aee61f2011-02-08 11:25:01 -08001152 * that you take care of task management as described in the
1153 * <a href="{@docRoot}guide/topics/fundamentals/tasks-and-back-stack.html">Tasks and Back
1154 * Stack</a> document.
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001155 *
Joe Onorato46439ce2010-11-19 13:56:21 -08001156 * @deprecated Use {@link Builder} instead.
The Android Open Source Project9066cfe2009-03-03 19:31:44 -08001157 */
Joe Onorato46439ce2010-11-19 13:56:21 -08001158 @Deprecated
The Android Open Source Project9066cfe2009-03-03 19:31:44 -08001159 public void setLatestEventInfo(Context context,
1160 CharSequence contentTitle, CharSequence contentText, PendingIntent contentIntent) {
Daniel Sandlerbe6e7e02013-02-01 17:49:11 -05001161 Notification.Builder builder = new Notification.Builder(context);
1162
1163 // First, ensure that key pieces of information that may have been set directly
1164 // are preserved
1165 builder.setWhen(this.when);
1166 builder.setSmallIcon(this.icon);
1167 builder.setPriority(this.priority);
1168 builder.setTicker(this.tickerText);
1169 builder.setNumber(this.number);
1170 builder.mFlags = this.flags;
1171 builder.setSound(this.sound, this.audioStreamType);
1172 builder.setDefaults(this.defaults);
1173 builder.setVibrate(this.vibrate);
1174
1175 // now apply the latestEventInfo fields
The Android Open Source Project9066cfe2009-03-03 19:31:44 -08001176 if (contentTitle != null) {
Daniel Sandlerbe6e7e02013-02-01 17:49:11 -05001177 builder.setContentTitle(contentTitle);
The Android Open Source Project9066cfe2009-03-03 19:31:44 -08001178 }
1179 if (contentText != null) {
Daniel Sandlerbe6e7e02013-02-01 17:49:11 -05001180 builder.setContentText(contentText);
The Android Open Source Project9066cfe2009-03-03 19:31:44 -08001181 }
Daniel Sandlerbe6e7e02013-02-01 17:49:11 -05001182 builder.setContentIntent(contentIntent);
1183 builder.buildInto(this);
The Android Open Source Project9066cfe2009-03-03 19:31:44 -08001184 }
1185
1186 @Override
1187 public String toString() {
1188 StringBuilder sb = new StringBuilder();
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001189 sb.append("Notification(pri=");
1190 sb.append(priority);
1191 sb.append(" contentView=");
Joe Onoratoc9596d62011-01-12 17:03:11 -08001192 if (contentView != null) {
1193 sb.append(contentView.getPackage());
1194 sb.append("/0x");
1195 sb.append(Integer.toHexString(contentView.getLayoutId()));
1196 } else {
1197 sb.append("null");
1198 }
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001199 // TODO(dsandler): defaults take precedence over local values, so reorder the branches below
Joe Onoratoc9596d62011-01-12 17:03:11 -08001200 sb.append(" vibrate=");
Daniel Sandler6738eee2012-11-16 12:03:32 -05001201 if ((this.defaults & DEFAULT_VIBRATE) != 0) {
1202 sb.append("default");
1203 } else if (this.vibrate != null) {
The Android Open Source Project9066cfe2009-03-03 19:31:44 -08001204 int N = this.vibrate.length-1;
1205 sb.append("[");
1206 for (int i=0; i<N; i++) {
1207 sb.append(this.vibrate[i]);
1208 sb.append(',');
1209 }
Simon Schoar8cf97d92009-06-10 22:08:37 +02001210 if (N != -1) {
1211 sb.append(this.vibrate[N]);
1212 }
The Android Open Source Project9066cfe2009-03-03 19:31:44 -08001213 sb.append("]");
The Android Open Source Project9066cfe2009-03-03 19:31:44 -08001214 } else {
1215 sb.append("null");
1216 }
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001217 sb.append(" sound=");
Daniel Sandler6738eee2012-11-16 12:03:32 -05001218 if ((this.defaults & DEFAULT_SOUND) != 0) {
The Android Open Source Project9066cfe2009-03-03 19:31:44 -08001219 sb.append("default");
Daniel Sandler6738eee2012-11-16 12:03:32 -05001220 } else if (this.sound != null) {
1221 sb.append(this.sound.toString());
The Android Open Source Project9066cfe2009-03-03 19:31:44 -08001222 } else {
1223 sb.append("null");
1224 }
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001225 sb.append(" defaults=0x");
The Android Open Source Project9066cfe2009-03-03 19:31:44 -08001226 sb.append(Integer.toHexString(this.defaults));
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001227 sb.append(" flags=0x");
Daniel Sandlere46cbd32010-06-17 10:35:26 -04001228 sb.append(Integer.toHexString(this.flags));
John Spurlockcf44a122014-03-24 11:02:36 -04001229 sb.append(" category="); sb.append(this.category);
Daniel Sandlera0a938c2012-03-15 08:42:37 -04001230 if (actions != null) {
1231 sb.append(" ");
1232 sb.append(actions.length);
1233 sb.append(" action");
1234 if (actions.length > 1) sb.append("s");
1235 }
1236 sb.append(")");
The Android Open Source Project9066cfe2009-03-03 19:31:44 -08001237 return sb.toString();
1238 }
Joe Onorato46439ce2010-11-19 13:56:21 -08001239
Jeff Sharkey6d515712012-09-20 16:06:08 -07001240 /** {@hide} */
1241 public void setUser(UserHandle user) {
Amith Yamasaniecbd68b2012-11-02 12:17:19 -07001242 if (user.getIdentifier() == UserHandle.USER_ALL) {
1243 user = UserHandle.OWNER;
1244 }
Jeff Sharkey6d515712012-09-20 16:06:08 -07001245 if (tickerView != null) {
1246 tickerView.setUser(user);
1247 }
1248 if (contentView != null) {
1249 contentView.setUser(user);
1250 }
1251 if (bigContentView != null) {
1252 bigContentView.setUser(user);
1253 }
1254 }
1255
Joe Onoratocb109a02011-01-18 17:57:41 -08001256 /**
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001257 * Builder class for {@link Notification} objects.
Joe Malin8d40d042012-11-05 11:36:40 -08001258 *
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001259 * Provides a convenient way to set the various fields of a {@link Notification} and generate
Scott Main183bf112012-08-13 19:12:13 -07001260 * content views using the platform's notification layout template. If your app supports
1261 * versions of Android as old as API level 4, you can instead use
1262 * {@link android.support.v4.app.NotificationCompat.Builder NotificationCompat.Builder},
1263 * available in the <a href="{@docRoot}tools/extras/support-library.html">Android Support
1264 * library</a>.
Joe Malin8d40d042012-11-05 11:36:40 -08001265 *
Scott Main183bf112012-08-13 19:12:13 -07001266 * <p>Example:
Joe Malin8d40d042012-11-05 11:36:40 -08001267 *
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001268 * <pre class="prettyprint">
Scott Main183bf112012-08-13 19:12:13 -07001269 * Notification noti = new Notification.Builder(mContext)
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001270 * .setContentTitle(&quot;New mail from &quot; + sender.toString())
1271 * .setContentText(subject)
1272 * .setSmallIcon(R.drawable.new_mail)
1273 * .setLargeIcon(aBitmap)
Chris Wrenfbd96ba2012-05-01 12:03:58 -04001274 * .build();
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001275 * </pre>
Joe Onoratocb109a02011-01-18 17:57:41 -08001276 */
Joe Onorato46439ce2010-11-19 13:56:21 -08001277 public static class Builder {
Daniel Sandler602ad1c2012-06-12 16:06:27 -04001278 private static final int MAX_ACTION_BUTTONS = 3;
Daniel Sandler8680bf82012-05-15 16:52:52 -04001279
Joe Onorato46439ce2010-11-19 13:56:21 -08001280 private Context mContext;
1281
1282 private long mWhen;
1283 private int mSmallIcon;
1284 private int mSmallIconLevel;
Joe Onorato8595a3d2010-11-19 18:12:07 -08001285 private int mNumber;
Joe Onorato46439ce2010-11-19 13:56:21 -08001286 private CharSequence mContentTitle;
1287 private CharSequence mContentText;
1288 private CharSequence mContentInfo;
Daniel Sandlerf3b73432012-03-27 15:01:25 -04001289 private CharSequence mSubText;
Joe Onorato46439ce2010-11-19 13:56:21 -08001290 private PendingIntent mContentIntent;
1291 private RemoteViews mContentView;
1292 private PendingIntent mDeleteIntent;
1293 private PendingIntent mFullScreenIntent;
1294 private CharSequence mTickerText;
1295 private RemoteViews mTickerView;
1296 private Bitmap mLargeIcon;
1297 private Uri mSound;
1298 private int mAudioStreamType;
1299 private long[] mVibrate;
1300 private int mLedArgb;
1301 private int mLedOnMs;
1302 private int mLedOffMs;
1303 private int mDefaults;
1304 private int mFlags;
Jeff Sharkey1c400132011-08-05 14:50:13 -07001305 private int mProgressMax;
1306 private int mProgress;
1307 private boolean mProgressIndeterminate;
John Spurlockcf44a122014-03-24 11:02:36 -04001308 private String mCategory;
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001309 private Bundle mExtras;
1310 private int mPriority;
Daniel Sandler8680bf82012-05-15 16:52:52 -04001311 private ArrayList<Action> mActions = new ArrayList<Action>(MAX_ACTION_BUTTONS);
Daniel Sandlera2985ed2012-04-03 16:42:00 -04001312 private boolean mUseChronometer;
Chris Wrenfbd96ba2012-05-01 12:03:58 -04001313 private Style mStyle;
Daniel Sandler0c890492012-09-12 17:23:10 -07001314 private boolean mShowWhen = true;
Joe Onorato46439ce2010-11-19 13:56:21 -08001315
Joe Onoratocb109a02011-01-18 17:57:41 -08001316 /**
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001317 * Constructs a new Builder with the defaults:
Joe Onoratocb109a02011-01-18 17:57:41 -08001318 *
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001319
1320 * <table>
1321 * <tr><th align=right>priority</th>
1322 * <td>{@link #PRIORITY_DEFAULT}</td></tr>
1323 * <tr><th align=right>when</th>
1324 * <td>now ({@link System#currentTimeMillis()})</td></tr>
1325 * <tr><th align=right>audio stream</th>
1326 * <td>{@link #STREAM_DEFAULT}</td></tr>
1327 * </table>
Joe Onoratocb109a02011-01-18 17:57:41 -08001328 *
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001329
1330 * @param context
1331 * A {@link Context} that will be used by the Builder to construct the
1332 * RemoteViews. The Context will not be held past the lifetime of this Builder
1333 * object.
Joe Onoratocb109a02011-01-18 17:57:41 -08001334 */
Joe Onorato46439ce2010-11-19 13:56:21 -08001335 public Builder(Context context) {
1336 mContext = context;
Andy Stadler110988c2010-12-03 14:29:16 -08001337
1338 // Set defaults to match the defaults of a Notification
Joe Onorato46439ce2010-11-19 13:56:21 -08001339 mWhen = System.currentTimeMillis();
Andy Stadler110988c2010-12-03 14:29:16 -08001340 mAudioStreamType = STREAM_DEFAULT;
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001341 mPriority = PRIORITY_DEFAULT;
Joe Onorato46439ce2010-11-19 13:56:21 -08001342 }
1343
Joe Onoratocb109a02011-01-18 17:57:41 -08001344 /**
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001345 * Add a timestamp pertaining to the notification (usually the time the event occurred).
Daniel Sandler0c890492012-09-12 17:23:10 -07001346 * It will be shown in the notification content view by default; use
1347 * {@link Builder#setShowWhen(boolean) setShowWhen} to control this.
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001348 *
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001349 * @see Notification#when
Joe Onoratocb109a02011-01-18 17:57:41 -08001350 */
Joe Onorato46439ce2010-11-19 13:56:21 -08001351 public Builder setWhen(long when) {
1352 mWhen = when;
1353 return this;
1354 }
1355
Joe Onoratocb109a02011-01-18 17:57:41 -08001356 /**
Daniel Sandler0c890492012-09-12 17:23:10 -07001357 * Control whether the timestamp set with {@link Builder#setWhen(long) setWhen} is shown
1358 * in the content view.
1359 */
1360 public Builder setShowWhen(boolean show) {
1361 mShowWhen = show;
1362 return this;
1363 }
1364
1365 /**
Daniel Sandlerd33b8032012-05-10 11:41:48 -04001366 * Show the {@link Notification#when} field as a stopwatch.
Joe Malin8d40d042012-11-05 11:36:40 -08001367 *
1368 * Instead of presenting <code>when</code> as a timestamp, the notification will show an
Daniel Sandlerd33b8032012-05-10 11:41:48 -04001369 * automatically updating display of the minutes and seconds since <code>when</code>.
Daniel Sandlera2985ed2012-04-03 16:42:00 -04001370 *
Daniel Sandlerd33b8032012-05-10 11:41:48 -04001371 * Useful when showing an elapsed time (like an ongoing phone call).
1372 *
1373 * @see android.widget.Chronometer
Daniel Sandlera2985ed2012-04-03 16:42:00 -04001374 * @see Notification#when
1375 */
1376 public Builder setUsesChronometer(boolean b) {
1377 mUseChronometer = b;
1378 return this;
1379 }
1380
1381 /**
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001382 * Set the small icon resource, which will be used to represent the notification in the
1383 * status bar.
Joe Onoratocb109a02011-01-18 17:57:41 -08001384 *
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001385
1386 * The platform template for the expanded view will draw this icon in the left, unless a
1387 * {@link #setLargeIcon(Bitmap) large icon} has also been specified, in which case the small
1388 * icon will be moved to the right-hand side.
1389 *
1390
1391 * @param icon
1392 * A resource ID in the application's package of the drawable to use.
1393 * @see Notification#icon
Joe Onoratocb109a02011-01-18 17:57:41 -08001394 */
Joe Onorato46439ce2010-11-19 13:56:21 -08001395 public Builder setSmallIcon(int icon) {
1396 mSmallIcon = icon;
1397 return this;
1398 }
1399
Joe Onoratocb109a02011-01-18 17:57:41 -08001400 /**
1401 * A variant of {@link #setSmallIcon(int) setSmallIcon(int)} that takes an additional
1402 * level parameter for when the icon is a {@link android.graphics.drawable.LevelListDrawable
1403 * LevelListDrawable}.
1404 *
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001405 * @param icon A resource ID in the application's package of the drawable to use.
Joe Onoratocb109a02011-01-18 17:57:41 -08001406 * @param level The level to use for the icon.
1407 *
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001408 * @see Notification#icon
1409 * @see Notification#iconLevel
Joe Onoratocb109a02011-01-18 17:57:41 -08001410 */
Joe Onorato46439ce2010-11-19 13:56:21 -08001411 public Builder setSmallIcon(int icon, int level) {
1412 mSmallIcon = icon;
1413 mSmallIconLevel = level;
1414 return this;
1415 }
1416
Joe Onoratocb109a02011-01-18 17:57:41 -08001417 /**
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001418 * Set the first line of text in the platform notification template.
Joe Onoratocb109a02011-01-18 17:57:41 -08001419 */
Joe Onorato46439ce2010-11-19 13:56:21 -08001420 public Builder setContentTitle(CharSequence title) {
Daniel Sandlerdcbaf662013-04-26 16:23:09 -04001421 mContentTitle = safeCharSequence(title);
Joe Onorato46439ce2010-11-19 13:56:21 -08001422 return this;
1423 }
1424
Joe Onoratocb109a02011-01-18 17:57:41 -08001425 /**
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001426 * Set the second line of text in the platform notification template.
Joe Onoratocb109a02011-01-18 17:57:41 -08001427 */
Joe Onorato46439ce2010-11-19 13:56:21 -08001428 public Builder setContentText(CharSequence text) {
Daniel Sandlerdcbaf662013-04-26 16:23:09 -04001429 mContentText = safeCharSequence(text);
Joe Onorato46439ce2010-11-19 13:56:21 -08001430 return this;
1431 }
1432
Joe Onoratocb109a02011-01-18 17:57:41 -08001433 /**
Joe Malin8d40d042012-11-05 11:36:40 -08001434 * Set the third line of text in the platform notification template.
Daniel Sandlerdcbaf662013-04-26 16:23:09 -04001435 * Don't use if you're also using {@link #setProgress(int, int, boolean)}; they occupy the
1436 * same location in the standard template.
Daniel Sandlerf3b73432012-03-27 15:01:25 -04001437 */
1438 public Builder setSubText(CharSequence text) {
Daniel Sandlerdcbaf662013-04-26 16:23:09 -04001439 mSubText = safeCharSequence(text);
Daniel Sandlerf3b73432012-03-27 15:01:25 -04001440 return this;
1441 }
1442
1443 /**
Joe Onoratocb109a02011-01-18 17:57:41 -08001444 * Set the large number at the right-hand side of the notification. This is
1445 * equivalent to setContentInfo, although it might show the number in a different
1446 * font size for readability.
1447 */
Joe Onorato8595a3d2010-11-19 18:12:07 -08001448 public Builder setNumber(int number) {
1449 mNumber = number;
1450 return this;
1451 }
1452
Joe Onoratocb109a02011-01-18 17:57:41 -08001453 /**
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001454 * A small piece of additional information pertaining to this notification.
1455 *
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001456 * The platform template will draw this on the last line of the notification, at the far
1457 * right (to the right of a smallIcon if it has been placed there).
Joe Onoratocb109a02011-01-18 17:57:41 -08001458 */
Joe Onorato46439ce2010-11-19 13:56:21 -08001459 public Builder setContentInfo(CharSequence info) {
Daniel Sandlerdcbaf662013-04-26 16:23:09 -04001460 mContentInfo = safeCharSequence(info);
Joe Onorato46439ce2010-11-19 13:56:21 -08001461 return this;
1462 }
1463
Joe Onoratocb109a02011-01-18 17:57:41 -08001464 /**
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001465 * Set the progress this notification represents.
1466 *
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001467 * The platform template will represent this using a {@link ProgressBar}.
Jeff Sharkey1c400132011-08-05 14:50:13 -07001468 */
1469 public Builder setProgress(int max, int progress, boolean indeterminate) {
1470 mProgressMax = max;
1471 mProgress = progress;
1472 mProgressIndeterminate = indeterminate;
1473 return this;
1474 }
1475
1476 /**
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001477 * Supply a custom RemoteViews to use instead of the platform template.
1478 *
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001479 * @see Notification#contentView
Joe Onoratocb109a02011-01-18 17:57:41 -08001480 */
Joe Onorato46439ce2010-11-19 13:56:21 -08001481 public Builder setContent(RemoteViews views) {
1482 mContentView = views;
1483 return this;
1484 }
1485
Joe Onoratocb109a02011-01-18 17:57:41 -08001486 /**
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001487 * Supply a {@link PendingIntent} to be sent when the notification is clicked.
1488 *
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001489 * As of {@link android.os.Build.VERSION_CODES#HONEYCOMB}, if this field is unset and you
1490 * have specified a custom RemoteViews with {@link #setContent(RemoteViews)}, you can use
1491 * {@link RemoteViews#setOnClickPendingIntent RemoteViews.setOnClickPendingIntent(int,PendingIntent)}
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001492 * to assign PendingIntents to individual views in that custom layout (i.e., to create
Daniel Sandlerf3b73432012-03-27 15:01:25 -04001493 * clickable buttons inside the notification view).
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001494 *
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001495 * @see Notification#contentIntent Notification.contentIntent
Joe Onoratocb109a02011-01-18 17:57:41 -08001496 */
Joe Onorato46439ce2010-11-19 13:56:21 -08001497 public Builder setContentIntent(PendingIntent intent) {
1498 mContentIntent = intent;
1499 return this;
1500 }
1501
Joe Onoratocb109a02011-01-18 17:57:41 -08001502 /**
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001503 * Supply a {@link PendingIntent} to send when the notification is cleared explicitly by the user.
1504 *
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001505 * @see Notification#deleteIntent
Joe Onoratocb109a02011-01-18 17:57:41 -08001506 */
Joe Onorato46439ce2010-11-19 13:56:21 -08001507 public Builder setDeleteIntent(PendingIntent intent) {
1508 mDeleteIntent = intent;
1509 return this;
1510 }
1511
Joe Onoratocb109a02011-01-18 17:57:41 -08001512 /**
1513 * An intent to launch instead of posting the notification to the status bar.
1514 * Only for use with extremely high-priority notifications demanding the user's
1515 * <strong>immediate</strong> attention, such as an incoming phone call or
1516 * alarm clock that the user has explicitly set to a particular time.
1517 * If this facility is used for something else, please give the user an option
1518 * to turn it off and use a normal notification, as this can be extremely
1519 * disruptive.
1520 *
1521 * @param intent The pending intent to launch.
1522 * @param highPriority Passing true will cause this notification to be sent
1523 * even if other notifications are suppressed.
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001524 *
1525 * @see Notification#fullScreenIntent
Joe Onoratocb109a02011-01-18 17:57:41 -08001526 */
Joe Onorato46439ce2010-11-19 13:56:21 -08001527 public Builder setFullScreenIntent(PendingIntent intent, boolean highPriority) {
1528 mFullScreenIntent = intent;
1529 setFlag(FLAG_HIGH_PRIORITY, highPriority);
1530 return this;
1531 }
1532
Joe Onoratocb109a02011-01-18 17:57:41 -08001533 /**
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001534 * Set the "ticker" text which is displayed in the status bar when the notification first
Joe Onoratocb109a02011-01-18 17:57:41 -08001535 * arrives.
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001536 *
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001537 * @see Notification#tickerText
Joe Onoratocb109a02011-01-18 17:57:41 -08001538 */
Joe Onorato46439ce2010-11-19 13:56:21 -08001539 public Builder setTicker(CharSequence tickerText) {
Daniel Sandlerdcbaf662013-04-26 16:23:09 -04001540 mTickerText = safeCharSequence(tickerText);
Joe Onorato46439ce2010-11-19 13:56:21 -08001541 return this;
1542 }
1543
Joe Onoratocb109a02011-01-18 17:57:41 -08001544 /**
1545 * Set the text that is displayed in the status bar when the notification first
1546 * arrives, and also a RemoteViews object that may be displayed instead on some
1547 * devices.
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001548 *
1549 * @see Notification#tickerText
1550 * @see Notification#tickerView
Joe Onoratocb109a02011-01-18 17:57:41 -08001551 */
Joe Onorato46439ce2010-11-19 13:56:21 -08001552 public Builder setTicker(CharSequence tickerText, RemoteViews views) {
Daniel Sandlerdcbaf662013-04-26 16:23:09 -04001553 mTickerText = safeCharSequence(tickerText);
Joe Onorato46439ce2010-11-19 13:56:21 -08001554 mTickerView = views;
1555 return this;
1556 }
1557
Joe Onoratocb109a02011-01-18 17:57:41 -08001558 /**
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001559 * Add a large icon to the notification (and the ticker on some devices).
1560 *
1561 * In the platform template, this image will be shown on the left of the notification view
1562 * in place of the {@link #setSmallIcon(int) small icon} (which will move to the right side).
1563 *
1564 * @see Notification#largeIcon
Joe Onoratocb109a02011-01-18 17:57:41 -08001565 */
Joe Onorato46439ce2010-11-19 13:56:21 -08001566 public Builder setLargeIcon(Bitmap icon) {
1567 mLargeIcon = icon;
1568 return this;
1569 }
1570
Joe Onoratocb109a02011-01-18 17:57:41 -08001571 /**
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001572 * Set the sound to play.
1573 *
1574 * It will be played on the {@link #STREAM_DEFAULT default stream} for notifications.
1575 *
1576 * @see Notification#sound
Joe Onoratocb109a02011-01-18 17:57:41 -08001577 */
Joe Onorato52f80cd2010-11-21 15:34:48 -08001578 public Builder setSound(Uri sound) {
1579 mSound = sound;
1580 mAudioStreamType = STREAM_DEFAULT;
1581 return this;
1582 }
1583
Joe Onoratocb109a02011-01-18 17:57:41 -08001584 /**
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001585 * Set the sound to play, along with a specific stream on which to play it.
Joe Onoratocb109a02011-01-18 17:57:41 -08001586 *
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001587 * See {@link android.media.AudioManager} for the <code>STREAM_</code> constants.
1588 *
1589 * @see Notification#sound
Joe Onoratocb109a02011-01-18 17:57:41 -08001590 */
Joe Onorato46439ce2010-11-19 13:56:21 -08001591 public Builder setSound(Uri sound, int streamType) {
1592 mSound = sound;
1593 mAudioStreamType = streamType;
1594 return this;
1595 }
1596
Joe Onoratocb109a02011-01-18 17:57:41 -08001597 /**
1598 * Set the vibration pattern to use.
1599 *
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001600
1601 * See {@link android.os.Vibrator#vibrate(long[], int)} for a discussion of the
1602 * <code>pattern</code> parameter.
1603 *
1604
1605 * @see Notification#vibrate
Joe Onoratocb109a02011-01-18 17:57:41 -08001606 */
Joe Onorato46439ce2010-11-19 13:56:21 -08001607 public Builder setVibrate(long[] pattern) {
1608 mVibrate = pattern;
1609 return this;
1610 }
1611
Joe Onoratocb109a02011-01-18 17:57:41 -08001612 /**
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001613 * Set the desired color for the indicator LED on the device, as well as the
1614 * blink duty cycle (specified in milliseconds).
1615 *
1616
1617 * Not all devices will honor all (or even any) of these values.
1618 *
1619
1620 * @see Notification#ledARGB
1621 * @see Notification#ledOnMS
1622 * @see Notification#ledOffMS
Joe Onoratocb109a02011-01-18 17:57:41 -08001623 */
Joe Onorato46439ce2010-11-19 13:56:21 -08001624 public Builder setLights(int argb, int onMs, int offMs) {
1625 mLedArgb = argb;
1626 mLedOnMs = onMs;
1627 mLedOffMs = offMs;
Joe Onorato46439ce2010-11-19 13:56:21 -08001628 return this;
1629 }
1630
Joe Onoratocb109a02011-01-18 17:57:41 -08001631 /**
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001632 * Set whether this is an "ongoing" notification.
Joe Onoratocb109a02011-01-18 17:57:41 -08001633 *
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001634
1635 * Ongoing notifications cannot be dismissed by the user, so your application or service
1636 * must take care of canceling them.
1637 *
1638
1639 * They are typically used to indicate a background task that the user is actively engaged
1640 * with (e.g., playing music) or is pending in some way and therefore occupying the device
1641 * (e.g., a file download, sync operation, active network connection).
1642 *
1643
1644 * @see Notification#FLAG_ONGOING_EVENT
1645 * @see Service#setForeground(boolean)
Joe Onoratocb109a02011-01-18 17:57:41 -08001646 */
Joe Onorato46439ce2010-11-19 13:56:21 -08001647 public Builder setOngoing(boolean ongoing) {
1648 setFlag(FLAG_ONGOING_EVENT, ongoing);
1649 return this;
1650 }
1651
Joe Onoratocb109a02011-01-18 17:57:41 -08001652 /**
1653 * Set this flag if you would only like the sound, vibrate
1654 * and ticker to be played if the notification is not already showing.
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001655 *
1656 * @see Notification#FLAG_ONLY_ALERT_ONCE
Joe Onoratocb109a02011-01-18 17:57:41 -08001657 */
Joe Onorato46439ce2010-11-19 13:56:21 -08001658 public Builder setOnlyAlertOnce(boolean onlyAlertOnce) {
1659 setFlag(FLAG_ONLY_ALERT_ONCE, onlyAlertOnce);
1660 return this;
1661 }
1662
Joe Onoratocb109a02011-01-18 17:57:41 -08001663 /**
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001664 * Make this notification automatically dismissed when the user touches it. The
1665 * PendingIntent set with {@link #setDeleteIntent} will be sent when this happens.
1666 *
1667 * @see Notification#FLAG_AUTO_CANCEL
Joe Onoratocb109a02011-01-18 17:57:41 -08001668 */
Joe Onorato46439ce2010-11-19 13:56:21 -08001669 public Builder setAutoCancel(boolean autoCancel) {
Joe Onorato281d83f2011-01-04 17:13:10 -08001670 setFlag(FLAG_AUTO_CANCEL, autoCancel);
Joe Onorato46439ce2010-11-19 13:56:21 -08001671 return this;
1672 }
1673
Joe Onoratocb109a02011-01-18 17:57:41 -08001674 /**
Griff Hazendfcb0802014-02-11 12:00:00 -08001675 * Set whether or not this notification should not bridge to other devices.
1676 *
1677 * <p>Some notifications can be bridged to other devices for remote display.
1678 * This hint can be set to recommend this notification not be bridged.
1679 */
1680 public Builder setLocalOnly(boolean localOnly) {
1681 setFlag(FLAG_LOCAL_ONLY, localOnly);
1682 return this;
1683 }
1684
1685 /**
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001686 * Set which notification properties will be inherited from system defaults.
Joe Onoratocb109a02011-01-18 17:57:41 -08001687 * <p>
1688 * The value should be one or more of the following fields combined with
1689 * bitwise-or:
1690 * {@link #DEFAULT_SOUND}, {@link #DEFAULT_VIBRATE}, {@link #DEFAULT_LIGHTS}.
1691 * <p>
1692 * For all default values, use {@link #DEFAULT_ALL}.
1693 */
Joe Onorato46439ce2010-11-19 13:56:21 -08001694 public Builder setDefaults(int defaults) {
1695 mDefaults = defaults;
1696 return this;
1697 }
1698
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001699 /**
1700 * Set the priority of this notification.
1701 *
1702 * @see Notification#priority
1703 */
1704 public Builder setPriority(int pri) {
1705 mPriority = pri;
1706 return this;
1707 }
Joe Malin8d40d042012-11-05 11:36:40 -08001708
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001709 /**
John Spurlockcf44a122014-03-24 11:02:36 -04001710 * Set the notification category.
Joe Malin8d40d042012-11-05 11:36:40 -08001711 *
John Spurlockcf44a122014-03-24 11:02:36 -04001712 * @see Notification#category
Griff Hazened0c87e2014-05-05 15:15:12 -07001713 * @hide
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001714 */
John Spurlockcf44a122014-03-24 11:02:36 -04001715 public Builder setCategory(String category) {
1716 mCategory = category;
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001717 return this;
1718 }
1719
1720 /**
Griff Hazen720042b2014-02-24 15:46:56 -08001721 * Merge additional metadata into this notification.
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001722 *
Griff Hazen720042b2014-02-24 15:46:56 -08001723 * <p>Values within the Bundle will replace existing extras values in this Builder.
1724 *
1725 * @see Notification#extras
1726 */
Griff Hazen959591e2014-05-15 22:26:18 -07001727 public Builder addExtras(Bundle extras) {
1728 if (extras != null) {
1729 if (mExtras == null) {
1730 mExtras = new Bundle(extras);
1731 } else {
1732 mExtras.putAll(extras);
1733 }
Griff Hazen720042b2014-02-24 15:46:56 -08001734 }
1735 return this;
1736 }
1737
1738 /**
1739 * Set metadata for this notification.
1740 *
1741 * <p>A reference to the Bundle is held for the lifetime of this Builder, and the Bundle's
Chris Wrenfbd96ba2012-05-01 12:03:58 -04001742 * current contents are copied into the Notification each time {@link #build()} is
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001743 * called.
1744 *
Griff Hazen720042b2014-02-24 15:46:56 -08001745 * <p>Replaces any existing extras values with those from the provided Bundle.
1746 * Use {@link #addExtras} to merge in metadata instead.
1747 *
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001748 * @see Notification#extras
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001749 */
Griff Hazen959591e2014-05-15 22:26:18 -07001750 public Builder setExtras(Bundle extras) {
1751 mExtras = extras;
Daniel Sandler2561b0b2012-02-13 21:04:12 -05001752 return this;
1753 }
1754
Daniel Sandlera0a938c2012-03-15 08:42:37 -04001755 /**
Griff Hazen720042b2014-02-24 15:46:56 -08001756 * Get the current metadata Bundle used by this notification Builder.
1757 *
1758 * <p>The returned Bundle is shared with this Builder.
1759 *
1760 * <p>The current contents of this Bundle are copied into the Notification each time
1761 * {@link #build()} is called.
1762 *
1763 * @see Notification#extras
1764 */
1765 public Bundle getExtras() {
1766 if (mExtras == null) {
1767 mExtras = new Bundle();
1768 }
1769 return mExtras;
1770 }
1771
1772 /**
Daniel Sandlera0a938c2012-03-15 08:42:37 -04001773 * Add an action to this notification. Actions are typically displayed by
1774 * the system as a button adjacent to the notification content.
Daniel Sandlercf1d39b2013-09-23 13:35:35 -04001775 * <p>
1776 * Every action must have an icon (32dp square and matching the
1777 * <a href="{@docRoot}design/style/iconography.html#action-bar">Holo
1778 * Dark action bar</a> visual style), a textual label, and a {@link PendingIntent}.
1779 * <p>
1780 * A notification in its expanded form can display up to 3 actions, from left to right in
1781 * the order they were added. Actions will not be displayed when the notification is
1782 * collapsed, however, so be sure that any essential functions may be accessed by the user
1783 * in some other way (for example, in the Activity pointed to by {@link #contentIntent}).
Daniel Sandlera0a938c2012-03-15 08:42:37 -04001784 *
1785 * @param icon Resource ID of a drawable that represents the action.
1786 * @param title Text describing the action.
1787 * @param intent PendingIntent to be fired when the action is invoked.
1788 */
1789 public Builder addAction(int icon, CharSequence title, PendingIntent intent) {
Daniel Sandlerdcbaf662013-04-26 16:23:09 -04001790 mActions.add(new Action(icon, safeCharSequence(title), intent));
Daniel Sandlera0a938c2012-03-15 08:42:37 -04001791 return this;
1792 }
1793
Chris Wrenfbd96ba2012-05-01 12:03:58 -04001794 /**
Griff Hazen959591e2014-05-15 22:26:18 -07001795 * Add an action to this notification. Actions are typically displayed by
1796 * the system as a button adjacent to the notification content.
1797 * <p>
1798 * Every action must have an icon (32dp square and matching the
1799 * <a href="{@docRoot}design/style/iconography.html#action-bar">Holo
1800 * Dark action bar</a> visual style), a textual label, and a {@link PendingIntent}.
1801 * <p>
1802 * A notification in its expanded form can display up to 3 actions, from left to right in
1803 * the order they were added. Actions will not be displayed when the notification is
1804 * collapsed, however, so be sure that any essential functions may be accessed by the user
1805 * in some other way (for example, in the Activity pointed to by {@link #contentIntent}).
1806 *
1807 * @param action The action to add.
1808 */
1809 public Builder addAction(Action action) {
1810 mActions.add(action);
1811 return this;
1812 }
1813
1814 /**
Chris Wrenfbd96ba2012-05-01 12:03:58 -04001815 * Add a rich notification style to be applied at build time.
1816 *
1817 * @param style Object responsible for modifying the notification style.
1818 */
1819 public Builder setStyle(Style style) {
1820 if (mStyle != style) {
1821 mStyle = style;
Daniel Sandlerc08dea22012-06-28 08:35:24 -07001822 if (mStyle != null) {
1823 mStyle.setBuilder(this);
1824 }
Chris Wrenfbd96ba2012-05-01 12:03:58 -04001825 }
1826 return this;
1827 }
1828
Joe Onorato46439ce2010-11-19 13:56:21 -08001829 private void setFlag(int mask, boolean value) {
1830 if (value) {
1831 mFlags |= mask;
1832 } else {
1833 mFlags &= ~mask;
1834 }
1835 }
1836
Daniel Sandler6387d2f2012-05-22 13:44:09 -04001837 private RemoteViews applyStandardTemplate(int resId, boolean fitIn1U) {
Joe Onorato561d3852010-11-20 18:09:34 -08001838 RemoteViews contentView = new RemoteViews(mContext.getPackageName(), resId);
Daniel Sandler9f7936a2012-05-21 16:14:28 -04001839 boolean showLine3 = false;
1840 boolean showLine2 = false;
Daniel Sandlerf3b73432012-03-27 15:01:25 -04001841 int smallIconImageViewId = R.id.icon;
1842 if (mLargeIcon != null) {
1843 contentView.setImageViewBitmap(R.id.icon, mLargeIcon);
1844 smallIconImageViewId = R.id.right_icon;
1845 }
Daniel Sandlere95658c2012-05-10 00:33:54 -04001846 if (mPriority < PRIORITY_LOW) {
1847 contentView.setInt(R.id.icon,
1848 "setBackgroundResource", R.drawable.notification_template_icon_low_bg);
1849 contentView.setInt(R.id.status_bar_latest_event_content,
1850 "setBackgroundResource", R.drawable.notification_bg_low);
1851 }
Joe Onorato561d3852010-11-20 18:09:34 -08001852 if (mSmallIcon != 0) {
Daniel Sandlerf3b73432012-03-27 15:01:25 -04001853 contentView.setImageViewResource(smallIconImageViewId, mSmallIcon);
1854 contentView.setViewVisibility(smallIconImageViewId, View.VISIBLE);
Jeff Sharkey1c400132011-08-05 14:50:13 -07001855 } else {
Daniel Sandlerf3b73432012-03-27 15:01:25 -04001856 contentView.setViewVisibility(smallIconImageViewId, View.GONE);
Joe Onorato561d3852010-11-20 18:09:34 -08001857 }
1858 if (mContentTitle != null) {
1859 contentView.setTextViewText(R.id.title, mContentTitle);
1860 }
1861 if (mContentText != null) {
Daniel Sandler9f7936a2012-05-21 16:14:28 -04001862 contentView.setTextViewText(R.id.text, mContentText);
1863 showLine3 = true;
Joe Onorato561d3852010-11-20 18:09:34 -08001864 }
1865 if (mContentInfo != null) {
1866 contentView.setTextViewText(R.id.info, mContentInfo);
Jeff Sharkey1c400132011-08-05 14:50:13 -07001867 contentView.setViewVisibility(R.id.info, View.VISIBLE);
Daniel Sandler9f7936a2012-05-21 16:14:28 -04001868 showLine3 = true;
Joe Onorato561d3852010-11-20 18:09:34 -08001869 } else if (mNumber > 0) {
Daniel Sandlerebce0112011-06-16 16:44:51 -04001870 final int tooBig = mContext.getResources().getInteger(
1871 R.integer.status_bar_notification_info_maxnum);
1872 if (mNumber > tooBig) {
1873 contentView.setTextViewText(R.id.info, mContext.getResources().getString(
1874 R.string.status_bar_notification_info_overflow));
Joe Onorato059a2f82011-01-04 10:27:01 -08001875 } else {
1876 NumberFormat f = NumberFormat.getIntegerInstance();
1877 contentView.setTextViewText(R.id.info, f.format(mNumber));
1878 }
Jeff Sharkey1c400132011-08-05 14:50:13 -07001879 contentView.setViewVisibility(R.id.info, View.VISIBLE);
Daniel Sandler9f7936a2012-05-21 16:14:28 -04001880 showLine3 = true;
Joe Onorato561d3852010-11-20 18:09:34 -08001881 } else {
1882 contentView.setViewVisibility(R.id.info, View.GONE);
1883 }
Daniel Sandlerf3b73432012-03-27 15:01:25 -04001884
Daniel Sandler9f7936a2012-05-21 16:14:28 -04001885 // Need to show three lines?
Daniel Sandlerf3b73432012-03-27 15:01:25 -04001886 if (mSubText != null) {
1887 contentView.setTextViewText(R.id.text, mSubText);
Daniel Sandler9f7936a2012-05-21 16:14:28 -04001888 if (mContentText != null) {
1889 contentView.setTextViewText(R.id.text2, mContentText);
Daniel Sandler9f7936a2012-05-21 16:14:28 -04001890 contentView.setViewVisibility(R.id.text2, View.VISIBLE);
1891 showLine2 = true;
1892 } else {
1893 contentView.setViewVisibility(R.id.text2, View.GONE);
1894 }
Jeff Sharkey1c400132011-08-05 14:50:13 -07001895 } else {
Daniel Sandlerf3b73432012-03-27 15:01:25 -04001896 contentView.setViewVisibility(R.id.text2, View.GONE);
1897 if (mProgressMax != 0 || mProgressIndeterminate) {
1898 contentView.setProgressBar(
1899 R.id.progress, mProgressMax, mProgress, mProgressIndeterminate);
1900 contentView.setViewVisibility(R.id.progress, View.VISIBLE);
Daniel Sandler9f7936a2012-05-21 16:14:28 -04001901 showLine2 = true;
Daniel Sandlerf3b73432012-03-27 15:01:25 -04001902 } else {
1903 contentView.setViewVisibility(R.id.progress, View.GONE);
1904 }
Jeff Sharkey1c400132011-08-05 14:50:13 -07001905 }
Daniel Sandler9f7936a2012-05-21 16:14:28 -04001906 if (showLine2) {
Daniel Sandler6387d2f2012-05-22 13:44:09 -04001907 if (fitIn1U) {
1908 // need to shrink all the type to make sure everything fits
1909 final Resources res = mContext.getResources();
1910 final float subTextSize = res.getDimensionPixelSize(
1911 R.dimen.notification_subtext_size);
1912 contentView.setTextViewTextSize(R.id.text, TypedValue.COMPLEX_UNIT_PX, subTextSize);
1913 }
Daniel Sandler9f7936a2012-05-21 16:14:28 -04001914 // vertical centering
1915 contentView.setViewPadding(R.id.line1, 0, 0, 0, 0);
1916 }
1917
Daniel Sandler0c890492012-09-12 17:23:10 -07001918 if (mWhen != 0 && mShowWhen) {
Daniel Sandlera2985ed2012-04-03 16:42:00 -04001919 if (mUseChronometer) {
1920 contentView.setViewVisibility(R.id.chronometer, View.VISIBLE);
1921 contentView.setLong(R.id.chronometer, "setBase",
1922 mWhen + (SystemClock.elapsedRealtime() - System.currentTimeMillis()));
1923 contentView.setBoolean(R.id.chronometer, "setStarted", true);
1924 } else {
1925 contentView.setViewVisibility(R.id.time, View.VISIBLE);
1926 contentView.setLong(R.id.time, "setTime", mWhen);
1927 }
Daniel Sandler0c890492012-09-12 17:23:10 -07001928 } else {
1929 contentView.setViewVisibility(R.id.time, View.GONE);
Joe Onorato561d3852010-11-20 18:09:34 -08001930 }
Daniel Sandler0c890492012-09-12 17:23:10 -07001931
Daniel Sandler9f7936a2012-05-21 16:14:28 -04001932 contentView.setViewVisibility(R.id.line3, showLine3 ? View.VISIBLE : View.GONE);
Daniel Sandler6387d2f2012-05-22 13:44:09 -04001933 contentView.setViewVisibility(R.id.overflow_divider, showLine3 ? View.VISIBLE : View.GONE);
Joe Onorato561d3852010-11-20 18:09:34 -08001934 return contentView;
1935 }
1936
Daniel Sandler96fd7c12012-03-30 16:37:36 -04001937 private RemoteViews applyStandardTemplateWithActions(int layoutId) {
Daniel Sandler6387d2f2012-05-22 13:44:09 -04001938 RemoteViews big = applyStandardTemplate(layoutId, false);
Daniel Sandler96fd7c12012-03-30 16:37:36 -04001939
1940 int N = mActions.size();
1941 if (N > 0) {
Chris Wrend6297db2012-05-03 16:20:13 -04001942 // Log.d("Notification", "has actions: " + mContentText);
Daniel Sandler96fd7c12012-03-30 16:37:36 -04001943 big.setViewVisibility(R.id.actions, View.VISIBLE);
Daniel Sandler6387d2f2012-05-22 13:44:09 -04001944 big.setViewVisibility(R.id.action_divider, View.VISIBLE);
Daniel Sandler8680bf82012-05-15 16:52:52 -04001945 if (N>MAX_ACTION_BUTTONS) N=MAX_ACTION_BUTTONS;
Chris Wren2c22eb02012-05-08 09:49:13 -04001946 big.removeAllViews(R.id.actions);
Daniel Sandler96fd7c12012-03-30 16:37:36 -04001947 for (int i=0; i<N; i++) {
1948 final RemoteViews button = generateActionButton(mActions.get(i));
Chris Wrend6297db2012-05-03 16:20:13 -04001949 //Log.d("Notification", "adding action " + i + ": " + mActions.get(i).title);
Daniel Sandler96fd7c12012-03-30 16:37:36 -04001950 big.addView(R.id.actions, button);
1951 }
1952 }
1953 return big;
1954 }
1955
Joe Onorato46439ce2010-11-19 13:56:21 -08001956 private RemoteViews makeContentView() {
1957 if (mContentView != null) {
1958 return mContentView;
1959 } else {
Daniel Sandler6387d2f2012-05-22 13:44:09 -04001960 return applyStandardTemplate(R.layout.notification_template_base, true); // no more special large_icon flavor
Joe Onorato46439ce2010-11-19 13:56:21 -08001961 }
1962 }
1963
1964 private RemoteViews makeTickerView() {
1965 if (mTickerView != null) {
1966 return mTickerView;
1967 } else {
Joe Onorato561d3852010-11-20 18:09:34 -08001968 if (mContentView == null) {
Daniel Sandlerf3b73432012-03-27 15:01:25 -04001969 return applyStandardTemplate(mLargeIcon == null
Joe Onorato561d3852010-11-20 18:09:34 -08001970 ? R.layout.status_bar_latest_event_ticker
Daniel Sandler6387d2f2012-05-22 13:44:09 -04001971 : R.layout.status_bar_latest_event_ticker_large_icon, true);
Joe Onorato561d3852010-11-20 18:09:34 -08001972 } else {
1973 return null;
1974 }
Joe Onorato46439ce2010-11-19 13:56:21 -08001975 }
1976 }
1977
Daniel Sandler96fd7c12012-03-30 16:37:36 -04001978 private RemoteViews makeBigContentView() {
1979 if (mActions.size() == 0) return null;
1980
Chris Wrenb023bf82012-04-23 16:05:42 -04001981 return applyStandardTemplateWithActions(R.layout.notification_template_big_base);
Daniel Sandler96fd7c12012-03-30 16:37:36 -04001982 }
1983
Daniel Sandler96fd7c12012-03-30 16:37:36 -04001984 private RemoteViews generateActionButton(Action action) {
Daniel Sandler8680bf82012-05-15 16:52:52 -04001985 final boolean tombstone = (action.actionIntent == null);
Joe Malin8d40d042012-11-05 11:36:40 -08001986 RemoteViews button = new RemoteViews(mContext.getPackageName(),
Daniel Sandler8680bf82012-05-15 16:52:52 -04001987 tombstone ? R.layout.notification_action_tombstone
1988 : R.layout.notification_action);
Chris Wrenbe63a952013-12-03 14:31:01 -05001989 button.setTextViewCompoundDrawablesRelative(R.id.action0, action.icon, 0, 0, 0);
Daniel Sandler96fd7c12012-03-30 16:37:36 -04001990 button.setTextViewText(R.id.action0, action.title);
Daniel Sandler8680bf82012-05-15 16:52:52 -04001991 if (!tombstone) {
Daniel Sandlere5518842012-05-10 16:20:40 -04001992 button.setOnClickPendingIntent(R.id.action0, action.actionIntent);
Daniel Sandlere5518842012-05-10 16:20:40 -04001993 }
Daniel Sandler96fd7c12012-03-30 16:37:36 -04001994 button.setContentDescription(R.id.action0, action.title);
1995 return button;
1996 }
1997
Joe Onoratocb109a02011-01-18 17:57:41 -08001998 /**
Chris Wrenfbd96ba2012-05-01 12:03:58 -04001999 * Apply the unstyled operations and return a new {@link Notification} object.
Daniel Sandlercf1d39b2013-09-23 13:35:35 -04002000 * @hide
Joe Onoratocb109a02011-01-18 17:57:41 -08002001 */
Daniel Sandlercf1d39b2013-09-23 13:35:35 -04002002 public Notification buildUnstyled() {
Joe Onorato46439ce2010-11-19 13:56:21 -08002003 Notification n = new Notification();
2004 n.when = mWhen;
2005 n.icon = mSmallIcon;
2006 n.iconLevel = mSmallIconLevel;
Joe Onorato8595a3d2010-11-19 18:12:07 -08002007 n.number = mNumber;
Joe Onorato46439ce2010-11-19 13:56:21 -08002008 n.contentView = makeContentView();
2009 n.contentIntent = mContentIntent;
2010 n.deleteIntent = mDeleteIntent;
2011 n.fullScreenIntent = mFullScreenIntent;
2012 n.tickerText = mTickerText;
2013 n.tickerView = makeTickerView();
2014 n.largeIcon = mLargeIcon;
2015 n.sound = mSound;
2016 n.audioStreamType = mAudioStreamType;
2017 n.vibrate = mVibrate;
2018 n.ledARGB = mLedArgb;
2019 n.ledOnMS = mLedOnMs;
2020 n.ledOffMS = mLedOffMs;
2021 n.defaults = mDefaults;
2022 n.flags = mFlags;
Daniel Sandler96fd7c12012-03-30 16:37:36 -04002023 n.bigContentView = makeBigContentView();
Daniel Sandler26c13432013-04-04 11:01:04 -04002024 if (mLedOnMs != 0 || mLedOffMs != 0) {
Joe Onorato8d0b6552010-11-22 16:09:29 -08002025 n.flags |= FLAG_SHOW_LIGHTS;
2026 }
2027 if ((mDefaults & DEFAULT_LIGHTS) != 0) {
2028 n.flags |= FLAG_SHOW_LIGHTS;
2029 }
John Spurlockcf44a122014-03-24 11:02:36 -04002030 n.category = mCategory;
Daniel Sandler2561b0b2012-02-13 21:04:12 -05002031 n.priority = mPriority;
Daniel Sandlera0a938c2012-03-15 08:42:37 -04002032 if (mActions.size() > 0) {
2033 n.actions = new Action[mActions.size()];
2034 mActions.toArray(n.actions);
2035 }
Daniel Sandlerbe6e7e02013-02-01 17:49:11 -05002036
Joe Onorato46439ce2010-11-19 13:56:21 -08002037 return n;
2038 }
Chris Wrenfbd96ba2012-05-01 12:03:58 -04002039
2040 /**
Daniel Sandlerf45564e2013-04-15 15:05:08 -04002041 * Capture, in the provided bundle, semantic information used in the construction of
2042 * this Notification object.
2043 * @hide
2044 */
Griff Hazen720042b2014-02-24 15:46:56 -08002045 public void populateExtras(Bundle extras) {
Daniel Sandlerf45564e2013-04-15 15:05:08 -04002046 // Store original information used in the construction of this object
2047 extras.putCharSequence(EXTRA_TITLE, mContentTitle);
2048 extras.putCharSequence(EXTRA_TEXT, mContentText);
2049 extras.putCharSequence(EXTRA_SUB_TEXT, mSubText);
2050 extras.putCharSequence(EXTRA_INFO_TEXT, mContentInfo);
2051 extras.putInt(EXTRA_SMALL_ICON, mSmallIcon);
2052 extras.putInt(EXTRA_PROGRESS, mProgress);
2053 extras.putInt(EXTRA_PROGRESS_MAX, mProgressMax);
2054 extras.putBoolean(EXTRA_PROGRESS_INDETERMINATE, mProgressIndeterminate);
2055 extras.putBoolean(EXTRA_SHOW_CHRONOMETER, mUseChronometer);
2056 extras.putBoolean(EXTRA_SHOW_WHEN, mShowWhen);
John Spurlockac08a472013-06-10 11:37:08 -04002057 if (mLargeIcon != null) {
2058 extras.putParcelable(EXTRA_LARGE_ICON, mLargeIcon);
2059 }
Daniel Sandlerf45564e2013-04-15 15:05:08 -04002060 }
2061
2062 /**
Chris Wrenfbd96ba2012-05-01 12:03:58 -04002063 * @deprecated Use {@link #build()} instead.
2064 */
2065 @Deprecated
2066 public Notification getNotification() {
2067 return build();
2068 }
2069
2070 /**
2071 * Combine all of the options that have been set and return a new {@link Notification}
2072 * object.
2073 */
2074 public Notification build() {
Daniel Sandlercf1d39b2013-09-23 13:35:35 -04002075 Notification n = buildUnstyled();
Daniel Sandlerf45564e2013-04-15 15:05:08 -04002076
Chris Wrenfbd96ba2012-05-01 12:03:58 -04002077 if (mStyle != null) {
Daniel Sandlercf1d39b2013-09-23 13:35:35 -04002078 n = mStyle.buildStyled(n);
Chris Wrenfbd96ba2012-05-01 12:03:58 -04002079 }
Daniel Sandlerf45564e2013-04-15 15:05:08 -04002080
2081 n.extras = mExtras != null ? new Bundle(mExtras) : new Bundle();
2082
Griff Hazen720042b2014-02-24 15:46:56 -08002083 populateExtras(n.extras);
Daniel Sandlerf45564e2013-04-15 15:05:08 -04002084 if (mStyle != null) {
2085 mStyle.addExtras(n.extras);
2086 }
2087
2088 return n;
Chris Wrenfbd96ba2012-05-01 12:03:58 -04002089 }
Daniel Sandlerbe6e7e02013-02-01 17:49:11 -05002090
2091 /**
2092 * Apply this Builder to an existing {@link Notification} object.
2093 *
2094 * @hide
2095 */
2096 public Notification buildInto(Notification n) {
Daniel Sandler1a497d32013-04-18 14:52:45 -04002097 build().cloneInto(n, true);
Daniel Sandlerbe6e7e02013-02-01 17:49:11 -05002098 return n;
2099 }
Chris Wrenfbd96ba2012-05-01 12:03:58 -04002100 }
2101
Chris Wrenfbd96ba2012-05-01 12:03:58 -04002102 /**
2103 * An object that can apply a rich notification style to a {@link Notification.Builder}
2104 * object.
2105 */
Griff Hazendfcb0802014-02-11 12:00:00 -08002106 public static abstract class Style {
Chris Wrend6297db2012-05-03 16:20:13 -04002107 private CharSequence mBigContentTitle;
2108 private CharSequence mSummaryText = null;
Daniel Sandler619738c2012-06-07 16:33:08 -04002109 private boolean mSummaryTextSet = false;
Chris Wrend6297db2012-05-03 16:20:13 -04002110
Chris Wrenfbd96ba2012-05-01 12:03:58 -04002111 protected Builder mBuilder;
2112
Chris Wrend6297db2012-05-03 16:20:13 -04002113 /**
2114 * Overrides ContentTitle in the big form of the template.
2115 * This defaults to the value passed to setContentTitle().
2116 */
2117 protected void internalSetBigContentTitle(CharSequence title) {
2118 mBigContentTitle = title;
2119 }
2120
2121 /**
2122 * Set the first line of text after the detail section in the big form of the template.
2123 */
2124 protected void internalSetSummaryText(CharSequence cs) {
2125 mSummaryText = cs;
Daniel Sandler619738c2012-06-07 16:33:08 -04002126 mSummaryTextSet = true;
Chris Wrend6297db2012-05-03 16:20:13 -04002127 }
2128
Chris Wrenfbd96ba2012-05-01 12:03:58 -04002129 public void setBuilder(Builder builder) {
2130 if (mBuilder != builder) {
2131 mBuilder = builder;
Daniel Sandlerc08dea22012-06-28 08:35:24 -07002132 if (mBuilder != null) {
2133 mBuilder.setStyle(this);
2134 }
Chris Wrenfbd96ba2012-05-01 12:03:58 -04002135 }
2136 }
2137
Chris Wrend6297db2012-05-03 16:20:13 -04002138 protected void checkBuilder() {
Chris Wrenfbd96ba2012-05-01 12:03:58 -04002139 if (mBuilder == null) {
2140 throw new IllegalArgumentException("Style requires a valid Builder object");
2141 }
Chris Wrenfbd96ba2012-05-01 12:03:58 -04002142 }
Chris Wrend6297db2012-05-03 16:20:13 -04002143
2144 protected RemoteViews getStandardView(int layoutId) {
2145 checkBuilder();
2146
2147 if (mBigContentTitle != null) {
2148 mBuilder.setContentTitle(mBigContentTitle);
2149 }
2150
Chris Wrend6297db2012-05-03 16:20:13 -04002151 RemoteViews contentView = mBuilder.applyStandardTemplateWithActions(layoutId);
2152
Chris Wrend6297db2012-05-03 16:20:13 -04002153 if (mBigContentTitle != null && mBigContentTitle.equals("")) {
2154 contentView.setViewVisibility(R.id.line1, View.GONE);
Chris Wren67dc9a02012-05-16 01:03:20 -04002155 } else {
2156 contentView.setViewVisibility(R.id.line1, View.VISIBLE);
Chris Wrend6297db2012-05-03 16:20:13 -04002157 }
2158
Daniel Sandler619738c2012-06-07 16:33:08 -04002159 // The last line defaults to the subtext, but can be replaced by mSummaryText
2160 final CharSequence overflowText =
2161 mSummaryTextSet ? mSummaryText
2162 : mBuilder.mSubText;
2163 if (overflowText != null) {
2164 contentView.setTextViewText(R.id.text, overflowText);
2165 contentView.setViewVisibility(R.id.overflow_divider, View.VISIBLE);
Daniel Sandler9f7936a2012-05-21 16:14:28 -04002166 contentView.setViewVisibility(R.id.line3, View.VISIBLE);
Daniel Sandler916ad912012-06-13 12:17:07 -04002167 } else {
2168 contentView.setViewVisibility(R.id.overflow_divider, View.GONE);
2169 contentView.setViewVisibility(R.id.line3, View.GONE);
Chris Wrend6297db2012-05-03 16:20:13 -04002170 }
2171
2172 return contentView;
2173 }
2174
Daniel Sandlerf45564e2013-04-15 15:05:08 -04002175 /**
2176 * @hide
2177 */
2178 public void addExtras(Bundle extras) {
2179 if (mSummaryTextSet) {
2180 extras.putCharSequence(EXTRA_SUMMARY_TEXT, mSummaryText);
2181 }
2182 if (mBigContentTitle != null) {
2183 extras.putCharSequence(EXTRA_TITLE_BIG, mBigContentTitle);
2184 }
2185 }
2186
Daniel Sandlercf1d39b2013-09-23 13:35:35 -04002187 /**
2188 * @hide
2189 */
2190 public abstract Notification buildStyled(Notification wip);
2191
2192 /**
2193 * Calls {@link android.app.Notification.Builder#build()} on the Builder this Style is
2194 * attached to.
2195 *
2196 * @return the fully constructed Notification.
2197 */
2198 public Notification build() {
2199 checkBuilder();
2200 return mBuilder.build();
2201 }
Joe Onorato46439ce2010-11-19 13:56:21 -08002202 }
Daniel Sandlerf3b73432012-03-27 15:01:25 -04002203
2204 /**
Daniel Sandler4dfbe832012-04-11 14:51:46 -04002205 * Helper class for generating large-format notifications that include a large image attachment.
Joe Malin8d40d042012-11-05 11:36:40 -08002206 *
Daniel Sandler4dfbe832012-04-11 14:51:46 -04002207 * This class is a "rebuilder": It consumes a Builder object and modifies its behavior, like so:
Daniel Sandlerf3b73432012-03-27 15:01:25 -04002208 * <pre class="prettyprint">
2209 * Notification noti = new Notification.BigPictureStyle(
2210 * new Notification.Builder()
Daniel Sandler4dfbe832012-04-11 14:51:46 -04002211 * .setContentTitle(&quot;New photo from &quot; + sender.toString())
Daniel Sandlerf3b73432012-03-27 15:01:25 -04002212 * .setContentText(subject)
Daniel Sandler4dfbe832012-04-11 14:51:46 -04002213 * .setSmallIcon(R.drawable.new_post)
Daniel Sandlerf3b73432012-03-27 15:01:25 -04002214 * .setLargeIcon(aBitmap))
2215 * .bigPicture(aBigBitmap)
2216 * .build();
2217 * </pre>
Joe Malin8d40d042012-11-05 11:36:40 -08002218 *
Daniel Sandler4dfbe832012-04-11 14:51:46 -04002219 * @see Notification#bigContentView
Daniel Sandlerf3b73432012-03-27 15:01:25 -04002220 */
Chris Wrenfbd96ba2012-05-01 12:03:58 -04002221 public static class BigPictureStyle extends Style {
Daniel Sandlerf3b73432012-03-27 15:01:25 -04002222 private Bitmap mPicture;
Chris Wren3745a3d2012-05-22 15:11:52 -04002223 private Bitmap mBigLargeIcon;
2224 private boolean mBigLargeIconSet = false;
Daniel Sandlerf3b73432012-03-27 15:01:25 -04002225
Chris Wrenfbd96ba2012-05-01 12:03:58 -04002226 public BigPictureStyle() {
2227 }
2228
Daniel Sandlerf3b73432012-03-27 15:01:25 -04002229 public BigPictureStyle(Builder builder) {
Chris Wrenfbd96ba2012-05-01 12:03:58 -04002230 setBuilder(builder);
Daniel Sandlerf3b73432012-03-27 15:01:25 -04002231 }
2232
Chris Wrend6297db2012-05-03 16:20:13 -04002233 /**
2234 * Overrides ContentTitle in the big form of the template.
2235 * This defaults to the value passed to setContentTitle().
2236 */
2237 public BigPictureStyle setBigContentTitle(CharSequence title) {
Daniel Sandlerdcbaf662013-04-26 16:23:09 -04002238 internalSetBigContentTitle(safeCharSequence(title));
Chris Wrend6297db2012-05-03 16:20:13 -04002239 return this;
2240 }
2241
2242 /**
2243 * Set the first line of text after the detail section in the big form of the template.
2244 */
2245 public BigPictureStyle setSummaryText(CharSequence cs) {
Daniel Sandlerdcbaf662013-04-26 16:23:09 -04002246 internalSetSummaryText(safeCharSequence(cs));
Chris Wrend6297db2012-05-03 16:20:13 -04002247 return this;
2248 }
2249
Chris Wren0bd664d2012-08-01 13:56:56 -04002250 /**
2251 * Provide the bitmap to be used as the payload for the BigPicture notification.
2252 */
Daniel Sandlerf3b73432012-03-27 15:01:25 -04002253 public BigPictureStyle bigPicture(Bitmap b) {
2254 mPicture = b;
2255 return this;
2256 }
2257
Chris Wren3745a3d2012-05-22 15:11:52 -04002258 /**
Chris Wren3745a3d2012-05-22 15:11:52 -04002259 * Override the large icon when the big notification is shown.
2260 */
2261 public BigPictureStyle bigLargeIcon(Bitmap b) {
2262 mBigLargeIconSet = true;
2263 mBigLargeIcon = b;
2264 return this;
2265 }
2266
Daniel Sandlerf3b73432012-03-27 15:01:25 -04002267 private RemoteViews makeBigContentView() {
Chris Wrend6297db2012-05-03 16:20:13 -04002268 RemoteViews contentView = getStandardView(R.layout.notification_template_big_picture);
Daniel Sandlerf3b73432012-03-27 15:01:25 -04002269
2270 contentView.setImageViewBitmap(R.id.big_picture, mPicture);
2271
2272 return contentView;
2273 }
2274
Daniel Sandlerf45564e2013-04-15 15:05:08 -04002275 /**
2276 * @hide
2277 */
2278 public void addExtras(Bundle extras) {
2279 super.addExtras(extras);
2280
2281 if (mBigLargeIconSet) {
2282 extras.putParcelable(EXTRA_LARGE_ICON_BIG, mBigLargeIcon);
2283 }
2284 extras.putParcelable(EXTRA_PICTURE, mPicture);
2285 }
2286
Daniel Sandlercf1d39b2013-09-23 13:35:35 -04002287 /**
2288 * @hide
2289 */
Chris Wrenfbd96ba2012-05-01 12:03:58 -04002290 @Override
Daniel Sandlercf1d39b2013-09-23 13:35:35 -04002291 public Notification buildStyled(Notification wip) {
Chris Wren3745a3d2012-05-22 15:11:52 -04002292 if (mBigLargeIconSet ) {
2293 mBuilder.mLargeIcon = mBigLargeIcon;
2294 }
Daniel Sandlerf3b73432012-03-27 15:01:25 -04002295 wip.bigContentView = makeBigContentView();
2296 return wip;
2297 }
2298 }
2299
2300 /**
Daniel Sandler4dfbe832012-04-11 14:51:46 -04002301 * Helper class for generating large-format notifications that include a lot of text.
Joe Malin8d40d042012-11-05 11:36:40 -08002302 *
Daniel Sandler4dfbe832012-04-11 14:51:46 -04002303 * This class is a "rebuilder": It consumes a Builder object and modifies its behavior, like so:
Daniel Sandlerf3b73432012-03-27 15:01:25 -04002304 * <pre class="prettyprint">
Daniel Sandler87682782012-11-07 14:04:42 -05002305 * Notification noti = new Notification.BigTextStyle(
Daniel Sandlerf3b73432012-03-27 15:01:25 -04002306 * new Notification.Builder()
2307 * .setContentTitle(&quot;New mail from &quot; + sender.toString())
2308 * .setContentText(subject)
2309 * .setSmallIcon(R.drawable.new_mail)
2310 * .setLargeIcon(aBitmap))
2311 * .bigText(aVeryLongString)
2312 * .build();
2313 * </pre>
Joe Malin8d40d042012-11-05 11:36:40 -08002314 *
Daniel Sandler4dfbe832012-04-11 14:51:46 -04002315 * @see Notification#bigContentView
Daniel Sandlerf3b73432012-03-27 15:01:25 -04002316 */
Chris Wrenfbd96ba2012-05-01 12:03:58 -04002317 public static class BigTextStyle extends Style {
Daniel Sandlerf3b73432012-03-27 15:01:25 -04002318 private CharSequence mBigText;
2319
Chris Wrenfbd96ba2012-05-01 12:03:58 -04002320 public BigTextStyle() {
2321 }
2322
Daniel Sandlerf3b73432012-03-27 15:01:25 -04002323 public BigTextStyle(Builder builder) {
Chris Wrenfbd96ba2012-05-01 12:03:58 -04002324 setBuilder(builder);
Daniel Sandlerf3b73432012-03-27 15:01:25 -04002325 }
2326
Chris Wrend6297db2012-05-03 16:20:13 -04002327 /**
2328 * Overrides ContentTitle in the big form of the template.
2329 * This defaults to the value passed to setContentTitle().
2330 */
2331 public BigTextStyle setBigContentTitle(CharSequence title) {
Daniel Sandlerdcbaf662013-04-26 16:23:09 -04002332 internalSetBigContentTitle(safeCharSequence(title));
Chris Wrend6297db2012-05-03 16:20:13 -04002333 return this;
2334 }
2335
2336 /**
2337 * Set the first line of text after the detail section in the big form of the template.
2338 */
2339 public BigTextStyle setSummaryText(CharSequence cs) {
Daniel Sandlerdcbaf662013-04-26 16:23:09 -04002340 internalSetSummaryText(safeCharSequence(cs));
Chris Wrend6297db2012-05-03 16:20:13 -04002341 return this;
2342 }
2343
Chris Wren0bd664d2012-08-01 13:56:56 -04002344 /**
2345 * Provide the longer text to be displayed in the big form of the
2346 * template in place of the content text.
2347 */
Daniel Sandlerf3b73432012-03-27 15:01:25 -04002348 public BigTextStyle bigText(CharSequence cs) {
Daniel Sandlerdcbaf662013-04-26 16:23:09 -04002349 mBigText = safeCharSequence(cs);
Daniel Sandlerf3b73432012-03-27 15:01:25 -04002350 return this;
2351 }
2352
Daniel Sandlerf45564e2013-04-15 15:05:08 -04002353 /**
2354 * @hide
2355 */
2356 public void addExtras(Bundle extras) {
2357 super.addExtras(extras);
2358
2359 extras.putCharSequence(EXTRA_TEXT, mBigText);
2360 }
2361
Daniel Sandlerf3b73432012-03-27 15:01:25 -04002362 private RemoteViews makeBigContentView() {
Daniel Sandler619738c2012-06-07 16:33:08 -04002363 // Remove the content text so line3 only shows if you have a summary
2364 final boolean hadThreeLines = (mBuilder.mContentText != null && mBuilder.mSubText != null);
Daniel Sandler6387d2f2012-05-22 13:44:09 -04002365 mBuilder.mContentText = null;
Daniel Sandler916ad912012-06-13 12:17:07 -04002366
Chris Wrend6297db2012-05-03 16:20:13 -04002367 RemoteViews contentView = getStandardView(R.layout.notification_template_big_text);
Joe Malin8d40d042012-11-05 11:36:40 -08002368
Daniel Sandler619738c2012-06-07 16:33:08 -04002369 if (hadThreeLines) {
2370 // vertical centering
2371 contentView.setViewPadding(R.id.line1, 0, 0, 0, 0);
2372 }
2373
Daniel Sandlerf3b73432012-03-27 15:01:25 -04002374 contentView.setTextViewText(R.id.big_text, mBigText);
2375 contentView.setViewVisibility(R.id.big_text, View.VISIBLE);
Chris Wren3c5f92432012-05-04 16:31:17 -04002376 contentView.setViewVisibility(R.id.text2, View.GONE);
Daniel Sandlerf3b73432012-03-27 15:01:25 -04002377
2378 return contentView;
2379 }
2380
Daniel Sandlercf1d39b2013-09-23 13:35:35 -04002381 /**
2382 * @hide
2383 */
Chris Wrenfbd96ba2012-05-01 12:03:58 -04002384 @Override
Daniel Sandlercf1d39b2013-09-23 13:35:35 -04002385 public Notification buildStyled(Notification wip) {
Daniel Sandlerf3b73432012-03-27 15:01:25 -04002386 wip.bigContentView = makeBigContentView();
Daniel Sandlerbe6e7e02013-02-01 17:49:11 -05002387
2388 wip.extras.putCharSequence(EXTRA_TEXT, mBigText);
2389
Daniel Sandlerf3b73432012-03-27 15:01:25 -04002390 return wip;
2391 }
2392 }
Daniel Sandler879c5e02012-04-17 16:46:51 -04002393
2394 /**
2395 * Helper class for generating large-format notifications that include a list of (up to 5) strings.
Joe Malin8d40d042012-11-05 11:36:40 -08002396 *
Daniel Sandler879c5e02012-04-17 16:46:51 -04002397 * This class is a "rebuilder": It consumes a Builder object and modifies its behavior, like so:
2398 * <pre class="prettyprint">
Chris Wrenfbd96ba2012-05-01 12:03:58 -04002399 * Notification noti = new Notification.InboxStyle(
Daniel Sandler879c5e02012-04-17 16:46:51 -04002400 * new Notification.Builder()
Chris Wrend6297db2012-05-03 16:20:13 -04002401 * .setContentTitle(&quot;5 New mails from &quot; + sender.toString())
Daniel Sandler879c5e02012-04-17 16:46:51 -04002402 * .setContentText(subject)
2403 * .setSmallIcon(R.drawable.new_mail)
2404 * .setLargeIcon(aBitmap))
2405 * .addLine(str1)
2406 * .addLine(str2)
Chris Wrend6297db2012-05-03 16:20:13 -04002407 * .setContentTitle("")
2408 * .setSummaryText(&quot;+3 more&quot;)
Daniel Sandler879c5e02012-04-17 16:46:51 -04002409 * .build();
2410 * </pre>
Joe Malin8d40d042012-11-05 11:36:40 -08002411 *
Daniel Sandler879c5e02012-04-17 16:46:51 -04002412 * @see Notification#bigContentView
2413 */
Chris Wrenfbd96ba2012-05-01 12:03:58 -04002414 public static class InboxStyle extends Style {
Daniel Sandler879c5e02012-04-17 16:46:51 -04002415 private ArrayList<CharSequence> mTexts = new ArrayList<CharSequence>(5);
2416
Chris Wrenfbd96ba2012-05-01 12:03:58 -04002417 public InboxStyle() {
2418 }
2419
Daniel Sandler879c5e02012-04-17 16:46:51 -04002420 public InboxStyle(Builder builder) {
Chris Wrenfbd96ba2012-05-01 12:03:58 -04002421 setBuilder(builder);
Daniel Sandler879c5e02012-04-17 16:46:51 -04002422 }
2423
Chris Wrend6297db2012-05-03 16:20:13 -04002424 /**
2425 * Overrides ContentTitle in the big form of the template.
2426 * This defaults to the value passed to setContentTitle().
2427 */
2428 public InboxStyle setBigContentTitle(CharSequence title) {
Daniel Sandlerdcbaf662013-04-26 16:23:09 -04002429 internalSetBigContentTitle(safeCharSequence(title));
Chris Wrend6297db2012-05-03 16:20:13 -04002430 return this;
2431 }
2432
2433 /**
2434 * Set the first line of text after the detail section in the big form of the template.
2435 */
2436 public InboxStyle setSummaryText(CharSequence cs) {
Daniel Sandlerdcbaf662013-04-26 16:23:09 -04002437 internalSetSummaryText(safeCharSequence(cs));
Chris Wrend6297db2012-05-03 16:20:13 -04002438 return this;
2439 }
2440
Chris Wren0bd664d2012-08-01 13:56:56 -04002441 /**
2442 * Append a line to the digest section of the Inbox notification.
2443 */
Daniel Sandler879c5e02012-04-17 16:46:51 -04002444 public InboxStyle addLine(CharSequence cs) {
Daniel Sandlerdcbaf662013-04-26 16:23:09 -04002445 mTexts.add(safeCharSequence(cs));
Daniel Sandler879c5e02012-04-17 16:46:51 -04002446 return this;
2447 }
2448
Daniel Sandlerf45564e2013-04-15 15:05:08 -04002449 /**
2450 * @hide
2451 */
2452 public void addExtras(Bundle extras) {
2453 super.addExtras(extras);
2454 CharSequence[] a = new CharSequence[mTexts.size()];
2455 extras.putCharSequenceArray(EXTRA_TEXT_LINES, mTexts.toArray(a));
2456 }
2457
Daniel Sandler879c5e02012-04-17 16:46:51 -04002458 private RemoteViews makeBigContentView() {
Daniel Sandler619738c2012-06-07 16:33:08 -04002459 // Remove the content text so line3 disappears unless you have a summary
2460 mBuilder.mContentText = null;
Chris Wrend6297db2012-05-03 16:20:13 -04002461 RemoteViews contentView = getStandardView(R.layout.notification_template_inbox);
Daniel Sandler619738c2012-06-07 16:33:08 -04002462
Chris Wrend6297db2012-05-03 16:20:13 -04002463 contentView.setViewVisibility(R.id.text2, View.GONE);
Daniel Sandler879c5e02012-04-17 16:46:51 -04002464
Chris Wrend6297db2012-05-03 16:20:13 -04002465 int[] rowIds = {R.id.inbox_text0, R.id.inbox_text1, R.id.inbox_text2, R.id.inbox_text3,
Chris Wren29bb6d92012-05-17 18:09:42 -04002466 R.id.inbox_text4, R.id.inbox_text5, R.id.inbox_text6};
Chris Wrend6297db2012-05-03 16:20:13 -04002467
Chris Wren4ed80d52012-05-17 09:30:03 -04002468 // Make sure all rows are gone in case we reuse a view.
2469 for (int rowId : rowIds) {
2470 contentView.setViewVisibility(rowId, View.GONE);
2471 }
2472
Chris Wren683ab002012-09-20 10:35:54 -04002473
Daniel Sandler879c5e02012-04-17 16:46:51 -04002474 int i=0;
2475 while (i < mTexts.size() && i < rowIds.length) {
2476 CharSequence str = mTexts.get(i);
2477 if (str != null && !str.equals("")) {
2478 contentView.setViewVisibility(rowIds[i], View.VISIBLE);
2479 contentView.setTextViewText(rowIds[i], str);
2480 }
2481 i++;
2482 }
2483
Chris Wren683ab002012-09-20 10:35:54 -04002484 contentView.setViewVisibility(R.id.inbox_end_pad,
2485 mTexts.size() > 0 ? View.VISIBLE : View.GONE);
2486
2487 contentView.setViewVisibility(R.id.inbox_more,
2488 mTexts.size() > rowIds.length ? View.VISIBLE : View.GONE);
Chris Wren29bb6d92012-05-17 18:09:42 -04002489
Daniel Sandler879c5e02012-04-17 16:46:51 -04002490 return contentView;
2491 }
2492
Daniel Sandlercf1d39b2013-09-23 13:35:35 -04002493 /**
2494 * @hide
2495 */
Chris Wrenfbd96ba2012-05-01 12:03:58 -04002496 @Override
Daniel Sandlercf1d39b2013-09-23 13:35:35 -04002497 public Notification buildStyled(Notification wip) {
Daniel Sandler879c5e02012-04-17 16:46:51 -04002498 wip.bigContentView = makeBigContentView();
Daniel Sandlerbe6e7e02013-02-01 17:49:11 -05002499
Daniel Sandler879c5e02012-04-17 16:46:51 -04002500 return wip;
2501 }
2502 }
The Android Open Source Project9066cfe2009-03-03 19:31:44 -08002503}