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