diff options
Diffstat (limited to 'doc/markers_design.txt')
| -rw-r--r-- | doc/markers_design.txt | 125 |
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. |