Adding upstream version 1.3+ds.upstream/1.3+dsupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 125 insertions, 0 deletions

diff --git a/doc/markers_design.txt b/doc/markers_design.txt
new file mode 100644
index 0000000..e37ff1c
--- /dev/null
+++ b/doc/markers_design.txt
@@ -0,0 +1,125 @@
+                             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.