1 files changed, 54 insertions, 14 deletions

diff --git a/layoutlib_api/src/com/android/layoutlib/api/LayoutScene.java b/layoutlib_api/src/com/android/layoutlib/api/LayoutScene.java
index 3429367..8c3d954 100644
--- a/layoutlib_api/src/com/android/layoutlib/api/LayoutScene.java
+++ b/layoutlib_api/src/com/android/layoutlib/api/LayoutScene.java
@@ -37,8 +37,18 @@ public class LayoutScene {
     public interface IAnimationListener {
         /**
          * Called when a new animation frame is available for display.
+         *
+         * <p>The {@link LayoutScene} object is provided as a convenience. It should be queried
+         * for the image through {@link LayoutScene#getImage()}.
+         *
+         * <p>If no {@link IImageFactory} is used, then each new animation frame will be rendered
+         * in its own new {@link BufferedImage} object. However if an image factory is used, and it
+         * always re-use the same object, then the image is only guaranteed to be valid during
+         * this method call. As soon as this method return the image content will be overridden
+         * with new drawing.
+         *
          */
-        void onNewFrame(BufferedImage image);
+        void onNewFrame(LayoutScene scene);
 
         /**
          * Called when the animation is done playing.
@@ -46,7 +56,7 @@ public class LayoutScene {
         void done(SceneResult result);
 
         /**
-         * Returns true if the animation is canceled.
+         * Return true to cancel the animation.
          */
         boolean isCanceled();
     }
@@ -61,6 +71,7 @@ public class LayoutScene {
     /**
      * Returns the {@link ViewInfo} object for the top level view.
      * <p>
+     *
      * This is reset to a new instance every time {@link #render()} is called and can be
      * <code>null</code> if the call failed (and the method returned a {@link SceneResult} with
      * {@link SceneStatus#ERROR_UNKNOWN} or {@link SceneStatus#NOT_IMPLEMENTED}.
@@ -145,44 +156,73 @@ public class LayoutScene {
     }
 
     /**
-     * Inserts a new child in a ViewGroup object.
+     * Inserts a new child in a ViewGroup object, and renders the result.
      * <p/>
-     * This does nothing more than change the layouy. To render the scene in its new state, a
-     * call to {@link #render()} is required.
+     * The child is first inflated and then added to its parent, before the given sibling.
+     * If the sibling is <code>null</code>, then it is added at the end of the ViewGroup.
      * <p/>
-     * Any amount of actions can be taken on the scene before {@link #render()} is called.
+     * If an animation listener is passed then the rendering is done asynchronously and the
+     * result is sent to the listener.
+     * If the listener is null, then the rendering is done synchronously.
+     *
+     * The child stays in the view hierarchy after the rendering is done. To remove it call
+     * {@link #removeChild(Object, int)}.
+     *
+     * @param parentView the parent View object to receive the new child.
+     * @param childXml an {@link IXmlPullParser} containing the content of the new child.
+     * @param beforeSibling the object in <var>parentView</var> to insert before. If
+     *             <code>null</code>, insert at the end.
+     * @param listener an optional {@link IAnimationListener}.
      *
      * @return a {@link SceneResult} indicating the status of the action.
      */
-    public SceneResult insertChild(Object parentView, IXmlPullParser childXml, int index) {
+    public SceneResult insertChild(Object parentView, IXmlPullParser childXml, Object beforeSibling,
+            IAnimationListener listener) {
         return NOT_IMPLEMENTED.getResult();
     }
 
     /**
-     * Inserts a new child in a ViewGroup object.
+     * Move a new child to a different ViewGroup object.
      * <p/>
-     * This does nothing more than change the layouy. To render the scene in its new state, a
-     * call to {@link #render()} is required.
+     * The child is first removed from its current parent, and then added to its new parent, before
+     * the given sibling. If the sibling is <code>null</code>, then it is added at the end
+     * of the ViewGroup.
      * <p/>
-     * Any amount of actions can be taken on the scene before {@link #render()} is called.
+     * If an animation listener is passed then the rendering is done asynchronously and the
+     * result is sent to the listener.
+     * If the listener is null, then the rendering is done synchronously.
+     *
+     * The child stays in the view hierarchy after the rendering is done. To remove it call
+     * {@link #removeChild(Object, int)}.
+     *
+     * @param parentView the parent View object to receive the child. Can be the current parent
+     *             already.
+     * @param childView the view to move.
+     * @param beforeSibling the object in <var>parentView</var> to insert before. If
+     *             <code>null</code>, insert at the end.
+     * @param listener an optional {@link IAnimationListener}.
      *
      * @return a {@link SceneResult} indicating the status of the action.
      */
-    public SceneResult moveChild(Object parentView, IXmlPullParser layoutParamsXml, int index) {
+    public SceneResult moveChild(Object parentView, Object childView, Object beforeSibling,
+            IAnimationListener listener) {
         return NOT_IMPLEMENTED.getResult();
     }
 
     /**
      * Removes a child from a ViewGroup object.
      * <p/>
-     * This does nothing more than change the layouy. To render the scene in its new state, a
+     * This does nothing more than change the layout. To render the scene in its new state, a
      * call to {@link #render()} is required.
      * <p/>
      * Any amount of actions can be taken on the scene before {@link #render()} is called.
      *
+     * @param childView the view object to remove from its parent
+     * @param listener an optional {@link IAnimationListener}.
+     *
      * @return a {@link SceneResult} indicating the status of the action.
      */
-    public SceneResult removeChild(Object parentView, int index) {
+    public SceneResult removeChild(Object childView, IAnimationListener listener) {
         return NOT_IMPLEMENTED.getResult();
     }