Marker menus now display custom markers in a document that are present

when the document is loaded.  The menus won't update with new markers,
though, and there's a couple other issues that need to be addressed
before its 100% reliable.

(bzr r2080)

1 files changed, 98 insertions, 0 deletions

diff --git a/doc/markers_design.txt b/doc/markers_design.txt
new file mode 100644
index 000000000..f41eaa8e4
--- /dev/null
+++ b/doc/markers_design.txt
@@ -0,0 +1,98 @@
+                             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.
+
+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:  tbd
+
+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:  tbd
+
+selection-chemistry.cpp:  tbd
+
+sp-marker-loc.h:  tbd
+
+display/nr-arena-shape.cpp:  tbd
+
+stock-items.cpp:  tbd
+
+dialogs/stroke-style.h:  tbd
+
+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.
+
+
+
+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.