[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/23 16:15:54

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

Log message:
        add more language

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/libvob/libvob/doc/pegboard/animation_api--mudyc/peg.rst.diff?tr1=1.7&tr2=1.8&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.7 
libvob/doc/pegboard/animation_api--mudyc/peg.rst:1.8
--- libvob/doc/pegboard/animation_api--mudyc/peg.rst:1.7        Wed Oct 15 
06:02:49 2003
+++ libvob/doc/pegboard/animation_api--mudyc/peg.rst    Thu Oct 23 16:15:54 2003
@@ -5,8 +5,8 @@
 
 :Authors:  mudyc
 :Date-Created: 2003-09-27
-:Last-Modified: $Date: 2003/10/15 10:02:49 $
-:Revision: $Revision: 1.7 $
+:Last-Modified: $Date: 2003/10/23 20:15:54 $
+:Revision: $Revision: 1.8 $
 :Status:   Current
 :Stakeholders: mudyc, tjl, benja
 :Scope:    Minor
@@ -19,14 +19,15 @@
 debug the animation and events, I propose that we make a new layer for 
 calling the animation routines.
 
-Instead of calling ::
+Instead of calling::
 
     AbstractUpdateManager.chg()
 
-directly, let us have a new API which is told the caller of ``chg``,
-for debugging::
+directly, let us have a new API which is::
 
-    anim.animate("MouseEventHdl");
+    anim.animate() ,
+    anim.switchVS() or
+    anim.rerenderVS()
 
 where ``anim`` is an instance of ``AnimationAPI``.
 
@@ -50,6 +51,57 @@
     add this API within the demo framework but then it would be
     very hard to call from the java side.
 
+    RESOLVED: Issue can be solved in future because this PEG
+    still gives a plenty of room for handling it. 
+    Implementing the interfaace in demo framework also makes 
+    it much more easier to use than old way and increments readability
+    of source.
+
+
+ISSUE: What about requesting a longer or shorter animation time,
+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
+should happen with a faster animation time (e.g. a menu closing)
+
+    RESOLVED: Later. It's easy to add this feature into AnimationAPI:
+
+        a) when we know issues with it,
+        b) we have prototype of it and
+        c) we have used the prototype in real program.
+    
+    This PEG is not about substitute of AbstractUpdateManager.
+    This PEG is about handling one window and vobscenes close to it.
+
+
+ISSUE: Should the default be to animate or not to animate?
+
+    RESOLVED: Again, this is not about substitute of AbstractUpdateManager.
+    Although, chg method should not called directly we explicitly call
+    animation with time, "animation" with very short time or reuse of
+    VobScene.
+
+
+Current State
+=============
+
+We heavily use the ``demo framework`` in our applications, see
+vob.putil.demo. ``Demo framework`` basicly is libvob using one window.
+One window is obivious to get more testing of irregular edge.
+
+Animation seen in window is made with one or two VobScenes.
+Although, VobScene is very sticky with *one* window we have no interfaces
+to handle them per *one* window.
+
+This PEG tries to be a solution to provide an interface
+for handling VobScenes per *one* window instead of
+current UpdateManager which handles multiple windows.
+
+Currently we use AbstactUpdateManager directly from programs.
+This is bad thing 'cause of it can prevent proper animation, e.g., 
+by setting no animation even animation should be seen. 
+
 
 Changes
 =======
@@ -60,8 +112,16 @@
 **No other objects are allowed to call the above named UpdateManager 
 methods in the source tree, except small demos.**
 
+AnimationAPI should be implemented in ``demo framework``.
+
 For safety of event handling, possibility to check if 
 VobScene has changed is added into the animation layer.
+For example if we need to wait until something draws
+on screen, all events before that needs to be passed trough.
+
+Debugging of animation API should use java's stacktrace to 
+print correct lines and classes.
+
 
 Let's define the following interface: ::
 
@@ -73,31 +133,33 @@
      * This interface encapsulates the low-level animation interface
      * such as AbstractUpdateManagers' chg and setNoAnimation methods. 
      * <p>
-     * This interface sets strict policy for several routines.
-     *
-     *   1) There must not be other place to get previous/last 
+     * This interface sets strict policy for several routines:
+     * <OL><LI>
+     *      There must not be other place to get previous/last 
      *      VobScene. If a VobScene is saved in other place than 
      *      here, it could prevent the GC to clean old VobScenes.
      *      By using only the correct 'previous' VobScene
      *      program can not get the famous 'invalid coorsys' bug.
-     * 
-     *   2) There must not be objects that call low-level animation 
+     * </LI>
+     * <LI>
+     *      There must not be objects that call low-level animation 
      *      interface to change animation state. This could prevent
      *      proper animation, e.g., by setting no animation even when
      *      animation should be done.
+     * </LI></OL>
      */
     public interface AnimationAPI {
 
 
         /** Animate to next VobScene by creating a new VobScene.
          */
-        void animate(String caller);
+        void animate();
 
 
         /** Switch to next VobScene by creating a new VobScene.
          * The switch is fast and no animation is seen.
          */
-        void switchVS(String caller);
+        void switchVS();
 
 
         /** Rerender the current VobScene. 
@@ -107,17 +169,19 @@
          * so e.g., any drag actions should be implemented to use
          * this method. 
         * <p>
+         * Implementation notice:
          * Even though new coordinate systems can be created, the current 
-         * coorder implementation uses finite range of coordinate systems, 
-        * And creating too many new coordinate systems leads to
+         * coorder implementation uses finite range of coordinate systems. 
+        * Creating too many new coordinate systems leads to
          * undefined behauviour.
         * @see VobCoorder
          */
-        void rerender(String caller);
+        void rerender();
  
 
        /** Get the current visible vobscene. 
-         * When programming, you create vobscenes
+         * <p>
+         * Prgogramming notice: When programming, you create vobscenes
          * for future usually, so this returns the obivious previous 
          * vobscene, e.g., to set coordinate system parameters.
          */
@@ -125,9 +189,13 @@
 
 
        /** Returns true if VobScene has changed from previous
-         * <code> animate</code> or <code>switchVS</code> method.
+         * <code>animate</code> or <code>switchVS</code> method.
+         * <p>
+         * Programming notice: 
          * In some situations when handling the events the programmer 
-         * needs to know whether the VobScene is new or the still the old one.
+         * needs to know whether the VobScene is new or the still the old one,
+         * e.g., when waiting the screen to update to move some new vob you
+         * you need to pass all events trough before the screen has updated.
         */
        boolean hasVSchanged();
     }