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 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.