[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Fenfire-dev] ReReRePost: PEG animation_api--mudyc
From: |
Tuomas Lukka |
Subject: |
Re: [Fenfire-dev] ReReRePost: PEG animation_api--mudyc |
Date: |
Sun, 26 Oct 2003 10:21:43 +0200 |
User-agent: |
Mutt/1.5.4i |
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