Update javadocs for heads up behavior.
The heads up notification is influences by full screen, sound,
vibration and priority. Update the documentation on those APIs to
explain this.
Also add some draft documentation for hidden API surfaces.
Bug: 15509793
Change-Id: Ie7dc99d9c1acf873782bdd010cdf28d11da256d7
diff --git a/core/java/android/app/Notification.java b/core/java/android/app/Notification.java
index 55abdb6..debe68a 100644
--- a/core/java/android/app/Notification.java
+++ b/core/java/android/app/Notification.java
@@ -91,7 +91,10 @@
* Use the default notification sound. This will ignore any given
* {@link #sound}.
*
-
+ * <p>
+ * A notification that is noisy is more likely to be presented as a heads-up notification.
+ * </p>
+ *
* @see #defaults
*/
@@ -102,6 +105,10 @@
* {@link #vibrate}. Using phone vibration requires the
* {@link android.Manifest.permission#VIBRATE VIBRATE} permission.
*
+ * <p>
+ * A notification that vibrates is more likely to be presented as a heads-up notification.
+ * </p>
+ *
* @see #defaults
*/
@@ -195,6 +202,11 @@
/**
* An intent to launch instead of posting the notification to the status bar.
*
+ * <p>
+ * The system UI may choose to display a heads-up notification, instead of
+ * launching this intent, while the user is using the device.
+ * </p>
+ *
* @see Notification.Builder#setFullScreenIntent
*/
public PendingIntent fullScreenIntent;
@@ -228,9 +240,10 @@
/**
* @hide
- * A medium-format version of {@link #contentView}, giving the Notification an
- * opportunity to add action buttons to contentView. The system UI may
- * choose to show this as a popup notification at its discretion.
+ * A medium-format version of {@link #contentView}, providing the Notification an
+ * opportunity to add action buttons to contentView. At its discretion, the system UI may
+ * choose to show this as a heads-up notification, which will pop up so the user can see
+ * it without leaving their current activity.
*/
public RemoteViews headsUpContentView;
@@ -243,6 +256,10 @@
* The sound to play.
*
* <p>
+ * A notification that is noisy is more likely to be presented as a heads-up notification.
+ * </p>
+ *
+ * <p>
* To play the default notification sound, see {@link #defaults}.
* </p>
*/
@@ -269,6 +286,10 @@
* To vibrate the default pattern, see {@link #defaults}.
* </p>
*
+ * <p>
+ * A notification that vibrates is more likely to be presented as a heads-up notification.
+ * </p>
+ *
* @see android.os.Vibrator#vibrate(long[],int)
*/
public long[] vibrate;
@@ -443,6 +464,12 @@
* situations, while the user might be interrupted for a higher-priority notification. The
* system will make a determination about how to interpret this priority when presenting
* the notification.
+ *
+ * <p>
+ * A notification that is at least {@link #PRIORITY_HIGH} is more likely to be presented
+ * as a heads-up notification.
+ * </p>
+ *
*/
@Priority
public int priority;
@@ -724,7 +751,8 @@
public static final String EXTRA_SCORE_MODIFIED = "android.scoreModified";
/**
- * Not used.
+ * {@link #extras} key: used to provide hints about the appropriateness of
+ * displaying this notification as a heads-up notification.
* @hide
*/
public static final String EXTRA_AS_HEADS_UP = "headsup";
@@ -755,19 +783,27 @@
public static final String EXTRA_MEDIA_SESSION = "android.mediaSession";
/**
- * Value for {@link #EXTRA_AS_HEADS_UP}.
+ * Value for {@link #EXTRA_AS_HEADS_UP} that indicates this notification should not be
+ * displayed in the heads up space.
+ *
+ * <p>
+ * If this notification has a {@link #fullScreenIntent}, then it will always launch the
+ * full-screen intent when posted.
+ * </p>
* @hide
*/
public static final int HEADS_UP_NEVER = 0;
/**
- * Default value for {@link #EXTRA_AS_HEADS_UP}.
+ * Default value for {@link #EXTRA_AS_HEADS_UP} that indicates this notification may be
+ * displayed as a heads up.
* @hide
*/
public static final int HEADS_UP_ALLOWED = 1;
/**
- * Value for {@link #EXTRA_AS_HEADS_UP}.
+ * Value for {@link #EXTRA_AS_HEADS_UP} that indicates this notification is a
+ * good candidate for display as a heads up.
* @hide
*/
public static final int HEADS_UP_REQUESTED = 2;
@@ -1903,6 +1939,11 @@
* to turn it off and use a normal notification, as this can be extremely
* disruptive.
*
+ * <p>
+ * The system UI may choose to display a heads-up notification, instead of
+ * launching this intent, while the user is using the device.
+ * </p>
+ *
* @param intent The pending intent to launch.
* @param highPriority Passing true will cause this notification to be sent
* even if other notifications are suppressed.
@@ -1958,6 +1999,10 @@
*
* It will be played on the {@link #STREAM_DEFAULT default stream} for notifications.
*
+ * <p>
+ * A notification that is noisy is more likely to be presented as a heads-up notification.
+ * </p>
+ *
* @see Notification#sound
*/
public Builder setSound(Uri sound) {
@@ -1971,6 +2016,10 @@
*
* See {@link android.media.AudioManager} for the <code>STREAM_</code> constants.
*
+ * <p>
+ * A notification that is noisy is more likely to be presented as a heads-up notification.
+ * </p>
+ *
* @see Notification#sound
*/
public Builder setSound(Uri sound, int streamType) {
@@ -1982,11 +2031,13 @@
/**
* Set the vibration pattern to use.
*
-
* See {@link android.os.Vibrator#vibrate(long[], int)} for a discussion of the
* <code>pattern</code> parameter.
*
-
+ * <p>
+ * A notification that vibrates is more likely to be presented as a heads-up notification.
+ * </p>
+ *
* @see Notification#vibrate
*/
public Builder setVibrate(long[] pattern) {
