Layoutlib API: updated API for insert/move/remove child.

Also added some new SceneStatus enums.

Change-Id: I225c58201d81cb1109d1d533fea48b6eacb2e286

2 files changed, 92 insertions, 20 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();
     }
 
diff --git a/layoutlib_api/src/com/android/layoutlib/api/SceneResult.java b/layoutlib_api/src/com/android/layoutlib/api/SceneResult.java
index 57094ea..784bc29 100644
--- a/layoutlib_api/src/com/android/layoutlib/api/SceneResult.java
+++ b/layoutlib_api/src/com/android/layoutlib/api/SceneResult.java
@@ -30,6 +30,10 @@ public class SceneResult {
         NOT_IMPLEMENTED,
         ERROR_TIMEOUT,
         ERROR_LOCK_INTERRUPTED,
+        ERROR_INFLATION,
+        ERROR_NOT_INFLATED,
+        ERROR_RENDER,
+        ERROR_ANIM_NOT_FOUND,
         ERROR_UNKNOWN;
 
         /**
@@ -58,9 +62,7 @@ public class SceneResult {
      * the given message.
      */
     public SceneResult(String errorMessage) {
-        mStatus = SceneStatus.ERROR_UNKNOWN;
-        mErrorMessage = errorMessage;
-        mThrowable = null;
+        this(SceneStatus.ERROR_UNKNOWN, errorMessage, null);
     }
 
     /**
@@ -68,17 +70,47 @@ public class SceneResult {
      * the given message and {@link Throwable}
      */
     public SceneResult(String errorMessage, Throwable t) {
-        mStatus = SceneStatus.ERROR_UNKNOWN;
+        this(SceneStatus.ERROR_UNKNOWN, errorMessage, t);
+    }
+
+    /**
+     * Creates a {@link SceneResult} object with the given SceneStatus, and the given message
+     * and {@link Throwable}.
+     * <p>
+     * This should not be used to create {@link SceneResult} object with
+     * {@link SceneStatus#SUCCESS}. Use {@link SceneResult#SUCCESS} instead.
+     *
+     * @param status the status
+     */
+    public SceneResult(SceneStatus status, String errorMessage) {
+        this(status, errorMessage, null);
+    }
+
+    /**
+     * Creates a {@link SceneResult} object with the given SceneStatus, and the given message
+     * and {@link Throwable}
+     * <p>
+     * This should not be used to create {@link SceneResult} object with
+     * {@link SceneStatus#SUCCESS}. Use {@link SceneResult#SUCCESS} instead.
+     *
+     * @param status the status
+     */
+    public SceneResult(SceneStatus status, String errorMessage, Throwable t) {
+        assert status != SceneStatus.SUCCESS;
+        mStatus = status;
         mErrorMessage = errorMessage;
         mThrowable = t;
     }
 
     /**
-     * Creates a{@link SceneResult} object with the given SceneStatus.
+     * Creates a {@link SceneResult} object with the given SceneStatus.
+     * <p>
+     * This should not be used to create {@link SceneResult} object with
+     * {@link SceneStatus#SUCCESS}. Use {@link SceneResult#SUCCESS} instead.
      *
      * @param status the status
      */
-    private SceneResult(SceneStatus status) {
+    public SceneResult(SceneStatus status) {
         mStatus = status;
         mErrorMessage = null;
         mThrowable = null;