summaryrefslogtreecommitdiffstats
path: root/doc/markers_design.txt
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 18:24:48 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 18:24:48 +0000
commitcca66b9ec4e494c1d919bff0f71a820d8afab1fa (patch)
tree146f39ded1c938019e1ed42d30923c2ac9e86789 /doc/markers_design.txt
parentInitial commit. (diff)
downloadinkscape-cca66b9ec4e494c1d919bff0f71a820d8afab1fa.tar.xz
inkscape-cca66b9ec4e494c1d919bff0f71a820d8afab1fa.zip
Adding upstream version 1.2.2.upstream/1.2.2upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/markers_design.txt')
-rw-r--r--doc/markers_design.txt125
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.