[Gzz-commits] libvob/doc/pegboard/buoydesign--tjl peg.rst

[Tuomas J. Lukka]

CVSROOT:        /cvsroot/libvob
Module name:    libvob
Branch:         
Changes by:     Tuomas J. Lukka <address@hidden>        03/08/08 10:17:56

Modified files:
        doc/pegboard/buoydesign--tjl: peg.rst 

Log message:
        The buoy manager geometry design

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

Patches:
Index: libvob/doc/pegboard/buoydesign--tjl/peg.rst
diff -u libvob/doc/pegboard/buoydesign--tjl/peg.rst:1.2 
libvob/doc/pegboard/buoydesign--tjl/peg.rst:1.3
--- libvob/doc/pegboard/buoydesign--tjl/peg.rst:1.2     Thu Apr 24 03:47:36 2003
+++ libvob/doc/pegboard/buoydesign--tjl/peg.rst Fri Aug  8 10:17:56 2003
@@ -3,27 +3,17 @@
 =============================================================
 
 :Author:   Tuomas J. Lukka
-:Last-Modified: $Date: 2003/04/24 07:47:36 $
-:Revision: $Revision: 1.2 $
+:Last-Modified: $Date: 2003/08/08 14:17:56 $
+:Revision: $Revision: 1.3 $
 :Status:   Incomplete
 
-Goals: get the xupdf and pp functionality under one model.
+This PEG attempts to define a flexible framework for FenPDF
+and related designs.
 
 
 Issues
 ======
 
-- How do we do non-regeneration of vobscenes on mouse events?
-
-    RESOLVED: Pass the old VobScene to the mouse event handler method
-    and use the boolean return value to determine whether
-    regeneration is needed.
-
-    This also fixes the idea that the *BuoyViewMainNode* is really a single
-    view in a single VobScene.
-
-- Should we let keystrokes also not-regenerate the vobscene?
-
 - Who creates the nodes? What about when a node contains a link 
   to itself? Are all nodes really the same?
 
@@ -143,8 +133,8 @@
     Link.c = TransclusionLink.c + o;
 
 
-Interfaces
-----------
+The Main Interfaces
+-------------------
 
 Now, the picture gets clearer: the whole structure of the current buoy view
 should be *defined* by a single facade:
@@ -168,6 +158,11 @@
        methods
            void link(int dir, int anchorCS, BuoyViewNodeType otherNode, Object 
linkId, Object otherAnchor)
 
+    class BuoyViewConnector "interface"
+       jlink
+       methods
+           void addBuoys(VobScene, BuoyViewMainNode, BuoyLinkListener)
+
     class BuoyViewMainNode "interface"
        jlink
        fields
@@ -184,16 +179,17 @@
            BuoyViewNodeType createMainNode(Object linkId, Object anchor, 
BuoyLinkListener l)
 
 
-    dep "calls" BuoyViewMainNode BuoyLinkListener
+    dep "calls" BuoyViewConnector BuoyLinkListener
     dep "use" RealBuoyViewManager BuoyViewNodeType
     dep "use" RealBuoyViewManager BuoyViewMainNode
+    dep "use" RealBuoyViewManager BuoyViewConnector
     dep "create" BuoyViewNodeType BuoyViewMainNode
 
     ---
 
-    vertically(60, zap, BuoyViewMainNode, BuoyViewNodeType);
+    vertically(60, zap, BuoyViewConnector, BuoyViewMainNode, BuoyViewNodeType);
     horizontally(100, foo, RealBuoyViewManager, zap);
-    vertically(140, bar, BuoyLinkListener, RealBuoyViewManager);
+    vertically(160, bar, BuoyLinkListener, RealBuoyViewManager);
 
 The linkId passed to BuoyLinkListener must be unique for each node 
 and the identifies the link -- it must be the same in both directions.
@@ -203,10 +199,12 @@
     // mainnode1's BuoyLinkListener set to l.
 
     mainnode1.renderMain(...);
+    connector.addBuoys(...);
     // l.link(d, *, nodetype2, L, A) got called as callback
 
     mainnode2 = nodetype2.createMainNode(L, A, l)
     mainnode2.renderMain(...);
+    connector.addBuoys(...);
     // l.link(-d, *, nodetype1, L, B) MUST GET CALLED
 
 Of course, if the underlying
@@ -227,17 +225,20 @@
     sequence CallBuoyManager
        call RealBuoyViewManager "render"
            call BuoyViewMainNodeA "renderMain"
+           call BuoyViewConnector "addBuoys"
                call RealBuoyViewManager "link(NodeTypeB)"
-                   call BuoyViewNodeTypeB "renderBuoy"
+           call BuoyViewNodeTypeB "renderBuoy"
        call RealBuoyViewManager "mouse"
            call BuoyViewNodeTypeB "createMainNode"
                create BuoyViewMainNodeB
        call RealBuoyViewManager "render"
            call BuoyViewMainNodeB "renderMain"
