125 lines
5.5 KiB
Text
125 lines
5.5 KiB
Text
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.
|