2 * Copyright (C) 2006 The Android Open Source Project
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
19 import android.annotation.IntDef;
20 import android.annotation.SystemApi;
21 import android.content.Context;
22 import android.content.pm.ActivityInfo;
23 import android.content.res.CompatibilityInfo;
24 import android.content.res.Configuration;
25 import android.graphics.Point;
26 import android.graphics.Rect;
27 import android.graphics.RectF;
28 import android.os.Bundle;
29 import android.os.IBinder;
30 import android.os.Looper;
31 import android.view.animation.Animation;
33 import java.io.PrintWriter;
34 import java.lang.annotation.Retention;
35 import java.lang.annotation.RetentionPolicy;
38 * This interface supplies all UI-specific behavior of the window manager. An
39 * instance of it is created by the window manager when it starts up, and allows
40 * customization of window layering, special window types, key dispatching, and
43 * <p>Because this provides deep interaction with the system window manager,
44 * specific methods on this interface can be called from a variety of contexts
45 * with various restrictions on what they can do. These are encoded through
46 * a suffixes at the end of a method encoding the thread the method is called
47 * from and any locks that are held when it is being called; if no suffix
48 * is attached to a method, then it is not called with any locks and may be
49 * called from the main window manager thread or another thread calling into
52 * <p>The current suffixes are:
55 * <dt> Ti <dd> Called from the input thread. This is the thread that
56 * collects pending input events and dispatches them to the appropriate window.
57 * It may block waiting for events to be processed, so that the input stream is
58 * properly serialized.
59 * <dt> Tq <dd> Called from the low-level input queue thread. This is the
60 * thread that reads events out of the raw input devices and places them
61 * into the global input queue that is read by the <var>Ti</var> thread.
62 * This thread should not block for a long period of time on anything but the
64 * <dt> Lw <dd> Called with the main window manager lock held. Because the
65 * window manager is a very low-level system service, there are few other
66 * system services you can call with this lock held. It is explicitly okay to
67 * make calls into the package manager and power manager; it is explicitly not
68 * okay to make calls into the activity manager or most other services. Note that
69 * {@link android.content.Context#checkPermission(String, int, int)} and
70 * variations require calling into the activity manager.
71 * <dt> Li <dd> Called with the input thread lock held. This lock can be
72 * acquired by the window manager while it holds the window lock, so this is
73 * even more restrictive than <var>Lw</var>.
78 public interface WindowManagerPolicy {
79 // Policy flags. These flags are also defined in frameworks/base/include/ui/Input.h.
80 public final static int FLAG_WAKE = 0x00000001;
81 public final static int FLAG_VIRTUAL = 0x00000002;
83 public final static int FLAG_INJECTED = 0x01000000;
84 public final static int FLAG_TRUSTED = 0x02000000;
85 public final static int FLAG_FILTERED = 0x04000000;
86 public final static int FLAG_DISABLE_KEY_REPEAT = 0x08000000;
88 public final static int FLAG_INTERACTIVE = 0x20000000;
89 public final static int FLAG_PASS_TO_USER = 0x40000000;
91 // Flags used for indicating whether the internal and/or external input devices
92 // of some type are available.
93 public final static int PRESENCE_INTERNAL = 1 << 0;
94 public final static int PRESENCE_EXTERNAL = 1 << 1;
96 public final static boolean WATCH_POINTER = false;
99 * Sticky broadcast of the current HDMI plugged state.
101 public final static String ACTION_HDMI_PLUGGED = "android.intent.action.HDMI_PLUGGED";
104 * Extra in {@link #ACTION_HDMI_PLUGGED} indicating the state: true if
105 * plugged in to HDMI, false if not.
107 public final static String EXTRA_HDMI_PLUGGED_STATE = "state";
110 * Set to {@code true} when intent was invoked from pressing the home key.
114 public static final String EXTRA_FROM_HOME_KEY = "android.intent.extra.FROM_HOME_KEY";
117 * Pass this event to the user / app. To be returned from
118 * {@link #interceptKeyBeforeQueueing}.
120 public final static int ACTION_PASS_TO_USER = 0x00000001;
123 * Interface to the Window Manager state associated with a particular
124 * window. You can hold on to an instance of this interface from the call
125 * to prepareAddWindow() until removeWindow().
127 public interface WindowState {
129 * Return the uid of the app that owns this window.
134 * Return the package name of the app that owns this window.
136 String getOwningPackage();
139 * Perform standard frame computation. The result can be obtained with
140 * getFrame() if so desired. Must be called with the window manager
143 * @param parentFrame The frame of the parent container this window
144 * is in, used for computing its basic position.
145 * @param displayFrame The frame of the overall display in which this
146 * window can appear, used for constraining the overall dimensions
148 * @param overlayFrame The frame within the display that is inside
149 * of the overlay region.
150 * @param contentFrame The frame within the display in which we would
151 * like active content to appear. This will cause windows behind to
152 * be resized to match the given content frame.
153 * @param visibleFrame The frame within the display that the window
154 * is actually visible, used for computing its visible insets to be
155 * given to windows behind.
156 * This can be used as a hint for scrolling (avoiding resizing)
157 * the window to make certain that parts of its content
159 * @param decorFrame The decor frame specified by policy specific to this window,
160 * to use for proper cropping during animation.
161 * @param stableFrame The frame around which stable system decoration is positioned.
162 * @param outsetFrame The frame that includes areas that aren't part of the surface but we
163 * want to treat them as such.
165 public void computeFrameLw(Rect parentFrame, Rect displayFrame,
166 Rect overlayFrame, Rect contentFrame, Rect visibleFrame, Rect decorFrame,
167 Rect stableFrame, Rect outsetFrame);
170 * Retrieve the current frame of the window that has been assigned by
171 * the window manager. Must be called with the window manager lock held.
173 * @return Rect The rectangle holding the window frame.
175 public Rect getFrameLw();
178 * Retrieve the current position of the window that is actually shown.
179 * Must be called with the window manager lock held.
181 * @return Point The point holding the shown window position.
183 public Point getShownPositionLw();
186 * Retrieve the frame of the display that this window was last
187 * laid out in. Must be called with the
188 * window manager lock held.
190 * @return Rect The rectangle holding the display frame.
192 public Rect getDisplayFrameLw();
195 * Retrieve the frame of the area inside the overscan region of the
196 * display that this window was last laid out in. Must be called with the
197 * window manager lock held.
199 * @return Rect The rectangle holding the display overscan frame.
201 public Rect getOverscanFrameLw();
204 * Retrieve the frame of the content area that this window was last
205 * laid out in. This is the area in which the content of the window
206 * should be placed. It will be smaller than the display frame to
207 * account for screen decorations such as a status bar or soft
208 * keyboard. Must be called with the
209 * window manager lock held.
211 * @return Rect The rectangle holding the content frame.
213 public Rect getContentFrameLw();
216 * Retrieve the frame of the visible area that this window was last
217 * laid out in. This is the area of the screen in which the window
218 * will actually be fully visible. It will be smaller than the
219 * content frame to account for transient UI elements blocking it
220 * such as an input method's candidates UI. Must be called with the
221 * window manager lock held.
223 * @return Rect The rectangle holding the visible frame.
225 public Rect getVisibleFrameLw();
228 * Returns true if this window is waiting to receive its given
229 * internal insets from the client app, and so should not impact the
230 * layout of other windows.
232 public boolean getGivenInsetsPendingLw();
235 * Retrieve the insets given by this window's client for the content
236 * area of windows behind it. Must be called with the
237 * window manager lock held.
239 * @return Rect The left, top, right, and bottom insets, relative
240 * to the window's frame, of the actual contents.
242 public Rect getGivenContentInsetsLw();
245 * Retrieve the insets given by this window's client for the visible
246 * area of windows behind it. Must be called with the
247 * window manager lock held.
249 * @return Rect The left, top, right, and bottom insets, relative
250 * to the window's frame, of the actual visible area.
252 public Rect getGivenVisibleInsetsLw();
255 * Retrieve the current LayoutParams of the window.
257 * @return WindowManager.LayoutParams The window's internal LayoutParams
260 public WindowManager.LayoutParams getAttrs();
263 * Return whether this window needs the menu key shown. Must be called
264 * with window lock held, because it may need to traverse down through
265 * window list to determine the result.
266 * @param bottom The bottom-most window to consider when determining this.
268 public boolean getNeedsMenuLw(WindowState bottom);
271 * Retrieve the current system UI visibility flags associated with
274 public int getSystemUiVisibility();
277 * Get the layer at which this window's surface will be Z-ordered.
279 public int getSurfaceLayer();
282 * Retrieve the type of the top-level window.
284 * @return the base type of the parent window if attached or its own type otherwise
286 public int getBaseType();
289 * Return the token for the application (actually activity) that owns
290 * this window. May return null for system windows.
292 * @return An IApplicationToken identifying the owning activity.
294 public IApplicationToken getAppToken();
297 * Return true if this window is participating in voice interaction.
299 public boolean isVoiceInteraction();
302 * Return true if, at any point, the application token associated with
303 * this window has actually displayed any windows. This is most useful
304 * with the "starting up" window to determine if any windows were
305 * displayed when it is closed.
307 * @return Returns true if one or more windows have been displayed,
310 public boolean hasAppShownWindows();
313 * Is this window visible? It is not visible if there is no
314 * surface, or we are in the process of running an exit animation
315 * that will remove the surface.
317 boolean isVisibleLw();
320 * Like {@link #isVisibleLw}, but also counts a window that is currently
321 * "hidden" behind the keyguard as visible. This allows us to apply
322 * things like window flags that impact the keyguard.
324 boolean isVisibleOrBehindKeyguardLw();
327 * Is this window currently visible to the user on-screen? It is
328 * displayed either if it is visible or it is currently running an
329 * animation before no longer being visible. Must be called with the
330 * window manager lock held.
332 boolean isDisplayedLw();
335 * Return true if this window (or a window it is attached to, but not
336 * considering its app token) is currently animating.
338 boolean isAnimatingLw();
341 * Is this window considered to be gone for purposes of layout?
343 boolean isGoneForLayoutLw();
346 * Returns true if the window has a surface that it has drawn a
347 * complete UI in to. Note that this is different from {@link #hasDrawnLw()}
348 * in that it also returns true if the window is READY_TO_SHOW, but was not yet
349 * promoted to HAS_DRAWN.
354 * Returns true if this window has been shown on screen at some time in
355 * the past. Must be called with the window manager lock held.
357 public boolean hasDrawnLw();
360 * Can be called by the policy to force a window to be hidden,
361 * regardless of whether the client or window manager would like
362 * it shown. Must be called with the window manager lock held.
363 * Returns true if {@link #showLw} was last called for the window.
365 public boolean hideLw(boolean doAnimation);
368 * Can be called to undo the effect of {@link #hideLw}, allowing a
369 * window to be shown as long as the window manager and client would
370 * also like it to be shown. Must be called with the window manager
372 * Returns true if {@link #hideLw} was last called for the window.
374 public boolean showLw(boolean doAnimation);
377 * Check whether the process hosting this window is currently alive.
379 public boolean isAlive();
382 * Check if window is on {@link Display#DEFAULT_DISPLAY}.
383 * @return true if window is on default display.
385 public boolean isDefaultDisplay();
388 * Check whether the window is currently dimming.
390 public boolean isDimming();
394 * Representation of a input consumer that the policy has added to the
395 * window manager to consume input events going to windows below it.
397 public interface InputConsumer {
399 * Remove the input consumer from the window manager.
405 * Interface for calling back in to the window manager that is private
406 * between it and the policy.
408 public interface WindowManagerFuncs {
409 public static final int LID_ABSENT = -1;
410 public static final int LID_CLOSED = 0;
411 public static final int LID_OPEN = 1;
413 public static final int CAMERA_LENS_COVER_ABSENT = -1;
414 public static final int CAMERA_LENS_UNCOVERED = 0;
415 public static final int CAMERA_LENS_COVERED = 1;
418 * Ask the window manager to re-evaluate the system UI flags.
420 public void reevaluateStatusBarVisibility();
423 * Add a input consumer which will consume all input events going to any window below it.
425 public InputConsumer addInputConsumer(Looper looper,
426 InputEventReceiver.Factory inputEventReceiverFactory);
429 * Returns a code that describes the current state of the lid switch.
431 public int getLidState();
434 * Lock the device now.
436 public void lockDeviceNow();
439 * Returns a code that descripbes whether the camera lens is covered or not.
441 public int getCameraLensCoverState();
444 * Switch the keyboard layout for the given device.
445 * Direction should be +1 or -1 to go to the next or previous keyboard layout.
447 public void switchKeyboardLayout(int deviceId, int direction);
450 * Switch the input method, to be precise, input method subtype.
452 * @param forwardDirection {@code true} to rotate in a forward direction.
454 public void switchInputMethod(boolean forwardDirection);
456 public void shutdown(boolean confirm);
457 public void rebootSafeMode(boolean confirm);
460 * Return the window manager lock needed to correctly call "Lw" methods.
462 public Object getWindowManagerLock();
464 /** Register a system listener for touch events */
465 void registerPointerEventListener(PointerEventListener listener);
467 /** Unregister a system listener for touch events */
468 void unregisterPointerEventListener(PointerEventListener listener);
471 public interface PointerEventListener {
473 * 1. onPointerEvent will be called on the service.UiThread.
474 * 2. motionEvent will be recycled after onPointerEvent returns so if it is needed later a
475 * copy() must be made and the copy must be recycled.
477 public void onPointerEvent(MotionEvent motionEvent);
480 /** Window has been added to the screen. */
481 public static final int TRANSIT_ENTER = 1;
482 /** Window has been removed from the screen. */
483 public static final int TRANSIT_EXIT = 2;
484 /** Window has been made visible. */
485 public static final int TRANSIT_SHOW = 3;
486 /** Window has been made invisible.
487 * TODO: Consider removal as this is unused. */
488 public static final int TRANSIT_HIDE = 4;
489 /** The "application starting" preview window is no longer needed, and will
490 * animate away to show the real window. */
491 public static final int TRANSIT_PREVIEW_DONE = 5;
493 // NOTE: screen off reasons are in order of significance, with more
494 // important ones lower than less important ones.
496 /** Screen turned off because of a device admin */
497 public final int OFF_BECAUSE_OF_ADMIN = 1;
498 /** Screen turned off because of power button */
499 public final int OFF_BECAUSE_OF_USER = 2;
500 /** Screen turned off because of timeout */
501 public final int OFF_BECAUSE_OF_TIMEOUT = 3;
504 @IntDef({USER_ROTATION_FREE, USER_ROTATION_LOCKED})
505 @Retention(RetentionPolicy.SOURCE)
506 public @interface UserRotationMode {}
508 /** When not otherwise specified by the activity's screenOrientation, rotation should be
509 * determined by the system (that is, using sensors). */
510 public final int USER_ROTATION_FREE = 0;
511 /** When not otherwise specified by the activity's screenOrientation, rotation is set by
513 public final int USER_ROTATION_LOCKED = 1;
516 * Perform initialization of the policy.
518 * @param context The system context we are running in.
520 public void init(Context context, IWindowManager windowManager,
521 WindowManagerFuncs windowManagerFuncs);
524 * @return true if com.android.internal.R.bool#config_forceDefaultOrientation is true.
526 public boolean isDefaultOrientationForced();
529 * Called by window manager once it has the initial, default native
530 * display dimensions.
532 public void setInitialDisplaySize(Display display, int width, int height, int density);
535 * Called by window manager to set the overscan region that should be used for the
538 public void setDisplayOverscan(Display display, int left, int top, int right, int bottom);
541 * Check permissions when adding a window.
543 * @param attrs The window's LayoutParams.
544 * @param outAppOp First element will be filled with the app op corresponding to
545 * this window, or OP_NONE.
547 * @return {@link WindowManagerGlobal#ADD_OKAY} if the add can proceed;
548 * else an error code, usually
549 * {@link WindowManagerGlobal#ADD_PERMISSION_DENIED}, to abort the add.
551 public int checkAddPermission(WindowManager.LayoutParams attrs, int[] outAppOp);
554 * Check permissions when adding a window.
556 * @param attrs The window's LayoutParams.
558 * @return True if the window may only be shown to the current user, false if the window can
559 * be shown on all users' windows.
561 public boolean checkShowToOwnerOnly(WindowManager.LayoutParams attrs);
564 * Sanitize the layout parameters coming from a client. Allows the policy
565 * to do things like ensure that windows of a specific type can't take
568 * @param attrs The window layout parameters to be modified. These values
569 * are modified in-place.
571 public void adjustWindowParamsLw(WindowManager.LayoutParams attrs);
574 * After the window manager has computed the current configuration based
575 * on its knowledge of the display and input devices, it gives the policy
576 * a chance to adjust the information contained in it. If you want to
577 * leave it as-is, simply do nothing.
579 * <p>This method may be called by any thread in the window manager, but
580 * no internal locks in the window manager will be held.
582 * @param config The Configuration being computed, for you to change as
584 * @param keyboardPresence Flags that indicate whether internal or external
585 * keyboards are present.
586 * @param navigationPresence Flags that indicate whether internal or external
587 * navigation devices are present.
589 public void adjustConfigurationLw(Configuration config, int keyboardPresence,
590 int navigationPresence);
593 * Assign a window type to a layer. Allows you to control how different
594 * kinds of windows are ordered on-screen.
596 * @param type The type of window being assigned.
598 * @return int An arbitrary integer used to order windows, with lower
599 * numbers below higher ones.
601 public int windowTypeToLayerLw(int type);
604 * Return how to Z-order sub-windows in relation to the window they are
605 * attached to. Return positive to have them ordered in front, negative for
608 * @param type The sub-window type code.
610 * @return int Layer in relation to the attached window, where positive is
611 * above and negative is below.
613 public int subWindowTypeToLayerLw(int type);
616 * Get the highest layer (actually one more than) that the wallpaper is
619 public int getMaxWallpaperLayer();
622 * Return the display width available after excluding any screen
623 * decorations that can never be removed. That is, system bar or
626 public int getNonDecorDisplayWidth(int fullWidth, int fullHeight, int rotation,
630 * Return the display height available after excluding any screen
631 * decorations that can never be removed. That is, system bar or
634 public int getNonDecorDisplayHeight(int fullWidth, int fullHeight, int rotation,
638 * Return the available screen width that we should report for the
639 * configuration. This must be no larger than
640 * {@link #getNonDecorDisplayWidth(int, int, int)}; it may be smaller than
641 * that to account for more transient decoration like a status bar.
643 public int getConfigDisplayWidth(int fullWidth, int fullHeight, int rotation,
647 * Return the available screen height that we should report for the
648 * configuration. This must be no larger than
649 * {@link #getNonDecorDisplayHeight(int, int, int)}; it may be smaller than
650 * that to account for more transient decoration like a status bar.
652 public int getConfigDisplayHeight(int fullWidth, int fullHeight, int rotation,
656 * Return whether the given window is forcibly hiding all windows except windows with
657 * FLAG_SHOW_WHEN_LOCKED set. Typically returns true for the keyguard.
659 public boolean isForceHiding(WindowManager.LayoutParams attrs);
663 * Return whether the given window can become one that passes isForceHiding() test.
664 * Typically returns true for the StatusBar.
666 public boolean isKeyguardHostWindow(WindowManager.LayoutParams attrs);
669 * Determine if a window that is behind one that is force hiding
670 * (as determined by {@link #isForceHiding}) should actually be hidden.
671 * For example, typically returns false for the status bar. Be careful
672 * to return false for any window that you may hide yourself, since this
673 * will conflict with what you set.
675 public boolean canBeForceHidden(WindowState win, WindowManager.LayoutParams attrs);
678 * Return the window that is hiding the keyguard, if such a thing exists.
680 public WindowState getWinShowWhenLockedLw();
683 * Called when the system would like to show a UI to indicate that an
684 * application is starting. You can use this to add a
685 * APPLICATION_STARTING_TYPE window with the given appToken to the window
686 * manager (using the normal window manager APIs) that will be shown until
687 * the application displays its own window. This is called without the
688 * window manager locked so that you can call back into it.
690 * @param appToken Token of the application being started.
691 * @param packageName The name of the application package being started.
692 * @param theme Resource defining the application's overall visual theme.
693 * @param nonLocalizedLabel The default title label of the application if
694 * no data is found in the resource.
695 * @param labelRes The resource ID the application would like to use as its name.
696 * @param icon The resource ID the application would like to use as its icon.
697 * @param windowFlags Window layout flags.
699 * @return Optionally you can return the View that was used to create the
700 * window, for easy removal in removeStartingWindow.
702 * @see #removeStartingWindow
704 public View addStartingWindow(IBinder appToken, String packageName,
705 int theme, CompatibilityInfo compatInfo, CharSequence nonLocalizedLabel,
706 int labelRes, int icon, int logo, int windowFlags);
709 * Called when the first window of an application has been displayed, while
710 * {@link #addStartingWindow} has created a temporary initial window for
711 * that application. You should at this point remove the window from the
712 * window manager. This is called without the window manager locked so
713 * that you can call back into it.
715 * <p>Note: due to the nature of these functions not being called with the
716 * window manager locked, you must be prepared for this function to be
717 * called multiple times and/or an initial time with a null View window
718 * even if you previously returned one.
720 * @param appToken Token of the application that has started.
721 * @param window Window View that was returned by createStartingWindow.
723 * @see #addStartingWindow
725 public void removeStartingWindow(IBinder appToken, View window);
728 * Prepare for a window being added to the window manager. You can throw an
729 * exception here to prevent the window being added, or do whatever setup
730 * you need to keep track of the window.
732 * @param win The window being added.
733 * @param attrs The window's LayoutParams.
735 * @return {@link WindowManagerGlobal#ADD_OKAY} if the add can proceed, else an
736 * error code to abort the add.
738 public int prepareAddWindowLw(WindowState win,
739 WindowManager.LayoutParams attrs);
742 * Called when a window is being removed from a window manager. Must not
743 * throw an exception -- clean up as much as possible.
745 * @param win The window being removed.
747 public void removeWindowLw(WindowState win);
750 * Control the animation to run when a window's state changes. Return a
751 * non-0 number to force the animation to a specific resource ID, or 0
752 * to use the default animation.
754 * @param win The window that is changing.
755 * @param transit What is happening to the window: {@link #TRANSIT_ENTER},
756 * {@link #TRANSIT_EXIT}, {@link #TRANSIT_SHOW}, or
757 * {@link #TRANSIT_HIDE}.
759 * @return Resource ID of the actual animation to use, or 0 for none.
761 public int selectAnimationLw(WindowState win, int transit);
764 * Determine the animation to run for a rotation transition based on the
765 * top fullscreen windows {@link WindowManager.LayoutParams#rotationAnimation}
766 * and whether it is currently fullscreen and frontmost.
768 * @param anim The exiting animation resource id is stored in anim[0], the
769 * entering animation resource id is stored in anim[1].
771 public void selectRotationAnimationLw(int anim[]);
774 * Validate whether the current top fullscreen has specified the same
775 * {@link WindowManager.LayoutParams#rotationAnimation} value as that
776 * being passed in from the previous top fullscreen window.
778 * @param exitAnimId exiting resource id from the previous window.
779 * @param enterAnimId entering resource id from the previous window.
780 * @param forceDefault For rotation animations only, if true ignore the
781 * animation values and just return false.
782 * @return true if the previous values are still valid, false if they
783 * should be replaced with the default.
785 public boolean validateRotationAnimationLw(int exitAnimId, int enterAnimId,
786 boolean forceDefault);
789 * Create and return an animation to re-display a force hidden window.
791 public Animation createForceHideEnterAnimation(boolean onWallpaper,
792 boolean goingToNotificationShade);
795 * Create and return an animation to let the wallpaper disappear after being shown on a force
798 public Animation createForceHideWallpaperExitAnimation(boolean goingToNotificationShade);
801 * Called from the input reader thread before a key is enqueued.
803 * <p>There are some actions that need to be handled here because they
804 * affect the power state of the device, for example, the power keys.
805 * Generally, it's best to keep as little as possible in the queue thread
806 * because it's the most fragile.
807 * @param event The key event.
808 * @param policyFlags The policy flags associated with the key.
810 * @return Actions flags: may be {@link #ACTION_PASS_TO_USER}.
812 public int interceptKeyBeforeQueueing(KeyEvent event, int policyFlags);
815 * Called from the input reader thread before a motion is enqueued when the device is in a
816 * non-interactive state.
818 * <p>There are some actions that need to be handled here because they
819 * affect the power state of the device, for example, waking on motions.
820 * Generally, it's best to keep as little as possible in the queue thread
821 * because it's the most fragile.
822 * @param policyFlags The policy flags associated with the motion.
824 * @return Actions flags: may be {@link #ACTION_PASS_TO_USER}.
826 public int interceptMotionBeforeQueueingNonInteractive(long whenNanos, int policyFlags);
829 * Called from the input dispatcher thread before a key is dispatched to a window.
831 * <p>Allows you to define
832 * behavior for keys that can not be overridden by applications.
833 * This method is called from the input thread, with no locks held.
835 * @param win The window that currently has focus. This is where the key
836 * event will normally go.
837 * @param event The key event.
838 * @param policyFlags The policy flags associated with the key.
839 * @return 0 if the key should be dispatched immediately, -1 if the key should
840 * not be dispatched ever, or a positive value indicating the number of
841 * milliseconds by which the key dispatch should be delayed before trying
844 public long interceptKeyBeforeDispatching(WindowState win, KeyEvent event, int policyFlags);
847 * Called from the input dispatcher thread when an application did not handle
848 * a key that was dispatched to it.
850 * <p>Allows you to define default global behavior for keys that were not handled
851 * by applications. This method is called from the input thread, with no locks held.
853 * @param win The window that currently has focus. This is where the key
854 * event will normally go.
855 * @param event The key event.
856 * @param policyFlags The policy flags associated with the key.
857 * @return Returns an alternate key event to redispatch as a fallback, or null to give up.
858 * The caller is responsible for recycling the key event.
860 public KeyEvent dispatchUnhandledKey(WindowState win, KeyEvent event, int policyFlags);
863 * Called when layout of the windows is about to start.
865 * @param isDefaultDisplay true if window is on {@link Display#DEFAULT_DISPLAY}.
866 * @param displayWidth The current full width of the screen.
867 * @param displayHeight The current full height of the screen.
868 * @param displayRotation The current rotation being applied to the base window.
869 * @param uiMode The current uiMode in configuration.
871 public void beginLayoutLw(boolean isDefaultDisplay, int displayWidth, int displayHeight,
872 int displayRotation, int uiMode);
875 * Returns the bottom-most layer of the system decor, above which no policy decor should
878 public int getSystemDecorLayerLw();
881 * Return the rectangle of the screen that is available for applications to run in.
882 * This will be called immediately after {@link #beginLayoutLw}.
884 * @param r The rectangle to be filled with the boundaries available to applications.
886 public void getContentRectLw(Rect r);
889 * Called for each window attached to the window manager as layout is
890 * proceeding. The implementation of this function must take care of
891 * setting the window's frame, either here or in finishLayout().
893 * @param win The window being positioned.
894 * @param attached For sub-windows, the window it is attached to; this
895 * window will already have had layoutWindow() called on it
896 * so you can use its Rect. Otherwise null.
898 public void layoutWindowLw(WindowState win, WindowState attached);
902 * Return the insets for the areas covered by system windows. These values
903 * are computed on the most recent layout, so they are not guaranteed to
906 * @param attrs The LayoutParams of the window.
907 * @param rotation Rotation of the display.
908 * @param outContentInsets The areas covered by system windows, expressed as positive insets.
909 * @param outStableInsets The areas covered by stable system windows irrespective of their
910 * current visibility. Expressed as positive insets.
911 * @param outOutsets The areas that are not real display, but we would like to treat as such.
914 public void getInsetHintLw(WindowManager.LayoutParams attrs, int rotation,
915 Rect outContentInsets, Rect outStableInsets, Rect outOutsets);
918 * Called when layout of the windows is finished. After this function has
919 * returned, all windows given to layoutWindow() <em>must</em> have had a
922 public void finishLayoutLw();
924 /** Layout state may have changed (so another layout will be performed) */
925 static final int FINISH_LAYOUT_REDO_LAYOUT = 0x0001;
926 /** Configuration state may have changed */
927 static final int FINISH_LAYOUT_REDO_CONFIG = 0x0002;
928 /** Wallpaper may need to move */
929 static final int FINISH_LAYOUT_REDO_WALLPAPER = 0x0004;
930 /** Need to recompute animations */
931 static final int FINISH_LAYOUT_REDO_ANIM = 0x0008;
934 * Called following layout of all windows before each window has policy applied.
936 * @param displayWidth The current full width of the screen.
937 * @param displayHeight The current full height of the screen.
939 public void beginPostLayoutPolicyLw(int displayWidth, int displayHeight);
942 * Called following layout of all window to apply policy to each window.
944 * @param win The window being positioned.
945 * @param attrs The LayoutParams of the window.
946 * @param attached For sub-windows, the window it is attached to. Otherwise null.
948 public void applyPostLayoutPolicyLw(WindowState win,
949 WindowManager.LayoutParams attrs, WindowState attached);
952 * Called following layout of all windows and after policy has been applied
953 * to each window. If in this function you do
954 * something that may have modified the animation state of another window,
955 * be sure to return non-zero in order to perform another pass through layout.
957 * @return Return any bit set of {@link #FINISH_LAYOUT_REDO_LAYOUT},
958 * {@link #FINISH_LAYOUT_REDO_CONFIG}, {@link #FINISH_LAYOUT_REDO_WALLPAPER},
959 * or {@link #FINISH_LAYOUT_REDO_ANIM}.
961 public int finishPostLayoutPolicyLw();
964 * Return true if it is okay to perform animations for an app transition
965 * that is about to occur. You may return false for this if, for example,
966 * the lock screen is currently displayed so the switch should happen
969 public boolean allowAppAnimationsLw();
973 * A new window has been focused.
975 public int focusChangedLw(WindowState lastFocus, WindowState newFocus);
978 * Called when the device has started waking up.
980 public void startedWakingUp();
983 * Called when the device has finished waking up.
985 public void finishedWakingUp();
988 * Called when the device has started going to sleep.
990 * @param why {@link #OFF_BECAUSE_OF_USER}, {@link #OFF_BECAUSE_OF_ADMIN},
991 * or {@link #OFF_BECAUSE_OF_TIMEOUT}.
993 public void startedGoingToSleep(int why);
996 * Called when the device has finished going to sleep.
998 * @param why {@link #OFF_BECAUSE_OF_USER}, {@link #OFF_BECAUSE_OF_ADMIN},
999 * or {@link #OFF_BECAUSE_OF_TIMEOUT}.
1001 public void finishedGoingToSleep(int why);
1004 * Called when the device is about to turn on the screen to show content.
1005 * When waking up, this method will be called once after the call to wakingUp().
1006 * When dozing, the method will be called sometime after the call to goingToSleep() and
1007 * may be called repeatedly in the case where the screen is pulsing on and off.
1009 * Must call back on the listener to tell it when the higher-level system
1010 * is ready for the screen to go on (i.e. the lock screen is shown).
1012 public void screenTurningOn(ScreenOnListener screenOnListener);
1015 * Called when the device has actually turned on the screen, i.e. the display power state has
1016 * been set to ON and the screen is unblocked.
1018 public void screenTurnedOn();
1021 * Called when the device has turned the screen off.
1023 public void screenTurnedOff();
1025 public interface ScreenOnListener {
1030 * Return whether the default display is on and not blocked by a black surface.
1032 public boolean isScreenOn();
1035 * Tell the policy that the lid switch has changed state.
1036 * @param whenNanos The time when the change occurred in uptime nanoseconds.
1037 * @param lidOpen True if the lid is now open.
1039 public void notifyLidSwitchChanged(long whenNanos, boolean lidOpen);
1042 * Tell the policy that the camera lens has been covered or uncovered.
1043 * @param whenNanos The time when the change occurred in uptime nanoseconds.
1044 * @param lensCovered True if the lens is covered.
1046 public void notifyCameraLensCoverSwitchChanged(long whenNanos, boolean lensCovered);
1049 * Tell the policy if anyone is requesting that keyguard not come on.
1051 * @param enabled Whether keyguard can be on or not. does not actually
1052 * turn it on, unless it was previously disabled with this function.
1054 * @see android.app.KeyguardManager.KeyguardLock#disableKeyguard()
1055 * @see android.app.KeyguardManager.KeyguardLock#reenableKeyguard()
1057 @SuppressWarnings("javadoc")
1058 public void enableKeyguard(boolean enabled);
1061 * Callback used by {@link WindowManagerPolicy#exitKeyguardSecurely}
1063 interface OnKeyguardExitResult {
1064 void onKeyguardExitResult(boolean success);
1068 * Tell the policy if anyone is requesting the keyguard to exit securely
1069 * (this would be called after the keyguard was disabled)
1070 * @param callback Callback to send the result back.
1071 * @see android.app.KeyguardManager#exitKeyguardSecurely(android.app.KeyguardManager.OnKeyguardExitResult)
1073 @SuppressWarnings("javadoc")
1074 void exitKeyguardSecurely(OnKeyguardExitResult callback);
1079 * Return whether the keyguard is currently locked.
1081 * @return true if in keyguard is locked.
1083 public boolean isKeyguardLocked();
1088 * Return whether the keyguard requires a password to unlock.
1090 * @return true if in keyguard is secure.
1092 public boolean isKeyguardSecure();
1095 * Return whether the keyguard is on.
1097 * @return true if in keyguard is on.
1099 public boolean isKeyguardShowingOrOccluded();
1102 * inKeyguardRestrictedKeyInputMode
1104 * if keyguard screen is showing or in restricted key input mode (i.e. in
1105 * keyguard password emergency screen). When in such mode, certain keys,
1106 * such as the Home key and the right soft keys, don't work.
1108 * @return true if in keyguard restricted input mode.
1110 public boolean inKeyguardRestrictedKeyInputMode();
1113 * Ask the policy to dismiss the keyguard, if it is currently shown.
1115 public void dismissKeyguardLw();
1118 * Notifies the keyguard that the activity has drawn it was waiting for.
1120 public void notifyActivityDrawnForKeyguardLw();
1123 * Ask the policy whether the Keyguard has drawn. If the Keyguard is disabled, this method
1124 * returns true as soon as we know that Keyguard is disabled.
1126 * @return true if the keyguard has drawn.
1128 public boolean isKeyguardDrawnLw();
1131 * Given an orientation constant, returns the appropriate surface rotation,
1132 * taking into account sensors, docking mode, rotation lock, and other factors.
1134 * @param orientation An orientation constant, such as
1135 * {@link android.content.pm.ActivityInfo#SCREEN_ORIENTATION_LANDSCAPE}.
1136 * @param lastRotation The most recently used rotation.
1137 * @return The surface rotation to use.
1139 public int rotationForOrientationLw(@ActivityInfo.ScreenOrientation int orientation,
1143 * Given an orientation constant and a rotation, returns true if the rotation
1144 * has compatible metrics to the requested orientation. For example, if
1145 * the application requested landscape and got seascape, then the rotation
1146 * has compatible metrics; if the application requested portrait and got landscape,
1147 * then the rotation has incompatible metrics; if the application did not specify
1148 * a preference, then anything goes.
1150 * @param orientation An orientation constant, such as
1151 * {@link android.content.pm.ActivityInfo#SCREEN_ORIENTATION_LANDSCAPE}.
1152 * @param rotation The rotation to check.
1153 * @return True if the rotation is compatible with the requested orientation.
1155 public boolean rotationHasCompatibleMetricsLw(@ActivityInfo.ScreenOrientation int orientation,
1159 * Called by the window manager when the rotation changes.
1161 * @param rotation The new rotation.
1163 public void setRotationLw(int rotation);
1166 * Called when the system is mostly done booting to set whether
1167 * the system should go into safe mode.
1169 public void setSafeMode(boolean safeMode);
1172 * Called when the system is mostly done booting.
1174 public void systemReady();
1177 * Called when the system is done booting to the point where the
1178 * user can start interacting with it.
1180 public void systemBooted();
1183 * Show boot time message to the user.
1185 public void showBootMessage(final CharSequence msg, final boolean always);
1188 * Hide the UI for showing boot messages, never to be displayed again.
1190 public void hideBootMessages();
1193 * Called when userActivity is signalled in the power manager.
1194 * This is safe to call from any thread, with any window manager locks held or not.
1196 public void userActivity();
1199 * Called when we have finished booting and can now display the home
1200 * screen to the user. This will happen after systemReady(), and at
1201 * this point the display is active.
1203 public void enableScreenAfterBoot();
1205 public void setCurrentOrientationLw(@ActivityInfo.ScreenOrientation int newOrientation);
1208 * Call from application to perform haptic feedback on its window.
1210 public boolean performHapticFeedbackLw(WindowState win, int effectId, boolean always);
1213 * Called when we have started keeping the screen on because a window
1214 * requesting this has become visible.
1216 public void keepScreenOnStartedLw();
1219 * Called when we have stopped keeping the screen on because the last window
1220 * requesting this is no longer visible.
1222 public void keepScreenOnStoppedLw();
1225 * Gets the current user rotation mode.
1227 * @return The rotation mode.
1229 * @see WindowManagerPolicy#USER_ROTATION_LOCKED
1230 * @see WindowManagerPolicy#USER_ROTATION_FREE
1233 public int getUserRotationMode();
1236 * Inform the policy that the user has chosen a preferred orientation ("rotation lock").
1238 * @param mode One of {@link WindowManagerPolicy#USER_ROTATION_LOCKED} or
1239 * {@link WindowManagerPolicy#USER_ROTATION_FREE}.
1240 * @param rotation One of {@link Surface#ROTATION_0}, {@link Surface#ROTATION_90},
1241 * {@link Surface#ROTATION_180}, {@link Surface#ROTATION_270}.
1243 public void setUserRotationMode(@UserRotationMode int mode, @Surface.Rotation int rotation);
1246 * Called when a new system UI visibility is being reported, allowing
1247 * the policy to adjust what is actually reported.
1248 * @param visibility The raw visibility reported by the status bar.
1249 * @return The new desired visibility.
1251 public int adjustSystemUiVisibilityLw(int visibility);
1254 * Specifies whether there is an on-screen navigation bar separate from the status bar.
1256 public boolean hasNavigationBar();
1259 * Lock the device now.
1261 public void lockNow(Bundle options);
1264 * Set the last used input method window state. This state is used to make IME transition
1268 public void setLastInputMethodWindowLw(WindowState ime, WindowState target);
1271 * Show the recents task list app.
1274 public void showRecentApps();
1277 * Show the global actions dialog.
1280 public void showGlobalActions();
1283 * @return The current height of the input method window.
1285 public int getInputMethodWindowVisibleHeightLw();
1288 * Called when the current user changes. Guaranteed to be called before the broadcast
1289 * of the new user id is made to all listeners.
1291 * @param newUserId The id of the incoming user.
1293 public void setCurrentUserLw(int newUserId);
1296 * Print the WindowManagerPolicy's state into the given stream.
1298 * @param prefix Text to print at the front of each line.
1299 * @param writer The PrintWriter to which you should dump your state. This will be
1300 * closed for you after you return.
1301 * @param args additional arguments to the dump request.
1303 public void dump(String prefix, PrintWriter writer, String[] args);
1306 * Returns whether a given window type can be magnified.
1308 * @param windowType The window type.
1309 * @return True if the window can be magnified.
1311 public boolean canMagnifyWindow(int windowType);
1314 * Returns whether a given window type is considered a top level one.
1315 * A top level window does not have a container, i.e. attached window,
1316 * or if it has a container it is laid out as a top-level window, not
1317 * as a child of its container.
1319 * @param windowType The window type.
1320 * @return True if the window is a top level one.
1322 public boolean isTopLevelWindow(int windowType);
1325 * Notifies the keyguard to start fading out.
1327 * @param startTime the start time of the animation in uptime milliseconds
1328 * @param fadeoutDuration the duration of the exit animation, in milliseconds
1330 public void startKeyguardExitAnimation(long startTime, long fadeoutDuration);