WindowInsets.java revision e69bebd5aa8ddc6f2e0c576a58b538b336516879
1/* 2 * Copyright (C) 2014 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 18package android.view; 19 20import android.graphics.Rect; 21 22/** 23 * Describes a set of insets for window content. 24 * 25 * <p>WindowInsets are immutable and may be expanded to include more inset types in the future. 26 * To adjust insets, use one of the supplied clone methods to obtain a new WindowInsets instance 27 * with the adjusted properties.</p> 28 * 29 * @see View.OnApplyWindowInsetsListener 30 * @see View#onApplyWindowInsets(WindowInsets) 31 */ 32public final class WindowInsets { 33 private Rect mSystemWindowInsets; 34 private Rect mWindowDecorInsets; 35 private Rect mTempRect; 36 private boolean mIsRound; 37 38 private boolean mSystemWindowInsetsConsumed = false; 39 private boolean mWindowDecorInsetsConsumed = false; 40 41 private static final Rect EMPTY_RECT = new Rect(0, 0, 0, 0); 42 43 /** 44 * Since new insets may be added in the future that existing apps couldn't 45 * know about, this fully empty constant shouldn't be made available to apps 46 * since it would allow them to inadvertently consume unknown insets by returning it. 47 * @hide 48 */ 49 public static final WindowInsets CONSUMED; 50 51 static { 52 CONSUMED = new WindowInsets(EMPTY_RECT, EMPTY_RECT); 53 CONSUMED.mSystemWindowInsetsConsumed = true; 54 CONSUMED.mWindowDecorInsetsConsumed = true; 55 } 56 57 /** @hide */ 58 public WindowInsets(Rect systemWindowInsets, Rect windowDecorInsets) { 59 this(systemWindowInsets, windowDecorInsets, false); 60 } 61 62 /** @hide */ 63 public WindowInsets(Rect systemWindowInsets, boolean isRound) { 64 this(systemWindowInsets, null, isRound); 65 } 66 67 /** @hide */ 68 public WindowInsets(Rect systemWindowInsets, Rect windowDecorInsets, boolean isRound) { 69 mSystemWindowInsetsConsumed = systemWindowInsets == null; 70 mSystemWindowInsets = mSystemWindowInsetsConsumed ? EMPTY_RECT : systemWindowInsets; 71 72 mWindowDecorInsetsConsumed = windowDecorInsets == null; 73 mWindowDecorInsets = mWindowDecorInsetsConsumed ? EMPTY_RECT : windowDecorInsets; 74 75 mIsRound = isRound; 76 } 77 78 /** 79 * Construct a new WindowInsets, copying all values from a source WindowInsets. 80 * 81 * @param src Source to copy insets from 82 */ 83 public WindowInsets(WindowInsets src) { 84 mSystemWindowInsets = src.mSystemWindowInsets; 85 mWindowDecorInsets = src.mWindowDecorInsets; 86 mSystemWindowInsetsConsumed = src.mSystemWindowInsetsConsumed; 87 mWindowDecorInsetsConsumed = src.mWindowDecorInsetsConsumed; 88 mIsRound = src.mIsRound; 89 } 90 91 /** @hide */ 92 public WindowInsets(Rect systemWindowInsets) { 93 this(systemWindowInsets, null); 94 } 95 96 /** 97 * Used to provide a safe copy of the system window insets to pass through 98 * to the existing fitSystemWindows method and other similar internals. 99 * @hide 100 */ 101 public Rect getSystemWindowInsets() { 102 if (mTempRect == null) { 103 mTempRect = new Rect(); 104 } 105 if (mSystemWindowInsets != null) { 106 mTempRect.set(mSystemWindowInsets); 107 } else { 108 // If there were no system window insets, this is just empty. 109 mTempRect.setEmpty(); 110 } 111 return mTempRect; 112 } 113 114 /** 115 * Returns the left system window inset in pixels. 116 * 117 * <p>The system window inset represents the area of a full-screen window that is 118 * partially or fully obscured by the status bar, navigation bar, IME or other system windows. 119 * </p> 120 * 121 * @return The left system window inset 122 */ 123 public int getSystemWindowInsetLeft() { 124 return mSystemWindowInsets.left; 125 } 126 127 /** 128 * Returns the top system window inset in pixels. 129 * 130 * <p>The system window inset represents the area of a full-screen window that is 131 * partially or fully obscured by the status bar, navigation bar, IME or other system windows. 132 * </p> 133 * 134 * @return The top system window inset 135 */ 136 public int getSystemWindowInsetTop() { 137 return mSystemWindowInsets.top; 138 } 139 140 /** 141 * Returns the right system window inset in pixels. 142 * 143 * <p>The system window inset represents the area of a full-screen window that is 144 * partially or fully obscured by the status bar, navigation bar, IME or other system windows. 145 * </p> 146 * 147 * @return The right system window inset 148 */ 149 public int getSystemWindowInsetRight() { 150 return mSystemWindowInsets.right; 151 } 152 153 /** 154 * Returns the bottom system window inset in pixels. 155 * 156 * <p>The system window inset represents the area of a full-screen window that is 157 * partially or fully obscured by the status bar, navigation bar, IME or other system windows. 158 * </p> 159 * 160 * @return The bottom system window inset 161 */ 162 public int getSystemWindowInsetBottom() { 163 return mSystemWindowInsets.bottom; 164 } 165 166 /** 167 * Returns the left window decor inset in pixels. 168 * 169 * <p>The window decor inset represents the area of the window content area that is 170 * partially or fully obscured by decorations within the window provided by the framework. 171 * This can include action bars, title bars, toolbars, etc.</p> 172 * 173 * @return The left window decor inset 174 * @hide pending API 175 */ 176 public int getWindowDecorInsetLeft() { 177 return mWindowDecorInsets.left; 178 } 179 180 /** 181 * Returns the top window decor inset in pixels. 182 * 183 * <p>The window decor inset represents the area of the window content area that is 184 * partially or fully obscured by decorations within the window provided by the framework. 185 * This can include action bars, title bars, toolbars, etc.</p> 186 * 187 * @return The top window decor inset 188 * @hide pending API 189 */ 190 public int getWindowDecorInsetTop() { 191 return mWindowDecorInsets.top; 192 } 193 194 /** 195 * Returns the right window decor inset in pixels. 196 * 197 * <p>The window decor inset represents the area of the window content area that is 198 * partially or fully obscured by decorations within the window provided by the framework. 199 * This can include action bars, title bars, toolbars, etc.</p> 200 * 201 * @return The right window decor inset 202 * @hide pending API 203 */ 204 public int getWindowDecorInsetRight() { 205 return mWindowDecorInsets.right; 206 } 207 208 /** 209 * Returns the bottom window decor inset in pixels. 210 * 211 * <p>The window decor inset represents the area of the window content area that is 212 * partially or fully obscured by decorations within the window provided by the framework. 213 * This can include action bars, title bars, toolbars, etc.</p> 214 * 215 * @return The bottom window decor inset 216 * @hide pending API 217 */ 218 public int getWindowDecorInsetBottom() { 219 return mWindowDecorInsets.bottom; 220 } 221 222 /** 223 * Returns true if this WindowInsets has nonzero system window insets. 224 * 225 * <p>The system window inset represents the area of a full-screen window that is 226 * partially or fully obscured by the status bar, navigation bar, IME or other system windows. 227 * </p> 228 * 229 * @return true if any of the system window inset values are nonzero 230 */ 231 public boolean hasSystemWindowInsets() { 232 return mSystemWindowInsets.left != 0 || mSystemWindowInsets.top != 0 || 233 mSystemWindowInsets.right != 0 || mSystemWindowInsets.bottom != 0; 234 } 235 236 /** 237 * Returns true if this WindowInsets has nonzero window decor insets. 238 * 239 * <p>The window decor inset represents the area of the window content area that is 240 * partially or fully obscured by decorations within the window provided by the framework. 241 * This can include action bars, title bars, toolbars, etc.</p> 242 * 243 * @return true if any of the window decor inset values are nonzero 244 * @hide pending API 245 */ 246 public boolean hasWindowDecorInsets() { 247 return mWindowDecorInsets.left != 0 || mWindowDecorInsets.top != 0 || 248 mWindowDecorInsets.right != 0 || mWindowDecorInsets.bottom != 0; 249 } 250 251 /** 252 * Returns true if this WindowInsets has any nonzero insets. 253 * 254 * @return true if any inset values are nonzero 255 */ 256 public boolean hasInsets() { 257 return hasSystemWindowInsets() || hasWindowDecorInsets(); 258 } 259 260 /** 261 * Check if these insets have been fully consumed. 262 * 263 * <p>Insets are considered "consumed" if the applicable <code>consume*</code> methods 264 * have been called such that all insets have been set to zero. This affects propagation of 265 * insets through the view hierarchy; insets that have not been fully consumed will continue 266 * to propagate down to child views.</p> 267 * 268 * <p>The result of this method is equivalent to the return value of 269 * {@link View#fitSystemWindows(android.graphics.Rect)}.</p> 270 * 271 * @return true if the insets have been fully consumed. 272 * @hide Pending API 273 */ 274 public boolean isConsumed() { 275 return mSystemWindowInsetsConsumed && mWindowDecorInsetsConsumed; 276 } 277 278 /** 279 * Returns true if the associated window has a round shape. 280 * 281 * <p>A round window's left, top, right and bottom edges reach all the way to the 282 * associated edges of the window but the corners may not be visible. Views responding 283 * to round insets should take care to not lay out critical elements within the corners 284 * where they may not be accessible.</p> 285 * 286 * @return True if the window is round 287 */ 288 public boolean isRound() { 289 return mIsRound; 290 } 291 292 /** 293 * Returns a copy of this WindowInsets with the system window insets fully consumed. 294 * 295 * @return A modified copy of this WindowInsets 296 */ 297 public WindowInsets consumeSystemWindowInsets() { 298 final WindowInsets result = new WindowInsets(this); 299 result.mSystemWindowInsets = EMPTY_RECT; 300 result.mSystemWindowInsetsConsumed = true; 301 return result; 302 } 303 304 /** 305 * Returns a copy of this WindowInsets with selected system window insets fully consumed. 306 * 307 * @param left true to consume the left system window inset 308 * @param top true to consume the top system window inset 309 * @param right true to consume the right system window inset 310 * @param bottom true to consume the bottom system window inset 311 * @return A modified copy of this WindowInsets 312 * @hide pending API 313 */ 314 public WindowInsets consumeSystemWindowInsets(boolean left, boolean top, 315 boolean right, boolean bottom) { 316 if (left || top || right || bottom) { 317 final WindowInsets result = new WindowInsets(this); 318 result.mSystemWindowInsets = new Rect( 319 left ? 0 : mSystemWindowInsets.left, 320 top ? 0 : mSystemWindowInsets.top, 321 right ? 0 : mSystemWindowInsets.right, 322 bottom ? 0 : mSystemWindowInsets.bottom); 323 result.mSystemWindowInsetsConsumed = !hasSystemWindowInsets(); 324 return result; 325 } 326 return this; 327 } 328 329 /** 330 * Returns a copy of this WindowInsets with selected system window insets replaced 331 * with new values. 332 * 333 * @param left New left inset in pixels 334 * @param top New top inset in pixels 335 * @param right New right inset in pixels 336 * @param bottom New bottom inset in pixels 337 * @return A modified copy of this WindowInsets 338 */ 339 public WindowInsets replaceSystemWindowInsets(int left, int top, 340 int right, int bottom) { 341 final WindowInsets result = new WindowInsets(this); 342 result.mSystemWindowInsets = new Rect(left, top, right, bottom); 343 return result; 344 } 345 346 /** 347 * @hide 348 */ 349 public WindowInsets consumeWindowDecorInsets() { 350 final WindowInsets result = new WindowInsets(this); 351 result.mWindowDecorInsets.set(0, 0, 0, 0); 352 result.mWindowDecorInsetsConsumed = true; 353 return result; 354 } 355 356 /** 357 * @hide 358 */ 359 public WindowInsets consumeWindowDecorInsets(boolean left, boolean top, 360 boolean right, boolean bottom) { 361 if (left || top || right || bottom) { 362 final WindowInsets result = new WindowInsets(this); 363 result.mWindowDecorInsets = new Rect(left ? 0 : mWindowDecorInsets.left, 364 top ? 0 : mWindowDecorInsets.top, 365 right ? 0 : mWindowDecorInsets.right, 366 bottom ? 0 : mWindowDecorInsets.bottom); 367 result.mWindowDecorInsetsConsumed = !hasWindowDecorInsets(); 368 return result; 369 } 370 return this; 371 } 372 373 /** 374 * @hide 375 */ 376 public WindowInsets replaceWindowDecorInsets(int left, int top, int right, int bottom) { 377 final WindowInsets result = new WindowInsets(this); 378 result.mWindowDecorInsets = new Rect(left, top, right, bottom); 379 result.mWindowDecorInsetsConsumed = !hasWindowDecorInsets(); 380 return result; 381 } 382 383 @Override 384 public String toString() { 385 return "WindowInsets{systemWindowInsets=" + mSystemWindowInsets + " windowDecorInsets=" + 386 mWindowDecorInsets + (isRound() ? "round}" : "}"); 387 } 388} 389