WindowManagerPolicy.java revision e849230f444653e692024b4321044cb9f6188919
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 17package android.view; 18 19import android.content.Context; 20import android.content.res.CompatibilityInfo; 21import android.content.res.Configuration; 22import android.graphics.Rect; 23import android.graphics.RectF; 24import android.os.IBinder; 25import android.os.LocalPowerManager; 26import android.os.Looper; 27import android.view.animation.Animation; 28 29import java.io.FileDescriptor; 30import java.io.PrintWriter; 31 32/** 33 * This interface supplies all UI-specific behavior of the window manager. An 34 * instance of it is created by the window manager when it starts up, and allows 35 * customization of window layering, special window types, key dispatching, and 36 * layout. 37 * 38 * <p>Because this provides deep interaction with the system window manager, 39 * specific methods on this interface can be called from a variety of contexts 40 * with various restrictions on what they can do. These are encoded through 41 * a suffixes at the end of a method encoding the thread the method is called 42 * from and any locks that are held when it is being called; if no suffix 43 * is attached to a method, then it is not called with any locks and may be 44 * called from the main window manager thread or another thread calling into 45 * the window manager. 46 * 47 * <p>The current suffixes are: 48 * 49 * <dl> 50 * <dt> Ti <dd> Called from the input thread. This is the thread that 51 * collects pending input events and dispatches them to the appropriate window. 52 * It may block waiting for events to be processed, so that the input stream is 53 * properly serialized. 54 * <dt> Tq <dd> Called from the low-level input queue thread. This is the 55 * thread that reads events out of the raw input devices and places them 56 * into the global input queue that is read by the <var>Ti</var> thread. 57 * This thread should not block for a long period of time on anything but the 58 * key driver. 59 * <dt> Lw <dd> Called with the main window manager lock held. Because the 60 * window manager is a very low-level system service, there are few other 61 * system services you can call with this lock held. It is explicitly okay to 62 * make calls into the package manager and power manager; it is explicitly not 63 * okay to make calls into the activity manager or most other services. Note that 64 * {@link android.content.Context#checkPermission(String, int, int)} and 65 * variations require calling into the activity manager. 66 * <dt> Li <dd> Called with the input thread lock held. This lock can be 67 * acquired by the window manager while it holds the window lock, so this is 68 * even more restrictive than <var>Lw</var>. 69 * </dl> 70 * 71 * @hide 72 */ 73public interface WindowManagerPolicy { 74 // Policy flags. These flags are also defined in frameworks/base/include/ui/Input.h. 75 public final static int FLAG_WAKE = 0x00000001; 76 public final static int FLAG_WAKE_DROPPED = 0x00000002; 77 public final static int FLAG_SHIFT = 0x00000004; 78 public final static int FLAG_CAPS_LOCK = 0x00000008; 79 public final static int FLAG_ALT = 0x00000010; 80 public final static int FLAG_ALT_GR = 0x00000020; 81 public final static int FLAG_MENU = 0x00000040; 82 public final static int FLAG_LAUNCHER = 0x00000080; 83 public final static int FLAG_VIRTUAL = 0x00000100; 84 85 public final static int FLAG_INJECTED = 0x01000000; 86 public final static int FLAG_TRUSTED = 0x02000000; 87 public final static int FLAG_FILTERED = 0x04000000; 88 public final static int FLAG_DISABLE_KEY_REPEAT = 0x08000000; 89 90 public final static int FLAG_WOKE_HERE = 0x10000000; 91 public final static int FLAG_BRIGHT_HERE = 0x20000000; 92 public final static int FLAG_PASS_TO_USER = 0x40000000; 93 94 // Flags used for indicating whether the internal and/or external input devices 95 // of some type are available. 96 public final static int PRESENCE_INTERNAL = 1 << 0; 97 public final static int PRESENCE_EXTERNAL = 1 << 1; 98 99 public final static boolean WATCH_POINTER = false; 100 101 /** 102 * Sticky broadcast of the current HDMI plugged state. 103 */ 104 public final static String ACTION_HDMI_PLUGGED = "android.intent.action.HDMI_PLUGGED"; 105 106 /** 107 * Extra in {@link #ACTION_HDMI_PLUGGED} indicating the state: true if 108 * plugged in to HDMI, false if not. 109 */ 110 public final static String EXTRA_HDMI_PLUGGED_STATE = "state"; 111 112 /** 113 * Pass this event to the user / app. To be returned from 114 * {@link #interceptKeyBeforeQueueing}. 115 */ 116 public final static int ACTION_PASS_TO_USER = 0x00000001; 117 118 /** 119 * This key event should extend the user activity timeout and turn the lights on. 120 * To be returned from {@link #interceptKeyBeforeQueueing}. 121 * Do not return this and {@link #ACTION_GO_TO_SLEEP} or {@link #ACTION_PASS_TO_USER}. 122 */ 123 public final static int ACTION_POKE_USER_ACTIVITY = 0x00000002; 124 125 /** 126 * This key event should put the device to sleep (and engage keyguard if necessary) 127 * To be returned from {@link #interceptKeyBeforeQueueing}. 128 * Do not return this and {@link #ACTION_POKE_USER_ACTIVITY} or {@link #ACTION_PASS_TO_USER}. 129 */ 130 public final static int ACTION_GO_TO_SLEEP = 0x00000004; 131 132 /** 133 * Interface to the Window Manager state associated with a particular 134 * window. You can hold on to an instance of this interface from the call 135 * to prepareAddWindow() until removeWindow(). 136 */ 137 public interface WindowState { 138 /** 139 * Perform standard frame computation. The result can be obtained with 140 * getFrame() if so desired. Must be called with the window manager 141 * lock held. 142 * 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 147 * of the window. 148 * @param systemFrame The frame within the display that any system 149 * elements are currently covering. These indicate which parts of 150 * the window should be considered completely obscured by the screen 151 * decorations. 152 * @param contentFrame The frame within the display in which we would 153 * like active content to appear. This will cause windows behind to 154 * be resized to match the given content frame. 155 * @param visibleFrame The frame within the display that the window 156 * is actually visible, used for computing its visible insets to be 157 * given to windows behind. 158 * This can be used as a hint for scrolling (avoiding resizing) 159 * the window to make certain that parts of its content 160 * are visible. 161 */ 162 public void computeFrameLw(Rect parentFrame, Rect displayFrame, 163 Rect systemFrame, Rect contentFrame, Rect visibleFrame); 164 165 /** 166 * Retrieve the current frame of the window that has been assigned by 167 * the window manager. Must be called with the window manager lock held. 168 * 169 * @return Rect The rectangle holding the window frame. 170 */ 171 public Rect getFrameLw(); 172 173 /** 174 * Retrieve the current frame of the window that is actually shown. 175 * Must be called with the window manager lock held. 176 * 177 * @return Rect The rectangle holding the shown window frame. 178 */ 179 public RectF getShownFrameLw(); 180 181 /** 182 * Retrieve the frame of the display that this window was last 183 * laid out in. Must be called with the 184 * window manager lock held. 185 * 186 * @return Rect The rectangle holding the display frame. 187 */ 188 public Rect getDisplayFrameLw(); 189 190 /** 191 * Retrieve the frame of the system elements that last covered the window. 192 * Must be called with the window manager lock held. 193 * 194 * @return Rect The rectangle holding the system frame. 195 */ 196 public Rect getSystemFrameLw(); 197 198 /** 199 * Retrieve the frame of the content area that this window was last 200 * laid out in. This is the area in which the content of the window 201 * should be placed. It will be smaller than the display frame to 202 * account for screen decorations such as a status bar or soft 203 * keyboard. Must be called with the 204 * window manager lock held. 205 * 206 * @return Rect The rectangle holding the content frame. 207 */ 208 public Rect getContentFrameLw(); 209 210 /** 211 * Retrieve the frame of the visible area that this window was last 212 * laid out in. This is the area of the screen in which the window 213 * will actually be fully visible. It will be smaller than the 214 * content frame to account for transient UI elements blocking it 215 * such as an input method's candidates UI. Must be called with the 216 * window manager lock held. 217 * 218 * @return Rect The rectangle holding the visible frame. 219 */ 220 public Rect getVisibleFrameLw(); 221 222 /** 223 * Returns true if this window is waiting to receive its given 224 * internal insets from the client app, and so should not impact the 225 * layout of other windows. 226 */ 227 public boolean getGivenInsetsPendingLw(); 228 229 /** 230 * Retrieve the insets given by this window's client for the content 231 * area of windows behind it. Must be called with the 232 * window manager lock held. 233 * 234 * @return Rect The left, top, right, and bottom insets, relative 235 * to the window's frame, of the actual contents. 236 */ 237 public Rect getGivenContentInsetsLw(); 238 239 /** 240 * Retrieve the insets given by this window's client for the visible 241 * area of windows behind it. Must be called with the 242 * window manager lock held. 243 * 244 * @return Rect The left, top, right, and bottom insets, relative 245 * to the window's frame, of the actual visible area. 246 */ 247 public Rect getGivenVisibleInsetsLw(); 248 249 /** 250 * Retrieve the current LayoutParams of the window. 251 * 252 * @return WindowManager.LayoutParams The window's internal LayoutParams 253 * instance. 254 */ 255 public WindowManager.LayoutParams getAttrs(); 256 257 /** 258 * Return whether this window needs the menu key shown. Must be called 259 * with window lock held, because it may need to traverse down through 260 * window list to determine the result. 261 * @param bottom The bottom-most window to consider when determining this. 262 */ 263 public boolean getNeedsMenuLw(WindowState bottom); 264 265 /** 266 * Retrieve the current system UI visibility flags associated with 267 * this window. 268 */ 269 public int getSystemUiVisibility(); 270 271 /** 272 * Get the layer at which this window's surface will be Z-ordered. 273 */ 274 public int getSurfaceLayer(); 275 276 /** 277 * Return the token for the application (actually activity) that owns 278 * this window. May return null for system windows. 279 * 280 * @return An IApplicationToken identifying the owning activity. 281 */ 282 public IApplicationToken getAppToken(); 283 284 /** 285 * Return true if, at any point, the application token associated with 286 * this window has actually displayed any windows. This is most useful 287 * with the "starting up" window to determine if any windows were 288 * displayed when it is closed. 289 * 290 * @return Returns true if one or more windows have been displayed, 291 * else false. 292 */ 293 public boolean hasAppShownWindows(); 294 295 /** 296 * Is this window visible? It is not visible if there is no 297 * surface, or we are in the process of running an exit animation 298 * that will remove the surface. 299 */ 300 boolean isVisibleLw(); 301 302 /** 303 * Like {@link #isVisibleLw}, but also counts a window that is currently 304 * "hidden" behind the keyguard as visible. This allows us to apply 305 * things like window flags that impact the keyguard. 306 */ 307 boolean isVisibleOrBehindKeyguardLw(); 308 309 /** 310 * Is this window currently visible to the user on-screen? It is 311 * displayed either if it is visible or it is currently running an 312 * animation before no longer being visible. Must be called with the 313 * window manager lock held. 314 */ 315 boolean isDisplayedLw(); 316 317 /** 318 * Return true if this window (or a window it is attached to, but not 319 * considering its app token) is currently animating. 320 */ 321 public boolean isAnimatingLw(); 322 323 /** 324 * Is this window considered to be gone for purposes of layout? 325 */ 326 boolean isGoneForLayoutLw(); 327 328 /** 329 * Returns true if this window has been shown on screen at some time in 330 * the past. Must be called with the window manager lock held. 331 */ 332 public boolean hasDrawnLw(); 333 334 /** 335 * Can be called by the policy to force a window to be hidden, 336 * regardless of whether the client or window manager would like 337 * it shown. Must be called with the window manager lock held. 338 * Returns true if {@link #showLw} was last called for the window. 339 */ 340 public boolean hideLw(boolean doAnimation); 341 342 /** 343 * Can be called to undo the effect of {@link #hideLw}, allowing a 344 * window to be shown as long as the window manager and client would 345 * also like it to be shown. Must be called with the window manager 346 * lock held. 347 * Returns true if {@link #hideLw} was last called for the window. 348 */ 349 public boolean showLw(boolean doAnimation); 350 351 /** 352 * Check whether the process hosting this window is currently alive. 353 */ 354 public boolean isAlive(); 355 } 356 357 /** 358 * Representation of a "fake window" that the policy has added to the 359 * window manager to consume events. 360 */ 361 public interface FakeWindow { 362 /** 363 * Remove the fake window from the window manager. 364 */ 365 void dismiss(); 366 } 367 368 /** 369 * Interface for calling back in to the window manager that is private 370 * between it and the policy. 371 */ 372 public interface WindowManagerFuncs { 373 public static final int LID_ABSENT = -1; 374 public static final int LID_CLOSED = 0; 375 public static final int LID_OPEN = 1; 376 377 /** 378 * Ask the window manager to re-evaluate the system UI flags. 379 */ 380 public void reevaluateStatusBarVisibility(); 381 382 /** 383 * Add a fake window to the window manager. This window sits 384 * at the top of the other windows and consumes events. 385 */ 386 public FakeWindow addFakeWindow(Looper looper, 387 InputEventReceiver.Factory inputEventReceiverFactory, 388 String name, int windowType, int layoutParamsFlags, boolean canReceiveKeys, 389 boolean hasFocus, boolean touchFullscreen); 390 391 /** 392 * Returns a code that describes the current state of the lid switch. 393 */ 394 public int getLidState(); 395 396 /** 397 * Creates an input channel that will receive all input from the input dispatcher. 398 */ 399 public InputChannel monitorInput(String name); 400 } 401 402 /** 403 * Bit mask that is set for all enter transition. 404 */ 405 public final int TRANSIT_ENTER_MASK = 0x1000; 406 407 /** 408 * Bit mask that is set for all exit transitions. 409 */ 410 public final int TRANSIT_EXIT_MASK = 0x2000; 411 412 /** Not set up for a transition. */ 413 public final int TRANSIT_UNSET = -1; 414 /** No animation for transition. */ 415 public final int TRANSIT_NONE = 0; 416 /** Window has been added to the screen. */ 417 public final int TRANSIT_ENTER = 1 | TRANSIT_ENTER_MASK; 418 /** Window has been removed from the screen. */ 419 public final int TRANSIT_EXIT = 2 | TRANSIT_EXIT_MASK; 420 /** Window has been made visible. */ 421 public final int TRANSIT_SHOW = 3 | TRANSIT_ENTER_MASK; 422 /** Window has been made invisible. */ 423 public final int TRANSIT_HIDE = 4 | TRANSIT_EXIT_MASK; 424 /** The "application starting" preview window is no longer needed, and will 425 * animate away to show the real window. */ 426 public final int TRANSIT_PREVIEW_DONE = 5; 427 /** A window in a new activity is being opened on top of an existing one 428 * in the same task. */ 429 public final int TRANSIT_ACTIVITY_OPEN = 6 | TRANSIT_ENTER_MASK; 430 /** The window in the top-most activity is being closed to reveal the 431 * previous activity in the same task. */ 432 public final int TRANSIT_ACTIVITY_CLOSE = 7 | TRANSIT_EXIT_MASK; 433 /** A window in a new task is being opened on top of an existing one 434 * in another activity's task. */ 435 public final int TRANSIT_TASK_OPEN = 8 | TRANSIT_ENTER_MASK; 436 /** A window in the top-most activity is being closed to reveal the 437 * previous activity in a different task. */ 438 public final int TRANSIT_TASK_CLOSE = 9 | TRANSIT_EXIT_MASK; 439 /** A window in an existing task is being displayed on top of an existing one 440 * in another activity's task. */ 441 public final int TRANSIT_TASK_TO_FRONT = 10 | TRANSIT_ENTER_MASK; 442 /** A window in an existing task is being put below all other tasks. */ 443 public final int TRANSIT_TASK_TO_BACK = 11 | TRANSIT_EXIT_MASK; 444 /** A window in a new activity that doesn't have a wallpaper is being 445 * opened on top of one that does, effectively closing the wallpaper. */ 446 public final int TRANSIT_WALLPAPER_CLOSE = 12 | TRANSIT_EXIT_MASK; 447 /** A window in a new activity that does have a wallpaper is being 448 * opened on one that didn't, effectively opening the wallpaper. */ 449 public final int TRANSIT_WALLPAPER_OPEN = 13 | TRANSIT_ENTER_MASK; 450 /** A window in a new activity is being opened on top of an existing one, 451 * and both are on top of the wallpaper. */ 452 public final int TRANSIT_WALLPAPER_INTRA_OPEN = 14 | TRANSIT_ENTER_MASK; 453 /** The window in the top-most activity is being closed to reveal the 454 * previous activity, and both are on top of he wallpaper. */ 455 public final int TRANSIT_WALLPAPER_INTRA_CLOSE = 15 | TRANSIT_EXIT_MASK; 456 457 // NOTE: screen off reasons are in order of significance, with more 458 // important ones lower than less important ones. 459 460 /** Screen turned off because of a device admin */ 461 public final int OFF_BECAUSE_OF_ADMIN = 1; 462 /** Screen turned off because of power button */ 463 public final int OFF_BECAUSE_OF_USER = 2; 464 /** Screen turned off because of timeout */ 465 public final int OFF_BECAUSE_OF_TIMEOUT = 3; 466 /** Screen turned off because of proximity sensor */ 467 public final int OFF_BECAUSE_OF_PROX_SENSOR = 4; 468 469 /** When not otherwise specified by the activity's screenOrientation, rotation should be 470 * determined by the system (that is, using sensors). */ 471 public final int USER_ROTATION_FREE = 0; 472 /** When not otherwise specified by the activity's screenOrientation, rotation is set by 473 * the user. */ 474 public final int USER_ROTATION_LOCKED = 1; 475 476 /** 477 * Perform initialization of the policy. 478 * 479 * @param context The system context we are running in. 480 * @param powerManager 481 */ 482 public void init(Context context, IWindowManager windowManager, 483 WindowManagerFuncs windowManagerFuncs, 484 LocalPowerManager powerManager); 485 486 /** 487 * Called by window manager once it has the initial, default native 488 * display dimensions. 489 */ 490 public void setInitialDisplaySize(Display display, int width, int height); 491 492 /** 493 * Check permissions when adding a window. 494 * 495 * @param attrs The window's LayoutParams. 496 * 497 * @return {@link WindowManagerImpl#ADD_OKAY} if the add can proceed; 498 * else an error code, usually 499 * {@link WindowManagerImpl#ADD_PERMISSION_DENIED}, to abort the add. 500 */ 501 public int checkAddPermission(WindowManager.LayoutParams attrs); 502 503 /** 504 * Sanitize the layout parameters coming from a client. Allows the policy 505 * to do things like ensure that windows of a specific type can't take 506 * input focus. 507 * 508 * @param attrs The window layout parameters to be modified. These values 509 * are modified in-place. 510 */ 511 public void adjustWindowParamsLw(WindowManager.LayoutParams attrs); 512 513 /** 514 * After the window manager has computed the current configuration based 515 * on its knowledge of the display and input devices, it gives the policy 516 * a chance to adjust the information contained in it. If you want to 517 * leave it as-is, simply do nothing. 518 * 519 * <p>This method may be called by any thread in the window manager, but 520 * no internal locks in the window manager will be held. 521 * 522 * @param config The Configuration being computed, for you to change as 523 * desired. 524 * @param keyboardPresence Flags that indicate whether internal or external 525 * keyboards are present. 526 * @param navigationPresence Flags that indicate whether internal or external 527 * navigation devices are present. 528 */ 529 public void adjustConfigurationLw(Configuration config, int keyboardPresence, 530 int navigationPresence); 531 532 /** 533 * Assign a window type to a layer. Allows you to control how different 534 * kinds of windows are ordered on-screen. 535 * 536 * @param type The type of window being assigned. 537 * 538 * @return int An arbitrary integer used to order windows, with lower 539 * numbers below higher ones. 540 */ 541 public int windowTypeToLayerLw(int type); 542 543 /** 544 * Return how to Z-order sub-windows in relation to the window they are 545 * attached to. Return positive to have them ordered in front, negative for 546 * behind. 547 * 548 * @param type The sub-window type code. 549 * 550 * @return int Layer in relation to the attached window, where positive is 551 * above and negative is below. 552 */ 553 public int subWindowTypeToLayerLw(int type); 554 555 /** 556 * Get the highest layer (actually one more than) that the wallpaper is 557 * allowed to be in. 558 */ 559 public int getMaxWallpaperLayer(); 560 561 /** 562 * Return true if the policy desires a full unified system nav bar. Otherwise, 563 * it is a phone-style status bar with optional nav bar. 564 */ 565 public boolean hasSystemNavBar(); 566 567 /** 568 * Return the display width available after excluding any screen 569 * decorations that can never be removed. That is, system bar or 570 * button bar. 571 */ 572 public int getNonDecorDisplayWidth(int fullWidth, int fullHeight, int rotation); 573 574 /** 575 * Return the display height available after excluding any screen 576 * decorations that can never be removed. That is, system bar or 577 * button bar. 578 */ 579 public int getNonDecorDisplayHeight(int fullWidth, int fullHeight, int rotation); 580 581 /** 582 * Return the available screen width that we should report for the 583 * configuration. This must be no larger than 584 * {@link #getNonDecorDisplayWidth(int, int, int)}; it may be smaller than 585 * that to account for more transient decoration like a status bar. 586 */ 587 public int getConfigDisplayWidth(int fullWidth, int fullHeight, int rotation); 588 589 /** 590 * Return the available screen height that we should report for the 591 * configuration. This must be no larger than 592 * {@link #getNonDecorDisplayHeight(int, int, int)}; it may be smaller than 593 * that to account for more transient decoration like a status bar. 594 */ 595 public int getConfigDisplayHeight(int fullWidth, int fullHeight, int rotation); 596 597 /** 598 * Return whether the given window should forcibly hide everything 599 * behind it. Typically returns true for the keyguard. 600 */ 601 public boolean doesForceHide(WindowState win, WindowManager.LayoutParams attrs); 602 603 /** 604 * Determine if a window that is behind one that is force hiding 605 * (as determined by {@link #doesForceHide}) should actually be hidden. 606 * For example, typically returns false for the status bar. Be careful 607 * to return false for any window that you may hide yourself, since this 608 * will conflict with what you set. 609 */ 610 public boolean canBeForceHidden(WindowState win, WindowManager.LayoutParams attrs); 611 612 /** 613 * Called when the system would like to show a UI to indicate that an 614 * application is starting. You can use this to add a 615 * APPLICATION_STARTING_TYPE window with the given appToken to the window 616 * manager (using the normal window manager APIs) that will be shown until 617 * the application displays its own window. This is called without the 618 * window manager locked so that you can call back into it. 619 * 620 * @param appToken Token of the application being started. 621 * @param packageName The name of the application package being started. 622 * @param theme Resource defining the application's overall visual theme. 623 * @param nonLocalizedLabel The default title label of the application if 624 * no data is found in the resource. 625 * @param labelRes The resource ID the application would like to use as its name. 626 * @param icon The resource ID the application would like to use as its icon. 627 * @param windowFlags Window layout flags. 628 * 629 * @return Optionally you can return the View that was used to create the 630 * window, for easy removal in removeStartingWindow. 631 * 632 * @see #removeStartingWindow 633 */ 634 public View addStartingWindow(IBinder appToken, String packageName, 635 int theme, CompatibilityInfo compatInfo, CharSequence nonLocalizedLabel, 636 int labelRes, int icon, int windowFlags); 637 638 /** 639 * Called when the first window of an application has been displayed, while 640 * {@link #addStartingWindow} has created a temporary initial window for 641 * that application. You should at this point remove the window from the 642 * window manager. This is called without the window manager locked so 643 * that you can call back into it. 644 * 645 * <p>Note: due to the nature of these functions not being called with the 646 * window manager locked, you must be prepared for this function to be 647 * called multiple times and/or an initial time with a null View window 648 * even if you previously returned one. 649 * 650 * @param appToken Token of the application that has started. 651 * @param window Window View that was returned by createStartingWindow. 652 * 653 * @see #addStartingWindow 654 */ 655 public void removeStartingWindow(IBinder appToken, View window); 656 657 /** 658 * Prepare for a window being added to the window manager. You can throw an 659 * exception here to prevent the window being added, or do whatever setup 660 * you need to keep track of the window. 661 * 662 * @param win The window being added. 663 * @param attrs The window's LayoutParams. 664 * 665 * @return {@link WindowManagerImpl#ADD_OKAY} if the add can proceed, else an 666 * error code to abort the add. 667 */ 668 public int prepareAddWindowLw(WindowState win, 669 WindowManager.LayoutParams attrs); 670 671 /** 672 * Called when a window is being removed from a window manager. Must not 673 * throw an exception -- clean up as much as possible. 674 * 675 * @param win The window being removed. 676 */ 677 public void removeWindowLw(WindowState win); 678 679 /** 680 * Control the animation to run when a window's state changes. Return a 681 * non-0 number to force the animation to a specific resource ID, or 0 682 * to use the default animation. 683 * 684 * @param win The window that is changing. 685 * @param transit What is happening to the window: {@link #TRANSIT_ENTER}, 686 * {@link #TRANSIT_EXIT}, {@link #TRANSIT_SHOW}, or 687 * {@link #TRANSIT_HIDE}. 688 * 689 * @return Resource ID of the actual animation to use, or 0 for none. 690 */ 691 public int selectAnimationLw(WindowState win, int transit); 692 693 /** 694 * Create and return an animation to re-display a force hidden window. 695 */ 696 public Animation createForceHideEnterAnimation(boolean onWallpaper); 697 698 /** 699 * Called from the input reader thread before a key is enqueued. 700 * 701 * <p>There are some actions that need to be handled here because they 702 * affect the power state of the device, for example, the power keys. 703 * Generally, it's best to keep as little as possible in the queue thread 704 * because it's the most fragile. 705 * @param event The key event. 706 * @param policyFlags The policy flags associated with the key. 707 * @param isScreenOn True if the screen is already on 708 * 709 * @return The bitwise or of the {@link #ACTION_PASS_TO_USER}, 710 * {@link #ACTION_POKE_USER_ACTIVITY} and {@link #ACTION_GO_TO_SLEEP} flags. 711 */ 712 public int interceptKeyBeforeQueueing(KeyEvent event, int policyFlags, boolean isScreenOn); 713 714 /** 715 * Called from the input reader thread before a motion is enqueued when the screen is off. 716 * 717 * <p>There are some actions that need to be handled here because they 718 * affect the power state of the device, for example, waking on motions. 719 * Generally, it's best to keep as little as possible in the queue thread 720 * because it's the most fragile. 721 * @param policyFlags The policy flags associated with the motion. 722 * 723 * @return The bitwise or of the {@link #ACTION_PASS_TO_USER}, 724 * {@link #ACTION_POKE_USER_ACTIVITY} and {@link #ACTION_GO_TO_SLEEP} flags. 725 */ 726 public int interceptMotionBeforeQueueingWhenScreenOff(int policyFlags); 727 728 /** 729 * Called from the input dispatcher thread before a key is dispatched to a window. 730 * 731 * <p>Allows you to define 732 * behavior for keys that can not be overridden by applications. 733 * This method is called from the input thread, with no locks held. 734 * 735 * @param win The window that currently has focus. This is where the key 736 * event will normally go. 737 * @param event The key event. 738 * @param policyFlags The policy flags associated with the key. 739 * @return 0 if the key should be dispatched immediately, -1 if the key should 740 * not be dispatched ever, or a positive value indicating the number of 741 * milliseconds by which the key dispatch should be delayed before trying 742 * again. 743 */ 744 public long interceptKeyBeforeDispatching(WindowState win, KeyEvent event, int policyFlags); 745 746 /** 747 * Called from the input dispatcher thread when an application did not handle 748 * a key that was dispatched to it. 749 * 750 * <p>Allows you to define default global behavior for keys that were not handled 751 * by applications. This method is called from the input thread, with no locks held. 752 * 753 * @param win The window that currently has focus. This is where the key 754 * event will normally go. 755 * @param event The key event. 756 * @param policyFlags The policy flags associated with the key. 757 * @return Returns an alternate key event to redispatch as a fallback, or null to give up. 758 * The caller is responsible for recycling the key event. 759 */ 760 public KeyEvent dispatchUnhandledKey(WindowState win, KeyEvent event, int policyFlags); 761 762 /** 763 * Called when layout of the windows is about to start. 764 * 765 * @param displayWidth The current full width of the screen. 766 * @param displayHeight The current full height of the screen. 767 * @param displayRotation The current rotation being applied to the base 768 * window. 769 */ 770 public void beginLayoutLw(int displayWidth, int displayHeight, int displayRotation); 771 772 /** 773 * Called for each window attached to the window manager as layout is 774 * proceeding. The implementation of this function must take care of 775 * setting the window's frame, either here or in finishLayout(). 776 * 777 * @param win The window being positioned. 778 * @param attrs The LayoutParams of the window. 779 * @param attached For sub-windows, the window it is attached to; this 780 * window will already have had layoutWindow() called on it 781 * so you can use its Rect. Otherwise null. 782 */ 783 public void layoutWindowLw(WindowState win, 784 WindowManager.LayoutParams attrs, WindowState attached); 785 786 787 /** 788 * Return the insets for the areas covered by system windows. These values 789 * are computed on the most recent layout, so they are not guaranteed to 790 * be correct. 791 * 792 * @param attrs The LayoutParams of the window. 793 * @param contentInset The areas covered by system windows, expressed as positive insets 794 * 795 */ 796 public void getContentInsetHintLw(WindowManager.LayoutParams attrs, Rect contentInset); 797 798 /** 799 * Called when layout of the windows is finished. After this function has 800 * returned, all windows given to layoutWindow() <em>must</em> have had a 801 * frame assigned. 802 */ 803 public void finishLayoutLw(); 804 805 /** Layout state may have changed (so another layout will be performed) */ 806 static final int FINISH_LAYOUT_REDO_LAYOUT = 0x0001; 807 /** Configuration state may have changed */ 808 static final int FINISH_LAYOUT_REDO_CONFIG = 0x0002; 809 /** Wallpaper may need to move */ 810 static final int FINISH_LAYOUT_REDO_WALLPAPER = 0x0004; 811 /** Need to recompute animations */ 812 static final int FINISH_LAYOUT_REDO_ANIM = 0x0008; 813 814 /** 815 * Called when animation of the windows is about to start. 816 * 817 * @param displayWidth The current full width of the screen. 818 * @param displayHeight The current full height of the screen. 819 */ 820 public void beginAnimationLw(int displayWidth, int displayHeight); 821 822 /** 823 * Called each time a window is animating. 824 * 825 * @param win The window being positioned. 826 * @param attrs The LayoutParams of the window. 827 */ 828 public void animatingWindowLw(WindowState win, 829 WindowManager.LayoutParams attrs); 830 831 /** 832 * Called when animation of the windows is finished. If in this function you do 833 * something that may have modified the animation state of another window, 834 * be sure to return true in order to perform another animation frame. 835 * 836 * @return Return any bit set of {@link #FINISH_LAYOUT_REDO_LAYOUT}, 837 * {@link #FINISH_LAYOUT_REDO_CONFIG}, {@link #FINISH_LAYOUT_REDO_WALLPAPER}, 838 * or {@link #FINISH_LAYOUT_REDO_ANIM}. 839 */ 840 public int finishAnimationLw(); 841 842 /** 843 * Return true if it is okay to perform animations for an app transition 844 * that is about to occur. You may return false for this if, for example, 845 * the lock screen is currently displayed so the switch should happen 846 * immediately. 847 */ 848 public boolean allowAppAnimationsLw(); 849 850 851 /** 852 * A new window has been focused. 853 */ 854 public int focusChangedLw(WindowState lastFocus, WindowState newFocus); 855 856 /** 857 * Called after the screen turns off. 858 * 859 * @param why {@link #OFF_BECAUSE_OF_USER} or 860 * {@link #OFF_BECAUSE_OF_TIMEOUT}. 861 */ 862 public void screenTurnedOff(int why); 863 864 public interface ScreenOnListener { 865 void onScreenOn(); 866 } 867 868 /** 869 * Called when the power manager would like to turn the screen on. 870 * Must call back on the listener to tell it when the higher-level system 871 * is ready for the screen to go on (i.e. the lock screen is shown). 872 */ 873 public void screenTurningOn(ScreenOnListener screenOnListener); 874 875 /** 876 * Return whether the screen is about to turn on or is currently on. 877 */ 878 public boolean isScreenOnEarly(); 879 880 /** 881 * Return whether the screen is fully turned on. 882 */ 883 public boolean isScreenOnFully(); 884 885 /** 886 * Tell the policy that the lid switch has changed state. 887 * @param whenNanos The time when the change occurred in uptime nanoseconds. 888 * @param lidOpen True if the lid is now open. 889 */ 890 public void notifyLidSwitchChanged(long whenNanos, boolean lidOpen); 891 892 /** 893 * Tell the policy if anyone is requesting that keyguard not come on. 894 * 895 * @param enabled Whether keyguard can be on or not. does not actually 896 * turn it on, unless it was previously disabled with this function. 897 * 898 * @see android.app.KeyguardManager.KeyguardLock#disableKeyguard() 899 * @see android.app.KeyguardManager.KeyguardLock#reenableKeyguard() 900 */ 901 public void enableKeyguard(boolean enabled); 902 903 /** 904 * Callback used by {@link WindowManagerPolicy#exitKeyguardSecurely} 905 */ 906 interface OnKeyguardExitResult { 907 void onKeyguardExitResult(boolean success); 908 } 909 910 /** 911 * Tell the policy if anyone is requesting the keyguard to exit securely 912 * (this would be called after the keyguard was disabled) 913 * @param callback Callback to send the result back. 914 * @see android.app.KeyguardManager#exitKeyguardSecurely(android.app.KeyguardManager.OnKeyguardExitResult) 915 */ 916 void exitKeyguardSecurely(OnKeyguardExitResult callback); 917 918 /** 919 * isKeyguardLocked 920 * 921 * Return whether the keyguard is currently locked. 922 * 923 * @return true if in keyguard is locked. 924 */ 925 public boolean isKeyguardLocked(); 926 927 /** 928 * isKeyguardSecure 929 * 930 * Return whether the keyguard requires a password to unlock. 931 * 932 * @return true if in keyguard is secure. 933 */ 934 public boolean isKeyguardSecure(); 935 936 /** 937 * inKeyguardRestrictedKeyInputMode 938 * 939 * if keyguard screen is showing or in restricted key input mode (i.e. in 940 * keyguard password emergency screen). When in such mode, certain keys, 941 * such as the Home key and the right soft keys, don't work. 942 * 943 * @return true if in keyguard restricted input mode. 944 */ 945 public boolean inKeyguardRestrictedKeyInputMode(); 946 947 /** 948 * Ask the policy to dismiss the keyguard, if it is currently shown. 949 */ 950 public void dismissKeyguardLw(); 951 952 /** 953 * Given an orientation constant, returns the appropriate surface rotation, 954 * taking into account sensors, docking mode, rotation lock, and other factors. 955 * 956 * @param orientation An orientation constant, such as 957 * {@link android.content.pm.ActivityInfo#SCREEN_ORIENTATION_LANDSCAPE}. 958 * @param lastRotation The most recently used rotation. 959 * @return The surface rotation to use. 960 */ 961 public int rotationForOrientationLw(int orientation, int lastRotation); 962 963 /** 964 * Given an orientation constant and a rotation, returns true if the rotation 965 * has compatible metrics to the requested orientation. For example, if 966 * the application requested landscape and got seascape, then the rotation 967 * has compatible metrics; if the application requested portrait and got landscape, 968 * then the rotation has incompatible metrics; if the application did not specify 969 * a preference, then anything goes. 970 * 971 * @param orientation An orientation constant, such as 972 * {@link android.content.pm.ActivityInfo#SCREEN_ORIENTATION_LANDSCAPE}. 973 * @param rotation The rotation to check. 974 * @return True if the rotation is compatible with the requested orientation. 975 */ 976 public boolean rotationHasCompatibleMetricsLw(int orientation, int rotation); 977 978 /** 979 * Called by the window manager when the rotation changes. 980 * 981 * @param rotation The new rotation. 982 */ 983 public void setRotationLw(int rotation); 984 985 /** 986 * Called when the system is mostly done booting to set whether 987 * the system should go into safe mode. 988 */ 989 public void setSafeMode(boolean safeMode); 990 991 /** 992 * Called when the system is mostly done booting. 993 */ 994 public void systemReady(); 995 996 /** 997 * Called when the system is done booting to the point where the 998 * user can start interacting with it. 999 */ 1000 public void systemBooted(); 1001 1002 /** 1003 * Show boot time message to the user. 1004 */ 1005 public void showBootMessage(final CharSequence msg, final boolean always); 1006 1007 /** 1008 * Hide the UI for showing boot messages, never to be displayed again. 1009 */ 1010 public void hideBootMessages(); 1011 1012 /** 1013 * Called when userActivity is signalled in the power manager. 1014 * This is safe to call from any thread, with any window manager locks held or not. 1015 */ 1016 public void userActivity(); 1017 1018 /** 1019 * Called when we have finished booting and can now display the home 1020 * screen to the user. This wilWl happen after systemReady(), and at 1021 * this point the display is active. 1022 */ 1023 public void enableScreenAfterBoot(); 1024 1025 public void setCurrentOrientationLw(int newOrientation); 1026 1027 /** 1028 * Call from application to perform haptic feedback on its window. 1029 */ 1030 public boolean performHapticFeedbackLw(WindowState win, int effectId, boolean always); 1031 1032 /** 1033 * Called when we have started keeping the screen on because a window 1034 * requesting this has become visible. 1035 */ 1036 public void screenOnStartedLw(); 1037 1038 /** 1039 * Called when we have stopped keeping the screen on because the last window 1040 * requesting this is no longer visible. 1041 */ 1042 public void screenOnStoppedLw(); 1043 1044 /** 1045 * Return false to disable key repeat events from being generated. 1046 */ 1047 public boolean allowKeyRepeat(); 1048 1049 /** 1050 * Inform the policy that the user has chosen a preferred orientation ("rotation lock"). 1051 * 1052 * @param mode One of {@link WindowManagerPolicy#USER_ROTATION_LOCKED} or 1053 * {@link * WindowManagerPolicy#USER_ROTATION_FREE}. 1054 * @param rotation One of {@link Surface#ROTATION_0}, {@link Surface#ROTATION_90}, 1055 * {@link Surface#ROTATION_180}, {@link Surface#ROTATION_270}. 1056 */ 1057 public void setUserRotationMode(int mode, int rotation); 1058 1059 /** 1060 * Called when a new system UI visibility is being reported, allowing 1061 * the policy to adjust what is actually reported. 1062 * @param visibility The raw visiblity reported by the status bar. 1063 * @return The new desired visibility. 1064 */ 1065 public int adjustSystemUiVisibilityLw(int visibility); 1066 1067 /** 1068 * Specifies whether there is an on-screen navigation bar separate from the status bar. 1069 */ 1070 public boolean hasNavigationBar(); 1071 1072 /** 1073 * Lock the device now. 1074 */ 1075 public void lockNow(); 1076 1077 /** 1078 * Check to see if a screensaver should be run instead of powering off the screen on timeout. 1079 * 1080 * @return true if the screensaver should run, false if the screen should turn off. 1081 * 1082 * @hide 1083 */ 1084 public boolean isScreenSaverEnabled(); 1085 1086 /** 1087 * Start the screensaver (if it is enabled and not yet running). 1088 * 1089 * @return Whether the screensaver was successfully started. 1090 * 1091 * @hide 1092 */ 1093 public boolean startScreenSaver(); 1094 1095 /** 1096 * Stop the screensaver if it is running. 1097 * 1098 * @hide 1099 */ 1100 public void stopScreenSaver(); 1101 1102 /** 1103 * Set the last used input method window state. This state is used to make IME transition 1104 * smooth. 1105 * @hide 1106 */ 1107 public void setLastInputMethodWindowLw(WindowState ime, WindowState target); 1108 1109 /** 1110 * Print the WindowManagerPolicy's state into the given stream. 1111 * 1112 * @param prefix Text to print at the front of each line. 1113 * @param fd The raw file descriptor that the dump is being sent to. 1114 * @param writer The PrintWriter to which you should dump your state. This will be 1115 * closed for you after you return. 1116 * @param args additional arguments to the dump request. 1117 */ 1118 public void dump(String prefix, FileDescriptor fd, PrintWriter writer, String[] args); 1119} 1120