                             Markers Design
                          Bryce W. Harrington
                              -----------

Markers (or "arrowheads") are drawing elements specified by the SVG
standard that can be placed on lines at one of three positions: Start,
End, or Midpoints.  This document isn't intended to be an exhaustive
guide to Markers, but rather to simply capture notes about the
implementation of them within Inkscape.

History
=======
The marker code was originally developed by Lauris for Sodipodi, but due
to various issues, the code was not hooked to the interface.  Thus
there was no way for users to actually put markers on lines.  He seems
to have also started some very preliminary work for doing dimensioning,
although the code is not far enough along to reveal the design intent.

Early in Inkscape, I dug through the code and reactivated the markers
function, and then hammered on a few of the main issues to get markers
to (mostly) work.  There were a variety of remaining issues (e.g., you
couldn't change marker colors, updates didn't work very well, and snap
points were messed up.)  But at least they no longer crashed when you
used them.  ;-)

Simarilius and others did the work of getting the UI hooked up for
markers, and other assorted fixes.  A set of stock markers were created
and distributed with Inkscape.

Since then, though, the code has sat mostly idle, as no one has had
time/inclination to put more work on it.  Despite this, the remaining
marker issues (color setting in particular) remain popular requests
among users.

I'm hoping this document assists anyone wishing to work on markers to
come up to speed with the code more easily than otherwise.

Implementation Files
====================
The following files contain code of relevance to markers:

marker.h: Defines the SPMarker and SPMarkerReference classes.  SPMarker
 holds information about the marker's reference points, dimensions,
 orientation, and viewbox.  It also contains an extra transform matrix,
 a list of views that will need updating if the marker's definition
 changes, and a set of options relating to units and aspect ratios.  The
 SPMarkerReference provides an URI reference for SPMarkers.

marker.cpp: Implements the sp_marker class, providing functionality for
 managing the relationship of markers to lines or other objects they've
 been applied to.  Updates reprs and properties as the marker's
 definition changes.  Handles updates/changes to marker views as well.

sp-shape.cpp:  "Shapes" are drawing objects which, among other things,
are able to have start, mid, and end markers applied to them.  This file
implements the handling of start, mid, and end markers, including
managing references, setting or unsetting, updating, transforming,
and updating them.

selection-chemistry.cpp:  One of the routines in this file implements a
function for copying defs, including markers.

sp-marker-loc.h:  Just contains a set of enum definitions for marker
locations (start/mid/end).

display/nr-arena-shape.cpp:  Arena Shapes handle adding, updating, and
etc. the children (like markers) of shapes.  This also takes care of
rendering a shape's markers by composing them into the parent's buffer.

helper/stock-items.cpp:  This file implements the code for loading
default marker definitions from Inkscape's markers directory and making
them available in the current document's defs section.

dialogs/stroke-style.cpp:  Implements the stroke style dialog, which
includes the widgets for displaying stock markers that can be applied to
lines.


Marker Architecture
===================
A marker is a distinct drawing element that exists in the <defs> section
of an SVG document.  Markers often appear multiple places in a document
- for instance, you might have a diagram with dozens of lines, each
tipped by a copy of the same arrow.  Rather than paste a copy of the
arrowhead in at each point it's used, a single definition is made, and a
reference, or 'href', is attached at each place its used.

In Inkscape, the marker definition is implemented as a 'SPMarker'
object, and each reference is a 'SPMarkerView' object.  Each SPMarker
has a listing of all its SPMarkerViews, which it can use for update
purposes when it changes.

SPShapes are objects which can take markers in one of three places:
start, middle, or end.  The SPShape class also has the routines for
doing the logistics of setting markers, coordinating references, and so
forth.

Rendering of the markers is coordinated by SPArenaShape, which handles
compositing of the rendered marker image into the parent shape's area,
and takes care of clipping boundaries and such.

We provide a set of stock markers that are loaded from the markers.svg
file and hooked into each loaded document's data structure.  This is
handled in the stock-items code.


Stroke Dialog
=============
In the stroke style dialog, several routines allow for setting and
interacting with the stroke markers.  Most of these routines are already
documented, but a few are worth some additional attention.

sp_marker_prev_new():  Generates the preview images of markers for
display in the marker menu.

sp_marker_list_from_doc():  Generates a listing of non-stock markers in
the document.  Generates preview and label for the marker.

ink_markers_preview_doc(): Returns a new document containing default
start, mid, and end markers by creating the SVG text and running it
through sp_document_new_from_mem.  I'm not entirely sure why this
exists, but it's called from sp_stroke_style_line_widget_new() so
presumably is needed.

ink_marker_menu():  Generates the marker menu.
