[Gzz-commits] gzz/doc/pegboard/vob_considerations--benja peg.rst

[Benja Fallenstein]

CVSROOT:        /cvsroot/gzz
Module name:    gzz
Changes by:     Benja Fallenstein <address@hidden>      02/12/19 19:45:22

Modified files:
        doc/pegboard/vob_considerations--benja: peg.rst 

Log message:
        more

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/gzz/doc/pegboard/vob_considerations--benja/peg.rst.diff?tr1=1.2&tr2=1.3&r1=text&r2=text

Patches:
Index: gzz/doc/pegboard/vob_considerations--benja/peg.rst
diff -u gzz/doc/pegboard/vob_considerations--benja/peg.rst:1.2 
gzz/doc/pegboard/vob_considerations--benja/peg.rst:1.3
--- gzz/doc/pegboard/vob_considerations--benja/peg.rst:1.2      Fri Dec  6 
14:54:19 2002
+++ gzz/doc/pegboard/vob_considerations--benja/peg.rst  Thu Dec 19 19:45:22 2002
@@ -4,8 +4,8 @@
 
 :Author:       Benja Fallenstein
 :Date:         2002-12-07
-:Revision:     $Revision: 1.2 $
-:Last-Modified:        $Date: 2002/12/06 19:54:19 $
+:Revision:     $Revision: 1.3 $
+:Last-Modified:        $Date: 2002/12/20 00:45:22 $
 :Type:         Architecture
 :Scope:                Major
 :Status:       Incomplete
@@ -24,6 +24,12 @@
 .. contents::
 
 
+
+-------------------------
+History of the vob system
+-------------------------
+
+
 First stage: The 0.6 system
 ===========================
 
@@ -76,7 +82,7 @@
 ``Object`` is created statically in some class and used
 as the key whenever a vob is placed into a scene in that role.
 
-This is somewhat ugly, but arguably not much less so than alternatives
+This is somewhat ugly, but arguably less so than alternatives
 (like the "vob path" hack, which bears some resemblance
 to the role key phenomenon).
 
@@ -84,29 +90,33 @@
 Second stage: Coordinate systems
 ================================
 
-In the second stage, invented by Tuomas in Spring 2002, modified
+The second stage, introduced by Tuomas in Spring 2002, modified
 the system by introducing *coordinate systems*. A coordinate system
 is defined by a coordinate transformation (translation and scale
 or possibly a full affine transformation) relative to the canvas.
 It is coordinate systems that take identities (keys) in this system,
-not vobs. A vob is placed in one or more coordinate systems;
-cell vobs are placed in a single coordsys, connection vobs are
-placed between the two coordinate systems they connect.
-This system allowed the practical integration of connections
-into the vob system proper.
-
-In this system, vobs do not necessarily represent
-an object with an identity; those showing cells do, those
-showing connections don't (these vobs represent the relation
-between two different identities). Probably it can be said
-that some vobs in this pattern represent objects with
-identity; these vobs fill the corresponding coordsys with content
-(for example, the cell vobs fill the coordsys for that cell).
-Other vobs represent annotations to these objects; these do
-not fill a coordsys, but draw over or near to it
-(for example the connections, but possibly also a vob
-that shows a little icon right next to a cell to indicate
-something about the cell).
+not vobs. 
+
+Because coordinate systems have identities and are interpolated
+between keyframes, vobs are now less overloaded: they can now be seen as
+graphical objects to be drawn in a coordinate system.
+
+The most important effect of this change is that it allows
+a single Vob to span two coordinate systems. The earlier system
+allowed animation of connections between vobs only in a kludgy
+way. The new system allows the connection vob to know both
+its start and end coordinate system and trivially draw itself
+from point A in coordsys 1 to point B in coordsys 2.
+
+However, while a vob is now just a graphical object without identity,
+some vobs are still drawn to show an object with identity, while
+others are drawn as 'decorations' showing additional information
+about those objects. For example, a vob that shows a cell
+is drawn to represent that cell to the user, while a vob showing
+a little icon next to the cell (to indicate it is has changed recently,
+say) does not represent the cell itself to the user, but
+additional information about the cell (even though both
+may be placed into the same coordinate system, keyed by the cell).
 
 It is still basically assumed in this system that there
 is a set of identities, and each coordsys represents one member
@@ -144,9 +154,131 @@
 in the middle" works in a different way. We use role
 keys to represent this kind of thing.
 
