Object tree

Overview

The object tree implements an XML-to-display primitive mapping, and provides an object hierarchy that can be modified using the GUI. Changes in the XML tree are automatically propagated to the object tree via observers, but not the other way around—a function called updateRepr() must be explicitly called. Relevant nodes of the object tree contains fully cascaded CSS style information. The object tree also includes clones of objects that are referenced by the <use> element in the XML tree.

SPObject (src/sp-object.h) is the abstract base class for each node in the object tree. Each derived class implements a certain SVG element type or is an abstract base class for a different node type.

SPItem (src/sp-item.h) is a derived class that is the base class for all graphic (visible) SVG nodes. It adds handling for styling, clipping, masking, and transforms.

The object tree is constructed from the XML tree by first manually constructing the SPRoot object (derived from SPObject) in SPDocument::createDoc() (src/document.h) and then calling the SPObject::invoke_build() member function. This function does some bookkeeping and then envokes the build() method (i.e. SPRoot::build() in the case of the root element). It also add the signaling that keeps objects in sync with the XML tree.

Functions

The most important functions from an architecture point of view defined by SPObject are:

envoke_build (SPObject)

 * Does bookkeeping.
 * Calls build() member function.
 * Adds signals to keep in sync with XML tree.

build (derived)

 * Calls parent class's build() method.
 * Reads in attributes by calling readAttr() for each attribute.

readAttr (SPObject)

 * Looks up key for attribute (string).
 * Calls setKeyValue() which does nothing other than call set()

set (derived)

 * Reads in attribute:
 ** Processing as needed (e.g. converting % length to absolute length).
 ** Calls requestDisplayUpdate() if required.
 * Calls parent class set() to handle unknown attributes.

requestDisplayUpdate(unsigned int flags) (SPObject)

 * Merge update flags into uflags.
 * If SP_OBJECT_MODIFIED_FLAG or SP_OBJECT_CHILD_MODIFIED_FLAG not previously set:
 ** If object has parent, call parent's requestDisplayUpdate with SP_OBJECT_CHILD_MODIFIED_FLAG
 ** Else call document->requestModified() function which signals to GTK to redraw by calling sp_document_idle_handler() which calls SPDocument::_updateDocument().

updateDisplay(SPCtx *ctx, unsigned flags) (SPObject)

 * Called by SPDocument::_updateDocument() which is called by SPDocument::ensureUpToDate(), etc.
 * Called on child objects by SPGroup::update(), etc.

 * Merges uflags into flags.
 * Merges uflags into mflags.
 * Updates style if necessary.
 * Call update( ctx, flags).

update (derived)

 * Performs object related updates like resolving % lengths.
 * Calls child objects with updated transform matrix and with SP_OBJECT_PARENT_MODIFIED_FLAG added to flags if needed.
 * Calls parent class update() if needed.

requestModified(unsigned int flags)

 * Merge modified flags into mflags.
 * If SP_OBJECT_MODIFIED_FLAG or SP_OBJECT_CHILD_MODIFIED_FLAG not previously set:
 ** If object has parent, call parent's requestModified with SP_OBJECT_CHILD_MODIFIED_FLAG
 ** Else call document->requestModified() function which signals to GTK to redraw.

Processes

This section lists program flows for typical processes.

Change Fill of <rect>

Note, not all function calls shown.

 ColorItem::buttonClicked(): Entrance
   sp_repr_css_set_property()
     Lots of calls to various functions to merge the new color into the rectangle's 'style' attribute.
   SPObject::repr_attr_changed: rect13
   SPRect::set: 2 fill:#ff0000: entrance: rect13 uflags: 0 mflags: 0 flags: 0
     SPShape::set, SPLPEItem::set, SPItem::set
     SPObject::set: 2 fill:#ff0000: entrance: rect13 uflags: 0 mflags: 0 flags: 0
       SPObject::requestDisplayUpdate: entrance: rect13 uflags: 0 mflags: 0 flags: 0
         SPObject::requestDisplayUpdate: entrance: svg2 uflags: 0 mflags: 0 flags: 0
           SPDocument::requestModified(): Entrance
             May call sp_document_idle_handler() and/or sp_document_rerouter_handler().
             This doesn't appear to trigger a display refresh. The refresh happens below.
           SPDocument::requestModified(): Exit
         SPObject::requestDisplayUpdate: exit: svg2 uflags: 2 mflags: 0 flags: 0
       SPObject::requestDisplayUpdate: exit: rect13 uflags: 9 mflags: 0 flags: 0
     SPObject::set: exit: rect13 uflags: 9 mflags: 0 flags: 0
   SPRect::set: exit: rect13 uflags: 9 mflags: 0 flags: 0
   Inkscape::DocumentUndo::maybeDone: Entrance
     SPDocument::ensureUpToDate(): Entrance
       SPDocument::_updateDocument(): Entrance
         SPObject::updateDisplay: entrance: svg2 uflags: 2 mflags: 0 flags: 0
           SPObject::updateDisplay: entrance: rect13 uflags: 9 mflags: 0 flags: 0
             SPRect::update: entrance: rect13 uflags: 0 mflags: 9 flags: 9
               SPShape::update, SPLPEItem::update, SPItem::update
             SPRect::update: exit: rect13 uflags: 0 mflags: 9 flags: 9
           SPObject::updateDisplay: exit: rect13 uflags: 0 mflags: 9 flags: 0
         SPObject::updateDisplay: exit: svg2 uflags: 0 mflags: 2 flags: 0
         SPDocument::_emitModified: Entrance
           SPObject::emitModified: entrance: svg2 uflags: 0 mflags: 2 flags: 0
             SPObject::emitModified: entrance: rect13 uflags: 0 mflags: 9 flags: 0
               SPShape::modified: entrance: rect13 uflags: 0 mflags: 0 flags: 0  Handles markers
               SPShape::modified: exit: rect13 uflags: 0 mflags: 0 flags: 0
             SPObject::emitModified: exit: rect13 uflags: 0 mflags: 0 flags: 0
           SPObject::emitModified: exit: svg2 uflags: 0 mflags: 0 flags: 0
         SPDocument::_emitModified: Exit
       SPDocument::_updateDocument(): Exit: root uflags: 0 mflags: 0
       SPDocument::_updateDocument(): Entrance  Called two times by SPDocument::ensureUpToDate()
       SPDocument::_updateDocument(): Exit: root uflags: 0 mflags: 0
     SPDocument::ensureUpToDate(): Exit
     Emit commit_signal which connects to SPDesktop::updateNow() which calls SPCanvas::updateNow().
     Render drawing on screen.
   Inkscape::DocumentUndo::maybeDone: Exit
 ColorItem::buttonClicked: Exit