[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/24 05:09:48

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

Log message:
        example added, language fixes

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/libvob/libvob/doc/pegboard/animation_api--mudyc/peg.rst.diff?tr1=1.11&tr2=1.12&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.11 
libvob/doc/pegboard/animation_api--mudyc/peg.rst:1.12
--- libvob/doc/pegboard/animation_api--mudyc/peg.rst:1.11       Fri Oct 24 
03:17:10 2003
+++ libvob/doc/pegboard/animation_api--mudyc/peg.rst    Fri Oct 24 05:09:47 2003
@@ -5,8 +5,8 @@
 
 :Authors:  mudyc
 :Date-Created: 2003-09-27
-:Last-Modified: $Date: 2003/10/24 07:17:10 $
-:Revision: $Revision: 1.11 $
+:Last-Modified: $Date: 2003/10/24 09:09:47 $
+:Revision: $Revision: 1.12 $
 :Status:   Current
 :Stakeholders: mudyc, tjl, benja
 :Scope:    Minor
@@ -25,8 +25,8 @@
 
 directly, let us have a new API which is::
 
-    anim.animate() ,
-    anim.switchVS() or
+    anim.animate()
+    anim.switchVS()
     anim.rerenderVS()
 
 where ``anim`` is an instance of ``AnimationAPI``.
@@ -77,16 +77,25 @@
     'animation with time', '"animation" with very short time' or 'reuse
     VobScene'.
 
+ISSUE: What package should this interface be in?
+libvob.view doesn't feel right - this isn't a view. How about
+libvob proper?
 
-Current State
-=============
+    RESOLVED: The author of this PEG doesn't want to overload 
+    the count of files in org.nongnu.libvob but is satisfied 
+    if the author of libvob wants the interface to be in there.
+
+
+Introduction
+============
 
 We heavily use the ``demo framework`` in our applications, see
-vob.putil.demo. ``Demo framework`` basicly is libvob using one window.
+vob.putil.demo. ``Demo framework`` basicly is libvob using one window;
+including dynamic realoading of jython source and switching between demo 
scenes.
 One window is obivious to get more testing with 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
+The animation seen in the window is made with one or two VobScenes.
+Although, VobScene is very close to *one* window we have no interfaces
 to handle them per *one* window.
 
 This PEG tries to be a solution to provide an interface
@@ -107,20 +116,23 @@
 **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``.
+WindowAnimation should be implemented with java and 
+used in ``demo framework``.
 
 For safety of event handling, possibility to check if 
-VobScene has changed is added into the animation layer.
+VobScene has changed, i.e. screen has updated,
+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.
+on screen, all events before we have the correct 
+screen needs to be passed trough without handling.
 
+Implementations of WindowAnimation should print out stack
+traces when debugging is enabled, to allow the programmer
+to see how the updates were initiated.
 
 Let's define the following interface: ::
 
-    package org.nongnu.libvob.view;
+    package org.nongnu.libvob;
     import org.nongnu.libvob.VobScene;
 
     /** An interface for providing common tool set for animation 
@@ -130,23 +142,48 @@
      * <p>
      * 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 
+     *      The previously shown vobscene should not be stored 
+     *      anywhere else. 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.
      * </LI>
      * <LI>
-     *      There must not be objects that call low-level animation 
-     *      interface to change animation state. This could prevent
+     *      No other objects should call the low-level animation 
+     *      interface in AbstractUpdateManager. This could prevent
      *      proper animation, e.g., by setting no animation even when
      *      animation should be done.
      * </LI></OL>
      */
-    public interface AnimationAPI {
+    public interface WindowAnimation {
 
 
         /** Animate to next VobScene by creating a new VobScene.
+         * The interpolation time between current screen and VobScene
+        * (screen after animations) in future is set via AbstractUpdateManager.
+         * @see AbstractUpdateManager
+         * <p>
+         * Example: When you want to interpolate a red box from rigth to left
+         * you could do it, like:
+         * <pre>
+         *     class Scene:
+         *          """ Example scene to animate red box from left to rigth 
and backwards.
+        *          """
+        *          def __init__(self, animation):
+        *              self.anim = animation
+         *              self.keyHit = 0
+        *              self.left = 100
+        *              self.right = 500
+        *          def scene(self, vs):
+        *              if self.keyHit == 1:
+        *                  cs = vs.orthoBoxCS(0, "RedBox", 0,self.left,50, 
1,1, 100,100)
+        *              else:
+        *                  cs = vs.orthoBoxCS(0, "RedBox", 0,self.right,50, 
1,1, 100,100)
+         *              vs.put(vob.vobs.RectBgVob(java.awt.Color.red), cs)
+        *          def key(self, key):
+         *              self.keyHit = 1 - self.keyHit
+        *              self.anim.animate()
+         * </pre>
          */
         void animate();
 
@@ -164,7 +201,7 @@
          * so e.g., any drag actions should be implemented to use
          * this method. 
         * <p>
-         * Implementation notice:
+         * Implementation note:
          * Even though new coordinate systems can be created, the current 
          * coorder implementation uses finite range of coordinate systems. 
         * Creating too many new coordinate systems leads to
@@ -176,17 +213,18 @@
 
        /** Get the current visible vobscene. 
          * <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.
+         * Prgogramming note: When programming, you create vobscenes
+         * for future usually, so this returns the current visible
+         * vobscene, e.g., to set coordinate system parameters or 
+         * use activated coordinate systems to catch mouse events.
          */
         VobScene getCurrentVS();
 
 
-       /** Returns true if VobScene has changed from previous
+       /** Returns true if VobScene has changed since previous
          * <code>animate</code> or <code>switchVS</code> method.
          * <p>
-         * Programming notice: 
+         * Programming note: 
          * In some situations when handling the events the programmer 
          * 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