The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 1 | /* |
| 2 | * Copyright (C) 2006 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 | package android.view; |
| 18 | |
Chris Craik | 9de95db | 2017-01-18 17:59:23 -0800 | [diff] [blame] | 19 | import android.annotation.NonNull; |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 20 | import android.graphics.Rect; |
Tiger Huang | 2b210c2 | 2019-03-18 21:21:26 +0800 | [diff] [blame] | 21 | import android.graphics.Region; |
Adam Powell | b6ab098 | 2015-01-07 17:00:12 -0800 | [diff] [blame] | 22 | import android.os.Bundle; |
Svetoslav Ganov | 736c275 | 2011-04-22 18:30:36 -0700 | [diff] [blame] | 23 | import android.view.accessibility.AccessibilityEvent; |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 24 | |
| 25 | /** |
| 26 | * Defines the responsibilities for a class that will be a parent of a View. |
| 27 | * This is the API that a view sees when it wants to interact with its parent. |
| 28 | * |
| 29 | */ |
| 30 | public interface ViewParent { |
| 31 | /** |
| 32 | * Called when something has changed which has invalidated the layout of a |
| 33 | * child of this view parent. This will schedule a layout pass of the view |
| 34 | * tree. |
| 35 | */ |
| 36 | public void requestLayout(); |
| 37 | |
| 38 | /** |
| 39 | * Indicates whether layout was requested on this view parent. |
| 40 | * |
| 41 | * @return true if layout was requested, false otherwise |
| 42 | */ |
| 43 | public boolean isLayoutRequested(); |
| 44 | |
| 45 | /** |
| 46 | * Called when a child wants the view hierarchy to gather and report |
| 47 | * transparent regions to the window compositor. Views that "punch" holes in |
| 48 | * the view hierarchy, such as SurfaceView can use this API to improve |
| 49 | * performance of the system. When no such a view is present in the |
| 50 | * hierarchy, this optimization in unnecessary and might slightly reduce the |
| 51 | * view hierarchy performance. |
| 52 | * |
| 53 | * @param child the view requesting the transparent region computation |
| 54 | * |
| 55 | */ |
| 56 | public void requestTransparentRegion(View child); |
| 57 | |
Chris Craik | 9de95db | 2017-01-18 17:59:23 -0800 | [diff] [blame] | 58 | |
| 59 | /** |
| 60 | * The target View has been invalidated, or has had a drawing property changed that |
| 61 | * requires the hierarchy to re-render. |
| 62 | * |
| 63 | * This method is called by the View hierarchy to signal ancestors that a View either needs to |
| 64 | * re-record its drawing commands, or drawing properties have changed. This is how Views |
| 65 | * schedule a drawing traversal. |
| 66 | * |
| 67 | * This signal is generally only dispatched for attached Views, since only they need to draw. |
| 68 | * |
| 69 | * @param child Direct child of this ViewParent containing target |
| 70 | * @param target The view that needs to redraw |
| 71 | */ |
| 72 | default void onDescendantInvalidated(@NonNull View child, @NonNull View target) { |
| 73 | if (getParent() != null) { |
| 74 | // Note: should pass 'this' as default, but can't since we may not be a View |
| 75 | getParent().onDescendantInvalidated(child, target); |
| 76 | } |
| 77 | } |
| 78 | |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 79 | /** |
| 80 | * All or part of a child is dirty and needs to be redrawn. |
| 81 | * |
| 82 | * @param child The child which is dirty |
| 83 | * @param r The area within the child that is invalid |
Chris Craik | 9de95db | 2017-01-18 17:59:23 -0800 | [diff] [blame] | 84 | * |
| 85 | * @deprecated Use {@link #onDescendantInvalidated(View, View)} instead. |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 86 | */ |
Chris Craik | 9de95db | 2017-01-18 17:59:23 -0800 | [diff] [blame] | 87 | @Deprecated |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 88 | public void invalidateChild(View child, Rect r); |
| 89 | |
| 90 | /** |
| 91 | * All or part of a child is dirty and needs to be redrawn. |
| 92 | * |
Gilles Debunne | cea4513 | 2011-11-24 02:19:27 +0100 | [diff] [blame] | 93 | * <p>The location array is an array of two int values which respectively |
| 94 | * define the left and the top position of the dirty child.</p> |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 95 | * |
Gilles Debunne | cea4513 | 2011-11-24 02:19:27 +0100 | [diff] [blame] | 96 | * <p>This method must return the parent of this ViewParent if the specified |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 97 | * rectangle must be invalidated in the parent. If the specified rectangle |
| 98 | * does not require invalidation in the parent or if the parent does not |
Gilles Debunne | cea4513 | 2011-11-24 02:19:27 +0100 | [diff] [blame] | 99 | * exist, this method must return null.</p> |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 100 | * |
Gilles Debunne | cea4513 | 2011-11-24 02:19:27 +0100 | [diff] [blame] | 101 | * <p>When this method returns a non-null value, the location array must |
| 102 | * have been updated with the left and top coordinates of this ViewParent.</p> |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 103 | * |
| 104 | * @param location An array of 2 ints containing the left and top |
| 105 | * coordinates of the child to invalidate |
| 106 | * @param r The area within the child that is invalid |
| 107 | * |
| 108 | * @return the parent of this ViewParent or null |
Chris Craik | 9de95db | 2017-01-18 17:59:23 -0800 | [diff] [blame] | 109 | * |
| 110 | * @deprecated Use {@link #onDescendantInvalidated(View, View)} instead. |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 111 | */ |
Chris Craik | 9de95db | 2017-01-18 17:59:23 -0800 | [diff] [blame] | 112 | @Deprecated |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 113 | public ViewParent invalidateChildInParent(int[] location, Rect r); |
| 114 | |
| 115 | /** |
| 116 | * Returns the parent if it exists, or null. |
| 117 | * |
| 118 | * @return a ViewParent or null if this ViewParent does not have a parent |
| 119 | */ |
| 120 | public ViewParent getParent(); |
| 121 | |
| 122 | /** |
| 123 | * Called when a child of this parent wants focus |
| 124 | * |
| 125 | * @param child The child of this ViewParent that wants focus. This view |
| 126 | * will contain the focused view. It is not necessarily the view that |
| 127 | * actually has focus. |
| 128 | * @param focused The view that is a descendant of child that actually has |
| 129 | * focus |
| 130 | */ |
| 131 | public void requestChildFocus(View child, View focused); |
| 132 | |
| 133 | /** |
| 134 | * Tell view hierarchy that the global view attributes need to be |
| 135 | * re-evaluated. |
| 136 | * |
| 137 | * @param child View whose attributes have changed. |
| 138 | */ |
| 139 | public void recomputeViewAttributes(View child); |
| 140 | |
| 141 | /** |
| 142 | * Called when a child of this parent is giving up focus |
| 143 | * |
| 144 | * @param child The view that is giving up focus |
| 145 | */ |
| 146 | public void clearChildFocus(View child); |
| 147 | |
Gilles Debunne | cea4513 | 2011-11-24 02:19:27 +0100 | [diff] [blame] | 148 | /** |
| 149 | * Compute the visible part of a rectangular region defined in terms of a child view's |
| 150 | * coordinates. |
| 151 | * |
| 152 | * <p>Returns the clipped visible part of the rectangle <code>r</code>, defined in the |
| 153 | * <code>child</code>'s local coordinate system. <code>r</code> is modified by this method to |
| 154 | * contain the result, expressed in the global (root) coordinate system.</p> |
| 155 | * |
| 156 | * <p>The resulting rectangle is always axis aligned. If a rotation is applied to a node in the |
| 157 | * View hierarchy, the result is the axis-aligned bounding box of the visible rectangle.</p> |
| 158 | * |
| 159 | * @param child A child View, whose rectangular visible region we want to compute |
| 160 | * @param r The input rectangle, defined in the child coordinate system. Will be overwritten to |
| 161 | * contain the resulting visible rectangle, expressed in global (root) coordinates |
| 162 | * @param offset The input coordinates of a point, defined in the child coordinate system. |
| 163 | * As with the <code>r</code> parameter, this will be overwritten to contain the global (root) |
| 164 | * coordinates of that point. |
| 165 | * A <code>null</code> value is valid (in case you are not interested in this result) |
| 166 | * @return true if the resulting rectangle is not empty, false otherwise |
| 167 | */ |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 168 | public boolean getChildVisibleRect(View child, Rect r, android.graphics.Point offset); |
| 169 | |
| 170 | /** |
| 171 | * Find the nearest view in the specified direction that wants to take focus |
| 172 | * |
| 173 | * @param v The view that currently has focus |
| 174 | * @param direction One of FOCUS_UP, FOCUS_DOWN, FOCUS_LEFT, and FOCUS_RIGHT |
| 175 | */ |
| 176 | public View focusSearch(View v, int direction); |
| 177 | |
| 178 | /** |
Vadim Tryshev | b5ced22 | 2017-01-17 19:31:35 -0800 | [diff] [blame] | 179 | * Find the nearest keyboard navigation cluster in the specified direction. |
| 180 | * This does not actually give focus to that cluster. |
Vadim Tryshev | 01b0c9e | 2016-11-21 15:25:01 -0800 | [diff] [blame] | 181 | * |
Vadim Tryshev | b5ced22 | 2017-01-17 19:31:35 -0800 | [diff] [blame] | 182 | * @param currentCluster The starting point of the search. Null means the current cluster is not |
| 183 | * found yet |
Vadim Tryshev | 01b0c9e | 2016-11-21 15:25:01 -0800 | [diff] [blame] | 184 | * @param direction Direction to look |
| 185 | * |
Vadim Tryshev | b5ced22 | 2017-01-17 19:31:35 -0800 | [diff] [blame] | 186 | * @return The nearest keyboard navigation cluster in the specified direction, or null if none |
Vadim Tryshev | 01b0c9e | 2016-11-21 15:25:01 -0800 | [diff] [blame] | 187 | * can be found |
| 188 | */ |
Vadim Tryshev | b5ced22 | 2017-01-17 19:31:35 -0800 | [diff] [blame] | 189 | View keyboardNavigationClusterSearch(View currentCluster, int direction); |
Vadim Tryshev | 01b0c9e | 2016-11-21 15:25:01 -0800 | [diff] [blame] | 190 | |
| 191 | /** |
Chet Haase | 0187a5d | 2013-04-23 06:55:04 -0700 | [diff] [blame] | 192 | * Change the z order of the child so it's on top of all other children. |
| 193 | * This ordering change may affect layout, if this container |
Chet Haase | cb96db8 | 2013-09-04 10:21:46 -0700 | [diff] [blame] | 194 | * uses an order-dependent layout scheme (e.g., LinearLayout). Prior |
Chet Haase | e8222dd | 2013-09-05 07:44:18 -0700 | [diff] [blame] | 195 | * to {@link android.os.Build.VERSION_CODES#KITKAT} this |
Chet Haase | 0187a5d | 2013-04-23 06:55:04 -0700 | [diff] [blame] | 196 | * method should be followed by calls to {@link #requestLayout()} and |
Chet Haase | cb96db8 | 2013-09-04 10:21:46 -0700 | [diff] [blame] | 197 | * {@link View#invalidate()} on this parent to force the parent to redraw |
| 198 | * with the new child ordering. |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 199 | * |
Chet Haase | 0187a5d | 2013-04-23 06:55:04 -0700 | [diff] [blame] | 200 | * @param child The child to bring to the top of the z order |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 201 | */ |
| 202 | public void bringChildToFront(View child); |
| 203 | |
| 204 | /** |
| 205 | * Tells the parent that a new focusable view has become available. This is |
| 206 | * to handle transitions from the case where there are no focusable views to |
| 207 | * the case where the first focusable view appears. |
| 208 | * |
| 209 | * @param v The view that has become newly focusable |
| 210 | */ |
| 211 | public void focusableViewAvailable(View v); |
| 212 | |
| 213 | /** |
Alan Viverette | 021627e | 2015-11-25 14:22:00 -0500 | [diff] [blame] | 214 | * Shows the context menu for the specified view or its ancestors. |
| 215 | * <p> |
| 216 | * In most cases, a subclass does not need to override this. However, if |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 217 | * the subclass is added directly to the window manager (for example, |
| 218 | * {@link ViewManager#addView(View, android.view.ViewGroup.LayoutParams)}) |
Alan Viverette | 021627e | 2015-11-25 14:22:00 -0500 | [diff] [blame] | 219 | * then it should override this and show the context menu. |
| 220 | * |
| 221 | * @param originalView the source view where the context menu was first |
| 222 | * invoked |
| 223 | * @return {@code true} if the context menu was shown, {@code false} |
| 224 | * otherwise |
| 225 | * @see #showContextMenuForChild(View, float, float) |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 226 | */ |
| 227 | public boolean showContextMenuForChild(View originalView); |
| 228 | |
| 229 | /** |
Alan Viverette | 021627e | 2015-11-25 14:22:00 -0500 | [diff] [blame] | 230 | * Shows the context menu for the specified view or its ancestors anchored |
| 231 | * to the specified view-relative coordinate. |
| 232 | * <p> |
| 233 | * In most cases, a subclass does not need to override this. However, if |
| 234 | * the subclass is added directly to the window manager (for example, |
| 235 | * {@link ViewManager#addView(View, android.view.ViewGroup.LayoutParams)}) |
| 236 | * then it should override this and show the context menu. |
Adam Powell | 2af189a | 2016-02-05 15:52:02 -0800 | [diff] [blame] | 237 | * <p> |
| 238 | * If a subclass overrides this method it should also override |
| 239 | * {@link #showContextMenuForChild(View)}. |
Oren Blasberg | ed39126 | 2015-09-01 12:12:51 -0700 | [diff] [blame] | 240 | * |
Alan Viverette | 021627e | 2015-11-25 14:22:00 -0500 | [diff] [blame] | 241 | * @param originalView the source view where the context menu was first |
| 242 | * invoked |
| 243 | * @param x the X coordinate in pixels relative to the original view to |
Oren Blasberg | 23e282d | 2016-04-20 13:43:45 -0700 | [diff] [blame] | 244 | * which the menu should be anchored, or {@link Float#NaN} to |
| 245 | * disable anchoring |
Alan Viverette | 021627e | 2015-11-25 14:22:00 -0500 | [diff] [blame] | 246 | * @param y the Y coordinate in pixels relative to the original view to |
Oren Blasberg | 23e282d | 2016-04-20 13:43:45 -0700 | [diff] [blame] | 247 | * which the menu should be anchored, or {@link Float#NaN} to |
| 248 | * disable anchoring |
Alan Viverette | 021627e | 2015-11-25 14:22:00 -0500 | [diff] [blame] | 249 | * @return {@code true} if the context menu was shown, {@code false} |
| 250 | * otherwise |
Oren Blasberg | ed39126 | 2015-09-01 12:12:51 -0700 | [diff] [blame] | 251 | */ |
Adam Powell | 2af189a | 2016-02-05 15:52:02 -0800 | [diff] [blame] | 252 | boolean showContextMenuForChild(View originalView, float x, float y); |
Oren Blasberg | ed39126 | 2015-09-01 12:12:51 -0700 | [diff] [blame] | 253 | |
| 254 | /** |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 255 | * Have the parent populate the specified context menu if it has anything to |
| 256 | * add (and then recurse on its parent). |
| 257 | * |
| 258 | * @param menu The menu to populate |
| 259 | */ |
| 260 | public void createContextMenu(ContextMenu menu); |
| 261 | |
| 262 | /** |
Clara Bayarri | 4423d91 | 2015-03-02 19:42:48 +0000 | [diff] [blame] | 263 | * Start an action mode for the specified view with the default type |
| 264 | * {@link ActionMode#TYPE_PRIMARY}. |
Gilles Debunne | cea4513 | 2011-11-24 02:19:27 +0100 | [diff] [blame] | 265 | * |
| 266 | * <p>In most cases, a subclass does not need to override this. However, if the |
Adam Powell | 6e34636 | 2010-07-23 10:18:23 -0700 | [diff] [blame] | 267 | * subclass is added directly to the window manager (for example, |
| 268 | * {@link ViewManager#addView(View, android.view.ViewGroup.LayoutParams)}) |
Gilles Debunne | cea4513 | 2011-11-24 02:19:27 +0100 | [diff] [blame] | 269 | * then it should override this and start the action mode.</p> |
Adam Powell | 6e34636 | 2010-07-23 10:18:23 -0700 | [diff] [blame] | 270 | * |
| 271 | * @param originalView The source view where the action mode was first invoked |
| 272 | * @param callback The callback that will handle lifecycle events for the action mode |
| 273 | * @return The new action mode if it was started, null otherwise |
Clara Bayarri | 4423d91 | 2015-03-02 19:42:48 +0000 | [diff] [blame] | 274 | * |
| 275 | * @see #startActionModeForChild(View, android.view.ActionMode.Callback, int) |
Adam Powell | 6e34636 | 2010-07-23 10:18:23 -0700 | [diff] [blame] | 276 | */ |
| 277 | public ActionMode startActionModeForChild(View originalView, ActionMode.Callback callback); |
| 278 | |
| 279 | /** |
Clara Bayarri | 4423d91 | 2015-03-02 19:42:48 +0000 | [diff] [blame] | 280 | * Start an action mode of a specific type for the specified view. |
| 281 | * |
| 282 | * <p>In most cases, a subclass does not need to override this. However, if the |
| 283 | * subclass is added directly to the window manager (for example, |
| 284 | * {@link ViewManager#addView(View, android.view.ViewGroup.LayoutParams)}) |
| 285 | * then it should override this and start the action mode.</p> |
| 286 | * |
| 287 | * @param originalView The source view where the action mode was first invoked |
| 288 | * @param callback The callback that will handle lifecycle events for the action mode |
| 289 | * @param type One of {@link ActionMode#TYPE_PRIMARY} or {@link ActionMode#TYPE_FLOATING}. |
| 290 | * @return The new action mode if it was started, null otherwise |
| 291 | */ |
| 292 | public ActionMode startActionModeForChild( |
| 293 | View originalView, ActionMode.Callback callback, int type); |
| 294 | |
| 295 | /** |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 296 | * This method is called on the parent when a child's drawable state |
| 297 | * has changed. |
| 298 | * |
| 299 | * @param child The child whose drawable state has changed. |
| 300 | */ |
| 301 | public void childDrawableStateChanged(View child); |
Clara Bayarri | 4423d91 | 2015-03-02 19:42:48 +0000 | [diff] [blame] | 302 | |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 303 | /** |
| 304 | * Called when a child does not want this parent and its ancestors to |
| 305 | * intercept touch events with |
| 306 | * {@link ViewGroup#onInterceptTouchEvent(MotionEvent)}. |
Gilles Debunne | cea4513 | 2011-11-24 02:19:27 +0100 | [diff] [blame] | 307 | * |
| 308 | * <p>This parent should pass this call onto its parents. This parent must obey |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 309 | * this request for the duration of the touch (that is, only clear the flag |
Gilles Debunne | cea4513 | 2011-11-24 02:19:27 +0100 | [diff] [blame] | 310 | * after this parent has received an up or a cancel.</p> |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 311 | * |
| 312 | * @param disallowIntercept True if the child does not want the parent to |
| 313 | * intercept touch events. |
| 314 | */ |
| 315 | public void requestDisallowInterceptTouchEvent(boolean disallowIntercept); |
Yigit Boyar | d62d5e9 | 2016-01-19 18:56:20 -0800 | [diff] [blame] | 316 | |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 317 | /** |
| 318 | * Called when a child of this group wants a particular rectangle to be |
| 319 | * positioned onto the screen. {@link ViewGroup}s overriding this can trust |
| 320 | * that: |
| 321 | * <ul> |
| 322 | * <li>child will be a direct child of this group</li> |
Yigit Boyar | d62d5e9 | 2016-01-19 18:56:20 -0800 | [diff] [blame] | 323 | * <li>rectangle will be in the child's content coordinates</li> |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 324 | * </ul> |
| 325 | * |
| 326 | * <p>{@link ViewGroup}s overriding this should uphold the contract:</p> |
| 327 | * <ul> |
| 328 | * <li>nothing will change if the rectangle is already visible</li> |
| 329 | * <li>the view port will be scrolled only just enough to make the |
| 330 | * rectangle visible</li> |
| 331 | * <ul> |
| 332 | * |
| 333 | * @param child The direct child making the request. |
| 334 | * @param rectangle The rectangle in the child's coordinates the child |
| 335 | * wishes to be on the screen. |
| 336 | * @param immediate True to forbid animated or delayed scrolling, |
| 337 | * false otherwise |
| 338 | * @return Whether the group scrolled to handle the operation |
| 339 | */ |
| 340 | public boolean requestChildRectangleOnScreen(View child, Rect rectangle, |
| 341 | boolean immediate); |
Svetoslav Ganov | 736c275 | 2011-04-22 18:30:36 -0700 | [diff] [blame] | 342 | |
| 343 | /** |
| 344 | * Called by a child to request from its parent to send an {@link AccessibilityEvent}. |
| 345 | * The child has already populated a record for itself in the event and is delegating |
| 346 | * to its parent to send the event. The parent can optionally add a record for itself. |
| 347 | * <p> |
| 348 | * Note: An accessibility event is fired by an individual view which populates the |
| 349 | * event with a record for its state and requests from its parent to perform |
| 350 | * the sending. The parent can optionally add a record for itself before |
| 351 | * dispatching the request to its parent. A parent can also choose not to |
| 352 | * respect the request for sending the event. The accessibility event is sent |
Gilles Debunne | cea4513 | 2011-11-24 02:19:27 +0100 | [diff] [blame] | 353 | * by the topmost view in the view tree.</p> |
Svetoslav Ganov | 736c275 | 2011-04-22 18:30:36 -0700 | [diff] [blame] | 354 | * |
| 355 | * @param child The child which requests sending the event. |
| 356 | * @param event The event to be sent. |
| 357 | * @return True if the event was sent. |
| 358 | */ |
| 359 | public boolean requestSendAccessibilityEvent(View child, AccessibilityEvent event); |
Adam Powell | 539ee87 | 2012-02-03 19:00:49 -0800 | [diff] [blame] | 360 | |
| 361 | /** |
| 362 | * Called when a child view now has or no longer is tracking transient state. |
| 363 | * |
Adam Powell | 0da4a28 | 2013-08-26 14:29:44 -0700 | [diff] [blame] | 364 | * <p>"Transient state" is any state that a View might hold that is not expected to |
| 365 | * be reflected in the data model that the View currently presents. This state only |
| 366 | * affects the presentation to the user within the View itself, such as the current |
| 367 | * state of animations in progress or the state of a text selection operation.</p> |
| 368 | * |
| 369 | * <p>Transient state is useful for hinting to other components of the View system |
| 370 | * that a particular view is tracking something complex but encapsulated. |
| 371 | * A <code>ListView</code> for example may acknowledge that list item Views |
| 372 | * with transient state should be preserved within their position or stable item ID |
| 373 | * instead of treating that view as trivially replaceable by the backing adapter. |
| 374 | * This allows adapter implementations to be simpler instead of needing to track |
| 375 | * the state of item view animations in progress such that they could be restored |
| 376 | * in the event of an unexpected recycling and rebinding of attached item views.</p> |
| 377 | * |
| 378 | * <p>This method is called on a parent view when a child view or a view within |
| 379 | * its subtree begins or ends tracking of internal transient state.</p> |
| 380 | * |
Adam Powell | 539ee87 | 2012-02-03 19:00:49 -0800 | [diff] [blame] | 381 | * @param child Child view whose state has changed |
| 382 | * @param hasTransientState true if this child has transient state |
Adam Powell | 539ee87 | 2012-02-03 19:00:49 -0800 | [diff] [blame] | 383 | */ |
| 384 | public void childHasTransientStateChanged(View child, boolean hasTransientState); |
Dianne Hackborn | 3a3a6cf | 2012-03-26 10:24:04 -0700 | [diff] [blame] | 385 | |
| 386 | /** |
| 387 | * Ask that a new dispatch of {@link View#fitSystemWindows(Rect) |
| 388 | * View.fitSystemWindows(Rect)} be performed. |
| 389 | */ |
| 390 | public void requestFitSystemWindows(); |
Svetoslav Ganov | 4213804 | 2012-03-20 11:51:39 -0700 | [diff] [blame] | 391 | |
| 392 | /** |
| 393 | * Gets the parent of a given View for accessibility. Since some Views are not |
| 394 | * exposed to the accessibility layer the parent for accessibility is not |
| 395 | * necessarily the direct parent of the View, rather it is a predecessor. |
| 396 | * |
| 397 | * @return The parent or <code>null</code> if no such is found. |
| 398 | */ |
| 399 | public ViewParent getParentForAccessibility(); |
| 400 | |
| 401 | /** |
Alan Viverette | 77e9a28 | 2013-09-12 17:16:09 -0700 | [diff] [blame] | 402 | * Notifies a view parent that the accessibility state of one of its |
| 403 | * descendants has changed and that the structure of the subtree is |
| 404 | * different. |
| 405 | * @param child The direct child whose subtree has changed. |
Phil Weaver | 63e4503 | 2017-05-11 10:54:37 -0700 | [diff] [blame] | 406 | * @param source The descendant view that changed. May not be {@code null}. |
Alan Viverette | 77e9a28 | 2013-09-12 17:16:09 -0700 | [diff] [blame] | 407 | * @param changeType A bit mask of the types of changes that occurred. One |
| 408 | * or more of: |
| 409 | * <ul> |
| 410 | * <li>{@link AccessibilityEvent#CONTENT_CHANGE_TYPE_CONTENT_DESCRIPTION} |
yingleiw | 6189b8c | 2019-08-21 11:13:08 -0700 | [diff] [blame] | 411 | * <li>{@link AccessibilityEvent#CONTENT_CHANGE_TYPE_STATE_DESCRIPTION} |
Alan Viverette | 77e9a28 | 2013-09-12 17:16:09 -0700 | [diff] [blame] | 412 | * <li>{@link AccessibilityEvent#CONTENT_CHANGE_TYPE_SUBTREE} |
| 413 | * <li>{@link AccessibilityEvent#CONTENT_CHANGE_TYPE_TEXT} |
| 414 | * <li>{@link AccessibilityEvent#CONTENT_CHANGE_TYPE_UNDEFINED} |
| 415 | * </ul> |
Svetoslav Ganov | 4213804 | 2012-03-20 11:51:39 -0700 | [diff] [blame] | 416 | */ |
Phil Weaver | 63e4503 | 2017-05-11 10:54:37 -0700 | [diff] [blame] | 417 | public void notifySubtreeAccessibilityStateChanged( |
| 418 | View child, @NonNull View source, int changeType); |
Fabrice Di Meglio | 9dd4c5c | 2013-02-08 18:15:07 -0800 | [diff] [blame] | 419 | |
| 420 | /** |
| 421 | * Tells if this view parent can resolve the layout direction. |
| 422 | * See {@link View#setLayoutDirection(int)} |
| 423 | * |
| 424 | * @return True if this view parent can resolve the layout direction. |
Fabrice Di Meglio | 9dd4c5c | 2013-02-08 18:15:07 -0800 | [diff] [blame] | 425 | */ |
| 426 | public boolean canResolveLayoutDirection(); |
| 427 | |
| 428 | /** |
| 429 | * Tells if this view parent layout direction is resolved. |
| 430 | * See {@link View#setLayoutDirection(int)} |
| 431 | * |
| 432 | * @return True if this view parent layout direction is resolved. |
Fabrice Di Meglio | 9dd4c5c | 2013-02-08 18:15:07 -0800 | [diff] [blame] | 433 | */ |
| 434 | public boolean isLayoutDirectionResolved(); |
| 435 | |
| 436 | /** |
| 437 | * Return this view parent layout direction. See {@link View#getLayoutDirection()} |
| 438 | * |
| 439 | * @return {@link View#LAYOUT_DIRECTION_RTL} if the layout direction is RTL or returns |
| 440 | * {@link View#LAYOUT_DIRECTION_LTR} if the layout direction is not RTL. |
Fabrice Di Meglio | 9dd4c5c | 2013-02-08 18:15:07 -0800 | [diff] [blame] | 441 | */ |
| 442 | public int getLayoutDirection(); |
| 443 | |
| 444 | /** |
| 445 | * Tells if this view parent can resolve the text direction. |
| 446 | * See {@link View#setTextDirection(int)} |
| 447 | * |
| 448 | * @return True if this view parent can resolve the text direction. |
Fabrice Di Meglio | 9dd4c5c | 2013-02-08 18:15:07 -0800 | [diff] [blame] | 449 | */ |
| 450 | public boolean canResolveTextDirection(); |
| 451 | |
| 452 | /** |
| 453 | * Tells if this view parent text direction is resolved. |
| 454 | * See {@link View#setTextDirection(int)} |
| 455 | * |
| 456 | * @return True if this view parent text direction is resolved. |
Fabrice Di Meglio | 9dd4c5c | 2013-02-08 18:15:07 -0800 | [diff] [blame] | 457 | */ |
| 458 | public boolean isTextDirectionResolved(); |
| 459 | |
| 460 | /** |
| 461 | * Return this view parent text direction. See {@link View#getTextDirection()} |
| 462 | * |
| 463 | * @return the resolved text direction. Returns one of: |
| 464 | * |
| 465 | * {@link View#TEXT_DIRECTION_FIRST_STRONG} |
| 466 | * {@link View#TEXT_DIRECTION_ANY_RTL}, |
| 467 | * {@link View#TEXT_DIRECTION_LTR}, |
| 468 | * {@link View#TEXT_DIRECTION_RTL}, |
| 469 | * {@link View#TEXT_DIRECTION_LOCALE} |
Fabrice Di Meglio | 9dd4c5c | 2013-02-08 18:15:07 -0800 | [diff] [blame] | 470 | */ |
| 471 | public int getTextDirection(); |
| 472 | |
| 473 | /** |
| 474 | * Tells if this view parent can resolve the text alignment. |
| 475 | * See {@link View#setTextAlignment(int)} |
| 476 | * |
| 477 | * @return True if this view parent can resolve the text alignment. |
Fabrice Di Meglio | 9dd4c5c | 2013-02-08 18:15:07 -0800 | [diff] [blame] | 478 | */ |
| 479 | public boolean canResolveTextAlignment(); |
| 480 | |
| 481 | /** |
| 482 | * Tells if this view parent text alignment is resolved. |
| 483 | * See {@link View#setTextAlignment(int)} |
| 484 | * |
| 485 | * @return True if this view parent text alignment is resolved. |
Fabrice Di Meglio | 9dd4c5c | 2013-02-08 18:15:07 -0800 | [diff] [blame] | 486 | */ |
| 487 | public boolean isTextAlignmentResolved(); |
| 488 | |
| 489 | /** |
| 490 | * Return this view parent text alignment. See {@link android.view.View#getTextAlignment()} |
| 491 | * |
| 492 | * @return the resolved text alignment. Returns one of: |
| 493 | * |
| 494 | * {@link View#TEXT_ALIGNMENT_GRAVITY}, |
| 495 | * {@link View#TEXT_ALIGNMENT_CENTER}, |
| 496 | * {@link View#TEXT_ALIGNMENT_TEXT_START}, |
| 497 | * {@link View#TEXT_ALIGNMENT_TEXT_END}, |
| 498 | * {@link View#TEXT_ALIGNMENT_VIEW_START}, |
| 499 | * {@link View#TEXT_ALIGNMENT_VIEW_END} |
Fabrice Di Meglio | 9dd4c5c | 2013-02-08 18:15:07 -0800 | [diff] [blame] | 500 | */ |
| 501 | public int getTextAlignment(); |
Adam Powell | 10ba277 | 2014-04-15 09:46:51 -0700 | [diff] [blame] | 502 | |
| 503 | /** |
| 504 | * React to a descendant view initiating a nestable scroll operation, claiming the |
| 505 | * nested scroll operation if appropriate. |
| 506 | * |
| 507 | * <p>This method will be called in response to a descendant view invoking |
| 508 | * {@link View#startNestedScroll(int)}. Each parent up the view hierarchy will be |
| 509 | * given an opportunity to respond and claim the nested scrolling operation by returning |
| 510 | * <code>true</code>.</p> |
| 511 | * |
| 512 | * <p>This method may be overridden by ViewParent implementations to indicate when the view |
| 513 | * is willing to support a nested scrolling operation that is about to begin. If it returns |
| 514 | * true, this ViewParent will become the target view's nested scrolling parent for the duration |
| 515 | * of the scroll operation in progress. When the nested scroll is finished this ViewParent |
| 516 | * will receive a call to {@link #onStopNestedScroll(View)}. |
| 517 | * </p> |
| 518 | * |
| 519 | * @param child Direct child of this ViewParent containing target |
| 520 | * @param target View that initiated the nested scroll |
| 521 | * @param nestedScrollAxes Flags consisting of {@link View#SCROLL_AXIS_HORIZONTAL}, |
| 522 | * {@link View#SCROLL_AXIS_VERTICAL} or both |
| 523 | * @return true if this ViewParent accepts the nested scroll operation |
| 524 | */ |
| 525 | public boolean onStartNestedScroll(View child, View target, int nestedScrollAxes); |
| 526 | |
| 527 | /** |
| 528 | * React to the successful claiming of a nested scroll operation. |
| 529 | * |
| 530 | * <p>This method will be called after |
| 531 | * {@link #onStartNestedScroll(View, View, int) onStartNestedScroll} returns true. It offers |
| 532 | * an opportunity for the view and its superclasses to perform initial configuration |
| 533 | * for the nested scroll. Implementations of this method should always call their superclass's |
| 534 | * implementation of this method if one is present.</p> |
| 535 | * |
| 536 | * @param child Direct child of this ViewParent containing target |
| 537 | * @param target View that initiated the nested scroll |
| 538 | * @param nestedScrollAxes Flags consisting of {@link View#SCROLL_AXIS_HORIZONTAL}, |
| 539 | * {@link View#SCROLL_AXIS_VERTICAL} or both |
| 540 | * @see #onStartNestedScroll(View, View, int) |
| 541 | * @see #onStopNestedScroll(View) |
| 542 | */ |
| 543 | public void onNestedScrollAccepted(View child, View target, int nestedScrollAxes); |
| 544 | |
| 545 | /** |
| 546 | * React to a nested scroll operation ending. |
| 547 | * |
| 548 | * <p>Perform cleanup after a nested scrolling operation. |
| 549 | * This method will be called when a nested scroll stops, for example when a nested touch |
| 550 | * scroll ends with a {@link MotionEvent#ACTION_UP} or {@link MotionEvent#ACTION_CANCEL} event. |
| 551 | * Implementations of this method should always call their superclass's implementation of this |
| 552 | * method if one is present.</p> |
| 553 | * |
| 554 | * @param target View that initiated the nested scroll |
| 555 | */ |
| 556 | public void onStopNestedScroll(View target); |
| 557 | |
| 558 | /** |
| 559 | * React to a nested scroll in progress. |
| 560 | * |
| 561 | * <p>This method will be called when the ViewParent's current nested scrolling child view |
| 562 | * dispatches a nested scroll event. To receive calls to this method the ViewParent must have |
| 563 | * previously returned <code>true</code> for a call to |
| 564 | * {@link #onStartNestedScroll(View, View, int)}.</p> |
| 565 | * |
| 566 | * <p>Both the consumed and unconsumed portions of the scroll distance are reported to the |
| 567 | * ViewParent. An implementation may choose to use the consumed portion to match or chase scroll |
| 568 | * position of multiple child elements, for example. The unconsumed portion may be used to |
| 569 | * allow continuous dragging of multiple scrolling or draggable elements, such as scrolling |
| 570 | * a list within a vertical drawer where the drawer begins dragging once the edge of inner |
| 571 | * scrolling content is reached.</p> |
| 572 | * |
| 573 | * @param target The descendent view controlling the nested scroll |
| 574 | * @param dxConsumed Horizontal scroll distance in pixels already consumed by target |
| 575 | * @param dyConsumed Vertical scroll distance in pixels already consumed by target |
| 576 | * @param dxUnconsumed Horizontal scroll distance in pixels not consumed by target |
| 577 | * @param dyUnconsumed Vertical scroll distance in pixels not consumed by target |
| 578 | */ |
| 579 | public void onNestedScroll(View target, int dxConsumed, int dyConsumed, |
| 580 | int dxUnconsumed, int dyUnconsumed); |
| 581 | |
| 582 | /** |
| 583 | * React to a nested scroll in progress before the target view consumes a portion of the scroll. |
| 584 | * |
| 585 | * <p>When working with nested scrolling often the parent view may want an opportunity |
| 586 | * to consume the scroll before the nested scrolling child does. An example of this is a |
| 587 | * drawer that contains a scrollable list. The user will want to be able to scroll the list |
| 588 | * fully into view before the list itself begins scrolling.</p> |
| 589 | * |
| 590 | * <p><code>onNestedPreScroll</code> is called when a nested scrolling child invokes |
| 591 | * {@link View#dispatchNestedPreScroll(int, int, int[], int[])}. The implementation should |
| 592 | * report how any pixels of the scroll reported by dx, dy were consumed in the |
| 593 | * <code>consumed</code> array. Index 0 corresponds to dx and index 1 corresponds to dy. |
| 594 | * This parameter will never be null. Initial values for consumed[0] and consumed[1] |
| 595 | * will always be 0.</p> |
| 596 | * |
| 597 | * @param target View that initiated the nested scroll |
| 598 | * @param dx Horizontal scroll distance in pixels |
| 599 | * @param dy Vertical scroll distance in pixels |
| 600 | * @param consumed Output. The horizontal and vertical scroll distance consumed by this parent |
| 601 | */ |
| 602 | public void onNestedPreScroll(View target, int dx, int dy, int[] consumed); |
| 603 | |
| 604 | /** |
| 605 | * Request a fling from a nested scroll. |
| 606 | * |
Adam Powell | b36e4f9 | 2014-05-01 10:23:33 -0700 | [diff] [blame] | 607 | * <p>This method signifies that a nested scrolling child has detected suitable conditions |
| 608 | * for a fling. Generally this means that a touch scroll has ended with a |
| 609 | * {@link VelocityTracker velocity} in the direction of scrolling that meets or exceeds |
| 610 | * the {@link ViewConfiguration#getScaledMinimumFlingVelocity() minimum fling velocity} |
| 611 | * along a scrollable axis.</p> |
| 612 | * |
Adam Powell | 10ba277 | 2014-04-15 09:46:51 -0700 | [diff] [blame] | 613 | * <p>If a nested scrolling child view would normally fling but it is at the edge of |
Adam Powell | b36e4f9 | 2014-05-01 10:23:33 -0700 | [diff] [blame] | 614 | * its own content, it can use this method to delegate the fling to its nested scrolling |
| 615 | * parent instead. The parent may optionally consume the fling or observe a child fling.</p> |
Adam Powell | 10ba277 | 2014-04-15 09:46:51 -0700 | [diff] [blame] | 616 | * |
| 617 | * @param target View that initiated the nested scroll |
Adam Powell | b72be59 | 2014-07-16 21:41:31 -0700 | [diff] [blame] | 618 | * @param velocityX Horizontal velocity in pixels per second |
Adam Powell | 10ba277 | 2014-04-15 09:46:51 -0700 | [diff] [blame] | 619 | * @param velocityY Vertical velocity in pixels per second |
Adam Powell | b36e4f9 | 2014-05-01 10:23:33 -0700 | [diff] [blame] | 620 | * @param consumed true if the child consumed the fling, false otherwise |
| 621 | * @return true if this parent consumed or otherwise reacted to the fling |
Adam Powell | 10ba277 | 2014-04-15 09:46:51 -0700 | [diff] [blame] | 622 | */ |
Adam Powell | b36e4f9 | 2014-05-01 10:23:33 -0700 | [diff] [blame] | 623 | public boolean onNestedFling(View target, float velocityX, float velocityY, boolean consumed); |
Adam Powell | b72be59 | 2014-07-16 21:41:31 -0700 | [diff] [blame] | 624 | |
| 625 | /** |
| 626 | * React to a nested fling before the target view consumes it. |
| 627 | * |
| 628 | * <p>This method siginfies that a nested scrolling child has detected a fling with the given |
| 629 | * velocity along each axis. Generally this means that a touch scroll has ended with a |
| 630 | * {@link VelocityTracker velocity} in the direction of scrolling that meets or exceeds |
| 631 | * the {@link ViewConfiguration#getScaledMinimumFlingVelocity() minimum fling velocity} |
| 632 | * along a scrollable axis.</p> |
| 633 | * |
| 634 | * <p>If a nested scrolling parent is consuming motion as part of a |
| 635 | * {@link #onNestedPreScroll(View, int, int, int[]) pre-scroll}, it may be appropriate for |
| 636 | * it to also consume the pre-fling to complete that same motion. By returning |
| 637 | * <code>true</code> from this method, the parent indicates that the child should not |
| 638 | * fling its own internal content as well.</p> |
| 639 | * |
| 640 | * @param target View that initiated the nested scroll |
| 641 | * @param velocityX Horizontal velocity in pixels per second |
| 642 | * @param velocityY Vertical velocity in pixels per second |
| 643 | * @return true if this parent consumed the fling ahead of the target view |
| 644 | */ |
| 645 | public boolean onNestedPreFling(View target, float velocityX, float velocityY); |
Adam Powell | b6ab098 | 2015-01-07 17:00:12 -0800 | [diff] [blame] | 646 | |
| 647 | /** |
| 648 | * React to an accessibility action delegated by a target descendant view before the target |
| 649 | * processes it. |
| 650 | * |
| 651 | * <p>This method may be called by a target descendant view if the target wishes to give |
| 652 | * a view in its parent chain a chance to react to the event before normal processing occurs. |
| 653 | * Most commonly this will be a scroll event such as |
| 654 | * {@link android.view.accessibility.AccessibilityNodeInfo#ACTION_SCROLL_FORWARD}. |
| 655 | * A ViewParent that supports acting as a nested scrolling parent should override this |
| 656 | * method and act accordingly to implement scrolling via accesibility systems.</p> |
| 657 | * |
| 658 | * @param target The target view dispatching this action |
| 659 | * @param action Action being performed; see |
| 660 | * {@link android.view.accessibility.AccessibilityNodeInfo} |
| 661 | * @param arguments Optional action arguments |
| 662 | * @return true if the action was consumed by this ViewParent |
| 663 | */ |
| 664 | public boolean onNestedPrePerformAccessibilityAction(View target, int action, Bundle arguments); |
Tiger Huang | 2b210c2 | 2019-03-18 21:21:26 +0800 | [diff] [blame] | 665 | |
| 666 | /** |
| 667 | * Given a touchable region of a child, this method reduces region by the bounds of all views on |
| 668 | * top of the child for which {@link View#canReceivePointerEvents} returns {@code true}. This |
| 669 | * applies recursively for all views in the view hierarchy on top of this one. |
| 670 | * |
| 671 | * @param touchableRegion The touchable region we want to modify. |
| 672 | * @param view A child view of this ViewGroup which indicates the z-order of the touchable |
| 673 | * region. |
| 674 | * @hide |
| 675 | */ |
| 676 | default void subtractObscuredTouchableRegion(Region touchableRegion, View view) { |
| 677 | } |
Arthur Hung | 5d01978 | 2019-11-06 19:42:44 +0800 | [diff] [blame] | 678 | |
| 679 | /** |
| 680 | * Unbuffered dispatch has been requested by a child of this view parent. |
| 681 | * This method is called by the View hierarchy to signal ancestors that a View needs to |
| 682 | * request unbuffered dispatch. |
| 683 | * |
| 684 | * @see View#requestUnbufferedDispatch(int) |
| 685 | * @hide |
| 686 | */ |
| 687 | default void onDescendantUnbufferedRequested() { |
| 688 | if (getParent() != null) { |
| 689 | getParent().onDescendantUnbufferedRequested(); |
| 690 | } |
| 691 | } |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 692 | } |