am 723ad75e: Merge "API cleanups for Notification." into klp-dev (a3ea0441) · Commits · e / os / android_frameworks_base

api/current.txt

+1 −5

core/java/android/app/Notification.java

+170 −31

Original line number	Original line	Diff line number	Diff line
	@@ -441,28 +441,119 @@ public class Notification implements Parcelable

	/**		/**
	* Additional semantic data to be carried around with this Notification.		* Additional semantic data to be carried around with this Notification.
			* <p>
			* The extras keys defined here are intended to capture the original inputs to {@link Builder}
			* APIs, and are intended to be used by
			* {@link android.service.notification.NotificationListenerService} implementations to extract
			* detailed information from notification objects.
	*/		*/
	public Bundle extras = new Bundle();		public Bundle extras = new Bundle();

	// extras keys for Builder inputs		/**
			* {@link #extras} key: this is the title of the notification,
			* as supplied to {@link Builder#setContentTitle(CharSequence)}.
			*/
	public static final String EXTRA_TITLE = "android.title";		public static final String EXTRA_TITLE = "android.title";

			/**
			* {@link #extras} key: this is the title of the notification when shown in expanded form,
			* e.g. as supplied to {@link BigTextStyle#setBigContentTitle(CharSequence)}.
			*/
	public static final String EXTRA_TITLE_BIG = EXTRA_TITLE + ".big";		public static final String EXTRA_TITLE_BIG = EXTRA_TITLE + ".big";

			/**
			* {@link #extras} key: this is the main text payload, as supplied to
			* {@link Builder#setContentText(CharSequence)}.
			*/
	public static final String EXTRA_TEXT = "android.text";		public static final String EXTRA_TEXT = "android.text";

			/**
			* {@link #extras} key: this is a third line of text, as supplied to
			* {@link Builder#setSubText(CharSequence)}.
			*/
	public static final String EXTRA_SUB_TEXT = "android.subText";		public static final String EXTRA_SUB_TEXT = "android.subText";

			/**
			* {@link #extras} key: this is a small piece of additional text as supplied to
			* {@link Builder#setContentInfo(CharSequence)}.
			*/
	public static final String EXTRA_INFO_TEXT = "android.infoText";		public static final String EXTRA_INFO_TEXT = "android.infoText";

			/**
			* {@link #extras} key: this is a line of summary information intended to be shown
			* alongside expanded notifications, as supplied to (e.g.)
			* {@link BigTextStyle#setSummaryText(CharSequence)}.
			*/
	public static final String EXTRA_SUMMARY_TEXT = "android.summaryText";		public static final String EXTRA_SUMMARY_TEXT = "android.summaryText";

			/**
			* {@link #extras} key: this is the resource ID of the notification's main small icon, as
			* supplied to {@link Builder#setSmallIcon(int)}.
			*/
	public static final String EXTRA_SMALL_ICON = "android.icon";		public static final String EXTRA_SMALL_ICON = "android.icon";

			/**
			* {@link #extras} key: this is a bitmap to be used instead of the small icon when showing the
			* notification payload, as
			* supplied to {@link Builder#setLargeIcon(android.graphics.Bitmap)}.
			*/
	public static final String EXTRA_LARGE_ICON = "android.largeIcon";		public static final String EXTRA_LARGE_ICON = "android.largeIcon";

			/**
			* {@link #extras} key: this is a bitmap to be used instead of the one from
			* {@link Builder#setLargeIcon(android.graphics.Bitmap)} when the notification is
			* shown in its expanded form, as supplied to
			* {@link BigPictureStyle#bigLargeIcon(android.graphics.Bitmap)}.
			*/
	public static final String EXTRA_LARGE_ICON_BIG = EXTRA_LARGE_ICON + ".big";		public static final String EXTRA_LARGE_ICON_BIG = EXTRA_LARGE_ICON + ".big";

			/**
			* {@link #extras} key: this is the progress value supplied to
			* {@link Builder#setProgress(int, int, boolean)}.
			*/
	public static final String EXTRA_PROGRESS = "android.progress";		public static final String EXTRA_PROGRESS = "android.progress";

			/**
			* {@link #extras} key: this is the maximum value supplied to
			* {@link Builder#setProgress(int, int, boolean)}.
			*/
	public static final String EXTRA_PROGRESS_MAX = "android.progressMax";		public static final String EXTRA_PROGRESS_MAX = "android.progressMax";

			/**
			* {@link #extras} key: whether the progress bar is indeterminate, supplied to
			* {@link Builder#setProgress(int, int, boolean)}.
			*/
	public static final String EXTRA_PROGRESS_INDETERMINATE = "android.progressIndeterminate";		public static final String EXTRA_PROGRESS_INDETERMINATE = "android.progressIndeterminate";

			/**
			* {@link #extras} key: whether {@link #when} should be shown as a count-up timer (specifically
			* a {@link android.widget.Chronometer}) instead of a timestamp, as supplied to
			* {@link Builder#setUsesChronometer(boolean)}.
			*/
	public static final String EXTRA_SHOW_CHRONOMETER = "android.showChronometer";		public static final String EXTRA_SHOW_CHRONOMETER = "android.showChronometer";

			/**
			* {@link #extras} key: whether {@link #when} should be shown,
			* as supplied to {@link Builder#setShowWhen(boolean)}.
			*/
	public static final String EXTRA_SHOW_WHEN = "android.showWhen";		public static final String EXTRA_SHOW_WHEN = "android.showWhen";

			/**
			* {@link #extras} key: this is a bitmap to be shown in {@link BigPictureStyle} expanded
			* notifications, supplied to {@link BigPictureStyle#bigPicture(android.graphics.Bitmap)}.
			*/
	public static final String EXTRA_PICTURE = "android.picture";		public static final String EXTRA_PICTURE = "android.picture";

			/**
			* {@link #extras} key: An array of CharSequences to show in {@link InboxStyle} expanded
			* notifications, each of which was supplied to {@link InboxStyle#addLine(CharSequence)}.
			*/
	public static final String EXTRA_TEXT_LINES = "android.textLines";		public static final String EXTRA_TEXT_LINES = "android.textLines";

	// extras keys for other interesting pieces of information		/**
			* {@link #extras} key: An array of people that this notification relates to, specified
			* by contacts provider contact URI.
			*/
	public static final String EXTRA_PEOPLE = "android.people";		public static final String EXTRA_PEOPLE = "android.people";

	/**		/**
	@@ -473,38 +564,53 @@ public class Notification implements Parcelable
	public static final String EXTRA_SCORE_MODIFIED = "android.scoreModified";		public static final String EXTRA_SCORE_MODIFIED = "android.scoreModified";

	/**		/**
	* Notification extra to specify heads up display preference.		* Not used.
	* @hide		* @hide
	*/		*/
	public static final String EXTRA_AS_HEADS_UP = "headsup";		public static final String EXTRA_AS_HEADS_UP = "headsup";

	/**		/**
	* Value for {@link #EXTRA_AS_HEADS_UP} indicating that heads up display is not appropriate.		* Value for {@link #EXTRA_AS_HEADS_UP}.
	* @hide		* @hide
	*/		*/
	public static final int HEADS_UP_NEVER = 0;		public static final int HEADS_UP_NEVER = 0;

	/**		/**
	* Default value for {@link #EXTRA_AS_HEADS_UP} indicating that heads up display is appropriate.		* Default value for {@link #EXTRA_AS_HEADS_UP}.
	* @hide		* @hide
	*/		*/
	public static final int HEADS_UP_ALLOWED = 1;		public static final int HEADS_UP_ALLOWED = 1;

	/**		/**
	* Value for {@link #EXTRA_AS_HEADS_UP} that advocates for heads up display.		* Value for {@link #EXTRA_AS_HEADS_UP}.
	* @hide		* @hide
	*/		*/
	public static final int HEADS_UP_REQUESTED = 2;		public static final int HEADS_UP_REQUESTED = 2;

	/**		/**
	* Structure to encapsulate an "action", including title and icon, that can be attached to a Notification.		* Structure to encapsulate a named action that can be shown as part of this notification.
			* It must include an icon, a label, and a {@link PendingIntent} to be fired when the action is
			* selected by the user.
			* <p>
			* Apps should use {@link Builder#addAction(int, CharSequence, PendingIntent)} to create and
			* attach actions.
	*/		*/
	public static class Action implements Parcelable {		public static class Action implements Parcelable {
			/**
			* Small icon representing the action.
			*/
	public int icon;		public int icon;
			/**
			* Title of the action.
			*/
	public CharSequence title;		public CharSequence title;
			/**
			* Intent to send when the user invokes this action. May be null, in which case the action
			* may be rendered in a disabled presentation by the system UI.
			*/
	public PendingIntent actionIntent;		public PendingIntent actionIntent;
	@SuppressWarnings("unused")
	public Action() { }		private Action() { }
	private Action(Parcel in) {		private Action(Parcel in) {
	icon = in.readInt();		icon = in.readInt();
	title = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(in);		title = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(in);
	@@ -512,16 +618,20 @@ public class Notification implements Parcelable
	actionIntent = PendingIntent.CREATOR.createFromParcel(in);		actionIntent = PendingIntent.CREATOR.createFromParcel(in);
	}		}
	}		}
	public Action(int icon_, CharSequence title_, PendingIntent intent_) {		/**
	this.icon = icon_;		* Use {@link Builder#addAction(int, CharSequence, PendingIntent)}.
	this.title = title_;		*/
	this.actionIntent = intent_;		public Action(int icon, CharSequence title, PendingIntent intent) {
			this.icon = icon;
			this.title = title;
			this.actionIntent = intent;
	}		}

	@Override		@Override
	public Action clone() {		public Action clone() {
	return new Action(		return new Action(
	this.icon,		this.icon,
	this.title.toString(),		this.title,
	this.actionIntent // safe to alias		this.actionIntent // safe to alias
	);		);
	}		}
	@@ -551,6 +661,12 @@ public class Notification implements Parcelable
	};		};
	}		}

			/**
			* Array of all {@link Action} structures attached to this notification by
			* {@link Builder#addAction(int, CharSequence, PendingIntent)}. Mostly useful for instances of
			* {@link android.service.notification.NotificationListenerService} that provide an alternative
			* interface for invoking actions.
			*/
	public Action[] actions;		public Action[] actions;

	/**		/**
	@@ -1477,8 +1593,15 @@ public class Notification implements Parcelable
	/**		/**
	* Add an action to this notification. Actions are typically displayed by		* Add an action to this notification. Actions are typically displayed by
	* the system as a button adjacent to the notification content.		* the system as a button adjacent to the notification content.
	* <br>		* <p>
	* A notification displays up to 3 actions, from left to right in the order they were added.		* Every action must have an icon (32dp square and matching the
			* <a href="{@docRoot}design/style/iconography.html#action-bar">Holo
			* Dark action bar</a> visual style), a textual label, and a {@link PendingIntent}.
			* <p>
			* A notification in its expanded form can display up to 3 actions, from left to right in
			* the order they were added. Actions will not be displayed when the notification is
			* collapsed, however, so be sure that any essential functions may be accessed by the user
			* in some other way (for example, in the Activity pointed to by {@link #contentIntent}).
	*		*
	* @param icon Resource ID of a drawable that represents the action.		* @param icon Resource ID of a drawable that represents the action.
	* @param title Text describing the action.		* @param title Text describing the action.
	@@ -1675,8 +1798,9 @@ public class Notification implements Parcelable

	/**		/**
	* Apply the unstyled operations and return a new {@link Notification} object.		* Apply the unstyled operations and return a new {@link Notification} object.
			* @hide
	*/		*/
	private Notification buildUnstyled() {		public Notification buildUnstyled() {
	Notification n = new Notification();		Notification n = new Notification();
	n.when = mWhen;		n.when = mWhen;
	n.icon = mSmallIcon;		n.icon = mSmallIcon;
	@@ -1754,12 +1878,10 @@ public class Notification implements Parcelable
	* object.		* object.
	*/		*/
	public Notification build() {		public Notification build() {
	final Notification n;		Notification n = buildUnstyled();

	if (mStyle != null) {		if (mStyle != null) {
	n = mStyle.build();		n = mStyle.buildStyled(n);
	} else {
	n = buildUnstyled();
	}		}

	n.extras = mExtras != null ? new Bundle(mExtras) : new Bundle();		n.extras = mExtras != null ? new Bundle(mExtras) : new Bundle();
	@@ -1869,7 +1991,21 @@ public class Notification implements Parcelable
	}		}
	}		}

	public abstract Notification build();		/**
			* @hide
			*/
			public abstract Notification buildStyled(Notification wip);

			/**
			* Calls {@link android.app.Notification.Builder#build()} on the Builder this Style is
			* attached to.
			*
			* @return the fully constructed Notification.
			*/
			public Notification build() {
			checkBuilder();
			return mBuilder.build();
			}
	}		}

	/**		/**
	@@ -1955,10 +2091,11 @@ public class Notification implements Parcelable
	extras.putParcelable(EXTRA_PICTURE, mPicture);		extras.putParcelable(EXTRA_PICTURE, mPicture);
	}		}

			/**
			* @hide
			*/
	@Override		@Override
	public Notification build() {		public Notification buildStyled(Notification wip) {
	checkBuilder();
	Notification wip = mBuilder.buildUnstyled();
	if (mBigLargeIconSet ) {		if (mBigLargeIconSet ) {
	mBuilder.mLargeIcon = mBigLargeIcon;		mBuilder.mLargeIcon = mBigLargeIcon;
	}		}
	@@ -2048,10 +2185,11 @@ public class Notification implements Parcelable
	return contentView;		return contentView;
	}		}

			/**
			* @hide
			*/
	@Override		@Override
	public Notification build() {		public Notification buildStyled(Notification wip) {
	checkBuilder();
	Notification wip = mBuilder.buildUnstyled();
	wip.bigContentView = makeBigContentView();		wip.bigContentView = makeBigContentView();

	wip.extras.putCharSequence(EXTRA_TEXT, mBigText);		wip.extras.putCharSequence(EXTRA_TEXT, mBigText);
	@@ -2159,10 +2297,11 @@ public class Notification implements Parcelable
	return contentView;		return contentView;
	}		}

			/**
			* @hide
			*/
	@Override		@Override
	public Notification build() {		public Notification buildStyled(Notification wip) {
	checkBuilder();
	Notification wip = mBuilder.buildUnstyled();
	wip.bigContentView = makeBigContentView();		wip.bigContentView = makeBigContentView();

	return wip;		return wip;

Original line number	Original line	Diff line number	Diff line
	@@ -3986,7 +3986,6 @@ package android.app {
	}		}

	public static class Notification.Action implements android.os.Parcelable {		public static class Notification.Action implements android.os.Parcelable {
	ctor public Notification.Action();
	ctor public Notification.Action(int, java.lang.CharSequence, android.app.PendingIntent);		ctor public Notification.Action(int, java.lang.CharSequence, android.app.PendingIntent);
	method public android.app.Notification.Action clone();		method public android.app.Notification.Action clone();
	method public int describeContents();		method public int describeContents();
	@@ -4002,7 +4001,6 @@ package android.app {
	ctor public Notification.BigPictureStyle(android.app.Notification.Builder);		ctor public Notification.BigPictureStyle(android.app.Notification.Builder);
	method public android.app.Notification.BigPictureStyle bigLargeIcon(android.graphics.Bitmap);		method public android.app.Notification.BigPictureStyle bigLargeIcon(android.graphics.Bitmap);
	method public android.app.Notification.BigPictureStyle bigPicture(android.graphics.Bitmap);		method public android.app.Notification.BigPictureStyle bigPicture(android.graphics.Bitmap);
	method public android.app.Notification build();
	method public android.app.Notification.BigPictureStyle setBigContentTitle(java.lang.CharSequence);		method public android.app.Notification.BigPictureStyle setBigContentTitle(java.lang.CharSequence);
	method public android.app.Notification.BigPictureStyle setSummaryText(java.lang.CharSequence);		method public android.app.Notification.BigPictureStyle setSummaryText(java.lang.CharSequence);
	}		}
	@@ -4011,7 +4009,6 @@ package android.app {
	ctor public Notification.BigTextStyle();		ctor public Notification.BigTextStyle();
	ctor public Notification.BigTextStyle(android.app.Notification.Builder);		ctor public Notification.BigTextStyle(android.app.Notification.Builder);
	method public android.app.Notification.BigTextStyle bigText(java.lang.CharSequence);		method public android.app.Notification.BigTextStyle bigText(java.lang.CharSequence);
	method public android.app.Notification build();
	method public android.app.Notification.BigTextStyle setBigContentTitle(java.lang.CharSequence);		method public android.app.Notification.BigTextStyle setBigContentTitle(java.lang.CharSequence);
	method public android.app.Notification.BigTextStyle setSummaryText(java.lang.CharSequence);		method public android.app.Notification.BigTextStyle setSummaryText(java.lang.CharSequence);
	}		}
	@@ -4056,14 +4053,13 @@ package android.app {
	ctor public Notification.InboxStyle();		ctor public Notification.InboxStyle();
	ctor public Notification.InboxStyle(android.app.Notification.Builder);		ctor public Notification.InboxStyle(android.app.Notification.Builder);
	method public android.app.Notification.InboxStyle addLine(java.lang.CharSequence);		method public android.app.Notification.InboxStyle addLine(java.lang.CharSequence);
	method public android.app.Notification build();
	method public android.app.Notification.InboxStyle setBigContentTitle(java.lang.CharSequence);		method public android.app.Notification.InboxStyle setBigContentTitle(java.lang.CharSequence);
	method public android.app.Notification.InboxStyle setSummaryText(java.lang.CharSequence);		method public android.app.Notification.InboxStyle setSummaryText(java.lang.CharSequence);
	}		}

	public static abstract class Notification.Style {		public static abstract class Notification.Style {
	ctor public Notification.Style();		ctor public Notification.Style();
	method public abstract android.app.Notification build();		method public android.app.Notification build();
	method protected void checkBuilder();		method protected void checkBuilder();
	method protected android.widget.RemoteViews getStandardView(int);		method protected android.widget.RemoteViews getStandardView(int);
	method protected void internalSetBigContentTitle(java.lang.CharSequence);		method protected void internalSetBigContentTitle(java.lang.CharSequence);