doc/markers_design.txt

   1                              Markers Design
   2                           Bryce W. Harrington
   3                               -----------
   4
   5 Markers (or "arrowheads") are drawing elements specified by the SVG
   6 standard that can be placed on lines at one of three positions: Start,
   7 End, or Midpoints.  This document isn't intended to be an exhaustive
   8 guide to Markers, but rather to simply capture notes about the
   9 implementation of them within Inkscape.
  10
  11 History
  12 =======
  13 The marker code was originally developed by Lauris for Sodipodi, but due
  14 to various issues, the code was not hooked to the interface.  Thus
  15 there was no way for users to actually put markers on lines.  He seems
  16 to have also started some very preliminary work for doing dimensioning,
  17 although the code is not far enough along to reveal the design intent.
  18
  19 Early in Inkscape, I dug through the code and reactivated the markers
  20 function, and then hammered on a few of the main issues to get markers
  21 to (mostly) work.  There were a variety of remaining issues (e.g., you
  22 couldn't change marker colors, updates didn't work very well, and snap
  23 points were messed up.)  But at least they no longer crashed when you
  24 used them.  ;-)
  25
  26 Simarilius and others did the work of getting the UI hooked up for
  27 markers, and other assorted fixes.  A set of stock markers were created
  28 and distributed with Inkscape.
  29
  30 Since then, though, the code has sat mostly idle, as no one has had
  31 time/inclination to put more work on it.  Despite this, the remaining
  32 marker issues (color setting in particular) remain popular requests
  33 among users.
  34
  35 I'm hoping this document assists anyone wishing to work on markers to
  36 come up to speed with the code more easily than otherwise.
  37
  38 Implementation Files
  39 ====================
  40 The following files contain code of relevance to markers:
  41
  42 marker.h: Defines the SPMarker and SPMarkerReference classes.  SPMarker
  43  holds information about the marker's reference points, dimensions,
  44  orientation, and viewbox.  It also contains an extra transform matrix,
  45  a list of views that will need updating if the marker's definition
  46  changes, and a set of options relating to units and aspect ratios.  The
  47  SPMarkerReference provides an URI reference for SPMarkers.
  48
  49 marker.cpp: Implements the sp_marker class, providing functionality for
  50  managing the relationship of markers to lines or other objects they've
  51  been applied to.  Updates reprs and properties as the marker's
  52  definition changes.  Handles updates/changes to marker views as well.
  53
  54 sp-shape.cpp:  "Shapes" are drawing objects which, among other things,
  55 are able to have start, mid, and end markers applied to them.  This file
  56 implements the handling of start, mid, and end markers, including
  57 managing references, setting or unsetting, updating, transforming,
  58 and updating them.
  59
  60 selection-chemistry.cpp:  One of the routines in this file implements a
  61 function for copying defs, including markers.
  62
  63 sp-marker-loc.h:  Just contains a set of enum definitions for marker
  64 locations (start/mid/end).
  65
  66 display/nr-arena-shape.cpp:  Arena Shapes handle adding, updating, and
  67 etc. the children (like markers) of shapes.  This also takes care of
  68 rendering a shape's markers by composing them into the parent's buffer.
  69
  70 helper/stock-items.cpp:  This file implements the code for loading
  71 default marker definitions from Inkscape's markers directory and making
  72 them available in the current document's defs section.
  73
  74 dialogs/stroke-style.cpp:  Implements the stroke style dialog, which
  75 includes the widgets for displaying stock markers that can be applied to
  76 lines.
  77
  78
  79 Marker Architecture
  80 ===================
  81 A marker is a distinct drawing element that exists in the <defs> section
  82 of an SVG document.  Markers often appear multiple places in a document
  83 - for instance, you might have a diagram with dozens of lines, each
  84 tipped by a copy of the same arrow.  Rather than paste a copy of the
  85 arrowhead in at each point it's used, a single definition is made, and a
  86 reference, or 'href', is attached at each place its used.
  87
  88 In Inkscape, the marker definition is implemented as a 'SPMarker'
  89 object, and each reference is a 'SPMarkerView' object.  Each SPMarker
  90 has a listing of all its SPMarkerViews, which it can use for update
  91 purposes when it changes.
  92
  93 SPShapes are objects which can take markers in one of three places:
  94 start, middle, or end.  The SPShape class also has the routines for
  95 doing the logistics of setting markers, coordinating references, and so
  96 forth.
  97
  98 Rendering of the markers is coordinated by SPArenaShape, which handles
  99 compositing of the rendered marker image into the parent shape's area,
 100 and takes care of clipping boundaries and such.
 101
 102 We provide a set of stock markers that are loaded from the markers.svg
 103 file and hooked into each loaded document's data structure.  This is
 104 handled in the stock-items code.
 105
 106
 107 Stroke Dialog
 108 =============
 109 In the stroke style dialog, several routines allow for setting and
 110 interacting with the stroke markers.  Most of these routines are already
 111 documented, but a few are worth some additional attention.
 112
 113 sp_marker_prev_new():  Generates the preview images of markers for
 114 display in the marker menu.
 115
 116 sp_marker_list_from_doc():  Generates a listing of non-stock markers in
 117 the document.  Generates preview and label for the marker.
 118
 119 ink_markers_preview_doc(): Returns a new document containing default
 120 start, mid, and end markers by creating the SVG text and running it
 121 through sp_document_new_from_mem.  I'm not entirely sure why this
 122 exists, but it's called from sp_stroke_style_line_widget_new() so
 123 presumably is needed.
 124
 125 ink_marker_menu():  Generates the marker menu.