[ff-cvs] libvob/doc/pegboard/animation_api--mudyc peg.rst

[Matti Katila]

CVSROOT:        /cvsroot/libvob
Module name:    libvob
Branch:         
Changes by:     Matti Katila <address@hidden>   03/10/10 14:15:15

Modified files:
        doc/pegboard/animation_api--mudyc: peg.rst 

Log message:
        benja\'s comments and discussion of the interface

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/libvob/libvob/doc/pegboard/animation_api--mudyc/peg.rst.diff?tr1=1.4&tr2=1.5&r1=text&r2=text

Patches:
Index: libvob/doc/pegboard/animation_api--mudyc/peg.rst
diff -u libvob/doc/pegboard/animation_api--mudyc/peg.rst:1.4 
libvob/doc/pegboard/animation_api--mudyc/peg.rst:1.5
--- libvob/doc/pegboard/animation_api--mudyc/peg.rst:1.4        Fri Oct 10 
07:05:48 2003
+++ libvob/doc/pegboard/animation_api--mudyc/peg.rst    Fri Oct 10 14:15:15 2003
@@ -5,42 +5,45 @@
 
 :Authors:  mudyc
 :Date-Created: 2003-09-27
-:Last-Modified: $Date: 2003/10/10 11:05:48 $
-:Revision: $Revision: 1.4 $
+:Last-Modified: $Date: 2003/10/10 18:15:15 $
+:Revision: $Revision: 1.5 $
 :Status:   Incomplete
 :Stakeholders: mudyc, tjl, benja, humppake
 :Scope:    Minor
 :Type:     Policy, Interface
 
 
-We have very powerful system for drawing in screen and making animations
-with it. In larger programs, where it's quite easy to write bugs, it's
-more than often when you missuse the current API. To make it easier to
-debug the animation and events, I propose  we make a new layer for 
+We have a very powerful system for drawing on the screen and animating.
+In larger programs, where it's quite easy to create bugs,
+the current API is misused more often. To make it easier to
+debug the animation and events, I propose that we make a new layer for 
 calling the animation routines.
 
-Instead of calling directly the: ::
+Instead of calling ::
 
     AbstractUpdateManager.chg()
 
-we should call a new api which can be switch to debug the caller, like: ::
+directly, let us have a new API which is told the caller of ``chg``,
+for debugging::
 
-    AnimationAPI.chg(String caller)
+    anim.chgAnimate("MouseEventHdl");
+
+where ``anim`` is an instance of ``AnimationAPI``.
 
 
 Issues
 ======
 
-ISSUE: How come we make sure that none other object call the public method 
+ISSUE: How can we make sure that none other object call the public method 
 AbstractUpdateManager.chg()?
 
    RESOLVED: Use the source, Luke. Yes, we have source and we can 
-   use the command `grep` to search trough source tree. After all, 
+   use the command ``grep`` to search trough source tree. After all, 
    this is easy to convert as a simple test.
 
 
 ISSUE: What about requesting a longer or shorter animation time, 
-or a non-standardanimation curve (i.e. linear instead of the 
+or a non-standard animation curve (i.e. linear instead of the 
 vibrating exponential)?
 Should this be covered by the animation API or bypassed to 
 AbstractUpdateManager? If there's a particular change that 
@@ -59,7 +62,7 @@
 should we hide some of its methods to package private?
 
     Small demos might still need these methods.
-    Otoh, safer the better. 
+    Otoh, the safer the better. 
 
 ISSUE: Should the default be to animate or not to animate?
 
@@ -70,11 +73,16 @@
 Changes
 =======
 
-We create a new animation layer which encapsulates 
+Create a new animation layer which encapsulates 
 AbstractUpdateManager method calls, i.e, chg() and setNoAnimation().
-The new layer is also the only one that takes care of reusing VobScenes.
-*No other objects are allowed to call these methods in 
-the source tree, except small demos.*
+The new layer will be the only one that takes care of reusing VobScenes.
+**No other objects are allowed to call the UpdateManager methods in 
+the source tree, except small demos.**
+
+XXX Sometimes when regeneratingVS, you need to be sure that 
+update has happen!
+    - Can new event be handler before new VobScene is created?!
+
 
 Let's define the following interface: ::
 
@@ -101,49 +109,30 @@
      */
     public interface AnimationAPI {
 
-       /** Set the update method in next change to reuse 
-         * of the previous vobscene.
-         * There's no animation between this and next frame, 
-         * only coordinate parameter changes are notable, 
-         * which indeed can also be like animation. 
-         * <p>
-         * If the update is set with other update set method after this set but
-         * before change, this set is obsoleted.
-         */
-       void reuseVS(String caller);
-
-
-       /** Set the update method in next change to animation/interpolation 
-         * action between vobmatcher keys
-         * <p>
-         * If the update is set with other update set method after this set but
-         * before change, this set is obsoleted.
-         * @see VobMatcher
-         */
-        void animate(String caller);
 
-       
-       /** Change to next frame.
-         * Throws an Error if no update method set.
+        /** Animate to next VobScene by creating a new VobScene.
          */
-        void chg(String caller);
+        void animate();
 
 
-       /** Shorthand for methods <code>reuseVS</code> and 
-         * instant <code>chg</code>.
+        /** Switch to next VobScene by creating a new VobScene.
+         * The switch is fast and no animation is seen.
          */
-        void chgReusingVS(String caller);
+        void switchVS();
 
-       /** Shorthand for methods <code>animation</code> and 
-         * instant <code>chg</code>.
-         */
-        void chgWithAnimation(String caller);
 
+        /** Rerender the current VobScene.
+         */
+        void rerender();
+ 
 
        /** Get the current visible vobscene. 
          * While programming, you are creating vobscene
          * for future usually, so this returns the obivious previous 
          * vobscene, e.g., to set coordinate system parameters.
          */
-        VobScene getLastVS();
+        VobScene getCurrentVS();
+
     } 
+
+