-(Note: A coordsys c1 inside coordsys p1 is interpolated
-to c2 inside p2 if the keys of c1 and c2 are equal, and if
-p1 is interpolated to p2. This is somewhat similar
-to the vob paths from above.)
-
+[XXX Say something about interpolation hierarchies here?
+Maybe leave as a detail; we don't need to say everything
+in a 50k view...]
+
+
+
+--------
+Analysis
+--------
+
+
+Role keys
+=========
+
+Role keys are here to stay. This is because indeed they solve
+an important problem-- in a PUI scrollbar, when we've hit
+'PageDown,' how do we animate the box inside the scrollbar
+appropriately without knowing that the two vobs placed
+into the vob scenes before and after interpolation should be
+interpolated to each other? The box has no 'identity' except
+its role in the scrollbar.
+
+Unlike currently used, though, as often as possible role keys
+should be defined publicly in methodless Java interfaces
+(so that they can be shared between all classes that use them).
+In the PUI scrollbar example, we could have::
+
+    interface ScrollbarKeys {
+       Object BUTTON_UP_KEY = new Object(),
+              BUTTON_DOWN_KEY = new Object(),
+              DRAG_BOX_KEY = new Object();
+    }
+
+This would allow two independent scrollbar implementations,
+maybe from two differrent widget toolkits, to be interpolated
+to each other. This is what the vob system is all about:
+Interpolation between views that were not explicitly programmed
+to be interpolatable to each other.
+
+
+What do we think of as a vob?
+=============================
+
+All the time since stage one, a vob has been *a graphical object
+without accessible internal structure*. While in stage one,
+a vob was always associated with an identity, since stage two,
+you can think of it simply as an image transformed by
+a coordinate system; in both cases, though, a vob is a primitive
+you cannot 'look into.'
+
+If a vob (graphical object) has internal structure, this structure
+is not *reified*, that is, it is not accessible through the vob system.
+Consider a vob representing a cell in stage one, above; there may be
+a cell border, textual content (possibly broken over multiple lines),
+and a line cursor. There definitely is internal structure, but it is
+impossible to substitute, say, a different kind of line cursor
+on the vob system level, since it treats the whole cell vob as
+an indivisible entity.
+
+Hierarchical coordinate systems (stage three) attempt to solve
+this problem by modelling only the primitive graphical objects
+as vobs. A cell would be drawn by using a border vob, one or more
+text vobs, and a line vob to show the cursor. 
+
+But consider what we'd consider to be a 'vob' or 'visual object'
+as an application programmer. The paradigm is that we place
+'visual objects' on the screen by putting them into coordinate
+systems; how would we interpret this when programming, for example,
+a zzstructural view? -- It seems to me that the earlier stages
+match the expectations better: the 'visual objects' are the cells;
+what's inside them is simply of no concern.
+
+I think it is here that the current vob system errs. By only
+providing for atomic objects as vobs, it forces the
+application programmer into micromanagement. I believe that
+a better definition of vob would be *a graphical object
+with ignorable internal structure*: An object
+which can be safely treated as a unit, ignoring its internals,
+but can also be seen as a collection of things.
+
+I propose to make ``Vob`` an interface with a ``place`` method,
+putting the given vob into a coordinate system. Additionally,
+I propose a ``Renderable`` subclass of ``Vob`` which takes on
+the current meaning of ``Vob``: an indivisible graphical primitive.
+Only ``Renderable`` objects can be placed into a ``VobMap``,
+and this is what a default ``place`` implementation
+in ``Renderable`` does. A more complex ``Vob`` implementation
+could create new coordinate systems inside the coordsys
+given to its ``place`` method, putting other vobs into
+these sub-coordsys. A vob showing a cell could be implemented
+that way.
+
+.. uml:: vob_and_renderable
+
+    class Vob "interface"
+       methods
+           place(into)
+
+    class Renderable
+       inherit Vob
+
+    ---
+    vertically(50, foo, Vob, Renderable);
+
+(The naming is a little bit ironic, since in the first stage
+vob system, ``Flob``, the predecessor of ``Vob``, was
+a subclass of ``Renderable``. Yet, it fits the roles really well.)
+
+``Vob`` could become a superinterface of the current ``HBox``,
+which adds methods to request the size and baseline at a given scale.
+Indeed it could be useful to put requests for size information
+into ``Vob``, leaving only baseline requests to ``HBox`` ("``HVob``"?).
+This would bring the interface close to ``CellView``; it may even
+be possible to unify ``Vob`` and ``CellView``. These are details
+out of scope for this PEG, though.
+
+``Vob.place()`` should return the coordinate system given to it;
+this allows writing ::
+
+    box = vob.place(vs, vs.boxCS(cs, key, 250, 250, 50, 50))
+
+-- i.e., making the placement of a vob a one-liner,
+which it should really be (since it should be an atomic action
+in the application programmer's mind), without losing the coordsys
+the vob was placed into (``vs.matcher.getCS(key)`` only works
+for non-repeating views, i.e. views that never use
+the same key twice under any circumstances).