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>

The process is started with:

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, finally continuing with:

 SPObject::repr_attr_changed: rect13
 SPRect::set: 2 fill:#ff0000: entrance: rect13 uflags: 0 mflags: 0 flags: 0
   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
         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
           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
           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
     SPDocument::_updateDocument(): Exit: root uflags: 0 mflags: 0
   SPDocument::ensureUpToDate(): Exit
   Inkscape::DocumentUndo::maybeDone: before signal
   Drawing::render:: Entrance
   Drawing::render:: Exit
   Drawing::render:: Entrance
   Drawing::render:: Exit
   Drawing::render:: Entrance
   Drawing::render:: Exit
   Drawing::render:: Entrance
   Drawing::render:: Exit
   Drawing::render:: Entrance
   Drawing::render:: Exit
   Drawing::render:: Entrance
   Drawing::render:: Exit
 Inkscape::DocumentUndo::maybeDone: Exit
ColorItem::buttonClicked: Exit