Merge "Update car mode API docs." (f02ac9e4) · Commits · e / os / android_frameworks_base

core/java/android/app/UiModeManager.java

+49 −26

Original line number	Original line	Diff line number	Diff line
	@@ -70,19 +70,26 @@ public class UiModeManager {
	* also monitor this Intent in order to be informed of mode changes or		* also monitor this Intent in order to be informed of mode changes or
	* prevent the normal car UI from being displayed by setting the result		* prevent the normal car UI from being displayed by setting the result
	* of the broadcast to {@link Activity#RESULT_CANCELED}.		* of the broadcast to {@link Activity#RESULT_CANCELED}.
			* <p>
			* This intent is broadcast when {@link #getCurrentModeType()} transitions to
			* {@link Configuration#UI_MODE_TYPE_CAR} from some other ui mode.
	*/		*/
	public static String ACTION_ENTER_CAR_MODE = "android.app.action.ENTER_CAR_MODE";		public static String ACTION_ENTER_CAR_MODE = "android.app.action.ENTER_CAR_MODE";

	/**		/**
	* Broadcast sent when the device's UI has switched to car mode, either by being placed in a car		* Broadcast sent when an app has entered car mode using either {@link #enableCarMode(int)} or
	* dock or explicit action of the user.		* {@link #enableCarMode(int, int)}.
			* <p>
			* Unlike {@link #ACTION_ENTER_CAR_MODE}, which is only sent when the global car mode state
			* (i.e. {@link #getCurrentModeType()}) transitions to {@link Configuration#UI_MODE_TYPE_CAR},
			* this intent is sent any time an app declares it has entered car mode. Thus, this intent is
			* intended for use by a component which needs to know not only when the global car mode state
			* changed, but also when the highest priority app declaring car mode has changed.
	* <p>		* <p>
	* In addition to the behavior for {@link #ACTION_ENTER_CAR_MODE}, this broadcast includes the		* This broadcast includes the package name of the app which requested to enter car mode in
	* package name of the app which requested to enter car mode in the		* {@link #EXTRA_CALLING_PACKAGE}. The priority the app entered car mode at is specified in
	* {@link #EXTRA_CALLING_PACKAGE}. If an app requested to enter car mode using
	* {@link #enableCarMode(int, int)} and specified a priority this will be specified in the
	* {@link #EXTRA_PRIORITY}.		* {@link #EXTRA_PRIORITY}.
	*		* <p>
	* This is primarily intended to be received by other components of the Android OS.		* This is primarily intended to be received by other components of the Android OS.
	* <p>		* <p>
	* Receiver requires permission: {@link android.Manifest.permission.HANDLE_CAR_MODE_CHANGES}		* Receiver requires permission: {@link android.Manifest.permission.HANDLE_CAR_MODE_CHANGES}
	@@ -96,17 +103,25 @@ public class UiModeManager {
	* Broadcast sent when the device's UI has switch away from car mode back		* Broadcast sent when the device's UI has switch away from car mode back
	* to normal mode. Typically used by a car mode app, to dismiss itself		* to normal mode. Typically used by a car mode app, to dismiss itself
	* when the user exits car mode.		* when the user exits car mode.
			* <p>
			* This intent is broadcast when {@link #getCurrentModeType()} transitions from
			* {@link Configuration#UI_MODE_TYPE_CAR} to some other ui mode.
	*/		*/
	public static String ACTION_EXIT_CAR_MODE = "android.app.action.EXIT_CAR_MODE";		public static String ACTION_EXIT_CAR_MODE = "android.app.action.EXIT_CAR_MODE";

	/**		/**
	* Broadcast sent when the device's UI has switched away from car mode back to normal mode.		* Broadcast sent when an app has exited car mode using {@link #disableCarMode(int)}.
	* Typically used by a car mode app, to dismiss itself when the user exits car mode.		* <p>
			* Unlike {@link #ACTION_EXIT_CAR_MODE}, which is only sent when the global car mode state
			* (i.e. {@link #getCurrentModeType()}) transitions to a non-car mode state such as
			* {@link Configuration#UI_MODE_TYPE_NORMAL}, this intent is sent any time an app declares it
			* has exited car mode. Thus, this intent is intended for use by a component which needs to
			* know not only when the global car mode state changed, but also when the highest priority app
			* declaring car mode has changed.
	* <p>		* <p>
	* In addition to the behavior for {@link #ACTION_EXIT_CAR_MODE}, this broadcast includes the		* This broadcast includes the package name of the app which requested to exit car mode in
	* package name of the app which requested to exit car mode in {@link #EXTRA_CALLING_PACKAGE}.		* {@link #EXTRA_CALLING_PACKAGE}. The priority the app originally entered car mode at is
	* If an app requested to enter car mode using {@link #enableCarMode(int, int)} and specified a		* specified in {@link #EXTRA_PRIORITY}.
	* priority this will be specified in the {@link #EXTRA_PRIORITY} when exiting car mode.
	* <p>		* <p>
	* If {@link #DISABLE_CAR_MODE_ALL_PRIORITIES} is used when disabling car mode (i.e. this is		* If {@link #DISABLE_CAR_MODE_ALL_PRIORITIES} is used when disabling car mode (i.e. this is
	* initiated by the user via the persistent car mode notification), this broadcast is sent once		* initiated by the user via the persistent car mode notification), this broadcast is sent once
	@@ -251,9 +266,7 @@ public class UiModeManager {
	* An app may request to enter car mode when the system is already in car mode. The app may		* An app may request to enter car mode when the system is already in car mode. The app may
	* specify a "priority" when entering car mode. The device will remain in car mode		* specify a "priority" when entering car mode. The device will remain in car mode
	* (i.e. {@link #getCurrentModeType()} is {@link Configuration#UI_MODE_TYPE_CAR}) as long as		* (i.e. {@link #getCurrentModeType()} is {@link Configuration#UI_MODE_TYPE_CAR}) as long as
	* there is a priority level at which car mode have been enabled. For example assume app A		* there is a priority level at which car mode have been enabled.
	* enters car mode at priority level 100, and then app B enters car mode at the default priority
	* (0). If app A exits car mode, the device will remain in car mode until app B exits car mode.
	* <p>		* <p>
	* Specifying a priority level when entering car mode is important in cases where multiple apps		* Specifying a priority level when entering car mode is important in cases where multiple apps
	* on a device implement a car-mode {@link android.telecom.InCallService} (see		* on a device implement a car-mode {@link android.telecom.InCallService} (see
	@@ -266,18 +279,28 @@ public class UiModeManager {
	* correct conditions exist for that app to be in car mode. The device maker should ensure that		* correct conditions exist for that app to be in car mode. The device maker should ensure that
	* where multiple apps exist on the device which can potentially enter car mode, appropriate		* where multiple apps exist on the device which can potentially enter car mode, appropriate
	* priorities are used to ensure that calls delivered by the		* priorities are used to ensure that calls delivered by the
	* {@link android.telecom.InCallService} API are delivered to the highest priority app.		* {@link android.telecom.InCallService} API are sent to the highest priority app given the
	* If app A and app B can both potentially enable car mode, and it is desired that app B is the		* desired behavior of the car mode experience on the device.
	* one which should receive call information, the priority for app B should be higher than the		* <p>
	* one for app A.		* If app A and app B both meet their own criteria to enable car mode, and it is desired that
			* app B should be the one which should receive call information in that scenario, the priority
			* for app B should be higher than the one for app A. The higher priority of app B compared to
			* A means it will be bound to during calls and app A will not. When app B no longer meets its
			* criteria for providing a car mode experience it uses {@link #disableCarMode(int)} to disable
			* car mode at its priority level. The system will then unbind from app B and bind to app A as
			* it has the next highest priority.
	* <p>		* <p>
	* When an app uses a priority to enable car mode, they can disable car mode at the specified		* When an app enables car mode at a certain priority, it can disable car mode at the specified
	* priority level using {@link #disableCarMode(int)}. An app may only enable car mode at a		* priority level using {@link #disableCarMode(int)}. An app may only enable car mode at a
	* single priority.		* single priority.
	* <p>		* <p>
	* Public apps are assumed to enter/exit car mode at {@link #DEFAULT_PRIORITY}.		* Public apps are assumed to enter/exit car mode at the lowest priority,
			* {@link #DEFAULT_PRIORITY}.
	*		*
	* @param priority The declared priority for the caller.		* @param priority The declared priority for the caller, where {@link #DEFAULT_PRIORITY} (0) is
			* the lowest priority and higher numbers represent a higher priority.
			* The priorities apps declare when entering car mode is determined by the
			* device manufacturer based on the desired car mode experience.
	* @param flags Car mode flags.		* @param flags Car mode flags.
	* @hide		* @hide
	*/		*/
	@@ -322,11 +345,11 @@ public class UiModeManager {
	/**		/**
	* The default priority used for entering car mode.		* The default priority used for entering car mode.
	* <p>		* <p>
	* Callers of the {@link UiModeManager#enableCarMode(int)} priority will be assigned the		* Callers of the {@link #enableCarMode(int)} priority will be assigned the default priority.
	* default priority.		* This is considered the lowest possible priority for enabling car mode.
	* <p>		* <p>
	* System apps can specify a priority other than the default priority when using		* System apps can specify a priority other than the default priority when using
	* {@link UiModeManager#enableCarMode(int, int)} to enable car mode.		* {@link #enableCarMode(int, int)} to enable car mode.
	* @hide		* @hide
	*/		*/
	@SystemApi		@SystemApi