1 /* 2 * Copyright (C) 2006 The Android Open Source Project 3 * 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 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 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. 15 */ 16 17 package android.view; 18 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.Rect; 26 import android.graphics.RectF; 27 import android.os.Bundle; 28 import android.os.IBinder; 29 import android.os.Looper; 30 import android.view.animation.Animation; 31 32 import java.io.PrintWriter; 33 import java.lang.annotation.Retention; 34 import java.lang.annotation.RetentionPolicy; 35 36 /** 37 * This interface supplies all UI-specific behavior of the window manager. An 38 * instance of it is created by the window manager when it starts up, and allows 39 * customization of window layering, special window types, key dispatching, and 40 * layout. 41 * 42 * <p>Because this provides deep interaction with the system window manager, 43 * specific methods on this interface can be called from a variety of contexts 44 * with various restrictions on what they can do. These are encoded through 45 * a suffixes at the end of a method encoding the thread the method is called 46 * from and any locks that are held when it is being called; if no suffix 47 * is attached to a method, then it is not called with any locks and may be 48 * called from the main window manager thread or another thread calling into 49 * the window manager. 50 * 51 * <p>The current suffixes are: 52 * 53 * <dl> 54 * <dt> Ti <dd> Called from the input thread. This is the thread that 55 * collects pending input events and dispatches them to the appropriate window. 56 * It may block waiting for events to be processed, so that the input stream is 57 * properly serialized. 58 * <dt> Tq <dd> Called from the low-level input queue thread. This is the 59 * thread that reads events out of the raw input devices and places them 60 * into the global input queue that is read by the <var>Ti</var> thread. 61 * This thread should not block for a long period of time on anything but the 62 * key driver. 63 * <dt> Lw <dd> Called with the main window manager lock held. Because the 64 * window manager is a very low-level system service, there are few other 65 * system services you can call with this lock held. It is explicitly okay to 66 * make calls into the package manager and power manager; it is explicitly not 67 * okay to make calls into the activity manager or most other services. Note that 68 * {@link android.content.Context#checkPermission(String, int, int)} and 69 * variations require calling into the activity manager. 70 * <dt> Li <dd> Called with the input thread lock held. This lock can be 71 * acquired by the window manager while it holds the window lock, so this is 72 * even more restrictive than <var>Lw</var>. 73 * </dl> 74 * 75 * @hide 76 */ 77 public interface WindowManagerPolicy { 78 // Policy flags. These flags are also defined in frameworks/base/include/ui/Input.h. 79 public final static int FLAG_WAKE = 0x00000001; 80 public final static int FLAG_VIRTUAL = 0x00000002; 81 82 public final static int FLAG_INJECTED = 0x01000000; 83 public final static int FLAG_TRUSTED = 0x02000000; 84 public final static int FLAG_FILTERED = 0x04000000; 85 public final static int FLAG_DISABLE_KEY_REPEAT = 0x08000000; 86 87 public final static int FLAG_INTERACTIVE = 0x20000000; 88 public final static int FLAG_PASS_TO_USER = 0x40000000; 89 90 // Flags used for indicating whether the internal and/or external input devices 91 // of some type are available. 92 public final static int PRESENCE_INTERNAL = 1 << 0; 93 public final static int PRESENCE_EXTERNAL = 1 << 1; 94 95 public final static boolean WATCH_POINTER = false; 96 97 /** 98 * Sticky broadcast of the current HDMI plugged state. 99 */ 100 public final static String ACTION_HDMI_PLUGGED = "android.intent.action.HDMI_PLUGGED"; 101 102 /** 103 * Extra in {@link #ACTION_HDMI_PLUGGED} indicating the state: true if 104 * plugged in to HDMI, false if not. 105 */ 106 public final static String EXTRA_HDMI_PLUGGED_STATE = "state"; 107 108 /** 109 * Set to {@code true} when intent was invoked from pressing the home key. 110 * @hide 111 */ 112 @SystemApi 113 public static final String EXTRA_FROM_HOME_KEY = "android.intent.extra.FROM_HOME_KEY"; 114 115 /** 116 * Pass this event to the user / app. To be returned from 117 * {@link #interceptKeyBeforeQueueing}. 118 */ 119 public final static int ACTION_PASS_TO_USER = 0x00000001; 120 121 /** 122 * Interface to the Window Manager state associated with a particular 123 * window. You can hold on to an instance of this interface from the call 124 * to prepareAddWindow() until removeWindow(). 125 */ 126 public interface WindowState { 127 /** 128 * Return the uid of the app that owns this window. 129 */ 130 int getOwningUid(); 131 132 /** 133 * Return the package name of the app that owns this window. 134 */ 135 String getOwningPackage(); 136 137 /** 138 * Perform standard frame computation. The result can be obtained with 139 * getFrame() if so desired. Must be called with the window manager 140 * lock held. 141 * 142 * @param parentFrame The frame of the parent container this window 143 * is in, used for computing its basic position. 144 * @param displayFrame The frame of the overall display in which this 145 * window can appear, used for constraining the overall dimensions 146 * of the window. 147 * @param overlayFrame The frame within the display that is inside 148 * of the overlay region. 149 * @param contentFrame The frame within the display in which we would 150 * like active content to appear. This will cause windows behind to 151 * be resized to match the given content frame. 152 * @param visibleFrame The frame within the display that the window 153 * is actually visible, used for computing its visible insets to be 154 * given to windows behind. 155 * This can be used as a hint for scrolling (avoiding resizing) 156 * the window to make certain that parts of its content 157 * are visible. 158 * @param decorFrame The decor frame specified by policy specific to this window, 159 * to use for proper cropping during animation. 160 * @param stableFrame The frame around which stable system decoration is positioned. 161 * @param outsetFrame The frame that includes areas that aren't part of the surface but we 162 * want to treat them as such. 163 */ 164 public void computeFrameLw(Rect parentFrame, Rect displayFrame, 165 Rect overlayFrame, Rect contentFrame, Rect visibleFrame, Rect decorFrame, 166 Rect stableFrame, Rect outsetFrame); 167 168 /** 169 * Retrieve the current frame of the window that has been assigned by 170 * the window manager. Must be called with the window manager lock held. 171 * 172 * @return Rect The rectangle holding the window frame. 173 */ 174 public Rect getFrameLw(); 175 176 /** 177 * Retrieve the current frame of the window that is actually shown. 178 * Must be called with the window manager lock held. 179 * 180 * @return Rect The rectangle holding the shown window frame. 181 */ 182 public RectF getShownFrameLw(); 183 184 /** 185 * Retrieve the frame of the display that this window was last 186 * laid out in. Must be called with the 187 * window manager lock held. 188 * 189 * @return Rect The rectangle holding the display frame. 190 */ 191 public Rect getDisplayFrameLw(); 192 193 /** 194 * Retrieve the frame of the area inside the overscan region of the 195 * display that this window was last laid out in. Must be called with the 196 * window manager lock held. 197 * 198 * @return Rect The rectangle holding the display overscan frame. 199 */ 200 public Rect getOverscanFrameLw(); 201 202 /** 203 * Retrieve the frame of the content area that this window was last 204 * laid out in. This is the area in which the content of the window 205 * should be placed. It will be smaller than the display frame to 206 * account for screen decorations such as a status bar or soft 207 * keyboard. Must be called with the 208 * window manager lock held. 209 * 210 * @return Rect The rectangle holding the content frame. 211 */ 212 public Rect getContentFrameLw(); 213 214 /** 215 * Retrieve the frame of the visible area that this window was last 216 * laid out in. This is the area of the screen in which the window 217 * will actually be fully visible. It will be smaller than the 218 * content frame to account for transient UI elements blocking it 219 * such as an input method's candidates UI. Must be called with the 220 * window manager lock held. 221 * 222 * @return Rect The rectangle holding the visible frame. 223 */ 224 public Rect getVisibleFrameLw(); 225 226 /** 227 * Returns true if this window is waiting to receive its given 228 * internal insets from the client app, and so should not impact the 229 * layout of other windows. 230 */ 231 public boolean getGivenInsetsPendingLw(); 232 233 /** 234 * Retrieve the insets given by this window's client for the content 235 * area of windows behind it. Must be called with the 236 * window manager lock held. 237 * 238 * @return Rect The left, top, right, and bottom insets, relative 239 * to the window's frame, of the actual contents. 240 */ 241 public Rect getGivenContentInsetsLw(); 242 243 /** 244 * Retrieve the insets given by this window's client for the visible 245 * area of windows behind it. Must be called with the 246 * window manager lock held. 247 * 248 * @return Rect The left, top, right, and bottom insets, relative 249 * to the window's frame, of the actual visible area. 250 */ 251 public Rect getGivenVisibleInsetsLw(); 252 253 /** 254 * Retrieve the current LayoutParams of the window. 255 * 256 * @return WindowManager.LayoutParams The window's internal LayoutParams 257 * instance. 258 */ 259 public WindowManager.LayoutParams getAttrs(); 260 261 /** 262 * Return whether this window needs the menu key shown. Must be called 263 * with window lock held, because it may need to traverse down through 264 * window list to determine the result. 265 * @param bottom The bottom-most window to consider when determining this. 266 */ 267 public boolean getNeedsMenuLw(WindowState bottom); 268 269 /** 270 * Retrieve the current system UI visibility flags associated with 271 * this window. 272 */ 273 public int getSystemUiVisibility(); 274 275 /** 276 * Get the layer at which this window's surface will be Z-ordered. 277 */ 278 public int getSurfaceLayer(); 279 280 /** 281 * Retrieve the type of the top-level window. 282 * 283 * @return the base type of the parent window if attached or its own type otherwise 284 */ 285 public int getBaseType(); 286 287 /** 288 * Return the token for the application (actually activity) that owns 289 * this window. May return null for system windows. 290 * 291 * @return An IApplicationToken identifying the owning activity. 292 */ 293 public IApplicationToken getAppToken(); 294 295 /** 296 * Return true if this window is participating in voice interaction. 297 */ 298 public boolean isVoiceInteraction(); 299 300 /** 301 * Return true if, at any point, the application token associated with 302 * this window has actually displayed any windows. This is most useful 303 * with the "starting up" window to determine if any windows were 304 * displayed when it is closed. 305 * 306 * @return Returns true if one or more windows have been displayed, 307 * else false. 308 */ 309 public boolean hasAppShownWindows(); 310 311 /** 312 * Is this window visible? It is not visible if there is no 313 * surface, or we are in the process of running an exit animation 314 * that will remove the surface. 315 */ 316 boolean isVisibleLw(); 317 318 /** 319 * Like {@link #isVisibleLw}, but also counts a window that is currently 320 * "hidden" behind the keyguard as visible. This allows us to apply 321 * things like window flags that impact the keyguard. 322 */ 323 boolean isVisibleOrBehindKeyguardLw(); 324 325 /** 326 * Is this window currently visible to the user on-screen? It is 327 * displayed either if it is visible or it is currently running an 328 * animation before no longer being visible. Must be called with the 329 * window manager lock held. 330 */ 331 boolean isDisplayedLw(); 332 333 /** 334 * Return true if this window (or a window it is attached to, but not 335 * considering its app token) is currently animating. 336 */ 337 public boolean isAnimatingLw(); 338 339 /** 340 * Is this window considered to be gone for purposes of layout? 341 */ 342 boolean isGoneForLayoutLw(); 343 344 /** 345 * Returns true if the window has a surface that it has drawn a 346 * complete UI in to. Note that this is different from {@link #hasDrawnLw()} 347 * in that it also returns true if the window is READY_TO_SHOW, but was not yet 348 * promoted to HAS_DRAWN. 349 */ 350 boolean isDrawnLw(); 351 352 /** 353 * Returns true if this window has been shown on screen at some time in 354 * the past. Must be called with the window manager lock held. 355 */ 356 public boolean hasDrawnLw(); 357 358 /** 359 * Can be called by the policy to force a window to be hidden, 360 * regardless of whether the client or window manager would like 361 * it shown. Must be called with the window manager lock held. 362 * Returns true if {@link #showLw} was last called for the window. 363 */ 364 public boolean hideLw(boolean doAnimation); 365 366 /** 367 * Can be called to undo the effect of {@link #hideLw}, allowing a 368 * window to be shown as long as the window manager and client would 369 * also like it to be shown. Must be called with the window manager 370 * lock held. 371 * Returns true if {@link #hideLw} was last called for the window. 372 */ 373 public boolean showLw(boolean doAnimation); 374 375 /** 376 * Check whether the process hosting this window is currently alive. 377 */ 378 public boolean isAlive(); 379 380 /** 381 * Check if window is on {@link Display#DEFAULT_DISPLAY}. 382 * @return true if window is on default display. 383 */ 384 public boolean isDefaultDisplay(); 385 386 /** 387 * Check whether the window is currently dimming. 388 */ 389 public boolean isDimming(); 390 } 391 392 /** 393 * Representation of a input consumer that the policy has added to the 394 * window manager to consume input events going to windows below it. 395 */ 396 public interface InputConsumer { 397 /** 398 * Remove the input consumer from the window manager. 399 */ 400 void dismiss(); 401 } 402 403 /** 404 * Interface for calling back in to the window manager that is private 405 * between it and the policy. 406 */ 407 public interface WindowManagerFuncs { 408 public static final int LID_ABSENT = -1; 409 public static final int LID_CLOSED = 0; 410 public static final int LID_OPEN = 1; 411 412 public static final int CAMERA_LENS_COVER_ABSENT = -1; 413 public static final int CAMERA_LENS_UNCOVERED = 0; 414 public static final int CAMERA_LENS_COVERED = 1; 415 416 /** 417 * Ask the window manager to re-evaluate the system UI flags. 418 */ 419 public void reevaluateStatusBarVisibility(); 420 421 /** 422 * Add a input consumer which will consume all input events going to any window below it. 423 */ 424 public InputConsumer addInputConsumer(Looper looper, 425 InputEventReceiver.Factory inputEventReceiverFactory); 426 427 /** 428 * Returns a code that describes the current state of the lid switch. 429 */ 430 public int getLidState(); 431 432 /** 433 * Returns a code that descripbes whether the camera lens is covered or not. 434 */ 435 public int getCameraLensCoverState(); 436 437 /** 438 * Switch the keyboard layout for the given device. 439 * Direction should be +1 or -1 to go to the next or previous keyboard layout. 440 */ 441 public void switchKeyboardLayout(int deviceId, int direction); 442 443 public void shutdown(boolean confirm); 444 public void rebootSafeMode(boolean confirm); 445 446 /** 447 * Return the window manager lock needed to correctly call "Lw" methods. 448 */ 449 public Object getWindowManagerLock(); 450 451 /** Register a system listener for touch events */ 452 void registerPointerEventListener(PointerEventListener listener); 453 454 /** Unregister a system listener for touch events */ 455 void unregisterPointerEventListener(PointerEventListener listener); 456 } 457 458 public interface PointerEventListener { 459 /** 460 * 1. onPointerEvent will be called on the service.UiThread. 461 * 2. motionEvent will be recycled after onPointerEvent returns so if it is needed later a 462 * copy() must be made and the copy must be recycled. 463 **/ 464 public void onPointerEvent(MotionEvent motionEvent); 465 } 466 467 /** Window has been added to the screen. */ 468 public static final int TRANSIT_ENTER = 1; 469 /** Window has been removed from the screen. */ 470 public static final int TRANSIT_EXIT = 2; 471 /** Window has been made visible. */ 472 public static final int TRANSIT_SHOW = 3; 473 /** Window has been made invisible. 474 * TODO: Consider removal as this is unused. */ 475 public static final int TRANSIT_HIDE = 4; 476 /** The "application starting" preview window is no longer needed, and will 477 * animate away to show the real window. */ 478 public static final int TRANSIT_PREVIEW_DONE = 5; 479 480 // NOTE: screen off reasons are in order of significance, with more 481 // important ones lower than less important ones. 482 483 /** Screen turned off because of a device admin */ 484 public final int OFF_BECAUSE_OF_ADMIN = 1; 485 /** Screen turned off because of power button */ 486 public final int OFF_BECAUSE_OF_USER = 2; 487 /** Screen turned off because of timeout */ 488 public final int OFF_BECAUSE_OF_TIMEOUT = 3; 489 490 /** @hide */ 491 @IntDef({USER_ROTATION_FREE, USER_ROTATION_LOCKED}) 492 @Retention(RetentionPolicy.SOURCE) 493 public @interface UserRotationMode {} 494 495 /** When not otherwise specified by the activity's screenOrientation, rotation should be 496 * determined by the system (that is, using sensors). */ 497 public final int USER_ROTATION_FREE = 0; 498 /** When not otherwise specified by the activity's screenOrientation, rotation is set by 499 * the user. */ 500 public final int USER_ROTATION_LOCKED = 1; 501 502 /** 503 * Perform initialization of the policy. 504 * 505 * @param context The system context we are running in. 506 */ 507 public void init(Context context, IWindowManager windowManager, 508 WindowManagerFuncs windowManagerFuncs); 509 510 /** 511 * @return true if com.android.internal.R.bool#config_forceDefaultOrientation is true. 512 */ 513 public boolean isDefaultOrientationForced(); 514 515 /** 516 * Called by window manager once it has the initial, default native 517 * display dimensions. 518 */ 519 public void setInitialDisplaySize(Display display, int width, int height, int density); 520 521 /** 522 * Called by window manager to set the overscan region that should be used for the 523 * given display. 524 */ 525 public void setDisplayOverscan(Display display, int left, int top, int right, int bottom); 526 527 /** 528 * Check permissions when adding a window. 529 * 530 * @param attrs The window's LayoutParams. 531 * @param outAppOp First element will be filled with the app op corresponding to 532 * this window, or OP_NONE. 533 * 534 * @return {@link WindowManagerGlobal#ADD_OKAY} if the add can proceed; 535 * else an error code, usually 536 * {@link WindowManagerGlobal#ADD_PERMISSION_DENIED}, to abort the add. 537 */ 538 public int checkAddPermission(WindowManager.LayoutParams attrs, int[] outAppOp); 539 540 /** 541 * Check permissions when adding a window. 542 * 543 * @param attrs The window's LayoutParams. 544 * 545 * @return True if the window may only be shown to the current user, false if the window can 546 * be shown on all users' windows. 547 */ 548 public boolean checkShowToOwnerOnly(WindowManager.LayoutParams attrs); 549 550 /** 551 * Sanitize the layout parameters coming from a client. Allows the policy 552 * to do things like ensure that windows of a specific type can't take 553 * input focus. 554 * 555 * @param attrs The window layout parameters to be modified. These values 556 * are modified in-place. 557 */ 558 public void adjustWindowParamsLw(WindowManager.LayoutParams attrs); 559 560 /** 561 * After the window manager has computed the current configuration based 562 * on its knowledge of the display and input devices, it gives the policy 563 * a chance to adjust the information contained in it. If you want to 564 * leave it as-is, simply do nothing. 565 * 566 * <p>This method may be called by any thread in the window manager, but 567 * no internal locks in the window manager will be held. 568 * 569 * @param config The Configuration being computed, for you to change as 570 * desired. 571 * @param keyboardPresence Flags that indicate whether internal or external 572 * keyboards are present. 573 * @param navigationPresence Flags that indicate whether internal or external 574 * navigation devices are present. 575 */ 576 public void adjustConfigurationLw(Configuration config, int keyboardPresence, 577 int navigationPresence); 578 579 /** 580 * Assign a window type to a layer. Allows you to control how different 581 * kinds of windows are ordered on-screen. 582 * 583 * @param type The type of window being assigned. 584 * 585 * @return int An arbitrary integer used to order windows, with lower 586 * numbers below higher ones. 587 */ 588 public int windowTypeToLayerLw(int type); 589 590 /** 591 * Return how to Z-order sub-windows in relation to the window they are 592 * attached to. Return positive to have them ordered in front, negative for 593 * behind. 594 * 595 * @param type The sub-window type code. 596 * 597 * @return int Layer in relation to the attached window, where positive is 598 * above and negative is below. 599 */ 600 public int subWindowTypeToLayerLw(int type); 601 602 /** 603 * Get the highest layer (actually one more than) that the wallpaper is 604 * allowed to be in. 605 */ 606 public int getMaxWallpaperLayer(); 607 608 /** 609 * Return the display width available after excluding any screen 610 * decorations that can never be removed. That is, system bar or 611 * button bar. 612 */ 613 public int getNonDecorDisplayWidth(int fullWidth, int fullHeight, int rotation); 614 615 /** 616 * Return the display height available after excluding any screen 617 * decorations that can never be removed. That is, system bar or 618 * button bar. 619 */ 620 public int getNonDecorDisplayHeight(int fullWidth, int fullHeight, int rotation); 621 622 /** 623 * Return the available screen width that we should report for the 624 * configuration. This must be no larger than 625 * {@link #getNonDecorDisplayWidth(int, int, int)}; it may be smaller than 626 * that to account for more transient decoration like a status bar. 627 */ 628 public int getConfigDisplayWidth(int fullWidth, int fullHeight, int rotation); 629 630 /** 631 * Return the available screen height that we should report for the 632 * configuration. This must be no larger than 633 * {@link #getNonDecorDisplayHeight(int, int, int)}; it may be smaller than 634 * that to account for more transient decoration like a status bar. 635 */ 636 public int getConfigDisplayHeight(int fullWidth, int fullHeight, int rotation); 637 638 /** 639 * Return whether the given window is forcibly hiding all windows except windows with 640 * FLAG_SHOW_WHEN_LOCKED set. Typically returns true for the keyguard. 641 */ 642 public boolean isForceHiding(WindowManager.LayoutParams attrs); 643 644 645 /** 646 * Return whether the given window can become one that passes isForceHiding() test. 647 * Typically returns true for the StatusBar. 648 */ 649 public boolean isKeyguardHostWindow(WindowManager.LayoutParams attrs); 650 651 /** 652 * Determine if a window that is behind one that is force hiding 653 * (as determined by {@link #isForceHiding}) should actually be hidden. 654 * For example, typically returns false for the status bar. Be careful 655 * to return false for any window that you may hide yourself, since this 656 * will conflict with what you set. 657 */ 658 public boolean canBeForceHidden(WindowState win, WindowManager.LayoutParams attrs); 659 660 /** 661 * Return the window that is hiding the keyguard, if such a thing exists. 662 */ 663 public WindowState getWinShowWhenLockedLw(); 664 665 /** 666 * Called when the system would like to show a UI to indicate that an 667 * application is starting. You can use this to add a 668 * APPLICATION_STARTING_TYPE window with the given appToken to the window 669 * manager (using the normal window manager APIs) that will be shown until 670 * the application displays its own window. This is called without the 671 * window manager locked so that you can call back into it. 672 * 673 * @param appToken Token of the application being started. 674 * @param packageName The name of the application package being started. 675 * @param theme Resource defining the application's overall visual theme. 676 * @param nonLocalizedLabel The default title label of the application if 677 * no data is found in the resource. 678 * @param labelRes The resource ID the application would like to use as its name. 679 * @param icon The resource ID the application would like to use as its icon. 680 * @param windowFlags Window layout flags. 681 * 682 * @return Optionally you can return the View that was used to create the 683 * window, for easy removal in removeStartingWindow. 684 * 685 * @see #removeStartingWindow 686 */ 687 public View addStartingWindow(IBinder appToken, String packageName, 688 int theme, CompatibilityInfo compatInfo, CharSequence nonLocalizedLabel, 689 int labelRes, int icon, int logo, int windowFlags); 690 691 /** 692 * Called when the first window of an application has been displayed, while 693 * {@link #addStartingWindow} has created a temporary initial window for 694 * that application. You should at this point remove the window from the 695 * window manager. This is called without the window manager locked so 696 * that you can call back into it. 697 * 698 * <p>Note: due to the nature of these functions not being called with the 699 * window manager locked, you must be prepared for this function to be 700 * called multiple times and/or an initial time with a null View window 701 * even if you previously returned one. 702 * 703 * @param appToken Token of the application that has started. 704 * @param window Window View that was returned by createStartingWindow. 705 * 706 * @see #addStartingWindow 707 */ 708 public void removeStartingWindow(IBinder appToken, View window); 709 710 /** 711 * Prepare for a window being added to the window manager. You can throw an 712 * exception here to prevent the window being added, or do whatever setup 713 * you need to keep track of the window. 714 * 715 * @param win The window being added. 716 * @param attrs The window's LayoutParams. 717 * 718 * @return {@link WindowManagerGlobal#ADD_OKAY} if the add can proceed, else an 719 * error code to abort the add. 720 */ 721 public int prepareAddWindowLw(WindowState win, 722 WindowManager.LayoutParams attrs); 723 724 /** 725 * Called when a window is being removed from a window manager. Must not 726 * throw an exception -- clean up as much as possible. 727 * 728 * @param win The window being removed. 729 */ 730 public void removeWindowLw(WindowState win); 731 732 /** 733 * Control the animation to run when a window's state changes. Return a 734 * non-0 number to force the animation to a specific resource ID, or 0 735 * to use the default animation. 736 * 737 * @param win The window that is changing. 738 * @param transit What is happening to the window: {@link #TRANSIT_ENTER}, 739 * {@link #TRANSIT_EXIT}, {@link #TRANSIT_SHOW}, or 740 * {@link #TRANSIT_HIDE}. 741 * 742 * @return Resource ID of the actual animation to use, or 0 for none. 743 */ 744 public int selectAnimationLw(WindowState win, int transit); 745 746 /** 747 * Determine the animation to run for a rotation transition based on the 748 * top fullscreen windows {@link WindowManager.LayoutParams#rotationAnimation} 749 * and whether it is currently fullscreen and frontmost. 750 * 751 * @param anim The exiting animation resource id is stored in anim[0], the 752 * entering animation resource id is stored in anim[1]. 753 */ 754 public void selectRotationAnimationLw(int anim[]); 755 756 /** 757 * Validate whether the current top fullscreen has specified the same 758 * {@link WindowManager.LayoutParams#rotationAnimation} value as that 759 * being passed in from the previous top fullscreen window. 760 * 761 * @param exitAnimId exiting resource id from the previous window. 762 * @param enterAnimId entering resource id from the previous window. 763 * @param forceDefault For rotation animations only, if true ignore the 764 * animation values and just return false. 765 * @return true if the previous values are still valid, false if they 766 * should be replaced with the default. 767 */ 768 public boolean validateRotationAnimationLw(int exitAnimId, int enterAnimId, 769 boolean forceDefault); 770 771 /** 772 * Create and return an animation to re-display a force hidden window. 773 */ 774 public Animation createForceHideEnterAnimation(boolean onWallpaper, 775 boolean goingToNotificationShade); 776 777 /** 778 * Create and return an animation to let the wallpaper disappear after being shown on a force 779 * hiding window. 780 */ 781 public Animation createForceHideWallpaperExitAnimation(boolean goingToNotificationShade); 782 783 /** 784 * Called from the input reader thread before a key is enqueued. 785 * 786 * <p>There are some actions that need to be handled here because they 787 * affect the power state of the device, for example, the power keys. 788 * Generally, it's best to keep as little as possible in the queue thread 789 * because it's the most fragile. 790 * @param event The key event. 791 * @param policyFlags The policy flags associated with the key. 792 * 793 * @return Actions flags: may be {@link #ACTION_PASS_TO_USER}. 794 */ 795 public int interceptKeyBeforeQueueing(KeyEvent event, int policyFlags); 796 797 /** 798 * Called from the input reader thread before a motion is enqueued when the device is in a 799 * non-interactive state. 800 * 801 * <p>There are some actions that need to be handled here because they 802 * affect the power state of the device, for example, waking on motions. 803 * Generally, it's best to keep as little as possible in the queue thread 804 * because it's the most fragile. 805 * @param policyFlags The policy flags associated with the motion. 806 * 807 * @return Actions flags: may be {@link #ACTION_PASS_TO_USER}. 808 */ 809 public int interceptMotionBeforeQueueingNonInteractive(long whenNanos, int policyFlags); 810 811 /** 812 * Called from the input dispatcher thread before a key is dispatched to a window. 813 * 814 * <p>Allows you to define 815 * behavior for keys that can not be overridden by applications. 816 * This method is called from the input thread, with no locks held. 817 * 818 * @param win The window that currently has focus. This is where the key 819 * event will normally go. 820 * @param event The key event. 821 * @param policyFlags The policy flags associated with the key. 822 * @return 0 if the key should be dispatched immediately, -1 if the key should 823 * not be dispatched ever, or a positive value indicating the number of 824 * milliseconds by which the key dispatch should be delayed before trying 825 * again. 826 */ 827 public long interceptKeyBeforeDispatching(WindowState win, KeyEvent event, int policyFlags); 828 829 /** 830 * Called from the input dispatcher thread when an application did not handle 831 * a key that was dispatched to it. 832 * 833 * <p>Allows you to define default global behavior for keys that were not handled 834 * by applications. This method is called from the input thread, with no locks held. 835 * 836 * @param win The window that currently has focus. This is where the key 837 * event will normally go. 838 * @param event The key event. 839 * @param policyFlags The policy flags associated with the key. 840 * @return Returns an alternate key event to redispatch as a fallback, or null to give up. 841 * The caller is responsible for recycling the key event. 842 */ 843 public KeyEvent dispatchUnhandledKey(WindowState win, KeyEvent event, int policyFlags); 844 845 /** 846 * Called when layout of the windows is about to start. 847 * 848 * @param isDefaultDisplay true if window is on {@link Display#DEFAULT_DISPLAY}. 849 * @param displayWidth The current full width of the screen. 850 * @param displayHeight The current full height of the screen. 851 * @param displayRotation The current rotation being applied to the base 852 * window. 853 */ 854 public void beginLayoutLw(boolean isDefaultDisplay, int displayWidth, int displayHeight, 855 int displayRotation); 856 857 /** 858 * Returns the bottom-most layer of the system decor, above which no policy decor should 859 * be applied. 860 */ 861 public int getSystemDecorLayerLw(); 862 863 /** 864 * Return the rectangle of the screen that is available for applications to run in. 865 * This will be called immediately after {@link #beginLayoutLw}. 866 * 867 * @param r The rectangle to be filled with the boundaries available to applications. 868 */ 869 public void getContentRectLw(Rect r); 870 871 /** 872 * Called for each window attached to the window manager as layout is 873 * proceeding. The implementation of this function must take care of 874 * setting the window's frame, either here or in finishLayout(). 875 * 876 * @param win The window being positioned. 877 * @param attached For sub-windows, the window it is attached to; this 878 * window will already have had layoutWindow() called on it 879 * so you can use its Rect. Otherwise null. 880 */ 881 public void layoutWindowLw(WindowState win, WindowState attached); 882 883 884 /** 885 * Return the insets for the areas covered by system windows. These values 886 * are computed on the most recent layout, so they are not guaranteed to 887 * be correct. 888 * 889 * @param attrs The LayoutParams of the window. 890 * @param rotation Rotation of the display. 891 * @param outContentInsets The areas covered by system windows, expressed as positive insets. 892 * @param outStableInsets The areas covered by stable system windows irrespective of their 893 * current visibility. Expressed as positive insets. 894 * @param outOutsets The areas that are not real display, but we would like to treat as such. 895 * 896 */ 897 public void getInsetHintLw(WindowManager.LayoutParams attrs, int rotation, 898 Rect outContentInsets, Rect outStableInsets, Rect outOutsets); 899 900 /** 901 * Called when layout of the windows is finished. After this function has 902 * returned, all windows given to layoutWindow() <em>must</em> have had a 903 * frame assigned. 904 */ 905 public void finishLayoutLw(); 906 907 /** Layout state may have changed (so another layout will be performed) */ 908 static final int FINISH_LAYOUT_REDO_LAYOUT = 0x0001; 909 /** Configuration state may have changed */ 910 static final int FINISH_LAYOUT_REDO_CONFIG = 0x0002; 911 /** Wallpaper may need to move */ 912 static final int FINISH_LAYOUT_REDO_WALLPAPER = 0x0004; 913 /** Need to recompute animations */ 914 static final int FINISH_LAYOUT_REDO_ANIM = 0x0008; 915 916 /** 917 * Called following layout of all windows before each window has policy applied. 918 * 919 * @param displayWidth The current full width of the screen. 920 * @param displayHeight The current full height of the screen. 921 */ 922 public void beginPostLayoutPolicyLw(int displayWidth, int displayHeight); 923 924 /** 925 * Called following layout of all window to apply policy to each window. 926 * 927 * @param win The window being positioned. 928 * @param attrs The LayoutParams of the window. 929 * @param attached For sub-windows, the window it is attached to. Otherwise null. 930 */ 931 public void applyPostLayoutPolicyLw(WindowState win, 932 WindowManager.LayoutParams attrs, WindowState attached); 933 934 /** 935 * Called following layout of all windows and after policy has been applied 936 * to each window. If in this function you do 937 * something that may have modified the animation state of another window, 938 * be sure to return non-zero in order to perform another pass through layout. 939 * 940 * @return Return any bit set of {@link #FINISH_LAYOUT_REDO_LAYOUT}, 941 * {@link #FINISH_LAYOUT_REDO_CONFIG}, {@link #FINISH_LAYOUT_REDO_WALLPAPER}, 942 * or {@link #FINISH_LAYOUT_REDO_ANIM}. 943 */ 944 public int finishPostLayoutPolicyLw(); 945 946 /** 947 * Return true if it is okay to perform animations for an app transition 948 * that is about to occur. You may return false for this if, for example, 949 * the lock screen is currently displayed so the switch should happen 950 * immediately. 951 */ 952 public boolean allowAppAnimationsLw(); 953 954 955 /** 956 * A new window has been focused. 957 */ 958 public int focusChangedLw(WindowState lastFocus, WindowState newFocus); 959 960 /** 961 * Called when the device has started waking up. 962 */ 963 public void startedWakingUp(); 964 965 /** 966 * Called when the device has finished waking up. 967 */ 968 public void finishedWakingUp(); 969 970 /** 971 * Called when the device has started going to sleep. 972 * 973 * @param why {@link #OFF_BECAUSE_OF_USER}, {@link #OFF_BECAUSE_OF_ADMIN}, 974 * or {@link #OFF_BECAUSE_OF_TIMEOUT}. 975 */ 976 public void startedGoingToSleep(int why); 977 978 /** 979 * Called when the device has finished going to sleep. 980 * 981 * @param why {@link #OFF_BECAUSE_OF_USER}, {@link #OFF_BECAUSE_OF_ADMIN}, 982 * or {@link #OFF_BECAUSE_OF_TIMEOUT}. 983 */ 984 public void finishedGoingToSleep(int why); 985 986 /** 987 * Called when the device is about to turn on the screen to show content. 988 * When waking up, this method will be called once after the call to wakingUp(). 989 * When dozing, the method will be called sometime after the call to goingToSleep() and 990 * may be called repeatedly in the case where the screen is pulsing on and off. 991 * 992 * Must call back on the listener to tell it when the higher-level system 993 * is ready for the screen to go on (i.e. the lock screen is shown). 994 */ 995 public void screenTurningOn(ScreenOnListener screenOnListener); 996 997 /** 998 * Called when the device has actually turned on the screen, i.e. the display power state has 999 * been set to ON and the screen is unblocked. 1000 */ 1001 public void screenTurnedOn(); 1002 1003 /** 1004 * Called when the device has turned the screen off. 1005 */ 1006 public void screenTurnedOff(); 1007 1008 public interface ScreenOnListener { 1009 void onScreenOn(); 1010 } 1011 1012 /** 1013 * Return whether the default display is on and not blocked by a black surface. 1014 */ 1015 public boolean isScreenOn(); 1016 1017 /** 1018 * Tell the policy that the lid switch has changed state. 1019 * @param whenNanos The time when the change occurred in uptime nanoseconds. 1020 * @param lidOpen True if the lid is now open. 1021 */ 1022 public void notifyLidSwitchChanged(long whenNanos, boolean lidOpen); 1023 1024 /** 1025 * Tell the policy that the camera lens has been covered or uncovered. 1026 * @param whenNanos The time when the change occurred in uptime nanoseconds. 1027 * @param lensCovered True if the lens is covered. 1028 */ 1029 public void notifyCameraLensCoverSwitchChanged(long whenNanos, boolean lensCovered); 1030 1031 /** 1032 * Tell the policy if anyone is requesting that keyguard not come on. 1033 * 1034 * @param enabled Whether keyguard can be on or not. does not actually 1035 * turn it on, unless it was previously disabled with this function. 1036 * 1037 * @see android.app.KeyguardManager.KeyguardLock#disableKeyguard() 1038 * @see android.app.KeyguardManager.KeyguardLock#reenableKeyguard() 1039 */ 1040 @SuppressWarnings("javadoc") 1041 public void enableKeyguard(boolean enabled); 1042 1043 /** 1044 * Callback used by {@link WindowManagerPolicy#exitKeyguardSecurely} 1045 */ 1046 interface OnKeyguardExitResult { 1047 void onKeyguardExitResult(boolean success); 1048 } 1049 1050 /** 1051 * Tell the policy if anyone is requesting the keyguard to exit securely 1052 * (this would be called after the keyguard was disabled) 1053 * @param callback Callback to send the result back. 1054 * @see android.app.KeyguardManager#exitKeyguardSecurely(android.app.KeyguardManager.OnKeyguardExitResult) 1055 */ 1056 @SuppressWarnings("javadoc") 1057 void exitKeyguardSecurely(OnKeyguardExitResult callback); 1058 1059 /** 1060 * isKeyguardLocked 1061 * 1062 * Return whether the keyguard is currently locked. 1063 * 1064 * @return true if in keyguard is locked. 1065 */ 1066 public boolean isKeyguardLocked(); 1067 1068 /** 1069 * isKeyguardSecure 1070 * 1071 * Return whether the keyguard requires a password to unlock. 1072 * 1073 * @return true if in keyguard is secure. 1074 */ 1075 public boolean isKeyguardSecure(); 1076 1077 /** 1078 * Return whether the keyguard is on. 1079 * 1080 * @return true if in keyguard is on. 1081 */ 1082 public boolean isKeyguardShowingOrOccluded(); 1083 1084 /** 1085 * inKeyguardRestrictedKeyInputMode 1086 * 1087 * if keyguard screen is showing or in restricted key input mode (i.e. in 1088 * keyguard password emergency screen). When in such mode, certain keys, 1089 * such as the Home key and the right soft keys, don't work. 1090 * 1091 * @return true if in keyguard restricted input mode. 1092 */ 1093 public boolean inKeyguardRestrictedKeyInputMode(); 1094 1095 /** 1096 * Ask the policy to dismiss the keyguard, if it is currently shown. 1097 */ 1098 public void dismissKeyguardLw(); 1099 1100 /** 1101 * Notifies the keyguard that the activity has drawn it was waiting for. 1102 */ 1103 public void notifyActivityDrawnForKeyguardLw(); 1104 1105 /** 1106 * Ask the policy whether the Keyguard has drawn. If the Keyguard is disabled, this method 1107 * returns true as soon as we know that Keyguard is disabled. 1108 * 1109 * @return true if the keyguard has drawn. 1110 */ 1111 public boolean isKeyguardDrawnLw(); 1112 1113 /** 1114 * Given an orientation constant, returns the appropriate surface rotation, 1115 * taking into account sensors, docking mode, rotation lock, and other factors. 1116 * 1117 * @param orientation An orientation constant, such as 1118 * {@link android.content.pm.ActivityInfo#SCREEN_ORIENTATION_LANDSCAPE}. 1119 * @param lastRotation The most recently used rotation. 1120 * @return The surface rotation to use. 1121 */ 1122 public int rotationForOrientationLw(@ActivityInfo.ScreenOrientation int orientation, 1123 int lastRotation); 1124 1125 /** 1126 * Given an orientation constant and a rotation, returns true if the rotation 1127 * has compatible metrics to the requested orientation. For example, if 1128 * the application requested landscape and got seascape, then the rotation 1129 * has compatible metrics; if the application requested portrait and got landscape, 1130 * then the rotation has incompatible metrics; if the application did not specify 1131 * a preference, then anything goes. 1132 * 1133 * @param orientation An orientation constant, such as 1134 * {@link android.content.pm.ActivityInfo#SCREEN_ORIENTATION_LANDSCAPE}. 1135 * @param rotation The rotation to check. 1136 * @return True if the rotation is compatible with the requested orientation. 1137 */ 1138 public boolean rotationHasCompatibleMetricsLw(@ActivityInfo.ScreenOrientation int orientation, 1139 int rotation); 1140 1141 /** 1142 * Called by the window manager when the rotation changes. 1143 * 1144 * @param rotation The new rotation. 1145 */ 1146 public void setRotationLw(int rotation); 1147 1148 /** 1149 * Called when the system is mostly done booting to set whether 1150 * the system should go into safe mode. 1151 */ 1152 public void setSafeMode(boolean safeMode); 1153 1154 /** 1155 * Called when the system is mostly done booting. 1156 */ 1157 public void systemReady(); 1158 1159 /** 1160 * Called when the system is done booting to the point where the 1161 * user can start interacting with it. 1162 */ 1163 public void systemBooted(); 1164 1165 /** 1166 * Show boot time message to the user. 1167 */ 1168 public void showBootMessage(final CharSequence msg, final boolean always); 1169 1170 /** 1171 * Hide the UI for showing boot messages, never to be displayed again. 1172 */ 1173 public void hideBootMessages(); 1174 1175 /** 1176 * Called when userActivity is signalled in the power manager. 1177 * This is safe to call from any thread, with any window manager locks held or not. 1178 */ 1179 public void userActivity(); 1180 1181 /** 1182 * Called when we have finished booting and can now display the home 1183 * screen to the user. This will happen after systemReady(), and at 1184 * this point the display is active. 1185 */ 1186 public void enableScreenAfterBoot(); 1187 1188 public void setCurrentOrientationLw(@ActivityInfo.ScreenOrientation int newOrientation); 1189 1190 /** 1191 * Call from application to perform haptic feedback on its window. 1192 */ 1193 public boolean performHapticFeedbackLw(WindowState win, int effectId, boolean always); 1194 1195 /** 1196 * Called when we have started keeping the screen on because a window 1197 * requesting this has become visible. 1198 */ 1199 public void keepScreenOnStartedLw(); 1200 1201 /** 1202 * Called when we have stopped keeping the screen on because the last window 1203 * requesting this is no longer visible. 1204 */ 1205 public void keepScreenOnStoppedLw(); 1206 1207 /** 1208 * Gets the current user rotation mode. 1209 * 1210 * @return The rotation mode. 1211 * 1212 * @see WindowManagerPolicy#USER_ROTATION_LOCKED 1213 * @see WindowManagerPolicy#USER_ROTATION_FREE 1214 */ 1215 @UserRotationMode 1216 public int getUserRotationMode(); 1217 1218 /** 1219 * Inform the policy that the user has chosen a preferred orientation ("rotation lock"). 1220 * 1221 * @param mode One of {@link WindowManagerPolicy#USER_ROTATION_LOCKED} or 1222 * {@link WindowManagerPolicy#USER_ROTATION_FREE}. 1223 * @param rotation One of {@link Surface#ROTATION_0}, {@link Surface#ROTATION_90}, 1224 * {@link Surface#ROTATION_180}, {@link Surface#ROTATION_270}. 1225 */ 1226 public void setUserRotationMode(@UserRotationMode int mode, @Surface.Rotation int rotation); 1227 1228 /** 1229 * Called when a new system UI visibility is being reported, allowing 1230 * the policy to adjust what is actually reported. 1231 * @param visibility The raw visibility reported by the status bar. 1232 * @return The new desired visibility. 1233 */ 1234 public int adjustSystemUiVisibilityLw(int visibility); 1235 1236 /** 1237 * Specifies whether there is an on-screen navigation bar separate from the status bar. 1238 */ 1239 public boolean hasNavigationBar(); 1240 1241 /** 1242 * Lock the device now. 1243 */ 1244 public void lockNow(Bundle options); 1245 1246 /** 1247 * Set the last used input method window state. This state is used to make IME transition 1248 * smooth. 1249 * @hide 1250 */ 1251 public void setLastInputMethodWindowLw(WindowState ime, WindowState target); 1252 1253 /** 1254 * Show the recents task list app. 1255 * @hide 1256 */ 1257 public void showRecentApps(); 1258 1259 /** 1260 * Show the global actions dialog. 1261 * @hide 1262 */ 1263 public void showGlobalActions(); 1264 1265 /** 1266 * @return The current height of the input method window. 1267 */ 1268 public int getInputMethodWindowVisibleHeightLw(); 1269 1270 /** 1271 * Called when the current user changes. Guaranteed to be called before the broadcast 1272 * of the new user id is made to all listeners. 1273 * 1274 * @param newUserId The id of the incoming user. 1275 */ 1276 public void setCurrentUserLw(int newUserId); 1277 1278 /** 1279 * Print the WindowManagerPolicy's state into the given stream. 1280 * 1281 * @param prefix Text to print at the front of each line. 1282 * @param writer The PrintWriter to which you should dump your state. This will be 1283 * closed for you after you return. 1284 * @param args additional arguments to the dump request. 1285 */ 1286 public void dump(String prefix, PrintWriter writer, String[] args); 1287 1288 /** 1289 * Returns whether a given window type can be magnified. 1290 * 1291 * @param windowType The window type. 1292 * @return True if the window can be magnified. 1293 */ 1294 public boolean canMagnifyWindow(int windowType); 1295 1296 /** 1297 * Returns whether a given window type is considered a top level one. 1298 * A top level window does not have a container, i.e. attached window, 1299 * or if it has a container it is laid out as a top-level window, not 1300 * as a child of its container. 1301 * 1302 * @param windowType The window type. 1303 * @return True if the window is a top level one. 1304 */ 1305 public boolean isTopLevelWindow(int windowType); 1306 1307 /** 1308 * Notifies the keyguard to start fading out. 1309 * 1310 * @param startTime the start time of the animation in uptime milliseconds 1311 * @param fadeoutDuration the duration of the exit animation, in milliseconds 1312 */ 1313 public void startKeyguardExitAnimation(long startTime, long fadeoutDuration); 1314 } 1315
