Home | History | Annotate | Download | only in view
      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 
     19 import android.graphics.Rect;
     20 import android.view.accessibility.AccessibilityEvent;
     21 
     22 /**
     23  * Defines the responsibilities for a class that will be a parent of a View.
     24  * This is the API that a view sees when it wants to interact with its parent.
     25  *
     26  */
     27 public interface ViewParent {
     28     /**
     29      * Called when something has changed which has invalidated the layout of a
     30      * child of this view parent. This will schedule a layout pass of the view
     31      * tree.
     32      */
     33     public void requestLayout();
     34 
     35     /**
     36      * Indicates whether layout was requested on this view parent.
     37      *
     38      * @return true if layout was requested, false otherwise
     39      */
     40     public boolean isLayoutRequested();
     41 
     42     /**
     43      * Called when a child wants the view hierarchy to gather and report
     44      * transparent regions to the window compositor. Views that "punch" holes in
     45      * the view hierarchy, such as SurfaceView can use this API to improve
     46      * performance of the system. When no such a view is present in the
     47      * hierarchy, this optimization in unnecessary and might slightly reduce the
     48      * view hierarchy performance.
     49      *
     50      * @param child the view requesting the transparent region computation
     51      *
     52      */
     53     public void requestTransparentRegion(View child);
     54 
     55     /**
     56      * All or part of a child is dirty and needs to be redrawn.
     57      *
     58      * @param child The child which is dirty
     59      * @param r The area within the child that is invalid
     60      */
     61     public void invalidateChild(View child, Rect r);
     62 
     63     /**
     64      * All or part of a child is dirty and needs to be redrawn.
     65      *
     66      * <p>The location array is an array of two int values which respectively
     67      * define the left and the top position of the dirty child.</p>
     68      *
     69      * <p>This method must return the parent of this ViewParent if the specified
     70      * rectangle must be invalidated in the parent. If the specified rectangle
     71      * does not require invalidation in the parent or if the parent does not
     72      * exist, this method must return null.</p>
     73      *
     74      * <p>When this method returns a non-null value, the location array must
     75      * have been updated with the left and top coordinates of this ViewParent.</p>
     76      *
     77      * @param location An array of 2 ints containing the left and top
     78      *        coordinates of the child to invalidate
     79      * @param r The area within the child that is invalid
     80      *
     81      * @return the parent of this ViewParent or null
     82      */
     83     public ViewParent invalidateChildInParent(int[] location, Rect r);
     84 
     85     /**
     86      * Returns the parent if it exists, or null.
     87      *
     88      * @return a ViewParent or null if this ViewParent does not have a parent
     89      */
     90     public ViewParent getParent();
     91 
     92     /**
     93      * Called when a child of this parent wants focus
     94      *
     95      * @param child The child of this ViewParent that wants focus. This view
     96      *        will contain the focused view. It is not necessarily the view that
     97      *        actually has focus.
     98      * @param focused The view that is a descendant of child that actually has
     99      *        focus
    100      */
    101     public void requestChildFocus(View child, View focused);
    102 
    103     /**
    104      * Tell view hierarchy that the global view attributes need to be
    105      * re-evaluated.
    106      *
    107      * @param child View whose attributes have changed.
    108      */
    109     public void recomputeViewAttributes(View child);
    110 
    111     /**
    112      * Called when a child of this parent is giving up focus
    113      *
    114      * @param child The view that is giving up focus
    115      */
    116     public void clearChildFocus(View child);
    117 
    118     /**
    119      * Compute the visible part of a rectangular region defined in terms of a child view's
    120      * coordinates.
    121      *
    122      * <p>Returns the clipped visible part of the rectangle <code>r</code>, defined in the
    123      * <code>child</code>'s local coordinate system. <code>r</code> is modified by this method to
    124      * contain the result, expressed in the global (root) coordinate system.</p>
    125      *
    126      * <p>The resulting rectangle is always axis aligned. If a rotation is applied to a node in the
    127      * View hierarchy, the result is the axis-aligned bounding box of the visible rectangle.</p>
    128      *
    129      * @param child A child View, whose rectangular visible region we want to compute
    130      * @param r The input rectangle, defined in the child coordinate system. Will be overwritten to
    131      * contain the resulting visible rectangle, expressed in global (root) coordinates
    132      * @param offset The input coordinates of a point, defined in the child coordinate system.
    133      * As with the <code>r</code> parameter, this will be overwritten to contain the global (root)
    134      * coordinates of that point.
    135      * A <code>null</code> value is valid (in case you are not interested in this result)
    136      * @return true if the resulting rectangle is not empty, false otherwise
    137      */
    138     public boolean getChildVisibleRect(View child, Rect r, android.graphics.Point offset);
    139 
    140     /**
    141      * Find the nearest view in the specified direction that wants to take focus
    142      *
    143      * @param v The view that currently has focus
    144      * @param direction One of FOCUS_UP, FOCUS_DOWN, FOCUS_LEFT, and FOCUS_RIGHT
    145      */
    146     public View focusSearch(View v, int direction);
    147 
    148     /**
    149      * Change the z order of the child so it's on top of all other children.
    150      * This ordering change may affect layout, if this container
    151      * uses an order-dependent layout scheme (e.g., LinearLayout). Prior
    152      * to {@link android.os.Build.VERSION_CODES#KITKAT} this
    153      * method should be followed by calls to {@link #requestLayout()} and
    154      * {@link View#invalidate()} on this parent to force the parent to redraw
    155      * with the new child ordering.
    156      *
    157      * @param child The child to bring to the top of the z order
    158      */
    159     public void bringChildToFront(View child);
    160 
    161     /**
    162      * Tells the parent that a new focusable view has become available. This is
    163      * to handle transitions from the case where there are no focusable views to
    164      * the case where the first focusable view appears.
    165      *
    166      * @param v The view that has become newly focusable
    167      */
    168     public void focusableViewAvailable(View v);
    169 
    170     /**
    171      * Bring up a context menu for the specified view or its ancestors.
    172      *
    173      * <p>In most cases, a subclass does not need to override this.  However, if
    174      * the subclass is added directly to the window manager (for example,
    175      * {@link ViewManager#addView(View, android.view.ViewGroup.LayoutParams)})
    176      * then it should override this and show the context menu.</p>
    177      *
    178      * @param originalView The source view where the context menu was first invoked
    179      * @return true if a context menu was displayed
    180      */
    181     public boolean showContextMenuForChild(View originalView);
    182 
    183     /**
    184      * Have the parent populate the specified context menu if it has anything to
    185      * add (and then recurse on its parent).
    186      *
    187      * @param menu The menu to populate
    188      */
    189     public void createContextMenu(ContextMenu menu);
    190 
    191     /**
    192      * Start an action mode for the specified view.
    193      *
    194      * <p>In most cases, a subclass does not need to override this. However, if the
    195      * subclass is added directly to the window manager (for example,
    196      * {@link ViewManager#addView(View, android.view.ViewGroup.LayoutParams)})
    197      * then it should override this and start the action mode.</p>
    198      *
    199      * @param originalView The source view where the action mode was first invoked
    200      * @param callback The callback that will handle lifecycle events for the action mode
    201      * @return The new action mode if it was started, null otherwise
    202      */
    203     public ActionMode startActionModeForChild(View originalView, ActionMode.Callback callback);
    204 
    205     /**
    206      * This method is called on the parent when a child's drawable state
    207      * has changed.
    208      *
    209      * @param child The child whose drawable state has changed.
    210      */
    211     public void childDrawableStateChanged(View child);
    212 
    213     /**
    214      * Called when a child does not want this parent and its ancestors to
    215      * intercept touch events with
    216      * {@link ViewGroup#onInterceptTouchEvent(MotionEvent)}.
    217      *
    218      * <p>This parent should pass this call onto its parents. This parent must obey
    219      * this request for the duration of the touch (that is, only clear the flag
    220      * after this parent has received an up or a cancel.</p>
    221      *
    222      * @param disallowIntercept True if the child does not want the parent to
    223      *            intercept touch events.
    224      */
    225     public void requestDisallowInterceptTouchEvent(boolean disallowIntercept);
    226 
    227     /**
    228      * Called when a child of this group wants a particular rectangle to be
    229      * positioned onto the screen.  {@link ViewGroup}s overriding this can trust
    230      * that:
    231      * <ul>
    232      *   <li>child will be a direct child of this group</li>
    233      *   <li>rectangle will be in the child's coordinates</li>
    234      * </ul>
    235      *
    236      * <p>{@link ViewGroup}s overriding this should uphold the contract:</p>
    237      * <ul>
    238      *   <li>nothing will change if the rectangle is already visible</li>
    239      *   <li>the view port will be scrolled only just enough to make the
    240      *       rectangle visible</li>
    241      * <ul>
    242      *
    243      * @param child The direct child making the request.
    244      * @param rectangle The rectangle in the child's coordinates the child
    245      *        wishes to be on the screen.
    246      * @param immediate True to forbid animated or delayed scrolling,
    247      *        false otherwise
    248      * @return Whether the group scrolled to handle the operation
    249      */
    250     public boolean requestChildRectangleOnScreen(View child, Rect rectangle,
    251             boolean immediate);
    252 
    253     /**
    254      * Called by a child to request from its parent to send an {@link AccessibilityEvent}.
    255      * The child has already populated a record for itself in the event and is delegating
    256      * to its parent to send the event. The parent can optionally add a record for itself.
    257      * <p>
    258      * Note: An accessibility event is fired by an individual view which populates the
    259      *       event with a record for its state and requests from its parent to perform
    260      *       the sending. The parent can optionally add a record for itself before
    261      *       dispatching the request to its parent. A parent can also choose not to
    262      *       respect the request for sending the event. The accessibility event is sent
    263      *       by the topmost view in the view tree.</p>
    264      *
    265      * @param child The child which requests sending the event.
    266      * @param event The event to be sent.
    267      * @return True if the event was sent.
    268      */
    269     public boolean requestSendAccessibilityEvent(View child, AccessibilityEvent event);
    270 
    271     /**
    272      * Called when a child view now has or no longer is tracking transient state.
    273      *
    274      * <p>"Transient state" is any state that a View might hold that is not expected to
    275      * be reflected in the data model that the View currently presents. This state only
    276      * affects the presentation to the user within the View itself, such as the current
    277      * state of animations in progress or the state of a text selection operation.</p>
    278      *
    279      * <p>Transient state is useful for hinting to other components of the View system
    280      * that a particular view is tracking something complex but encapsulated.
    281      * A <code>ListView</code> for example may acknowledge that list item Views
    282      * with transient state should be preserved within their position or stable item ID
    283      * instead of treating that view as trivially replaceable by the backing adapter.
    284      * This allows adapter implementations to be simpler instead of needing to track
    285      * the state of item view animations in progress such that they could be restored
    286      * in the event of an unexpected recycling and rebinding of attached item views.</p>
    287      *
    288      * <p>This method is called on a parent view when a child view or a view within
    289      * its subtree begins or ends tracking of internal transient state.</p>
    290      *
    291      * @param child Child view whose state has changed
    292      * @param hasTransientState true if this child has transient state
    293      */
    294     public void childHasTransientStateChanged(View child, boolean hasTransientState);
    295 
    296     /**
    297      * Ask that a new dispatch of {@link View#fitSystemWindows(Rect)
    298      * View.fitSystemWindows(Rect)} be performed.
    299      */
    300     public void requestFitSystemWindows();
    301 
    302     /**
    303      * Gets the parent of a given View for accessibility. Since some Views are not
    304      * exposed to the accessibility layer the parent for accessibility is not
    305      * necessarily the direct parent of the View, rather it is a predecessor.
    306      *
    307      * @return The parent or <code>null</code> if no such is found.
    308      */
    309     public ViewParent getParentForAccessibility();
    310 
    311     /**
    312      * Notifies a view parent that the accessibility state of one of its
    313      * descendants has changed and that the structure of the subtree is
    314      * different.
    315      * @param child The direct child whose subtree has changed.
    316      * @param source The descendant view that changed.
    317      * @param changeType A bit mask of the types of changes that occurred. One
    318      *            or more of:
    319      *            <ul>
    320      *            <li>{@link AccessibilityEvent#CONTENT_CHANGE_TYPE_CONTENT_DESCRIPTION}
    321      *            <li>{@link AccessibilityEvent#CONTENT_CHANGE_TYPE_SUBTREE}
    322      *            <li>{@link AccessibilityEvent#CONTENT_CHANGE_TYPE_TEXT}
    323      *            <li>{@link AccessibilityEvent#CONTENT_CHANGE_TYPE_UNDEFINED}
    324      *            </ul>
    325      */
    326     public void notifySubtreeAccessibilityStateChanged(View child, View source, int changeType);
    327 
    328     /**
    329      * Tells if this view parent can resolve the layout direction.
    330      * See {@link View#setLayoutDirection(int)}
    331      *
    332      * @return True if this view parent can resolve the layout direction.
    333      */
    334     public boolean canResolveLayoutDirection();
    335 
    336     /**
    337      * Tells if this view parent layout direction is resolved.
    338      * See {@link View#setLayoutDirection(int)}
    339      *
    340      * @return True if this view parent layout direction is resolved.
    341      */
    342     public boolean isLayoutDirectionResolved();
    343 
    344     /**
    345      * Return this view parent layout direction. See {@link View#getLayoutDirection()}
    346      *
    347      * @return {@link View#LAYOUT_DIRECTION_RTL} if the layout direction is RTL or returns
    348      * {@link View#LAYOUT_DIRECTION_LTR} if the layout direction is not RTL.
    349      */
    350     public int getLayoutDirection();
    351 
    352     /**
    353      * Tells if this view parent can resolve the text direction.
    354      * See {@link View#setTextDirection(int)}
    355      *
    356      * @return True if this view parent can resolve the text direction.
    357      */
    358     public boolean canResolveTextDirection();
    359 
    360     /**
    361      * Tells if this view parent text direction is resolved.
    362      * See {@link View#setTextDirection(int)}
    363      *
    364      * @return True if this view parent text direction is resolved.
    365      */
    366     public boolean isTextDirectionResolved();
    367 
    368     /**
    369      * Return this view parent text direction. See {@link View#getTextDirection()}
    370      *
    371      * @return the resolved text direction. Returns one of:
    372      *
    373      * {@link View#TEXT_DIRECTION_FIRST_STRONG}
    374      * {@link View#TEXT_DIRECTION_ANY_RTL},
    375      * {@link View#TEXT_DIRECTION_LTR},
    376      * {@link View#TEXT_DIRECTION_RTL},
    377      * {@link View#TEXT_DIRECTION_LOCALE}
    378      */
    379     public int getTextDirection();
    380 
    381     /**
    382      * Tells if this view parent can resolve the text alignment.
    383      * See {@link View#setTextAlignment(int)}
    384      *
    385      * @return True if this view parent can resolve the text alignment.
    386      */
    387     public boolean canResolveTextAlignment();
    388 
    389     /**
    390      * Tells if this view parent text alignment is resolved.
    391      * See {@link View#setTextAlignment(int)}
    392      *
    393      * @return True if this view parent text alignment is resolved.
    394      */
    395     public boolean isTextAlignmentResolved();
    396 
    397     /**
    398      * Return this view parent text alignment. See {@link android.view.View#getTextAlignment()}
    399      *
    400      * @return the resolved text alignment. Returns one of:
    401      *
    402      * {@link View#TEXT_ALIGNMENT_GRAVITY},
    403      * {@link View#TEXT_ALIGNMENT_CENTER},
    404      * {@link View#TEXT_ALIGNMENT_TEXT_START},
    405      * {@link View#TEXT_ALIGNMENT_TEXT_END},
    406      * {@link View#TEXT_ALIGNMENT_VIEW_START},
    407      * {@link View#TEXT_ALIGNMENT_VIEW_END}
    408      */
    409     public int getTextAlignment();
    410 }
    411