Re: [Fenfire-dev] ReReRePost: PEG animation_api--mudyc

[Tuomas Lukka]

We're nearly there!

On Sat, Oct 25, 2003 at 05:33:25PM +0300, Matti Katila wrote:
> Let's define the following interface: ::
> 
>     package org.nongnu.libvob;
>     import org.nongnu.libvob.VobScene;
> 
>     /** An interface for providing common tool set for animation 
>      *  and animation debugging information.
>      *  This interface encapsulates the low-level animation interface
>      *  such as AbstractUpdateManagers' chg and setNoAnimation methods. 
>      * <p>
>      *  This interface sets strict policy for several routines:
>      * <ol><li>
>      *      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>
>      *      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>
>      * <p>
>      *  Methods <code>animate</code> , <code>switchVS</code> and 
>      *  <code>rerender</code> are pending state methods, i.e., 
>      *  the time when the operation of the method is accomplished 
>      *  is (undetermined) soon but not immediately. 
>      */
>     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.
>          * This method is pending, i.e., next screen update is soon 
>          * but not immediately.
>          * <p> 
>          * Animation between scenes is done between keys, i.e., key "A" in 
>          * current visible scene will animate to where 
>          * key "A" is in scene in future.
>          *
>          * @see AbstractUpdateManager
>          * @see VobMatcher
>          * <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

Urrh - remember the coding convention, which is especially important
in this context: from this code, no-one can know what "animation" should be.
If you name it "windowAnimation", and the attribute likewise, the example
will be much clearer.

I think though I'd prefer this example in the main javadoc, and for it to
have examples of all the methods of WindowAnimation.


>          *              self.keyHit = 0
>        *              self.left = 100
>        *              self.right = 500
>        *          def scene(self, vs):
>        *              if self.keyHit == 0:
>        *                  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();
> 
> 
>         /** Switch to next VobScene by creating a new VobScene.
>          * The switch is fast and no animation is seen. 
>          * This method is pending, i.e., next screen update is soon 
>          * but not immediately.
>          */
>         void switchVS();

You should say in the javadocs of this method as well that this
only schedules the update.


>         /** Rerender the current VobScene. 
>          * This method is pending, i.e., next screen update is soon 
>          * but not immediately.
>          * <p>
>          * Changes in next frame are seen if coordinate system
>          * parameters are set. Rerendering the current VobScene 
>          * is much faster than creating a new VobScene, 
>          * so e.g., any drag actions should be implemented to use
>          * this method. 
>        * <p>
>          * 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
>          * undefined behauviour.
>        * @see VobCoorder
>          */
>         void rerender();
>  
> 
>       /** Get the current visible vobscene. 
>          * <p>
>          * 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 there are pending methods that 
>          * create a new VobScene which has not yet been updated
>          * within window. The methods that create a new VobScene
>          * are <code>animate</code> and <code>switchVS</code>.
>          * <p>
>          * 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 to move some new vob you
>          * you need to pass all events trough before the screen has updated.
>        */
>       boolean hasPendingVS();

This name "hasPendingVS" is really bad, I think. 
What is the "Pending VS"? How can I get it?
I think you have maybe misunderstood the meaning of the word "pending".

I'd suggest "isUpdatePending()".

And an example of its use (in the main javadoc) is quite vital, I think.

        Tuomas