WindowInsets.java revision f4a3941ebe0dab5eeded96059a6a5f7c1d075e64
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 static final Rect EMPTY_RECT = new Rect(0, 0, 0, 0); 39 40 /** 41 * Since new insets may be added in the future that existing apps couldn't 42 * know about, this fully empty constant shouldn't be made available to apps 43 * since it would allow them to inadvertently consume unknown insets by returning it. 44 * @hide 45 */ 46 public static final WindowInsets EMPTY = new WindowInsets(EMPTY_RECT, EMPTY_RECT); 47 48 /** @hide */ 49 public WindowInsets(Rect systemWindowInsets, Rect windowDecorInsets) { 50 this(systemWindowInsets, windowDecorInsets, false); 51 } 52 53 /** @hide */ 54 public WindowInsets(Rect systemWindowInsets, boolean isRound) { 55 this(systemWindowInsets, EMPTY_RECT, isRound); 56 } 57 58 /** @hide */ 59 public WindowInsets(Rect systemWindowInsets, Rect windowDecorInsets, boolean isRound) { 60 mSystemWindowInsets = systemWindowInsets; 61 mWindowDecorInsets = windowDecorInsets; 62 mIsRound = isRound; 63 } 64 65 /** 66 * Construct a new WindowInsets, copying all values from a source WindowInsets. 67 * 68 * @param src Source to copy insets from 69 */ 70 public WindowInsets(WindowInsets src) { 71 mSystemWindowInsets = src.mSystemWindowInsets; 72 mWindowDecorInsets = src.mWindowDecorInsets; 73 mIsRound = src.mIsRound; 74 } 75 76 /** @hide */ 77 public WindowInsets(Rect systemWindowInsets) { 78 this(systemWindowInsets, EMPTY_RECT); 79 } 80 81 /** 82 * Used to provide a safe copy of the system window insets to pass through 83 * to the existing fitSystemWindows method and other similar internals. 84 * @hide 85 */ 86 public Rect getSystemWindowInsets() { 87 if (mTempRect == null) { 88 mTempRect = new Rect(); 89 } 90 mTempRect.set(mSystemWindowInsets); 91 return mTempRect; 92 } 93 94 /** 95 * Returns the left system window inset in pixels. 96 * 97 * <p>The system window inset represents the area of a full-screen window that is 98 * partially or fully obscured by the status bar, navigation bar, IME or other system windows. 99 * </p> 100 * 101 * @return The left system window inset 102 */ 103 public int getSystemWindowInsetLeft() { 104 return mSystemWindowInsets.left; 105 } 106 107 /** 108 * Returns the top system window inset in pixels. 109 * 110 * <p>The system window inset represents the area of a full-screen window that is 111 * partially or fully obscured by the status bar, navigation bar, IME or other system windows. 112 * </p> 113 * 114 * @return The top system window inset 115 */ 116 public int getSystemWindowInsetTop() { 117 return mSystemWindowInsets.top; 118 } 119 120 /** 121 * Returns the right system window inset in pixels. 122 * 123 * <p>The system window inset represents the area of a full-screen window that is 124 * partially or fully obscured by the status bar, navigation bar, IME or other system windows. 125 * </p> 126 * 127 * @return The right system window inset 128 */ 129 public int getSystemWindowInsetRight() { 130 return mSystemWindowInsets.right; 131 } 132 133 /** 134 * Returns the bottom system window inset in pixels. 135 * 136 * <p>The system window inset represents the area of a full-screen window that is 137 * partially or fully obscured by the status bar, navigation bar, IME or other system windows. 138 * </p> 139 * 140 * @return The bottom system window inset 141 */ 142 public int getSystemWindowInsetBottom() { 143 return mSystemWindowInsets.bottom; 144 } 145 146 /** 147 * Returns the left window decor inset in pixels. 148 * 149 * <p>The window decor inset represents the area of the window content area that is 150 * partially or fully obscured by decorations within the window provided by the framework. 151 * This can include action bars, title bars, toolbars, etc.</p> 152 * 153 * @return The left window decor inset 154 * @hide pending API 155 */ 156 public int getWindowDecorInsetLeft() { 157 return mWindowDecorInsets.left; 158 } 159 160 /** 161 * Returns the top 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 top window decor inset 168 * @hide pending API 169 */ 170 public int getWindowDecorInsetTop() { 171 return mWindowDecorInsets.top; 172 } 173 174 /** 175 * Returns the right 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 right window decor inset 182 * @hide pending API 183 */ 184 public int getWindowDecorInsetRight() { 185 return mWindowDecorInsets.right; 186 } 187 188 /** 189 * Returns the bottom 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 bottom window decor inset 196 * @hide pending API 197 */ 198 public int getWindowDecorInsetBottom() { 199 return mWindowDecorInsets.bottom; 200 } 201 202 /** 203 * Returns true if this WindowInsets has nonzero system window insets. 204 * 205 * <p>The system window inset represents the area of a full-screen window that is 206 * partially or fully obscured by the status bar, navigation bar, IME or other system windows. 207 * </p> 208 * 209 * @return true if any of the system window inset values are nonzero 210 */ 211 public boolean hasSystemWindowInsets() { 212 return mSystemWindowInsets.left != 0 || mSystemWindowInsets.top != 0 || 213 mSystemWindowInsets.right != 0 || mSystemWindowInsets.bottom != 0; 214 } 215 216 /** 217 * Returns true if this WindowInsets has nonzero window decor insets. 218 * 219 * <p>The window decor inset represents the area of the window content area that is 220 * partially or fully obscured by decorations within the window provided by the framework. 221 * This can include action bars, title bars, toolbars, etc.</p> 222 * 223 * @return true if any of the window decor inset values are nonzero 224 * @hide pending API 225 */ 226 public boolean hasWindowDecorInsets() { 227 return mWindowDecorInsets.left != 0 || mWindowDecorInsets.top != 0 || 228 mWindowDecorInsets.right != 0 || mWindowDecorInsets.bottom != 0; 229 } 230 231 /** 232 * Returns true if this WindowInsets has any nonzero insets. 233 * 234 * @return true if any inset values are nonzero 235 */ 236 public boolean hasInsets() { 237 return hasSystemWindowInsets() || hasWindowDecorInsets(); 238 } 239 240 /** 241 * Returns true if the associated window has a round shape. 242 * 243 * <p>A round window's left, top, right and bottom edges reach all the way to the 244 * associated edges of the window but the corners may not be visible. Views responding 245 * to round insets should take care to not lay out critical elements within the corners 246 * where they may not be accessible.</p> 247 * 248 * @return True if the window is round 249 */ 250 public boolean isRound() { 251 return mIsRound; 252 } 253 254 /** 255 * Returns a copy of this WindowInsets with the system window insets fully consumed. 256 * 257 * @return A modified copy of this WindowInsets 258 */ 259 public WindowInsets consumeSystemWindowInsets() { 260 final WindowInsets result = new WindowInsets(this); 261 result.mSystemWindowInsets = new Rect(0, 0, 0, 0); 262 return result; 263 } 264 265 /** 266 * Returns a copy of this WindowInsets with selected system window insets fully consumed. 267 * 268 * @param left true to consume the left system window inset 269 * @param top true to consume the top system window inset 270 * @param right true to consume the right system window inset 271 * @param bottom true to consume the bottom system window inset 272 * @return A modified copy of this WindowInsets 273 * @hide pending API 274 */ 275 public WindowInsets consumeSystemWindowInsets(boolean left, boolean top, 276 boolean right, boolean bottom) { 277 if (left || top || right || bottom) { 278 final WindowInsets result = new WindowInsets(this); 279 result.mSystemWindowInsets = new Rect(left ? 0 : mSystemWindowInsets.left, 280 top ? 0 : mSystemWindowInsets.top, 281 right ? 0 : mSystemWindowInsets.right, 282 bottom ? 0 : mSystemWindowInsets.bottom); 283 return result; 284 } 285 return this; 286 } 287 288 /** 289 * Returns a copy of this WindowInsets with selected system window insets replaced 290 * with new values. 291 * 292 * @param left New left inset in pixels 293 * @param top New top inset in pixels 294 * @param right New right inset in pixels 295 * @param bottom New bottom inset in pixels 296 * @return A modified copy of this WindowInsets 297 */ 298 public WindowInsets replaceSystemWindowInsets(int left, int top, 299 int right, int bottom) { 300 final WindowInsets result = new WindowInsets(this); 301 result.mSystemWindowInsets = new Rect(left, top, right, bottom); 302 return result; 303 } 304 305 /** 306 * @hide 307 */ 308 public WindowInsets consumeWindowDecorInsets() { 309 final WindowInsets result = new WindowInsets(this); 310 result.mWindowDecorInsets.set(0, 0, 0, 0); 311 return result; 312 } 313 314 /** 315 * @hide 316 */ 317 public WindowInsets consumeWindowDecorInsets(boolean left, boolean top, 318 boolean right, boolean bottom) { 319 if (left || top || right || bottom) { 320 final WindowInsets result = new WindowInsets(this); 321 result.mWindowDecorInsets = new Rect(left ? 0 : mWindowDecorInsets.left, 322 top ? 0 : mWindowDecorInsets.top, 323 right ? 0 : mWindowDecorInsets.right, 324 bottom ? 0 : mWindowDecorInsets.bottom); 325 return result; 326 } 327 return this; 328 } 329 330 /** 331 * @hide 332 */ 333 public WindowInsets replaceWindowDecorInsets(int left, int top, int right, int bottom) { 334 final WindowInsets result = new WindowInsets(this); 335 result.mWindowDecorInsets = new Rect(left, top, right, bottom); 336 return result; 337 } 338 339 @Override 340 public String toString() { 341 return "WindowInsets{systemWindowInsets=" + mSystemWindowInsets + " windowDecorInsets=" + 342 mWindowDecorInsets + (isRound() ? "round}" : "}"); 343 } 344} 345