Document behavior and usage of ViewGroup.bringChildToFront()

A call to ViewGroup.bringChildToFront() or View.bringToFront()
(which delegates to the parent's bringChildToFront() method) needs
to be followed by a call to requestLayout() and invalidate() on the
parent container in order for the changes to
actually happen. That is, the order of the child views would change, but
the parent container would not run layout or even invalidation without
being told to, so there would be no visible change until something else
caused a layout and invalidation to occur.

This change clarifies this requirement in the javadocs.

Issue #8667065 bringtoTop does not work

Change-Id: Ibe41a6318dddf9fb79382e1c9fd1d21ab4510976

diff --git a/core/java/android/view/View.java b/core/java/android/view/View.java
index 11e392d..7259060 100644 (file)
--- a/core/java/android/view/View.java
+++ b/core/java/android/view/View.java
@@ -8696,7 +8696,12 @@ public class View implements Drawable.Callback, KeyEvent.Callback,
 
     /**
      * Change the view's z order in the tree, so it's on top of other sibling
-     * views
+     * views. This ordering change may affect layout, if the parent container
+     * uses an order-dependent layout scheme (e.g., LinearLayout). This
+     * method should be followed by calls to {@link #requestLayout()} and
+     * {@link View#invalidate()} on the parent.
+     *
+     * @see ViewGroup#bringChildToFront(View)
      */
     public void bringToFront() {
         if (mParent != null) {

diff --git a/core/java/android/view/ViewParent.java b/core/java/android/view/ViewParent.java
index 4b70bc0..d79aa7e 100644 (file)
--- a/core/java/android/view/ViewParent.java
+++ b/core/java/android/view/ViewParent.java
@@ -146,9 +146,13 @@ public interface ViewParent {
     public View focusSearch(View v, int direction);
 
     /**
-     * Change the z order of the child so it's on top of all other children
+     * Change the z order of the child so it's on top of all other children.
+     * This ordering change may affect layout, if this container
+     * uses an order-dependent layout scheme (e.g., LinearLayout). This
+     * method should be followed by calls to {@link #requestLayout()} and
+     * {@link View#invalidate()} on this parent.
      * 
-     * @param child
+     * @param child The child to bring to the top of the z order
      */
     public void bringChildToFront(View child);