Adding upstream version 1.0.2.upstream/1.0.2upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 490 insertions, 0 deletions

diff --git a/doc/architecture.txt b/doc/architecture.txt
new file mode 100644
index 0000000..961d960
--- /dev/null
+++ b/doc/architecture.txt
@@ -0,0 +1,490 @@
+Sodipodi internal architecture
+
+1. Overview
+
+The Sodipodi display and editing engine is built using the
+"Model-View-Controller" (MVC) paradigm.  Unlike "classic" MVC
+programs, we have further split model into two distinct layers,
+'backbone' and 'document'. This has proven to be extremely powerful
+technique, giving us clear and fast implementation, functional
+granularity and easy expandibility.
+
+1.1. Agnostic XML backbone
+
+The basis of the sodipodi document is its plain XML representation in
+memory. This is a tree-shaped structure, in which each node is
+represented by a lightweight typeless object (SPRepr). These objects
+implement a minimal interface of both control (methods) and mutation
+events (callbacks).  We use the term 'agnostic' for describing that
+part of model, to underline the typeless nature of SPRepr. More or
+less, this is just an XML file representation in memory.
+
+1.2. Typed SVG document
+
+The most actively used part of the sodipodi document model is the SVG
+object tree. This is constructed on top of the XML tree, and reacts to
+all mutation events in the agnostic tree, thus always keeping its
+internal state synchronized with the backbone. The opposite is not
+true - the XML backbone is not aware of the SVG object tree, and thus
+does not react to its modifications. If writeback to the backbone is
+needed, it must be requested explicitly by the controller.  The SVG
+tree is constructed of SPObject subclasses - in general there is one
+subclass for each SVG element type, plus abstract base classes.
+
+1.3. NRArena view
+
+NRarena is an abstract display engine that allows construction of
+'display caches' from NRArenaItem subclasses. These are lightweight,
+having only some basic object types, and used for most of the display
+needs of Sodipodi.  Both the editing window, and the bitmap export
+code create special NRArena instances, and ask the SVG document to
+show itself to the given NRArena.  There is a ::show virtual method,
+implemented by all visible object classes, that adds an NRArenaItem
+node to the display tree. The completed display cache is used for fast
+screen updates and stripe based bitmap exports.  During the NRArena
+lifetime SVG objects keep all of the display cache elements constantly
+updated, thus ensuring the display is always up to date.
+
+1.4. Controllers
+
+Like the model suggests, controllers can be implemented acting on
+different layers.  Which one is best depends on the type of action
+that the given controller performs. Usually very generic and
+single-shot operating controllers act on the SPRepr layer, while those
+providing visual feedback or tied to a certain object type act on the
+SPObject layer.
+
+
+
+2. Detailed view
+
+2.1. SPRepr
+
+The most basic SVG (XML) document backbone is implemented as an
+in-memory tree of SPRepr objects, each object corresponding to a
+single node in the XML file.  Currently there are only two types of
+SPReprs - normal element nodes and text nodes.  More types may be
+added in the future, but the structure will probably always remain
+much simpler (and faster) than DOM.
+
+SPRepr may have:
+- attributes (keyword/value) pairs
+- content (text)
+- child nodes
+
+Attribute values are textual, and no checks are performed in that
+layer to ensure document validity. Also, CSS style strings are
+unparsed in that layer.  The SPRepr tree is built during document
+loading or creation. As it is textual and always synchronized with the
+display, unfiltered saving involves just dumping it into a file.
+
+The basic API acting on SPRepr level is really spartan.
+
+SPRepr *sp_repr_new (const unsigned char *name)
+SPRepr *sp_repr_new_text (const unsigned char *content)
+SPRepr *sp_repr_ref (SPRepr *repr)
+SPRepr *sp_repr_unref (SPRepr *repr)
+SPRepr *sp_repr_duplicate (SPRepr *repr)
+
+int sp_repr_set_content (SPRepr *repr, const unsigned char *content)
+int sp_repr_set_attr (SPRepr *repr, const unsigned char *key, const unsigned char *value)
+int sp_repr_add_child (SPRepr *repr, SPRepr *child, SPRepr *ref)
+int sp_repr_remove_child (SPRepr *repr, SPRepr *child)
+int sp_repr_change_order (SPRepr *repr, SPRepr *child, SPRepr *ref)
+
+In addition there are some accessor methods and lot of convenience ones.
+
+Each SPRepr can have one or many event vectors associated with it.
+Event vector is a block of callback pointers for different kind of
+mutation events.
+
+void sp_repr_add_listener (SPRepr *repr, const SPReprEventVector *vector, void *data)
+void sp_repr_remove_listener_by_data (SPRepr *repr, void *data)
+
+struct _SPReprEventVector {
+        void (* destroy) (SPRepr *repr, gpointer data);
+        gboolean (* add_child) (SPRepr *repr, SPRepr *child, SPRepr *ref, gpointer data);
+        void (* child_added) (SPRepr *repr, SPRepr *child, SPRepr *ref, gpointer data);
+        gboolean (* remove_child) (SPRepr *repr, SPRepr *child, SPRepr *ref, gpointer data);
+        void (* child_removed) (SPRepr *repr, SPRepr *child, SPRepr *ref, gpointer data);
+        gboolean (* change_attr) (SPRepr *repr, const guchar *key, const guchar *oldval, const guchar *newval, gpointer data);
+        void (* attr_changed) (SPRepr *repr, const guchar *key, const guchar *oldval, const guchar *newval, gpointer data);
+        gboolean (* change_content) (SPRepr *repr, const guchar *oldcontent, const guchar *newcontent, gpointer data);
+        void (* content_changed) (SPRepr *repr, const guchar *oldcontent, const guchar *newcontent, gpointer data);
+        gboolean (* change_order) (SPRepr *repr, SPRepr *child, SPRepr *oldref, SPRepr *newref, gpointer data);
+        void (* order_changed) (SPRepr *repr, SPRepr *child, SPRepr *oldref, SPRepr *newref, gpointer data);
+}
+
+All events, except destroys (which are unconditional), have pre- and
+post- event callbacks.  The pre-event callback's return value is used to
+signal whether the given modification is allowed. If it is FALSE the
+operation will be cancelled and the invoking method will also return
+FALSE.  Using callbacks in block is much more convenient than adding
+them one-by-one, as the listening code usually wants to install several
+handlers at once, and the same set of handlers for many different
+nodes. NULL pointers are allowed in event vector.
+
+Although the most important functionality of the SPRepr tree is to
+serve as a document backbone, it has other functions besides
+that. SPReprs are also used to store preferences, the copy buffer and
+the undo stack.
+
+
+
+2.2. SPObject
+
+SPObject is an abstract base class of all of the document nodes at the
+SVG document level. Each SPObject subclass implements a certain SVG
+element node type, or is an abstract base class for different node
+types.  The SPObject layer is bound to the SPRepr layer, closely
+following the SPRepr mutations via callbacks.  During creation,
+SPObject parses and interprets all textual attributes and CSS style
+strings of the SPRepr, and later updates the internal state whenever
+it receives a signal about a change. The opposite is not true - there
+are methods manipulating SPObjects directly and such changes do not
+propagate to the SPRepr layer. This is important for implementation of
+the undo stack, animations and other features.
+
+SPObjects are bound to the higher-level container SPDocument, which
+provides document level functionality such as the undo stack,
+dictionary and so on.
+
+SPObjects are implemented using the Gtk object system (GObjects in gtk
+2 version), which provides an extremely powerful and flexible OO
+framework in pure C.
+
+SPObject class hierarchy
+
+SPObject ABSTRACT
+  SPObjectGroup ABSTRACT
+    SPNamedView <sodipodi:namedview>
+    SPClipPath <clipPath>
+  SPGuide <sodipodi:guide>
+  SPPaintServer ABSTRACT
+    SPGradient ABSTRACT
+      SPLinearGradient <linearGradient>
+      SPRadialGradient <radialGradient>
+    SPPattern <pattern>
+  SPDefs <defs>
+  SPItem ABSTRACT
+    SPGroup <g>
+      SPRoot <svg>
+      SPAnchor <a>
+  SPImage <image>
+  SPPath ABSTARCT
+    SPShape <path>
+      SPLine <line>
+      SPPolyLine <polyline>
+      SPPolygon <polygon>
+        SPStar <sodipodi:star>
+      SPRect <rect>
+      SPSpiral <sodipodi:spiral>
+      SPGenericEllipse ABSTRACT
+        SPCircle <circle>
+        SPEllipse <ellipse>
+	SPArc <sodipodi:arc>
+  SPChars ABSTRACT
+    SPString TEXT NODE
+  SPDefs <defs>
+  SPText <text>
+  SPTSpan <tspan>
+
+SPObject internals
+
+struct _SPObject {
+	GtkObject object;
+	unsigned int hrefcount;
+	SPDocument *document;
+	SPObject *parent;
+	SPObject *next;
+	SPRepr *repr;
+	unsigned char *id;
+	SPStyle *style;
+	const unsigned char *title;
+	const unsigned char *description;
+};
+
+The basic refcounting is handled by the parent class
+(GtkObject). Hrefcount is used for weak references, for example, to
+determine whether any graphical element references a certain gradient
+node.  The parent and next fields are used to establish the tree
+structure.  Id is copy of the SPRepr 'id' attribute for normal nodes,
+and is used as a unique index of all objects in the given document.
+
+Virtual methods
+
+/******** Disclaimer *******/
+This will change a lot in the future
+
+void ::build (SPObject *object, SPDocument *document, SPRepr *repr)
+
+This has to be invoked immediately after creation of an SPObject. The
+frontend method ensures that the new object is properly attached to
+the document and repr; implementation then will parse all of the attributes,
+generate the children objects and so on.  Invoking ::build on the SPRoot
+object results in creation of the whole document tree (this is, what
+SPDocument does after the creation of the XML tree).
+
+void ::release (SPObject *object)
+
+This is the opposite of ::build. It has to be invoked as soon as the
+object is removed from the tree, even if it is still alive according
+to reference count. The frontend unregisters the object from the
+document and releases the SPRepr bindings; implementations should free
+state data and release all child objects.  Invoking ::release on
+SPRoot destroys the whole document tree.
+
+void ::child_added (SPObject *object, SPRepr *child, SPRepr *ref)
+void ::remove_child (SPObject *object, SPRepr *child)
+void ::order_changed (SPObject *object, SPRepr *repr, SPRepr *oldref, SPRepr *newref)
+
+These are invoked whenever the given mutation event happens in the XML
+tree.  ::remove_child is invoked BEFORE removal from the XML tree
+happens, so grouping objects can safely release the child data.  The
+other two will be invoked AFTER the actual XML tree mutation.  Only
+grouping objects have to implement these.
+
+void ::read_attr (SPObject *object, const unsigned char *key)
+
+Signals object that the XML attribute is changed. The frontend checks
+for 'id' attribute; implementations have to read the actual attribute
+value and update the internal state.
+
+void ::read_content (SPObject *object)
+
+Signals object that the XML node content has changed. Only meaningful for
+SPString implementing XML TEXT node.
+
+void ::modified (SPObject *object, unsigned int flags)
+
+Virtual method AND signal implementing asynchronous state change
+notification. Whenever the object internal state changes, it requests
+that ::modified will be scheduled from the idle loop.  Flags are given
+as hints as to what exactly changes. Read the relevant section for
+more information.
+
+SPRepr ::write (SPObject *object, SPRepr *repr, unsigned int flags)
+
+Requests SPObject internal state to be written back to the SPRepr. If
+the SP_OBJECT_WRITE_BUILD flag is set, SPRepr is created, if necessary.
+This is used at various places, most notably to generate a plain SVG
+document, and to complete certain GUI operations.
+
+
+
+2.3. SPItem
+
+SPItem is an abstract base class for all graphic (visible) SVG nodes. It
+is a subclass of SPObject, with great deal of specific functionality.
+
+SPItem internals
+
+struct _SPItem {
+        SPObject object;
+        unsigned int sensitive : 1;
+        unsigned int stop_paint: 1;
+        double affine[6];
+        SPItemView *display;
+        SPClipPath *clip;
+};
+
+Affine is a 3x2 matrix describing transformation from the item to the
+parent local coordinate systems. Each display in linked list has a link
+to a single NRArenaItem that implements actual renderable image of
+the item.
+
+Virtual methods
+
+/******** Disclaimer *******/
+This will change a lot in the future
+Only the most important are listed
+
+void ::bbox (SPItem *item, ArtDRect *bbox, const double *transform)
+
+Calculates item's logical bounding box.  The logical bbox does not
+take into account the stroke width, nor certain other visual
+properties. Transformation is a 3x2 matrix describing coordinate
+transform from the item's local coordinate system to the coordinate
+system of the bounding box.
+
+void ::print (SPItem *item, SPPrintContext *ctx)
+
+Prints the item's visual representation, using the internal printing
+frontend.  In the future this may be turned into a more generic
+exporting method.
+
+char ::description (SPItem *item)
+
+Gives a short description of the item suitable for use in a statusbar,
+etc. 
+
+NRArenaItem ::show (SPItem *item, NRArena *arena)
+
+Creates an NRArena display cache representation of the item. The
+frontend places the generated item into a hierarchy; implementations
+have to build a correct NRArenaItem and keep it up to date.
+
+void (* hide) (SPitem *item, NRArena *arena)
+
+The opposite of ::show.
+
+void ::write_transform (SPItem *item, SPRepr *repr, double *transform)
+
+Tries to remove the extra transformation by modifying other aspects of
+the item representation.  For example, by changing the rectangle width
+and height, the scaling component of the transformation can be
+dropped.  This is used to make the SVG file more human-readable.
+
+void ::menu (SPItem *item, SPDesktop *desktop, GtkMenu *menu)
+
+Appends item specific lines into the menu. This is used to generate
+the context menu, and will probably move into a separate module in 
+the future.
+
+
+
+2.4 SPDocument
+
+SPDocument serves as the container of both model trees (agnostic XML
+and typed object tree), and implements all of the document-level
+functionality used by the program.
+
+SPDocument implements undo and redo stacks and an id-based object
+dictionary.  Thanks to unique id attributes, the latter can be used to
+map from the XML tree back to the object tree.  Documents are
+themselves registered by the main program metaobject 'Sodipodi', which
+does elementary bookkeeping.
+
+SPDocument performs the basic operations needed for asynchronous
+update notification (SPObject ::modified virtual method), and implements
+the 'modified' signal, as well.
+
+Many document level operations, like load, save, print, export and so on,
+use SPDocument as their basic datatype.
+
+2.4.1. Undo and Redo implementation
+
+Using the split document model gives sodipodi a very simple and clean
+undo implementation. Whenever mutation occurs in the XML tree,
+SPObject invokes one of the five corresponding handlers of its
+container document. This writes down a generic description of the
+given action, and appends it to the recent action list, kept by the
+document. There will be as many action records as there are mutation
+events, which are all kept and processed together in the undo
+stack. Two methods exist to indicate that the given action is completed:
+
+void sp_document_done (SPDocument *document)
+void sp_document_maybe_done (SPDocument *document, const unsigned char *key)
+
+Both move the recent action list into the undo stack and clear the
+list afterwards.  While the first method does an unconditional push,
+the second one first checks the key of the most recent stack entry. If
+the keys are identical, the current action list is appended to the
+existing stack entry, instead of pushing it onto its own.  This
+behaviour can be used to collect multi-step actions (like winding the
+Gtk spinbutton) from the UI into a single undoable step.
+
+For controls implemented by Sodipodi itself, implementing undo as a
+single step is usually done in a more efficient way. Most controls have
+the abstract model of grab, drag, release, and change user
+action. During the grab phase, all modifications are done to the
+SPObject directly - i.e. they do not change XML tree, and thus do not
+generate undo actions either.  Only at the release phase (normally
+associated with releasing the mousebutton), changes are written back
+to the XML tree, thus generating only a single set of undo actions.
+
+
+2.5. SPView and SPviewWidget
+
+SPView is an abstract base class of all UI document views.  This
+includes both the editing window and the SVG preview, but does not
+include the non-UI RGBA buffer-based NRArenas nor the XML editor or
+similar views.  The SPView base class has very little functionality of
+its own.
+
+SPViewWidget is a GUI widget that contain a single SPView. It is also
+an abstract base class with little functionality of its own.
+
+2.6. SPDesktop
+
+SPDesktop is a subclass of SPView, implementing an editable document
+canvas.  It is extensively used by many UI controls that need certain
+visual representations of their own.
+
+SPDesktop provides a certain set of SPCanvasItems, serving as GUI
+layers of different control objects. The one containing the whole
+document is the drawing layer. In addition to it, there are grid,
+guide, sketch and control layers. The sketch layer is used for
+temporary drawing objects, before the real objects in document are
+created. The control layer contains editing knots, rubberband and
+similar non-document UI objects.
+
+Each SPDesktop is associated with a SPNamedView node of the document
+tree.  Currently, all desktops are created from a single main named
+view, but in the future there may be support for different ones.
+SPNamedView serves as an in-document container for desktop-related
+data, like grid and guideline placement, snapping options and so on.
+
+Associated with each SPDesktop are the two most important editing
+related objects - SPSelection and SPEventContext.
+
+Sodipodi keeps track of the active desktop and invokes notification
+signals whenever it changes. UI elements can use these to update their
+display to the selection of the currently active editing window.
+
+2.7. SPSelection
+
+This is a per-desktop object that keeps the list of selected objects
+at the given desktop. Both SPItem and SPRepr lists can be retrieved
+from the selection. Many actions operate on the selection, so it is
+widely used throughout the Sodipodi code.
+
+SPSelection also implements its own asynchronous notification signals,
+that UI elements can listen to.
+
+2.8. SPEventContext
+
+SPEventContext is an abstract base class of all tools. As the name
+indicates, event context implementations process UI events (mouse
+movements and keypresses) and take actions (like creating or modifying
+objects).  There is one event context implementation for each tool,
+plus few abstract base classes. Writing a new tool involves
+subclassing SPEventContext.
+
+
+
+3. Some thoughts
+
+3.1. Why do we need a two-level model tree?
+
+The need for a typed object tree is obvious if we want to utilize OO
+programming - which we certainly want to do. Although implemented in pure C,
+Sodipodi uses the gtk (glib in future versions) type and object system,
+which gives us an extremely powerful set of OO functionality. As SVG is
+designed with inheritance in mind, using object subclassing to represent
+it is perfectly the right thing to do.
+
+But there are also areas where typed object structure would make
+things more complex. For example, to implement the copy buffer we had
+to save the full state of copied objects. While this could be done
+with the separate virtual method of SPObject, we can use a much easier
+way and create the duplicate corresponding SPRepr.  As our document
+model already has to implement generation of full object
+representation for SPRepr tree of nodes, generation of new objects
+during paste happens automatically when the given SPRepr is inserted
+into XML tree. The agnostic xml tree is also used for undo stack, as
+described earlier.
+
+The main benefit comes from the extreme simplicity of the XML tree
+manipulation API.  All operations can be done, using only around 10
+methods, which makes code much more robust, and is perfect for
+implementing compatibility sensitive things, like a plugin API.
+
+The XML tree also makes implementing two SVG features - cloning and
+animations - much easier by providing an invariant backbone.
+
+
+
+22. Novemebr 2002
+Lauris Kaplinski
+<lauris@kaplinski.com>