UiModeManager.java revision 7299c41630935a2b106e73e5603579a7747f7535 
1package android.app;
2
3import android.content.Context;
4import android.content.res.Configuration;
5import android.os.RemoteException;
6import android.os.ServiceManager;
7import android.util.Log;
8
9/**
10 * This class provides access to the system uimode services.  These services
11 * allow applications to control UI modes of the device.
12 * It provides functionality to disable the car mode and it gives access to the
13 * night mode settings.
14 *
15 * <p>These facilities are built on top of the underlying
16 * {@link android.content.Intent#ACTION_DOCK_EVENT} broadcasts that are sent when the user
17 * physical places the device into and out of a dock.  When that happens,
18 * the UiModeManager switches the system {@link android.content.res.Configuration}
19 * to the appropriate UI mode, sends broadcasts about the mode switch, and
20 * starts the corresponding mode activity if appropriate.  See the
21 * broadcasts {@link #ACTION_ENTER_CAR_MODE} and
22 * {@link #ACTION_ENTER_DESK_MODE} for more information.
23 *
24 * <p>In addition, the user may manually switch the system to car mode without
25 * physically being in a dock.  While in car mode -- whether by manual action
26 * from the user or being physically placed in a dock -- a notification is
27 * displayed allowing the user to exit dock mode.  Thus the dock mode
28 * represented here may be different than the current state of the underlying
29 * dock event broadcast.
30 *
31 * <p>You do not instantiate this class directly; instead, retrieve it through
32 * {@link android.content.Context#getSystemService
33 * Context.getSystemService(Context.UI_MODE_SERVICE)}.
34 */
35public class UiModeManager {
36    private static final String TAG = "UiModeManager";
37
38    /**
39     * Broadcast sent when the device's UI has switched to car mode, either
40     * by being placed in a car dock or explicit action of the user.  After
41     * sending the broadcast, the system will start the intent
42     * {@link android.content.Intent#ACTION_MAIN} with category
43     * {@link android.content.Intent#CATEGORY_CAR_DOCK}
44     * to display the car UI, which typically what an application would
45     * implement to provide their own interface.  However, applications can
46     * also monitor this Intent in order to be informed of mode changes or
47     * prevent the normal car UI from being displayed by setting the result
48     * of the broadcast to {@link Activity#RESULT_CANCELED}.
49     */
50    public static String ACTION_ENTER_CAR_MODE = "android.app.action.ENTER_CAR_MODE";
51
52    /**
53     * Broadcast sent when the device's UI has switch away from car mode back
54     * to normal mode.  Typically used by a car mode app, to dismiss itself
55     * when the user exits car mode.
56     */
57    public static String ACTION_EXIT_CAR_MODE = "android.app.action.EXIT_CAR_MODE";
58
59    /**
60     * Broadcast sent when the device's UI has switched to desk mode,
61     * by being placed in a desk dock.  After
62     * sending the broadcast, the system will start the intent
63     * {@link android.content.Intent#ACTION_MAIN} with category
64     * {@link android.content.Intent#CATEGORY_DESK_DOCK}
65     * to display the desk UI, which typically what an application would
66     * implement to provide their own interface.  However, applications can
67     * also monitor this Intent in order to be informed of mode changes or
68     * prevent the normal desk UI from being displayed by setting the result
69     * of the broadcast to {@link Activity#RESULT_CANCELED}.
70     */
71    public static String ACTION_ENTER_DESK_MODE = "android.app.action.ENTER_DESK_MODE";
72
73    /**
74     * Broadcast sent when the device's UI has switch away from car mode back
75     * to normal mode.  Typically used by a car mode app, to dismiss itself
76     * when the user exits car mode.
77     */
78    public static String ACTION_EXIT_DESK_MODE = "android.app.action.EXIT_DESK_MODE";
79
80    /** Constant for {@link #setNightMode(int)} and {@link #getNightMode()}:
81     * automatically switch night mode on and off based on the time.
82     */
83    public static final int MODE_NIGHT_AUTO = Configuration.UI_MODE_NIGHT_UNDEFINED >> 4;
84
85    /** Constant for {@link #setNightMode(int)} and {@link #getNightMode()}:
86     * never run in night mode.
87     */
88    public static final int MODE_NIGHT_NO = Configuration.UI_MODE_NIGHT_NO >> 4;
89
90    /** Constant for {@link #setNightMode(int)} and {@link #getNightMode()}:
91     * always run in night mode.
92     */
93    public static final int MODE_NIGHT_YES = Configuration.UI_MODE_NIGHT_YES >> 4;
94
95    private IUiModeManager mService;
96
97    /*package*/ UiModeManager() {
98        mService = IUiModeManager.Stub.asInterface(
99                ServiceManager.getService(Context.UI_MODE_SERVICE));
100    }
101
102    /**
103     * Turn off special mode if currently in car mode.
104     */
105    public void disableCarMode() {
106        if (mService != null) {
107            try {
108                mService.disableCarMode();
109            } catch (RemoteException e) {
110                Log.e(TAG, "disableCarMode: RemoteException", e);
111            }
112        }
113    }
114
115    /**
116     * Return the current running mode type.  May be one of
117     * {@link Configuration#UI_MODE_TYPE_NORMAL Configuration.UI_MODE_TYPE_NORMAL},
118     * {@link Configuration#UI_MODE_TYPE_DESK Configuration.UI_MODE_TYPE_DESK}, or
119     * {@link Configuration#UI_MODE_TYPE_CAR Configuration.UI_MODE_TYPE_CAR},
120     */
121    public int getCurrentModeType() {
122        if (mService != null) {
123            try {
124                return mService.getCurrentModeType();
125            } catch (RemoteException e) {
126                Log.e(TAG, "getCurrentModeType: RemoteException", e);
127            }
128        }
129        return Configuration.UI_MODE_TYPE_NORMAL;
130    }
131
132    /**
133     * Sets the night mode.  Changes to the night mode are only effective when
134     * the car or desk mode is enabled on a device.
135     *
136     * <p>The mode can be one of:
137     * <ul>
138     *   <li><em>{@link #MODE_NIGHT_NO}<em> - sets the device into notnight
139     *       mode.</li>
140     *   <li><em>{@link #MODE_NIGHT_YES}</em> - sets the device into night mode.
141     *   </li>
142     *   <li><em>{@link #MODE_NIGHT_AUTO}</em> - automatic night/notnight switching
143     *       depending on the location and certain other sensors.</li>
144     * </ul>
145     */
146    public void setNightMode(int mode) {
147        if (mService != null) {
148            try {
149                mService.setNightMode(mode);
150            } catch (RemoteException e) {
151                Log.e(TAG, "setNightMode: RemoteException", e);
152            }
153        }
154    }
155
156    /**
157     * Returns the currently configured night mode.
158     *
159     * @return {@link #MODE_NIGHT_NO}, {@link #MODE_NIGHT_YES}, or
160     *  {@link #MODE_NIGHT_AUTO}.  When an error occurred -1 is returned.
161     */
162    public int getNightMode() {
163        if (mService != null) {
164            try {
165                return mService.getNightMode();
166            } catch (RemoteException e) {
167                Log.e(TAG, "getNightMode: RemoteException", e);
168            }
169        }
170        return -1;
171    }
172}
173