+           call BuoyViewConnector "addBuoys"
                call RealBuoyViewManager "link(NodeTypeA)"
-                   call BuoyViewNodeTypeA "renderBuoy"
+           call BuoyViewNodeTypeA "renderBuoy"
 
     seqobject RealBuoyViewManager
+    seqobject BuoyViewConnector
     seqobject BuoyViewNodeTypeA
     seqobject BuoyViewNodeTypeB
     seqobject BuoyViewMainNodeA
@@ -246,7 +247,7 @@
 
     ---
     RealBuoyViewManager.c = (0,0);
-    horizontally(100, foo, RealBuoyViewManager, BuoyViewNodeTypeA, 
+    horizontally(20, foo, RealBuoyViewManager, BuoyViewConnector, 
BuoyViewNodeTypeA, 
                BuoyViewMainNodeA, BuoyViewNodeTypeB,
                    BuoyViewMainNodeB.ghost);
 
@@ -259,167 +260,77 @@
 Its node type object is called to create the new focus object. Then, the 
 render pattern is repeated, but now with BuoyViewMainNodeB in the focus.
 
-The semi-pluggable implementation
----------------------------------
-
-In this implementation of the BuoyViewMainNode and BuoyViewNodeType interfaces,
-the node and link types are almost pluggable. There are naturally some 
problems with
-full pluggability, due to the bidirectionality of the links: some node types
-will only match some other node types, etc.
-
-As the main example, consider the above case with ZZ cell nodes, PP canvases
-and scrollblocks. The ZZ cell nodes and PP canvases are both in ZZstructure
-and use cellviews so they can be handled by the same linking managers,
-but the scrollblocks cannot.
-
-The following diagram shows the current arrangement, where
-the pluggability is handled through the interfaces
-CellBuoyViewNodeType (where the concrete cbvnodetypes
-create their respective mainnodes) and CellBuoyViewLinker.
-
-.. UML:: SemiPluggableBuoys
-
-    jlinkpackage org.nongnu.libvob.buoy
-
-    class BuoyViewNodeType "interface"
-       jlink
-
-    class BuoyViewMainNode "interface"
-       jlink
-
-    class BuoyLinkListener "interface"
-       jlink
-
-    class BuoyAdaptor
-       jlink
-       inherit BuoyViewNodeType
-       assoc multi(*) - multi(*) CellBuoyViewNodeType
-
-    class BuoyAdaptor.LinkAdaptor
-       jlink
-       inherit gzz.view.CellPlacementHook
-       assoc multi(*) - multi(1) BuoyAdaptor
-       assoc multi(*) - multi(1) BuoyLinkListener
-
-    class gzz.view.CellPlacementHook "interface"
-       jlink
-
-    class CellBuoyViewNodeType "interface"
-       jlink
-       methods
-           boolean ownsCell(Cell c)
-           void renderBuoy(VobScene vs, int into, Cell c)
-           BuoyViewMainNode createMainNode(Cell c, CellPlacementHook hook)
-
-    class CellBuoyViewLinker "interface"
-       jlink
-       methods
-           void doLinks(Cell c, VobScene vs, int cs, 
-                                   BuoyViewNodeType cellNodeType, 
-                                   BuoyLinkListener l);
+Varying geometries
+------------------
 
+It is possible (e.g., FenPDF has this) that different main nodees require 
+different geometries for the buoys.
 
+Let's list the design pressures:
 
-    class ConcreteNodeType "pseudo"
-       inherit CellBuoyViewNodeType
-    class ConcreteMainNode "pseudo"
-       inherit BuoyViewMainNode
+- The size of the area reserved for the buoy view has to be changeable easily
+  (e.g., in FenPDF, scrolling the separator)
 
+- The sizes and geometries should be set centrally, pluggably, not hardcoded
+  to the different view
 
-    dep "call" ConcreteMainNode gzz.view.CellPlacementHook
-    dep "call" BuoyAdaptor.LinkAdaptor CellBuoyViewLinker
-    dep "call" CellBuoyViewLinker BuoyLinkListener
+- The geometries depend on the main node type, but not on the content (at least
+  yet).
 
-    dep "create" ConcreteNodeType ConcreteMainNode
+- Different connectors should be able to have different buoy geometries 
(think, e.g.,
+  about normal structlink buoys in fenpdf vs. the treetime buoys)
 
-    ---
-    vertically(150, gazz, BuoyViewNodeType, BuoyViewMainNode, 
BuoyLinkListener);
-    vertically(60, foo, BuoyAdaptor, BuoyAdaptor.LinkAdaptor, 
gzz.view.CellPlacementHook);
-    vertically(300, cbv, CellBuoyViewNodeType, CellBuoyViewLinker);
-    vertically(60, conc, ConcreteNodeType, ConcreteMainNode);
+So, the solution is to provide the buoymanager different geometry managers, 
+multiplexed between main node types and buoy types.
+There are two different geometry managers, one for the main view and another
+for the buoys.
 
-    horizontally(20, groo, gazz, foo, cbv, conc);
+Both may be called two ways: to create the coordinate systems, or just to set
+the changed coordinates.
 
-    BuoyAdaptor.c = (0,0);
+Here's the geometer for the main views::
 
+    public interface BuoyMainViewGeometer {
+       /** Create or set the main coordinate system size.
+        * @param into The matching parent and parent, giving the rectangle into
+        *             which to place the cs.
+        * @param key The key to use for the returned coordinate system
+        *             in into. There may be others in between.
+        * @param create Whether to create the coordinate systems or just set 
parameters
+        *              in existing ones.
+        * @return The coordinate system into which to place the main view.
+        */
+       int mainCS(int into, Object key, boolean create);
+    }
 
-There are two different types of links that this part of the systme
-needs to know: Cell to Cell and Cell to PermaScroll.
-...
+And here's the geometer for the buoys::
 
-In the next diagram, the classes that implement the pagespan nodes 
-and their associations to the rest of the system are shown.
-The cellNodeType BuoyViewNodeType is the node type that is to be used
-for xanalogical links to cells.
+    public interface BuoyGeometer {
 
-..  UML:: PageSpanSemiPluggableBuoyNodes
+       /** Create any parameter coordinate systems depending on the surrounding
+        * rectangle. 
+        * This method **may** set state inside the BuoyGeometer.
+        * @param into The matching parent and parent, giving the rectangle in
+        *             which the whole buoyview and mainview are placed.
+        * @param create Whether to create the coordinate systems or just set 
parameters
+        *              in existing ones.
+        */
+       void prepare(int into, boolean create);
 
-    jlinkpackage org.nongnu.libvob.buoy
+       /** Create or set the main coordinate system size.
+        * @param into The matching parent and parent, giving the rectangle in
+        *             which the whole buoyview and mainview are placed.
+        * @param anchor The coordinate system of the anchor, or -1 if not 
applicable.
+        * @param key The key to use for the returned coordinate system
+        *             in into. There may be others in between.
+        * @param w,h The size requested for the buoy.
+        */
+       int buoyCS(int into, int anchor, Object key, float w, float h);
 
-    class CellBuoyViewLinker "interface"
-       jlink
-    class BuoyViewNodeType "interface"
-       jlink
-    class BuoyViewMainNode "interface"
-       jlink
-
-    class ScrollblockCellLinker
-       jlink
-       inherit CellBuoyViewLinker
-       assoc - multi(1) role(cellNodeType) BuoyViewNodeType
-
-    awhole = assoc ScrollblockCellLinker - multi(1) role(transclusionNodeType) 
WholePageSpanNodeType
-    aanchor = assoc ScrollblockCellLinker - multi(1) role(xulinkNodeType) 
AnchorPageSpanNodeType
-
-    class AbstractPageSpanNodeType "pyClass"
-       inherit BuoyViewNodeType
-       methods
-           createMainNode(linkId, anchorSpan, listener)
+    }
 
-    class WholePageSpanNodeType "pyClass"
-       inherit AbstractPageSpanNodeType
-    class AnchorPageSpanNodeType "pyClass"
-       inherit AbstractPageSpanNodeType
-    class PageSpanMainNode "pyClass"
-       inherit BuoyViewMainNode
 
-    dep "create" AbstractPageSpanNodeType PageSpanMainNode
 
-    ---
-
-    CellBuoyViewLinker.c = (0,0);
-
-    horizontally(80, inters, CellBuoyViewLinker, 
-                       BuoyViewNodeType, BuoyViewMainNode);
-    
-    horizontally(220, pspnt, WholePageSpanNodeType, AnchorPageSpanNodeType);
-
-    vertically(30, pspstuff, AbstractPageSpanNodeType, pspnt, 
PageSpanMainNode);
-
-    vertically(100, topi, CellBuoyViewLinker, ScrollblockCellLinker);
-
-    AbstractPageSpanNodeType.c = ScrollblockCellLinker.c + (100, -100);
-
-    awhole.p = ScrollblockCellLinker.c{left} .. WholePageSpanNodeType.c;
-    aanchor.p = ScrollblockCellLinker.c{right} .. AnchorPageSpanNodeType.c;
-
-As seen, ScrollblockCellLinker is the class implementing CellBuoyViewLinker,
-and when asked to make links for a given cell, it looks for both
-enfiladeoverlaps (transclusions) and xu links. Different types
-of pagespannodetypes are used for these: for transclusions seeing
-the whole original pagespan scrollblock is good, and for xu links,
-seeing only the anchor part of the target is good.
-
-Foo::
-
-    class PPCanvasNode
-       inherit CellBuoyViewNodeType
-
-    class PPCanvasCursor
-       fields
-           float x, y
-           float zoom
-       inherit BuoyViewMainNode
 
-    dep "create" PPCanvasNode PPCanvasCursor
 
+.. :vim set syntax=text: