WindowInsets.java revision 973ddaacaef255b8659d35cfe4151dd5b7436138 
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, Rect windowDecorInsets, boolean isRound) {
55        mSystemWindowInsets = systemWindowInsets;
56        mWindowDecorInsets = windowDecorInsets;
57        mIsRound = isRound;
58    }
59
60    /**
61     * Construct a new WindowInsets, copying all values from a source WindowInsets.
62     *
63     * @param src Source to copy insets from
64     */
65    public WindowInsets(WindowInsets src) {
66        mSystemWindowInsets = src.mSystemWindowInsets;
67        mWindowDecorInsets = src.mWindowDecorInsets;
68        mIsRound = src.mIsRound;
69    }
70
71    /** @hide */
72    public WindowInsets(Rect systemWindowInsets) {
73        this(systemWindowInsets, EMPTY_RECT);
74    }
75
76    /**
77     * Used to provide a safe copy of the system window insets to pass through
78     * to the existing fitSystemWindows method and other similar internals.
79     * @hide
80     */
81    public Rect getSystemWindowInsets() {
82        if (mTempRect == null) {
83            mTempRect = new Rect();
84        }
85        mTempRect.set(mSystemWindowInsets);
86        return mTempRect;
87    }
88
89    /**
90     * Returns the left system window inset in pixels.
91     *
92     * <p>The system window inset represents the area of a full-screen window that is
93     * partially or fully obscured by the status bar, navigation bar, IME or other system windows.
94     * </p>
95     *
96     * @return The left system window inset
97     */
98    public int getSystemWindowInsetLeft() {
99        return mSystemWindowInsets.left;
100    }
101
102    /**
103     * Returns the top system window inset in pixels.
104     *
105     * <p>The system window inset represents the area of a full-screen window that is
106     * partially or fully obscured by the status bar, navigation bar, IME or other system windows.
107     * </p>
108     *
109     * @return The top system window inset
110     */
111    public int getSystemWindowInsetTop() {
112        return mSystemWindowInsets.top;
113    }
114
115    /**
116     * Returns the right system window inset in pixels.
117     *
118     * <p>The system window inset represents the area of a full-screen window that is
119     * partially or fully obscured by the status bar, navigation bar, IME or other system windows.
120     * </p>
121     *
122     * @return The right system window inset
123     */
124    public int getSystemWindowInsetRight() {
125        return mSystemWindowInsets.right;
126    }
127
128    /**
129     * Returns the bottom system window inset in pixels.
130     *
131     * <p>The system window inset represents the area of a full-screen window that is
132     * partially or fully obscured by the status bar, navigation bar, IME or other system windows.
133     * </p>
134     *
135     * @return The bottom system window inset
136     */
137    public int getSystemWindowInsetBottom() {
138        return mSystemWindowInsets.bottom;
139    }
140
141    /**
142     * Returns the left window decor inset in pixels.
143     *
144     * <p>The window decor inset represents the area of the window content area that is
145     * partially or fully obscured by decorations within the window provided by the framework.
146     * This can include action bars, title bars, toolbars, etc.</p>
147     *
148     * @return The left window decor inset
149     */
150    public int getWindowDecorInsetLeft() {
151        return mWindowDecorInsets.left;
152    }
153
154    /**
155     * Returns the top window decor inset in pixels.
156     *
157     * <p>The window decor inset represents the area of the window content area that is
158     * partially or fully obscured by decorations within the window provided by the framework.
159     * This can include action bars, title bars, toolbars, etc.</p>
160     *
161     * @return The top window decor inset
162     */
163    public int getWindowDecorInsetTop() {
164        return mWindowDecorInsets.top;
165    }
166
167    /**
168     * Returns the right window decor inset in pixels.
169     *
170     * <p>The window decor inset represents the area of the window content area that is
171     * partially or fully obscured by decorations within the window provided by the framework.
172     * This can include action bars, title bars, toolbars, etc.</p>
173     *
174     * @return The right window decor inset
175     */
176    public int getWindowDecorInsetRight() {
177        return mWindowDecorInsets.right;
178    }
179
180    /**
181     * Returns the bottom window decor inset in pixels.
182     *
183     * <p>The window decor inset represents the area of the window content area that is
184     * partially or fully obscured by decorations within the window provided by the framework.
185     * This can include action bars, title bars, toolbars, etc.</p>
186     *
187     * @return The bottom window decor inset
188     */
189    public int getWindowDecorInsetBottom() {
190        return mWindowDecorInsets.bottom;
191    }
192
193    /**
194     * Returns true if this WindowInsets has nonzero system window insets.
195     *
196     * <p>The system window inset represents the area of a full-screen window that is
197     * partially or fully obscured by the status bar, navigation bar, IME or other system windows.
198     * </p>
199     *
200     * @return true if any of the system window inset values are nonzero
201     */
202    public boolean hasSystemWindowInsets() {
203        return mSystemWindowInsets.left != 0 || mSystemWindowInsets.top != 0 ||
204                mSystemWindowInsets.right != 0 || mSystemWindowInsets.bottom != 0;
205    }
206
207    /**
208     * Returns true if this WindowInsets has nonzero window decor insets.
209     *
210     * <p>The window decor inset represents the area of the window content area that is
211     * partially or fully obscured by decorations within the window provided by the framework.
212     * This can include action bars, title bars, toolbars, etc.</p>
213     *
214     * @return true if any of the window decor inset values are nonzero
215     */
216    public boolean hasWindowDecorInsets() {
217        return mWindowDecorInsets.left != 0 || mWindowDecorInsets.top != 0 ||
218                mWindowDecorInsets.right != 0 || mWindowDecorInsets.bottom != 0;
219    }
220
221    /**
222     * Returns true if this WindowInsets has any nonzero insets.
223     *
224     * @return true if any inset values are nonzero
225     */
226    public boolean hasInsets() {
227        return hasSystemWindowInsets() || hasWindowDecorInsets();
228    }
229
230    /**
231     * Returns true if the associated window has a round shape.
232     *
233     * <p>A round window's left, top, right and bottom edges reach all the way to the
234     * associated edges of the window but the corners may not be visible. Views responding
235     * to round insets should take care to not lay out critical elements within the corners
236     * where they may not be accessible.</p>
237     *
238     * @return True if the window is round
239     */
240    public boolean isRound() {
241        return mIsRound;
242    }
243
244    public WindowInsets cloneWithSystemWindowInsetsConsumed() {
245        final WindowInsets result = new WindowInsets(this);
246        result.mSystemWindowInsets = new Rect(0, 0, 0, 0);
247        return result;
248    }
249
250    public WindowInsets cloneWithSystemWindowInsetsConsumed(boolean left, boolean top,
251            boolean right, boolean bottom) {
252        if (left || top || right || bottom) {
253            final WindowInsets result = new WindowInsets(this);
254            result.mSystemWindowInsets = new Rect(left ? 0 : mSystemWindowInsets.left,
255                    top ? 0 : mSystemWindowInsets.top,
256                    right ? 0 : mSystemWindowInsets.right,
257                    bottom ? 0 : mSystemWindowInsets.bottom);
258            return result;
259        }
260        return this;
261    }
262
263    public WindowInsets cloneWithSystemWindowInsets(int left, int top, int right, int bottom) {
264        final WindowInsets result = new WindowInsets(this);
265        result.mSystemWindowInsets = new Rect(left, top, right, bottom);
266        return result;
267    }
268
269    public WindowInsets cloneWithWindowDecorInsetsConsumed() {
270        final WindowInsets result = new WindowInsets(this);
271        result.mWindowDecorInsets.set(0, 0, 0, 0);
272        return result;
273    }
274
275    public WindowInsets cloneWithWindowDecorInsetsConsumed(boolean left, boolean top,
276            boolean right, boolean bottom) {
277        if (left || top || right || bottom) {
278            final WindowInsets result = new WindowInsets(this);
279            result.mWindowDecorInsets = new Rect(left ? 0 : mWindowDecorInsets.left,
280                    top ? 0 : mWindowDecorInsets.top,
281                    right ? 0 : mWindowDecorInsets.right,
282                    bottom ? 0 : mWindowDecorInsets.bottom);
283            return result;
284        }
285        return this;
286    }
287
288    public WindowInsets cloneWithWindowDecorInsets(int left, int top, int right, int bottom) {
289        final WindowInsets result = new WindowInsets(this);
290        result.mWindowDecorInsets = new Rect(left, top, right, bottom);
291        return result;
292    }
293
294    @Override
295    public String toString() {
296        return "WindowInsets{systemWindowInsets=" + mSystemWindowInsets + " windowDecorInsets=" +
297                mWindowDecorInsets + (isRound() ? "round}" : "}");
298    }
299}
300