• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Copyright (C) 2013 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 package android.view;
17 
18 import android.animation.LayoutTransition;
19 import android.annotation.NonNull;
20 import android.content.Context;
21 import android.graphics.Canvas;
22 import android.graphics.Rect;
23 import android.graphics.drawable.Drawable;
24 
25 import java.util.ArrayList;
26 
27 /**
28  * An overlay is an extra layer that sits on top of a View (the "host view")
29  * which is drawn after all other content in that view (including children,
30  * if the view is a ViewGroup). Interaction with the overlay layer is done
31  * by adding and removing drawables.
32  *
33  * <p>An overlay requested from a ViewGroup is of type {@link ViewGroupOverlay},
34  * which also supports adding and removing views.</p>
35  *
36  * @see View#getOverlay() View.getOverlay()
37  * @see ViewGroup#getOverlay() ViewGroup.getOverlay()
38  * @see ViewGroupOverlay
39  */
40 public class ViewOverlay {
41 
42     /**
43      * The actual container for the drawables (and views, if it's a ViewGroupOverlay).
44      * All of the management and rendering details for the overlay are handled in
45      * OverlayViewGroup.
46      */
47     OverlayViewGroup mOverlayViewGroup;
48 
ViewOverlay(Context context, View hostView)49     ViewOverlay(Context context, View hostView) {
50         mOverlayViewGroup = new OverlayViewGroup(context, hostView);
51     }
52 
53     /**
54      * Used internally by View and ViewGroup to handle drawing and invalidation
55      * of the overlay
56      * @return
57      */
getOverlayView()58     ViewGroup getOverlayView() {
59         return mOverlayViewGroup;
60     }
61 
62     /**
63      * Adds a {@link Drawable} to the overlay. The bounds of the drawable should be relative to
64      * the host view. Any drawable added to the overlay should be removed when it is no longer
65      * needed or no longer visible. Adding an already existing {@link Drawable}
66      * is a no-op. Passing <code>null</code> parameter will result in an
67      * {@link IllegalArgumentException} being thrown.
68      *
69      * @param drawable The {@link Drawable} to be added to the overlay. This drawable will be
70      * drawn when the view redraws its overlay. {@link Drawable}s will be drawn in the order that
71      * they were added.
72      * @see #remove(Drawable)
73      */
add(@onNull Drawable drawable)74     public void add(@NonNull Drawable drawable) {
75         mOverlayViewGroup.add(drawable);
76     }
77 
78     /**
79      * Removes the specified {@link Drawable} from the overlay. Removing a {@link Drawable} that was
80      * not added with {@link #add(Drawable)} is a no-op. Passing <code>null</code> parameter will
81      * result in an {@link IllegalArgumentException} being thrown.
82      *
83      * @param drawable The {@link Drawable} to be removed from the overlay.
84      * @see #add(Drawable)
85      */
remove(@onNull Drawable drawable)86     public void remove(@NonNull Drawable drawable) {
87         mOverlayViewGroup.remove(drawable);
88     }
89 
90     /**
91      * Removes all content from the overlay.
92      */
clear()93     public void clear() {
94         mOverlayViewGroup.clear();
95     }
96 
isEmpty()97     boolean isEmpty() {
98         return mOverlayViewGroup.isEmpty();
99     }
100 
101     /**
102      * OverlayViewGroup is a container that View and ViewGroup use to host
103      * drawables and views added to their overlays  ({@link ViewOverlay} and
104      * {@link ViewGroupOverlay}, respectively). Drawables are added to the overlay
105      * via the add/remove methods in ViewOverlay, Views are added/removed via
106      * ViewGroupOverlay. These drawable and view objects are
107      * drawn whenever the view itself is drawn; first the view draws its own
108      * content (and children, if it is a ViewGroup), then it draws its overlay
109      * (if it has one).
110      *
111      * <p>Besides managing and drawing the list of drawables, this class serves
112      * two purposes:
113      * (1) it noops layout calls because children are absolutely positioned and
114      * (2) it forwards all invalidation calls to its host view. The invalidation
115      * redirect is necessary because the overlay is not a child of the host view
116      * and invalidation cannot therefore follow the normal path up through the
117      * parent hierarchy.</p>
118      *
119      * @see View#getOverlay()
120      * @see ViewGroup#getOverlay()
121      */
122     static class OverlayViewGroup extends ViewGroup {
123 
124         /**
125          * The View for which this is an overlay. Invalidations of the overlay are redirected to
126          * this host view.
127          */
128         final View mHostView;
129 
130         /**
131          * The set of drawables to draw when the overlay is rendered.
132          */
133         ArrayList<Drawable> mDrawables = null;
134 
OverlayViewGroup(Context context, View hostView)135         OverlayViewGroup(Context context, View hostView) {
136             super(context);
137             mHostView = hostView;
138             mAttachInfo = mHostView.mAttachInfo;
139 
140             mRight = hostView.getWidth();
141             mBottom = hostView.getHeight();
142             // pass right+bottom directly to RenderNode, since not going through setters
143             mRenderNode.setLeftTopRightBottom(0, 0, mRight, mBottom);
144         }
145 
add(@onNull Drawable drawable)146         public void add(@NonNull Drawable drawable) {
147             if (drawable == null) {
148                 throw new IllegalArgumentException("drawable must be non-null");
149             }
150             if (mDrawables == null) {
151                 mDrawables = new ArrayList<>();
152             }
153             if (!mDrawables.contains(drawable)) {
154                 // Make each drawable unique in the overlay; can't add it more than once
155                 mDrawables.add(drawable);
156                 invalidate(drawable.getBounds());
157                 drawable.setCallback(this);
158             }
159         }
160 
remove(@onNull Drawable drawable)161         public void remove(@NonNull Drawable drawable) {
162             if (drawable == null) {
163                 throw new IllegalArgumentException("drawable must be non-null");
164             }
165             if (mDrawables != null) {
166                 mDrawables.remove(drawable);
167                 invalidate(drawable.getBounds());
168                 drawable.setCallback(null);
169             }
170         }
171 
172         @Override
verifyDrawable(@onNull Drawable who)173         protected boolean verifyDrawable(@NonNull Drawable who) {
174             return super.verifyDrawable(who) || (mDrawables != null && mDrawables.contains(who));
175         }
176 
add(@onNull View child)177         public void add(@NonNull View child) {
178             if (child == null) {
179                 throw new IllegalArgumentException("view must be non-null");
180             }
181 
182             if (child.getParent() instanceof ViewGroup) {
183                 ViewGroup parent = (ViewGroup) child.getParent();
184                 if (parent != mHostView && parent.getParent() != null &&
185                         parent.mAttachInfo != null) {
186                     // Moving to different container; figure out how to position child such that
187                     // it is in the same location on the screen
188                     int[] parentLocation = new int[2];
189                     int[] hostViewLocation = new int[2];
190                     parent.getLocationOnScreen(parentLocation);
191                     mHostView.getLocationOnScreen(hostViewLocation);
192                     child.offsetLeftAndRight(parentLocation[0] - hostViewLocation[0]);
193                     child.offsetTopAndBottom(parentLocation[1] - hostViewLocation[1]);
194                 }
195                 parent.removeView(child);
196                 if (parent.getLayoutTransition() != null) {
197                     // LayoutTransition will cause the child to delay removal - cancel it
198                     parent.getLayoutTransition().cancel(LayoutTransition.DISAPPEARING);
199                 }
200                 // fail-safe if view is still attached for any reason
201                 if (child.getParent() != null) {
202                     child.mParent = null;
203                 }
204             }
205             super.addView(child);
206         }
207 
remove(@onNull View view)208         public void remove(@NonNull View view) {
209             if (view == null) {
210                 throw new IllegalArgumentException("view must be non-null");
211             }
212 
213             super.removeView(view);
214         }
215 
clear()216         public void clear() {
217             removeAllViews();
218             if (mDrawables != null) {
219                 for (Drawable drawable : mDrawables) {
220                     drawable.setCallback(null);
221                 }
222                 mDrawables.clear();
223             }
224         }
225 
isEmpty()226         boolean isEmpty() {
227             if (getChildCount() == 0 &&
228                     (mDrawables == null || mDrawables.size() == 0)) {
229                 return true;
230             }
231             return false;
232         }
233 
234         @Override
invalidateDrawable(@onNull Drawable drawable)235         public void invalidateDrawable(@NonNull Drawable drawable) {
236             invalidate(drawable.getBounds());
237         }
238 
239         @Override
dispatchDraw(Canvas canvas)240         protected void dispatchDraw(Canvas canvas) {
241             super.dispatchDraw(canvas);
242             final int numDrawables = (mDrawables == null) ? 0 : mDrawables.size();
243             for (int i = 0; i < numDrawables; ++i) {
244                 mDrawables.get(i).draw(canvas);
245             }
246         }
247 
248         @Override
onLayout(boolean changed, int l, int t, int r, int b)249         protected void onLayout(boolean changed, int l, int t, int r, int b) {
250             // Noop: children are positioned absolutely
251         }
252 
253         /*
254          The following invalidation overrides exist for the purpose of redirecting invalidation to
255          the host view. The overlay is not parented to the host view (since a View cannot be a
256          parent), so the invalidation cannot proceed through the normal parent hierarchy.
257          There is a built-in assumption that the overlay exactly covers the host view, therefore
258          the invalidation rectangles received do not need to be adjusted when forwarded to
259          the host view.
260          */
261 
262         @Override
invalidate(Rect dirty)263         public void invalidate(Rect dirty) {
264             super.invalidate(dirty);
265             if (mHostView != null) {
266                 mHostView.invalidate(dirty);
267             }
268         }
269 
270         @Override
invalidate(int l, int t, int r, int b)271         public void invalidate(int l, int t, int r, int b) {
272             super.invalidate(l, t, r, b);
273             if (mHostView != null) {
274                 mHostView.invalidate(l, t, r, b);
275             }
276         }
277 
278         @Override
invalidate()279         public void invalidate() {
280             super.invalidate();
281             if (mHostView != null) {
282                 mHostView.invalidate();
283             }
284         }
285 
286         @Override
invalidate(boolean invalidateCache)287         void invalidate(boolean invalidateCache) {
288             super.invalidate(invalidateCache);
289             if (mHostView != null) {
290                 mHostView.invalidate(invalidateCache);
291             }
292         }
293 
294         @Override
invalidateViewProperty(boolean invalidateParent, boolean forceRedraw)295         void invalidateViewProperty(boolean invalidateParent, boolean forceRedraw) {
296             super.invalidateViewProperty(invalidateParent, forceRedraw);
297             if (mHostView != null) {
298                 mHostView.invalidateViewProperty(invalidateParent, forceRedraw);
299             }
300         }
301 
302         @Override
invalidateParentCaches()303         protected void invalidateParentCaches() {
304             super.invalidateParentCaches();
305             if (mHostView != null) {
306                 mHostView.invalidateParentCaches();
307             }
308         }
309 
310         @Override
invalidateParentIfNeeded()311         protected void invalidateParentIfNeeded() {
312             super.invalidateParentIfNeeded();
313             if (mHostView != null) {
314                 mHostView.invalidateParentIfNeeded();
315             }
316         }
317 
318         /**
319          * @hide
320          */
321         @Override
damageChild(View child, final Rect dirty)322         public void damageChild(View child, final Rect dirty) {
323             if (mHostView != null) {
324                 // Note: This is not a "fast" invalidation. Would be nice to instead invalidate
325                 // using DisplayList properties and a dirty rect instead of causing a real
326                 // invalidation of the host view
327                 int left = child.mLeft;
328                 int top = child.mTop;
329                 if (!child.getMatrix().isIdentity()) {
330                     child.transformRect(dirty);
331                 }
332                 dirty.offset(left, top);
333                 mHostView.invalidate(dirty);
334             }
335         }
336 
337         /**
338          * @hide
339          */
340         @Override
damageChildInParent(int left, int top, Rect dirty)341         protected ViewParent damageChildInParent(int left, int top, Rect dirty) {
342             if (mHostView instanceof ViewGroup) {
343                 return ((ViewGroup) mHostView).damageChildInParent(left, top, dirty);
344             }
345             return null;
346         }
347 
348         @Override
invalidateChildInParent(int[] location, Rect dirty)349         public ViewParent invalidateChildInParent(int[] location, Rect dirty) {
350             if (mHostView != null) {
351                 dirty.offset(location[0], location[1]);
352                 if (mHostView instanceof ViewGroup) {
353                     location[0] = 0;
354                     location[1] = 0;
355                     super.invalidateChildInParent(location, dirty);
356                     return ((ViewGroup) mHostView).invalidateChildInParent(location, dirty);
357                 } else {
358                     invalidate(dirty);
359                 }
360             }
361             return null;
362         }
363     }
364 
365 }
366