NotificationCompat.java revision c4e68f1b0c0cb95f499812383ccb282643777226
1/* 2 * Copyright (C) 2012 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.support.v4.app; 18 19import android.app.Notification; 20import android.app.NotificationManager; 21import android.app.PendingIntent; 22import android.content.Context; 23import android.graphics.Bitmap; 24import android.media.AudioManager; 25import android.net.Uri; 26import android.os.Build; 27import android.widget.RemoteViews; 28import java.util.ArrayList; 29 30/** 31 * Helper for accessing features in {@link android.app.Notification} 32 * introduced after API level 4 in a backwards compatible fashion. 33 */ 34public class NotificationCompat { 35 36 /** 37 * Use all default values (where applicable). 38 */ 39 public static final int DEFAULT_ALL = ~0; 40 41 /** 42 * Use the default notification sound. This will ignore any sound set using 43 * {@link Builder#setSound} 44 * 45 * @see Builder#setDefaults 46 */ 47 public static final int DEFAULT_SOUND = 1; 48 49 /** 50 * Use the default notification vibrate. This will ignore any vibrate set using 51 * {@link Builder#setVibrate}. Using phone vibration requires the 52 * {@link android.Manifest.permission#VIBRATE VIBRATE} permission. 53 * 54 * @see Builder#setDefaults 55 */ 56 public static final int DEFAULT_VIBRATE = 2; 57 58 /** 59 * Use the default notification lights. This will ignore the 60 * {@link #FLAG_SHOW_LIGHTS} bit, and values set with {@link Builder#setLights}. 61 * 62 * @see Builder#setDefaults 63 */ 64 public static final int DEFAULT_LIGHTS = 4; 65 66 /** 67 * Use this constant as the value for audioStreamType to request that 68 * the default stream type for notifications be used. Currently the 69 * default stream type is {@link AudioManager#STREAM_NOTIFICATION}. 70 */ 71 public static final int STREAM_DEFAULT = -1; 72 73 /** 74 * Bit set in the Notification flags field when LEDs should be turned on 75 * for this notification. 76 */ 77 public static final int FLAG_SHOW_LIGHTS = 0x00000001; 78 79 /** 80 * Bit set in the Notification flags field if this notification is in 81 * reference to something that is ongoing, like a phone call. It should 82 * not be set if this notification is in reference to something that 83 * happened at a particular point in time, like a missed phone call. 84 */ 85 public static final int FLAG_ONGOING_EVENT = 0x00000002; 86 87 /** 88 * Bit set in the Notification flags field if 89 * the audio will be repeated until the notification is 90 * cancelled or the notification window is opened. 91 */ 92 public static final int FLAG_INSISTENT = 0x00000004; 93 94 /** 95 * Bit set in the Notification flags field if the notification's sound, 96 * vibrate and ticker should only be played if the notification is not already showing. 97 */ 98 public static final int FLAG_ONLY_ALERT_ONCE = 0x00000008; 99 100 /** 101 * Bit set in the Notification flags field if the notification should be canceled when 102 * it is clicked by the user. 103 */ 104 public static final int FLAG_AUTO_CANCEL = 0x00000010; 105 106 /** 107 * Bit set in the Notification flags field if the notification should not be canceled 108 * when the user clicks the Clear all button. 109 */ 110 public static final int FLAG_NO_CLEAR = 0x00000020; 111 112 /** 113 * Bit set in the Notification flags field if this notification represents a currently 114 * running service. This will normally be set for you by 115 * {@link android.app.Service#startForeground}. 116 */ 117 public static final int FLAG_FOREGROUND_SERVICE = 0x00000040; 118 119 /** 120 * Obsolete flag indicating high-priority notifications; use the priority field instead. 121 * 122 * @deprecated Use {@link NotificationCompat.Builder#setPriority(int)} with a positive value. 123 */ 124 public static final int FLAG_HIGH_PRIORITY = 0x00000080; 125 126 /** 127 * Default notification priority for {@link NotificationCompat.Builder#setPriority(int)}. 128 * If your application does not prioritize its own notifications, 129 * use this value for all notifications. 130 */ 131 public static final int PRIORITY_DEFAULT = 0; 132 133 /** 134 * Lower notification priority for {@link NotificationCompat.Builder#setPriority(int)}, 135 * for items that are less important. The UI may choose to show 136 * these items smaller, or at a different position in the list, 137 * compared with your app's {@link #PRIORITY_DEFAULT} items. 138 */ 139 public static final int PRIORITY_LOW = -1; 140 141 /** 142 * Lowest notification priority for {@link NotificationCompat.Builder#setPriority(int)}; 143 * these items might not be shown to the user except under 144 * special circumstances, such as detailed notification logs. 145 */ 146 public static final int PRIORITY_MIN = -2; 147 148 /** 149 * Higher notification priority for {@link NotificationCompat.Builder#setPriority(int)}, 150 * for more important notifications or alerts. The UI may choose 151 * to show these items larger, or at a different position in 152 * notification lists, compared with your app's {@link #PRIORITY_DEFAULT} items. 153 */ 154 public static final int PRIORITY_HIGH = 1; 155 156 /** 157 * Highest notification priority for {@link NotificationCompat.Builder#setPriority(int)}, 158 * for your application's most important items that require the user's 159 * prompt attention or input. 160 */ 161 public static final int PRIORITY_MAX = 2; 162 163 /** 164 * Notification extras key: this is the title of the notification, 165 * as supplied to {@link Builder#setContentTitle(CharSequence)}. 166 */ 167 public static final String EXTRA_TITLE = "android.title"; 168 169 /** 170 * Notification extras key: this is the title of the notification when shown in expanded form, 171 * e.g. as supplied to {@link BigTextStyle#setBigContentTitle(CharSequence)}. 172 */ 173 public static final String EXTRA_TITLE_BIG = EXTRA_TITLE + ".big"; 174 175 /** 176 * Notification extras key: this is the main text payload, as supplied to 177 * {@link Builder#setContentText(CharSequence)}. 178 */ 179 public static final String EXTRA_TEXT = "android.text"; 180 181 /** 182 * Notification extras key: this is a third line of text, as supplied to 183 * {@link Builder#setSubText(CharSequence)}. 184 */ 185 public static final String EXTRA_SUB_TEXT = "android.subText"; 186 187 /** 188 * Notification extras key: this is a small piece of additional text as supplied to 189 * {@link Builder#setContentInfo(CharSequence)}. 190 */ 191 public static final String EXTRA_INFO_TEXT = "android.infoText"; 192 193 /** 194 * Notification extras key: this is a line of summary information intended to be shown 195 * alongside expanded notifications, as supplied to (e.g.) 196 * {@link BigTextStyle#setSummaryText(CharSequence)}. 197 */ 198 public static final String EXTRA_SUMMARY_TEXT = "android.summaryText"; 199 200 /** 201 * Notification extras key: this is the resource ID of the notification's main small icon, as 202 * supplied to {@link Builder#setSmallIcon(int)}. 203 */ 204 public static final String EXTRA_SMALL_ICON = "android.icon"; 205 206 /** 207 * Notification extras key: this is a bitmap to be used instead of the small icon when showing the 208 * notification payload, as 209 * supplied to {@link Builder#setLargeIcon(android.graphics.Bitmap)}. 210 */ 211 public static final String EXTRA_LARGE_ICON = "android.largeIcon"; 212 213 /** 214 * Notification extras key: this is a bitmap to be used instead of the one from 215 * {@link Builder#setLargeIcon(android.graphics.Bitmap)} when the notification is 216 * shown in its expanded form, as supplied to 217 * {@link BigPictureStyle#bigLargeIcon(android.graphics.Bitmap)}. 218 */ 219 public static final String EXTRA_LARGE_ICON_BIG = EXTRA_LARGE_ICON + ".big"; 220 221 /** 222 * Notification extras key: this is the progress value supplied to 223 * {@link Builder#setProgress(int, int, boolean)}. 224 */ 225 public static final String EXTRA_PROGRESS = "android.progress"; 226 227 /** 228 * Notification extras key: this is the maximum value supplied to 229 * {@link Builder#setProgress(int, int, boolean)}. 230 */ 231 public static final String EXTRA_PROGRESS_MAX = "android.progressMax"; 232 233 /** 234 * Notification extras key: whether the progress bar is indeterminate, supplied to 235 * {@link Builder#setProgress(int, int, boolean)}. 236 */ 237 public static final String EXTRA_PROGRESS_INDETERMINATE = "android.progressIndeterminate"; 238 239 /** 240 * Notification extras key: whether the when field set using {@link Builder#setWhen} should 241 * be shown as a count-up timer (specifically a {@link android.widget.Chronometer}) instead 242 * of a timestamp, as supplied to {@link Builder#setUsesChronometer(boolean)}. 243 */ 244 public static final String EXTRA_SHOW_CHRONOMETER = "android.showChronometer"; 245 246 /** 247 * Notification extras key: this is a bitmap to be shown in {@link BigPictureStyle} expanded 248 * notifications, supplied to {@link BigPictureStyle#bigPicture(android.graphics.Bitmap)}. 249 */ 250 public static final String EXTRA_PICTURE = "android.picture"; 251 252 /** 253 * Notification extras key: An array of CharSequences to show in {@link InboxStyle} expanded 254 * notifications, each of which was supplied to {@link InboxStyle#addLine(CharSequence)}. 255 */ 256 public static final String EXTRA_TEXT_LINES = "android.textLines"; 257 258 /** 259 * Notification extras key: An array of people that this notification relates to, specified 260 * by contacts provider contact URI. 261 */ 262 public static final String EXTRA_PEOPLE = "android.people"; 263 264 private static final NotificationCompatImpl IMPL; 265 266 interface NotificationCompatImpl { 267 public Notification build(Builder b); 268 } 269 270 static class NotificationCompatImplBase implements NotificationCompatImpl { 271 public Notification build(Builder b) { 272 Notification result = (Notification) b.mNotification; 273 result.setLatestEventInfo(b.mContext, b.mContentTitle, 274 b.mContentText, b.mContentIntent); 275 // translate high priority requests into legacy flag 276 if (b.mPriority > PRIORITY_DEFAULT) { 277 result.flags |= FLAG_HIGH_PRIORITY; 278 } 279 return result; 280 } 281 } 282 283 static class NotificationCompatImplGingerbread extends NotificationCompatImplBase { 284 public Notification build(Builder b) { 285 Notification result = (Notification) b.mNotification; 286 result.setLatestEventInfo(b.mContext, b.mContentTitle, 287 b.mContentText, b.mContentIntent); 288 result = NotificationCompatGingerbread.add(result, b.mContext, 289 b.mContentTitle, b.mContentText, b.mContentIntent, b.mFullScreenIntent); 290 // translate high priority requests into legacy flag 291 if (b.mPriority > PRIORITY_DEFAULT) { 292 result.flags |= FLAG_HIGH_PRIORITY; 293 } 294 return result; 295 } 296 } 297 298 static class NotificationCompatImplHoneycomb implements NotificationCompatImpl { 299 public Notification build(Builder b) { 300 return NotificationCompatHoneycomb.add(b.mContext, b.mNotification, 301 b.mContentTitle, b.mContentText, b.mContentInfo, b.mTickerView, 302 b.mNumber, b.mContentIntent, b.mFullScreenIntent, b.mLargeIcon); 303 } 304 } 305 306 static class NotificationCompatImplIceCreamSandwich implements NotificationCompatImpl { 307 public Notification build(Builder b) { 308 return NotificationCompatIceCreamSandwich.add(b.mContext, b.mNotification, 309 b.mContentTitle, b.mContentText, b.mContentInfo, b.mTickerView, 310 b.mNumber, b.mContentIntent, b.mFullScreenIntent, b.mLargeIcon, 311 b.mProgressMax, b.mProgress, b.mProgressIndeterminate); 312 } 313 } 314 315 static class NotificationCompatImplJellybean implements NotificationCompatImpl { 316 public Notification build(Builder b) { 317 NotificationCompatJellybean jbBuilder = new NotificationCompatJellybean( 318 b.mContext, b.mNotification, b.mContentTitle, b.mContentText, b.mContentInfo, 319 b.mTickerView, b.mNumber, b.mContentIntent, b.mFullScreenIntent, b.mLargeIcon, 320 b.mProgressMax, b.mProgress, b.mProgressIndeterminate, 321 b.mUseChronometer, b.mPriority, b.mSubText); 322 for (Action action: b.mActions) { 323 jbBuilder.addAction(action.icon, action.title, action.actionIntent); 324 } 325 if (b.mStyle != null) { 326 if (b.mStyle instanceof BigTextStyle) { 327 BigTextStyle style = (BigTextStyle) b.mStyle; 328 jbBuilder.addBigTextStyle(style.mBigContentTitle, 329 style.mSummaryTextSet, 330 style.mSummaryText, 331 style.mBigText); 332 } else if (b.mStyle instanceof InboxStyle) { 333 InboxStyle style = (InboxStyle) b.mStyle; 334 jbBuilder.addInboxStyle(style.mBigContentTitle, 335 style.mSummaryTextSet, 336 style.mSummaryText, 337 style.mTexts); 338 } else if (b.mStyle instanceof BigPictureStyle) { 339 BigPictureStyle style = (BigPictureStyle) b.mStyle; 340 jbBuilder.addBigPictureStyle(style.mBigContentTitle, 341 style.mSummaryTextSet, 342 style.mSummaryText, 343 style.mPicture, 344 style.mBigLargeIcon, 345 style.mBigLargeIconSet); 346 } 347 } 348 return(jbBuilder.build()); 349 } 350 } 351 352 static { 353 if (Build.VERSION.SDK_INT >= 16) { 354 IMPL = new NotificationCompatImplJellybean(); 355 } else if (Build.VERSION.SDK_INT >= 14) { 356 IMPL = new NotificationCompatImplIceCreamSandwich(); 357 } else if (Build.VERSION.SDK_INT >= 11) { 358 IMPL = new NotificationCompatImplHoneycomb(); 359 } else if (Build.VERSION.SDK_INT >= 9) { 360 IMPL = new NotificationCompatImplGingerbread(); 361 } else { 362 IMPL = new NotificationCompatImplBase(); 363 } 364 } 365 366 /** 367 * Builder class for {@link NotificationCompat} objects. Allows easier control over 368 * all the flags, as well as help constructing the typical notification layouts. 369 * <p> 370 * On platform versions that don't offer expanded notifications, methods that depend on 371 * expanded notifications have no effect. 372 * </p> 373 * <p> 374 * For example, action buttons won't appear on platforms prior to Android 4.1. Action 375 * buttons depend on expanded notifications, which are only available in Android 4.1 376 * and later. 377 * <p> 378 * For this reason, you should always ensure that UI controls in a notification are also 379 * available in an {@link android.app.Activity} in your app, and you should always start that 380 * {@link android.app.Activity} when users click the notification. To do this, use the 381 * {@link NotificationCompat.Builder#setContentIntent setContentIntent()} 382 * method. 383 * </p> 384 * 385 */ 386 public static class Builder { 387 Context mContext; 388 389 CharSequence mContentTitle; 390 CharSequence mContentText; 391 PendingIntent mContentIntent; 392 PendingIntent mFullScreenIntent; 393 RemoteViews mTickerView; 394 Bitmap mLargeIcon; 395 CharSequence mContentInfo; 396 int mNumber; 397 int mPriority; 398 boolean mUseChronometer; 399 Style mStyle; 400 CharSequence mSubText; 401 int mProgressMax; 402 int mProgress; 403 boolean mProgressIndeterminate; 404 ArrayList<Action> mActions = new ArrayList<Action>(); 405 406 Notification mNotification = new Notification(); 407 408 /** 409 * Constructor. 410 * 411 * Automatically sets the when field to {@link System#currentTimeMillis() 412 * System.currentTimeMillis()} and the audio stream to the 413 * {@link Notification#STREAM_DEFAULT}. 414 * 415 * @param context A {@link Context} that will be used to construct the 416 * RemoteViews. The Context will not be held past the lifetime of this 417 * Builder object. 418 */ 419 public Builder(Context context) { 420 mContext = context; 421 422 // Set defaults to match the defaults of a Notification 423 mNotification.when = System.currentTimeMillis(); 424 mNotification.audioStreamType = Notification.STREAM_DEFAULT; 425 mPriority = PRIORITY_DEFAULT; 426 } 427 428 /** 429 * Set the time that the event occurred. Notifications in the panel are 430 * sorted by this time. 431 */ 432 public Builder setWhen(long when) { 433 mNotification.when = when; 434 return this; 435 } 436 437 /** 438 * Show the {@link Notification#when} field as a stopwatch. 439 * 440 * Instead of presenting <code>when</code> as a timestamp, the notification will show an 441 * automatically updating display of the minutes and seconds since <code>when</code>. 442 * 443 * Useful when showing an elapsed time (like an ongoing phone call). 444 * 445 * @see android.widget.Chronometer 446 * @see Notification#when 447 */ 448 public Builder setUsesChronometer(boolean b) { 449 mUseChronometer = b; 450 return this; 451 } 452 453 /** 454 * Set the small icon to use in the notification layouts. Different classes of devices 455 * may return different sizes. See the UX guidelines for more information on how to 456 * design these icons. 457 * 458 * @param icon A resource ID in the application's package of the drawble to use. 459 */ 460 public Builder setSmallIcon(int icon) { 461 mNotification.icon = icon; 462 return this; 463 } 464 465 /** 466 * A variant of {@link #setSmallIcon(int) setSmallIcon(int)} that takes an additional 467 * level parameter for when the icon is a {@link android.graphics.drawable.LevelListDrawable 468 * LevelListDrawable}. 469 * 470 * @param icon A resource ID in the application's package of the drawble to use. 471 * @param level The level to use for the icon. 472 * 473 * @see android.graphics.drawable.LevelListDrawable 474 */ 475 public Builder setSmallIcon(int icon, int level) { 476 mNotification.icon = icon; 477 mNotification.iconLevel = level; 478 return this; 479 } 480 481 /** 482 * Set the title (first row) of the notification, in a standard notification. 483 */ 484 public Builder setContentTitle(CharSequence title) { 485 mContentTitle = title; 486 return this; 487 } 488 489 /** 490 * Set the text (second row) of the notification, in a standard notification. 491 */ 492 public Builder setContentText(CharSequence text) { 493 mContentText = text; 494 return this; 495 } 496 497 /** 498 * Set the third line of text in the platform notification template. 499 * Don't use if you're also using {@link #setProgress(int, int, boolean)}; 500 * they occupy the same location in the standard template. 501 * <br> 502 * If the platform does not provide large-format notifications, this method has no effect. 503 * The third line of text only appears in expanded view. 504 * <br> 505 */ 506 public Builder setSubText(CharSequence text) { 507 mSubText = text; 508 return this; 509 } 510 511 /** 512 * Set the large number at the right-hand side of the notification. This is 513 * equivalent to setContentInfo, although it might show the number in a different 514 * font size for readability. 515 */ 516 public Builder setNumber(int number) { 517 mNumber = number; 518 return this; 519 } 520 521 /** 522 * Set the large text at the right-hand side of the notification. 523 */ 524 public Builder setContentInfo(CharSequence info) { 525 mContentInfo = info; 526 return this; 527 } 528 529 /** 530 * Set the progress this notification represents, which may be 531 * represented as a {@link android.widget.ProgressBar}. 532 */ 533 public Builder setProgress(int max, int progress, boolean indeterminate) { 534 mProgressMax = max; 535 mProgress = progress; 536 mProgressIndeterminate = indeterminate; 537 return this; 538 } 539 540 /** 541 * Supply a custom RemoteViews to use instead of the standard one. 542 */ 543 public Builder setContent(RemoteViews views) { 544 mNotification.contentView = views; 545 return this; 546 } 547 548 /** 549 * Supply a {@link PendingIntent} to send when the notification is clicked. 550 * If you do not supply an intent, you can now add PendingIntents to individual 551 * views to be launched when clicked by calling {@link RemoteViews#setOnClickPendingIntent 552 * RemoteViews.setOnClickPendingIntent(int,PendingIntent)}. Be sure to 553 * read {@link Notification#contentIntent Notification.contentIntent} for 554 * how to correctly use this. 555 */ 556 public Builder setContentIntent(PendingIntent intent) { 557 mContentIntent = intent; 558 return this; 559 } 560 561 /** 562 * Supply a {@link PendingIntent} to send when the notification is cleared by the user 563 * directly from the notification panel. For example, this intent is sent when the user 564 * clicks the "Clear all" button, or the individual "X" buttons on notifications. This 565 * intent is not sent when the application calls {@link NotificationManager#cancel 566 * NotificationManager.cancel(int)}. 567 */ 568 public Builder setDeleteIntent(PendingIntent intent) { 569 mNotification.deleteIntent = intent; 570 return this; 571 } 572 573 /** 574 * An intent to launch instead of posting the notification to the status bar. 575 * Only for use with extremely high-priority notifications demanding the user's 576 * <strong>immediate</strong> attention, such as an incoming phone call or 577 * alarm clock that the user has explicitly set to a particular time. 578 * If this facility is used for something else, please give the user an option 579 * to turn it off and use a normal notification, as this can be extremely 580 * disruptive. 581 * 582 * @param intent The pending intent to launch. 583 * @param highPriority Passing true will cause this notification to be sent 584 * even if other notifications are suppressed. 585 */ 586 public Builder setFullScreenIntent(PendingIntent intent, boolean highPriority) { 587 mFullScreenIntent = intent; 588 setFlag(FLAG_HIGH_PRIORITY, highPriority); 589 return this; 590 } 591 592 /** 593 * Set the text that is displayed in the status bar when the notification first 594 * arrives. 595 */ 596 public Builder setTicker(CharSequence tickerText) { 597 mNotification.tickerText = tickerText; 598 return this; 599 } 600 601 /** 602 * Set the text that is displayed in the status bar when the notification first 603 * arrives, and also a RemoteViews object that may be displayed instead on some 604 * devices. 605 */ 606 public Builder setTicker(CharSequence tickerText, RemoteViews views) { 607 mNotification.tickerText = tickerText; 608 mTickerView = views; 609 return this; 610 } 611 612 /** 613 * Set the large icon that is shown in the ticker and notification. 614 */ 615 public Builder setLargeIcon(Bitmap icon) { 616 mLargeIcon = icon; 617 return this; 618 } 619 620 /** 621 * Set the sound to play. It will play on the default stream. 622 */ 623 public Builder setSound(Uri sound) { 624 mNotification.sound = sound; 625 mNotification.audioStreamType = Notification.STREAM_DEFAULT; 626 return this; 627 } 628 629 /** 630 * Set the sound to play. It will play on the stream you supply. 631 * 632 * @see #STREAM_DEFAULT 633 * @see AudioManager for the <code>STREAM_</code> constants. 634 */ 635 public Builder setSound(Uri sound, int streamType) { 636 mNotification.sound = sound; 637 mNotification.audioStreamType = streamType; 638 return this; 639 } 640 641 /** 642 * Set the vibration pattern to use. 643 * 644 * @see android.os.Vibrator for a discussion of the <code>pattern</code> 645 * parameter. 646 */ 647 public Builder setVibrate(long[] pattern) { 648 mNotification.vibrate = pattern; 649 return this; 650 } 651 652 /** 653 * Set the argb value that you would like the LED on the device to blnk, as well as the 654 * rate. The rate is specified in terms of the number of milliseconds to be on 655 * and then the number of milliseconds to be off. 656 */ 657 public Builder setLights(int argb, int onMs, int offMs) { 658 mNotification.ledARGB = argb; 659 mNotification.ledOnMS = onMs; 660 mNotification.ledOffMS = offMs; 661 boolean showLights = mNotification.ledOnMS != 0 && mNotification.ledOffMS != 0; 662 mNotification.flags = (mNotification.flags & ~Notification.FLAG_SHOW_LIGHTS) | 663 (showLights ? Notification.FLAG_SHOW_LIGHTS : 0); 664 return this; 665 } 666 667 /** 668 * Set whether this is an ongoing notification. 669 * 670 * <p>Ongoing notifications differ from regular notifications in the following ways: 671 * <ul> 672 * <li>Ongoing notifications are sorted above the regular notifications in the 673 * notification panel.</li> 674 * <li>Ongoing notifications do not have an 'X' close button, and are not affected 675 * by the "Clear all" button. 676 * </ul> 677 */ 678 public Builder setOngoing(boolean ongoing) { 679 setFlag(Notification.FLAG_ONGOING_EVENT, ongoing); 680 return this; 681 } 682 683 /** 684 * Set this flag if you would only like the sound, vibrate 685 * and ticker to be played if the notification is not already showing. 686 */ 687 public Builder setOnlyAlertOnce(boolean onlyAlertOnce) { 688 setFlag(Notification.FLAG_ONLY_ALERT_ONCE, onlyAlertOnce); 689 return this; 690 } 691 692 /** 693 * Setting this flag will make it so the notification is automatically 694 * canceled when the user clicks it in the panel. The PendingIntent 695 * set with {@link #setDeleteIntent} will be broadcast when the notification 696 * is canceled. 697 */ 698 public Builder setAutoCancel(boolean autoCancel) { 699 setFlag(Notification.FLAG_AUTO_CANCEL, autoCancel); 700 return this; 701 } 702 703 /** 704 * Set the default notification options that will be used. 705 * <p> 706 * The value should be one or more of the following fields combined with 707 * bitwise-or: 708 * {@link Notification#DEFAULT_SOUND}, {@link Notification#DEFAULT_VIBRATE}, 709 * {@link Notification#DEFAULT_LIGHTS}. 710 * <p> 711 * For all default values, use {@link Notification#DEFAULT_ALL}. 712 */ 713 public Builder setDefaults(int defaults) { 714 mNotification.defaults = defaults; 715 if ((defaults & Notification.DEFAULT_LIGHTS) != 0) { 716 mNotification.flags |= Notification.FLAG_SHOW_LIGHTS; 717 } 718 return this; 719 } 720 721 private void setFlag(int mask, boolean value) { 722 if (value) { 723 mNotification.flags |= mask; 724 } else { 725 mNotification.flags &= ~mask; 726 } 727 } 728 729 /** 730 * Set the relative priority for this notification. 731 * 732 * Priority is an indication of how much of the user's 733 * valuable attention should be consumed by this 734 * notification. Low-priority notifications may be hidden from 735 * the user in certain situations, while the user might be 736 * interrupted for a higher-priority notification. 737 * The system sets a notification's priority based on various factors including the 738 * setPriority value. The effect may differ slightly on different platforms. 739 */ 740 public Builder setPriority(int pri) { 741 mPriority = pri; 742 return this; 743 } 744 745 /** 746 * Add an action to this notification. Actions are typically displayed by 747 * the system as a button adjacent to the notification content. 748 * <br> 749 * Action buttons won't appear on platforms prior to Android 4.1. Action 750 * buttons depend on expanded notifications, which are only available in Android 4.1 751 * and later. To ensure that an action button's functionality is always available, first 752 * implement the functionality in the {@link android.app.Activity} that starts when a user 753 * clicks the notification (see {@link #setContentIntent setContentIntent()}), and then 754 * enhance the notification by implementing the same functionality with 755 * {@link #addAction addAction()}. 756 * 757 * @param icon Resource ID of a drawable that represents the action. 758 * @param title Text describing the action. 759 * @param intent {@link android.app.PendingIntent} to be fired when the action is invoked. 760 */ 761 public Builder addAction(int icon, CharSequence title, PendingIntent intent) { 762 mActions.add(new Action(icon, title, intent)); 763 return this; 764 } 765 766 /** 767 * Add a rich notification style to be applied at build time. 768 * <br> 769 * If the platform does not provide rich notification styles, this method has no effect. The 770 * user will always see the normal notification style. 771 * 772 * @param style Object responsible for modifying the notification style. 773 */ 774 public Builder setStyle(Style style) { 775 if (mStyle != style) { 776 mStyle = style; 777 if (mStyle != null) { 778 mStyle.setBuilder(this); 779 } 780 } 781 return this; 782 } 783 784 /** 785 * @deprecated Use {@link #build()} instead. 786 */ 787 @Deprecated 788 public Notification getNotification() { 789 return (Notification) IMPL.build(this); 790 } 791 792 /** 793 * Combine all of the options that have been set and return a new {@link Notification} 794 * object. 795 */ 796 public Notification build() { 797 return (Notification) IMPL.build(this); 798 } 799 } 800 801 /** 802 * An object that can apply a rich notification style to a {@link Notification.Builder} 803 * object. 804 * <br> 805 * If the platform does not provide rich notification styles, methods in this class have no 806 * effect. 807 */ 808 public static abstract class Style 809 { 810 Builder mBuilder; 811 CharSequence mBigContentTitle; 812 CharSequence mSummaryText; 813 boolean mSummaryTextSet = false; 814 815 public void setBuilder(Builder builder) { 816 if (mBuilder != builder) { 817 mBuilder = builder; 818 if (mBuilder != null) { 819 mBuilder.setStyle(this); 820 } 821 } 822 } 823 824 public Notification build() { 825 Notification notification = null; 826 if (mBuilder != null) { 827 notification = mBuilder.build(); 828 } 829 return notification; 830 } 831 } 832 833 /** 834 * Helper class for generating large-format notifications that include a large image attachment. 835 * <br> 836 * If the platform does not provide large-format notifications, this method has no effect. The 837 * user will always see the normal notification view. 838 * <br> 839 * This class is a "rebuilder": It attaches to a Builder object and modifies its behavior, like so: 840 * <pre class="prettyprint"> 841 * Notification noti = new Notification.Builder() 842 * .setContentTitle("New photo from " + sender.toString()) 843 * .setContentText(subject) 844 * .setSmallIcon(R.drawable.new_post) 845 * .setLargeIcon(aBitmap) 846 * .setStyle(new Notification.BigPictureStyle() 847 * .bigPicture(aBigBitmap)) 848 * .build(); 849 * </pre> 850 * 851 * @see Notification#bigContentView 852 */ 853 public static class BigPictureStyle extends Style { 854 Bitmap mPicture; 855 Bitmap mBigLargeIcon; 856 boolean mBigLargeIconSet; 857 858 public BigPictureStyle() { 859 } 860 861 public BigPictureStyle(Builder builder) { 862 setBuilder(builder); 863 } 864 865 /** 866 * Overrides ContentTitle in the big form of the template. 867 * This defaults to the value passed to setContentTitle(). 868 */ 869 public BigPictureStyle setBigContentTitle(CharSequence title) { 870 mBigContentTitle = title; 871 return this; 872 } 873 874 /** 875 * Set the first line of text after the detail section in the big form of the template. 876 */ 877 public BigPictureStyle setSummaryText(CharSequence cs) { 878 mSummaryText = cs; 879 mSummaryTextSet = true; 880 return this; 881 } 882 883 /** 884 * Provide the bitmap to be used as the payload for the BigPicture notification. 885 */ 886 public BigPictureStyle bigPicture(Bitmap b) { 887 mPicture = b; 888 return this; 889 } 890 891 /** 892 * Override the large icon when the big notification is shown. 893 */ 894 public BigPictureStyle bigLargeIcon(Bitmap b) { 895 mBigLargeIcon = b; 896 mBigLargeIconSet = true; 897 return this; 898 } 899 } 900 901 /** 902 * Helper class for generating large-format notifications that include a lot of text. 903 * 904 * <br> 905 * If the platform does not provide large-format notifications, this method has no effect. The 906 * user will always see the normal notification view. 907 * <br> 908 * This class is a "rebuilder": It attaches to a Builder object and modifies its behavior, like so: 909 * <pre class="prettyprint"> 910 * Notification noti = new Notification.Builder() 911 * .setContentTitle("New mail from " + sender.toString()) 912 * .setContentText(subject) 913 * .setSmallIcon(R.drawable.new_mail) 914 * .setLargeIcon(aBitmap) 915 * .setStyle(new Notification.BigTextStyle() 916 * .bigText(aVeryLongString)) 917 * .build(); 918 * </pre> 919 * 920 * @see Notification#bigContentView 921 */ 922 public static class BigTextStyle extends Style { 923 CharSequence mBigText; 924 925 public BigTextStyle() { 926 } 927 928 public BigTextStyle(Builder builder) { 929 setBuilder(builder); 930 } 931 932 /** 933 * Overrides ContentTitle in the big form of the template. 934 * This defaults to the value passed to setContentTitle(). 935 */ 936 public BigTextStyle setBigContentTitle(CharSequence title) { 937 mBigContentTitle = title; 938 return this; 939 } 940 941 /** 942 * Set the first line of text after the detail section in the big form of the template. 943 */ 944 public BigTextStyle setSummaryText(CharSequence cs) { 945 mSummaryText = cs; 946 mSummaryTextSet = true; 947 return this; 948 } 949 950 /** 951 * Provide the longer text to be displayed in the big form of the 952 * template in place of the content text. 953 */ 954 public BigTextStyle bigText(CharSequence cs) { 955 mBigText = cs; 956 return this; 957 } 958 } 959 960 /** 961 * Helper class for generating large-format notifications that include a list of (up to 5) strings. 962 * 963 * <br> 964 * If the platform does not provide large-format notifications, this method has no effect. The 965 * user will always see the normal notification view. 966 * <br> 967 * This class is a "rebuilder": It attaches to a Builder object and modifies its behavior, like so: 968 * <pre class="prettyprint"> 969 * Notification noti = new Notification.Builder() 970 * .setContentTitle("5 New mails from " + sender.toString()) 971 * .setContentText(subject) 972 * .setSmallIcon(R.drawable.new_mail) 973 * .setLargeIcon(aBitmap) 974 * .setStyle(new Notification.InboxStyle() 975 * .addLine(str1) 976 * .addLine(str2) 977 * .setContentTitle("") 978 * .setSummaryText("+3 more")) 979 * .build(); 980 * </pre> 981 * 982 * @see Notification#bigContentView 983 */ 984 public static class InboxStyle extends Style { 985 ArrayList<CharSequence> mTexts = new ArrayList<CharSequence>(); 986 987 public InboxStyle() { 988 } 989 990 public InboxStyle(Builder builder) { 991 setBuilder(builder); 992 } 993 994 /** 995 * Overrides ContentTitle in the big form of the template. 996 * This defaults to the value passed to setContentTitle(). 997 */ 998 public InboxStyle setBigContentTitle(CharSequence title) { 999 mBigContentTitle = title; 1000 return this; 1001 } 1002 1003 /** 1004 * Set the first line of text after the detail section in the big form of the template. 1005 */ 1006 public InboxStyle setSummaryText(CharSequence cs) { 1007 mSummaryText = cs; 1008 mSummaryTextSet = true; 1009 return this; 1010 } 1011 1012 /** 1013 * Append a line to the digest section of the Inbox notification. 1014 */ 1015 public InboxStyle addLine(CharSequence cs) { 1016 mTexts.add(cs); 1017 return this; 1018 } 1019 } 1020 1021 public static class Action { 1022 public int icon; 1023 public CharSequence title; 1024 public PendingIntent actionIntent; 1025 1026 public Action(int icon_, CharSequence title_, PendingIntent intent_) { 1027 this.icon = icon_; 1028 this.title = title_; 1029 this.actionIntent = intent_; 1030 } 1031 } 1032} 1033