Merge "Clean up night mode documentation" (dbea715a) · Commits · e / os / android_frameworks_base

core/java/android/app/UiModeManager.java

+55 −22

Original line number	Diff line number	Diff line
		@@ -16,12 +16,16 @@

		package android.app;

		import android.annotation.IntDef;
		import android.content.Context;
		import android.content.res.Configuration;
		import android.os.RemoteException;
		import android.os.ServiceManager;
		import android.util.Log;

		import java.lang.annotation.Retention;
		import java.lang.annotation.RetentionPolicy;

		/**
		* This class provides access to the system uimode services. These services
		* allow applications to control UI modes of the device.
		@@ -93,17 +97,25 @@ public class UiModeManager {
		*/
		public static String ACTION_EXIT_DESK_MODE = "android.app.action.EXIT_DESK_MODE";

		/** Constant for {@link #setNightMode(int)} and {@link #getNightMode()}:
		/** @hide */
		@IntDef({MODE_NIGHT_AUTO, MODE_NIGHT_NO, MODE_NIGHT_YES})
		@Retention(RetentionPolicy.SOURCE)
		public @interface NightMode {}

		/**
		* Constant for {@link #setNightMode(int)} and {@link #getNightMode()}:
		* automatically switch night mode on and off based on the time.
		*/
		public static final int MODE_NIGHT_AUTO = Configuration.UI_MODE_NIGHT_UNDEFINED >> 4;

		/** Constant for {@link #setNightMode(int)} and {@link #getNightMode()}:
		/**
		* Constant for {@link #setNightMode(int)} and {@link #getNightMode()}:
		* never run in night mode.
		*/
		public static final int MODE_NIGHT_NO = Configuration.UI_MODE_NIGHT_NO >> 4;

		/** Constant for {@link #setNightMode(int)} and {@link #getNightMode()}:
		/**
		* Constant for {@link #setNightMode(int)} and {@link #getNightMode()}:
		* always run in night mode.
		*/
		public static final int MODE_NIGHT_YES = Configuration.UI_MODE_NIGHT_YES >> 4;
		@@ -195,20 +207,28 @@ public class UiModeManager {
		}

		/**
		* Sets the night mode. Changes to the night mode are only effective when
		* the car or desk mode is enabled on a device.
		*
		* <p>The mode can be one of:
		* Sets the night mode.
		* <p>
		* The mode can be one of:
		* <ul>
		* <li><em>{@link #MODE_NIGHT_NO}<em> - sets the device into notnight
		* mode.</li>
		* <li><em>{@link #MODE_NIGHT_YES}</em> - sets the device into night mode.
		* </li>
		* <li><em>{@link #MODE_NIGHT_AUTO}</em> - automatic night/notnight switching
		* depending on the location and certain other sensors.</li>
		* <li><em>{@link #MODE_NIGHT_NO}<em> sets the device into
		* {@code notnight} mode</li>
		* <li><em>{@link #MODE_NIGHT_YES}</em> sets the device into
		* {@code night} mode</li>
		* <li><em>{@link #MODE_NIGHT_AUTO}</em> automatically switches between
		* {@code night} and {@code notnight} based on the device's current
		* location and certain other sensors</li>
		* </ul>
		* <p>
		* <strong>Note:</strong> On API 22 and below, changes to the night mode
		* are only effective when the {@link Configuration#UI_MODE_TYPE_CAR car}
		* or {@link Configuration#UI_MODE_TYPE_DESK desk} mode is enabled on a
		* device. Starting in API 23, changes to night mode are always effective.
		*
		* @param mode the night mode to set
		* @see #getNightMode()
		*/
		public void setNightMode(int mode) {
		public void setNightMode(@NightMode int mode) {
		if (mService != null) {
		try {
		mService.setNightMode(mode);
		@@ -219,11 +239,20 @@ public class UiModeManager {
		}

		/**
		* @return the currently configured night mode. May be one of
		* {@link #MODE_NIGHT_NO}, {@link #MODE_NIGHT_YES},
		* {@link #MODE_NIGHT_AUTO}, or -1 on error.
		* Returns the currently configured night mode.
		* <p>
		* May be one of:
		* <ul>
		* <li>{@link #MODE_NIGHT_NO}</li>
		* <li>{@link #MODE_NIGHT_YES}</li>
		* <li>{@link #MODE_NIGHT_AUTO}</li>
		* <li>{@code -1} on error</li>
		* </ul>
		*
		* @return the current night mode, or {@code -1} on error
		* @see #setNightMode(int)
		*/
		public int getNightMode() {
		public @NightMode int getNightMode() {
		if (mService != null) {
		try {
		return mService.getNightMode();
		@@ -250,9 +279,13 @@ public class UiModeManager {
		}

		/**
		* @return If Night mode is locked or not. When Night mode is locked, changing Night mode
		* is only allowed to privileged system components and normal application's call
		* to change Night mode using {@link #setNightMode(int)} will silently fail.
		* Returns whether night mode is locked or not.
		* <p>
		* When night mode is locked, only privileged system components may change
		* night mode and calls from non-privileged applications to change night
		* mode will fail silently.
		*
		* @return {@code true} if night mode is locked or {@code false} otherwise
		*/
		public boolean isNightModeLocked() {
		if (mService != null) {