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