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.
  16
  17 Early in Inkscape, I dug through the code and reactivated the markers
  18 function, and then hammered on a few of the main issues to get markers
  19 to (mostly) work.  There were a variety of remaining issues (e.g., you
  20 couldn't change marker colors, updates didn't work very well, and snap
  21 points were messed up.)  But at least they no longer crashed when you
  22 used them.  ;-)
  23
  24 Simarilius and others did the work of getting the UI hooked up for
  25 markers, and other assorted fixes.  A set of stock markers were created
  26 and distributed with Inkscape.
  27
  28 Since then, though, the code has sat mostly idle, as no one has had
  29 time/inclination to put more work on it.  Despite this, the remaining
  30 marker issues (color setting in particular) remain popular requests
  31 among users.
  32
  33 I'm hoping this document assists anyone wishing to work on markers to
  34 come up to speed with the code more easily than otherwise.
  35
  36 Implementation Files
  37 ====================
  38 The following files contain code of relevance to markers:
  39
  40 marker.h:  tbd
  41
  42 marker.cpp: Implements the sp_marker class, providing functionality for
  43  managing the relationship of markers to lines or other objects they've
  44  been applied to.  Updates reprs and properties as the marker's
  45  definition changes.  Handles updates/changes to marker views as well.
  46
  47 sp-shape.cpp:  tbd
  48
  49 selection-chemistry.cpp:  tbd
  50
  51 sp-marker-loc.h:  tbd
  52
  53 display/nr-arena-shape.cpp:  tbd
  54
  55 stock-items.cpp:  tbd
  56
  57 dialogs/stroke-style.h:  tbd
  58
  59 dialogs/stroke-style.cpp:  Implements the stroke style dialog, which
  60 includes the widgets for displaying stock markers that can be applied to
  61 lines.
  62
  63
  64 Marker Architecture
  65 ===================
  66 A marker is a distinct drawing element that exists in the <defs> section
  67 of an SVG document.  Markers often appear multiple places in a document
  68 - for instance, you might have a diagram with dozens of lines, each
  69 tipped by a copy of the same arrow.  Rather than paste a copy of the
  70 arrowhead in at each point it's used, a single definition is made, and a
  71 reference, or 'href', is attached at each place its used.
  72
  73 In Inkscape, the marker definition is implemented as a 'SPMarker'
  74 object, and each reference is a 'SPMarkerView' object.  Each SPMarker
  75 has a listing of all its SPMarkerViews, which it can use for update
  76 purposes when it changes.
  77
  78
  79
  80 Stroke Dialog
  81 =============
  82 In the stroke style dialog, several routines allow for setting and
  83 interacting with the stroke markers.  Most of these routines are already
  84 documented, but a few are worth some additional attention.
  85
  86 sp_marker_prev_new():  Generates the preview images of markers for
  87 display in the marker menu.
  88
  89 sp_marker_list_from_doc():  Generates a listing of non-stock markers in
  90 the document.  Generates preview and label for the marker.
  91
  92 ink_markers_preview_doc(): Returns a new document containing default
  93 start, mid, and end markers by creating the SVG text and running it
  94 through sp_document_new_from_mem.  I'm not entirely sure why this
  95 exists, but it's called from sp_stroke_style_line_widget_new() so
  96 presumably is needed.
  97
  98 ink_marker_menu():  Generates the marker menu.