1/*
2 * Copyright (C) 2011 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
17package android.support.v4.view;
18
19import android.os.Build;
20import android.support.annotation.NonNull;
21import android.support.annotation.RequiresApi;
22import android.support.v4.view.ViewCompat.ScrollAxis;
23import android.view.View;
24import android.view.ViewGroup;
25import android.view.accessibility.AccessibilityEvent;
26
27/**
28 * Helper for accessing features in {@link ViewGroup}
29 * introduced after API level 4 in a backwards compatible fashion.
30 */
31public final class ViewGroupCompat {
32
33    /**
34     * This constant is a {@link #setLayoutMode(ViewGroup, int) layoutMode}.
35     * Clip bounds are the raw values of {@link android.view.View#getLeft() left},
36     * {@link android.view.View#getTop() top},
37     * {@link android.view.View#getRight() right} and {@link android.view.View#getBottom() bottom}.
38     */
39    public static final int LAYOUT_MODE_CLIP_BOUNDS = 0;
40
41    /**
42     * This constant is a {@link #setLayoutMode(ViewGroup, int) layoutMode}.
43     * Optical bounds describe where a widget appears to be. They sit inside the clip
44     * bounds which need to cover a larger area to allow other effects,
45     * such as shadows and glows, to be drawn.
46     */
47    public static final int LAYOUT_MODE_OPTICAL_BOUNDS = 1;
48
49    static class ViewGroupCompatBaseImpl {
50        public int getLayoutMode(ViewGroup group) {
51            return LAYOUT_MODE_CLIP_BOUNDS;
52        }
53
54        public void setLayoutMode(ViewGroup group, int mode) {
55            // no-op, didn't exist. Views only support clip bounds.
56        }
57
58        public void setTransitionGroup(ViewGroup group, boolean isTransitionGroup) {
59        }
60
61        public boolean isTransitionGroup(ViewGroup group) {
62            return false;
63        }
64
65        public int getNestedScrollAxes(ViewGroup group) {
66            if (group instanceof NestedScrollingParent) {
67                return ((NestedScrollingParent) group).getNestedScrollAxes();
68            }
69            return ViewCompat.SCROLL_AXIS_NONE;
70        }
71    }
72
73    @RequiresApi(18)
74    static class ViewGroupCompatApi18Impl extends ViewGroupCompatBaseImpl {
75        @Override
76        public int getLayoutMode(ViewGroup group) {
77            return group.getLayoutMode();
78        }
79
80        @Override
81        public void setLayoutMode(ViewGroup group, int mode) {
82            group.setLayoutMode(mode);
83        }
84    }
85
86    @RequiresApi(21)
87    static class ViewGroupCompatApi21Impl extends ViewGroupCompatApi18Impl {
88        @Override
89        public void setTransitionGroup(ViewGroup group, boolean isTransitionGroup) {
90            group.setTransitionGroup(isTransitionGroup);
91        }
92
93        @Override
94        public boolean isTransitionGroup(ViewGroup group) {
95            return group.isTransitionGroup();
96        }
97
98        @Override
99        public int getNestedScrollAxes(ViewGroup group) {
100            return group.getNestedScrollAxes();
101        }
102    }
103
104    static final ViewGroupCompatBaseImpl IMPL;
105    static {
106        if (Build.VERSION.SDK_INT >= 21) {
107            IMPL = new ViewGroupCompatApi21Impl();
108        } else if (Build.VERSION.SDK_INT >= 18) {
109            IMPL = new ViewGroupCompatApi18Impl();
110        } else {
111            IMPL = new ViewGroupCompatBaseImpl();
112        }
113    }
114
115    /*
116     * Hide the constructor.
117     */
118    private ViewGroupCompat() {}
119
120    /**
121     * Called when a child has requested sending an {@link AccessibilityEvent} and
122     * gives an opportunity to its parent to augment the event.
123     * <p>
124     * If an {@link AccessibilityDelegateCompat} has been specified via calling
125     * {@link ViewCompat#setAccessibilityDelegate(View, AccessibilityDelegateCompat)} its
126     * {@link AccessibilityDelegateCompat#onRequestSendAccessibilityEvent(ViewGroup, View,
127     * AccessibilityEvent)} is responsible for handling this call.
128     * </p>
129     *
130     * @param group The group whose method to invoke.
131     * @param child The child which requests sending the event.
132     * @param event The event to be sent.
133     * @return True if the event should be sent.
134     *
135     * @deprecated Use {@link ViewGroup#onRequestSendAccessibilityEvent(View, AccessibilityEvent)}
136     * directly.
137     */
138    @Deprecated
139    public static boolean onRequestSendAccessibilityEvent(ViewGroup group, View child,
140            AccessibilityEvent event) {
141        return group.onRequestSendAccessibilityEvent(child, event);
142    }
143
144    /**
145     * Enable or disable the splitting of MotionEvents to multiple children during touch event
146     * dispatch. This behavior is enabled by default for applications that target an
147     * SDK version of 11 (Honeycomb) or newer. On earlier platform versions this feature
148     * was not supported and this method is a no-op.
149     *
150     * <p>When this option is enabled MotionEvents may be split and dispatched to different child
151     * views depending on where each pointer initially went down. This allows for user interactions
152     * such as scrolling two panes of content independently, chording of buttons, and performing
153     * independent gestures on different pieces of content.
154     *
155     * @param group ViewGroup to modify
156     * @param split <code>true</code> to allow MotionEvents to be split and dispatched to multiple
157     *              child views. <code>false</code> to only allow one child view to be the target of
158     *              any MotionEvent received by this ViewGroup.
159     *
160     * @deprecated Use {@link ViewGroup#setMotionEventSplittingEnabled(boolean)} directly.
161     */
162    @Deprecated
163    public static void setMotionEventSplittingEnabled(ViewGroup group, boolean split) {
164        group.setMotionEventSplittingEnabled(split);
165    }
166
167    /**
168     * Returns the basis of alignment during layout operations on this ViewGroup:
169     * either {@link #LAYOUT_MODE_CLIP_BOUNDS} or {@link #LAYOUT_MODE_OPTICAL_BOUNDS}.
170     * <p>
171     * If no layoutMode was explicitly set, either programmatically or in an XML resource,
172     * the method returns the layoutMode of the view's parent ViewGroup if such a parent exists,
173     * otherwise the method returns a default value of {@link #LAYOUT_MODE_CLIP_BOUNDS}.
174     *
175     * @return the layout mode to use during layout operations
176     *
177     * @see #setLayoutMode(ViewGroup, int)
178     */
179    public static int getLayoutMode(ViewGroup group) {
180        return IMPL.getLayoutMode(group);
181    }
182
183    /**
184     * Sets the basis of alignment during the layout of this ViewGroup.
185     * Valid values are either {@link #LAYOUT_MODE_CLIP_BOUNDS} or
186     * {@link #LAYOUT_MODE_OPTICAL_BOUNDS}.
187     *
188     * @param mode the layout mode to use during layout operations
189     *
190     * @see #getLayoutMode(ViewGroup)
191     */
192    public static void setLayoutMode(ViewGroup group, int mode) {
193        IMPL.setLayoutMode(group, mode);
194    }
195
196    /**
197     * Changes whether or not this ViewGroup should be treated as a single entity during
198     * Activity Transitions.
199     * @param isTransitionGroup Whether or not the ViewGroup should be treated as a unit
200     *                          in Activity transitions. If false, the ViewGroup won't transition,
201     *                          only its children. If true, the entire ViewGroup will transition
202     *                          together.
203     */
204    public static void setTransitionGroup(ViewGroup group, boolean isTransitionGroup) {
205        IMPL.setTransitionGroup(group, isTransitionGroup);
206    }
207
208    /**
209     * Returns true if this ViewGroup should be considered as a single entity for removal
210     * when executing an Activity transition. If this is false, child elements will move
211     * individually during the transition.
212     */
213    public static boolean isTransitionGroup(ViewGroup group) {
214        return IMPL.isTransitionGroup(group);
215    }
216
217    /**
218     * Return the current axes of nested scrolling for this ViewGroup.
219     *
220     * <p>A ViewGroup returning something other than {@link ViewCompat#SCROLL_AXIS_NONE} is
221     * currently acting as a nested scrolling parent for one or more descendant views in
222     * the hierarchy.</p>
223     *
224     * @return Flags indicating the current axes of nested scrolling
225     * @see ViewCompat#SCROLL_AXIS_HORIZONTAL
226     * @see ViewCompat#SCROLL_AXIS_VERTICAL
227     * @see ViewCompat#SCROLL_AXIS_NONE
228     */
229    @ScrollAxis
230    public static int getNestedScrollAxes(@NonNull ViewGroup group) {
231        return IMPL.getNestedScrollAxes(group);
232    }
233}
234