WindowInsets.java revision 6642e51ac5d0351f02fc929817603d7371e08e10 
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 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     */
155    public int getWindowDecorInsetLeft() {
156        return mWindowDecorInsets.left;
157    }
158
159    /**
160     * Returns the top window decor inset in pixels.
161     *
162     * <p>The window decor inset represents the area of the window content area that is
163     * partially or fully obscured by decorations within the window provided by the framework.
164     * This can include action bars, title bars, toolbars, etc.</p>
165     *
166     * @return The top window decor inset
167     */
168    public int getWindowDecorInsetTop() {
169        return mWindowDecorInsets.top;
170    }
171
172    /**
173     * Returns the right window decor inset in pixels.
174     *
175     * <p>The window decor inset represents the area of the window content area that is
176     * partially or fully obscured by decorations within the window provided by the framework.
177     * This can include action bars, title bars, toolbars, etc.</p>
178     *
179     * @return The right window decor inset
180     */
181    public int getWindowDecorInsetRight() {
182        return mWindowDecorInsets.right;
183    }
184
185    /**
186     * Returns the bottom window decor inset in pixels.
187     *
188     * <p>The window decor inset represents the area of the window content area that is
189     * partially or fully obscured by decorations within the window provided by the framework.
190     * This can include action bars, title bars, toolbars, etc.</p>
191     *
192     * @return The bottom window decor inset
193     */
194    public int getWindowDecorInsetBottom() {
195        return mWindowDecorInsets.bottom;
196    }
197
198    /**
199     * Returns true if this WindowInsets has nonzero system window insets.
200     *
201     * <p>The system window inset represents the area of a full-screen window that is
202     * partially or fully obscured by the status bar, navigation bar, IME or other system windows.
203     * </p>
204     *
205     * @return true if any of the system window inset values are nonzero
206     */
207    public boolean hasSystemWindowInsets() {
208        return mSystemWindowInsets.left != 0 || mSystemWindowInsets.top != 0 ||
209                mSystemWindowInsets.right != 0 || mSystemWindowInsets.bottom != 0;
210    }
211
212    /**
213     * Returns true if this WindowInsets has nonzero window decor insets.
214     *
215     * <p>The window decor inset represents the area of the window content area that is
216     * partially or fully obscured by decorations within the window provided by the framework.
217     * This can include action bars, title bars, toolbars, etc.</p>
218     *
219     * @return true if any of the window decor inset values are nonzero
220     */
221    public boolean hasWindowDecorInsets() {
222        return mWindowDecorInsets.left != 0 || mWindowDecorInsets.top != 0 ||
223                mWindowDecorInsets.right != 0 || mWindowDecorInsets.bottom != 0;
224    }
225
226    /**
227     * Returns true if this WindowInsets has any nonzero insets.
228     *
229     * @return true if any inset values are nonzero
230     */
231    public boolean hasInsets() {
232        return hasSystemWindowInsets() || hasWindowDecorInsets();
233    }
234
235    /**
236     * Returns true if the associated window has a round shape.
237     *
238     * <p>A round window's left, top, right and bottom edges reach all the way to the
239     * associated edges of the window but the corners may not be visible. Views responding
240     * to round insets should take care to not lay out critical elements within the corners
241     * where they may not be accessible.</p>
242     *
243     * @return True if the window is round
244     */
245    public boolean isRound() {
246        return mIsRound;
247    }
248
249    public WindowInsets cloneWithSystemWindowInsetsConsumed() {
250        final WindowInsets result = new WindowInsets(this);
251        result.mSystemWindowInsets = new Rect(0, 0, 0, 0);
252        return result;
253    }
254
255    public WindowInsets cloneWithSystemWindowInsetsConsumed(boolean left, boolean top,
256            boolean right, boolean bottom) {
257        if (left || top || right || bottom) {
258            final WindowInsets result = new WindowInsets(this);
259            result.mSystemWindowInsets = new Rect(left ? 0 : mSystemWindowInsets.left,
260                    top ? 0 : mSystemWindowInsets.top,
261                    right ? 0 : mSystemWindowInsets.right,
262                    bottom ? 0 : mSystemWindowInsets.bottom);
263            return result;
264        }
265        return this;
266    }
267
268    public WindowInsets cloneWithSystemWindowInsets(int left, int top, int right, int bottom) {
269        final WindowInsets result = new WindowInsets(this);
270        result.mSystemWindowInsets = new Rect(left, top, right, bottom);
271        return result;
272    }
273
274    public WindowInsets cloneWithWindowDecorInsetsConsumed() {
275        final WindowInsets result = new WindowInsets(this);
276        result.mWindowDecorInsets.set(0, 0, 0, 0);
277        return result;
278    }
279
280    public WindowInsets cloneWithWindowDecorInsetsConsumed(boolean left, boolean top,
281            boolean right, boolean bottom) {
282        if (left || top || right || bottom) {
283            final WindowInsets result = new WindowInsets(this);
284            result.mWindowDecorInsets = new Rect(left ? 0 : mWindowDecorInsets.left,
285                    top ? 0 : mWindowDecorInsets.top,
286                    right ? 0 : mWindowDecorInsets.right,
287                    bottom ? 0 : mWindowDecorInsets.bottom);
288            return result;
289        }
290        return this;
291    }
292
293    public WindowInsets cloneWithWindowDecorInsets(int left, int top, int right, int bottom) {
294        final WindowInsets result = new WindowInsets(this);
295        result.mWindowDecorInsets = new Rect(left, top, right, bottom);
296        return result;
297    }
298
299    @Override
300    public String toString() {
301        return "WindowInsets{systemWindowInsets=" + mSystemWindowInsets + " windowDecorInsets=" +
302                mWindowDecorInsets + (isRound() ? "round}" : "}");
303    }
304}
305