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