Path Markup syntax: XPS-style

This topic describes in detail the powerful and complex mini-language you can use to specify path geometries more compactly. Mako's implementation is based on "Abbreviated Geometry Syntax" described in the Open XPS Standard (Open XML Paper Specification (Open XPS®), ECMA 388).

White space

For brevity, a single space is shown in the syntax sections that follow, but multiple spaces are also acceptable wherever a single space is shown.

Two numbers don’t actually have to be separated by a comma or white space, but this can only be done when the resulting string is unambiguous. For instance, 2..3 is actually two numbers: "2." And ".3". Similarly, 2-3 is "2" and "-3". Spaces are not required before or after commands, either.

Syntax

The Path Markup syntax for a IDOMPathGeometry() is composed of an optional FillRule value and one or more figure descriptions. With it, you can create path geometry with simple markup, then create stoked or filled paths and shapes to add to a page or canvas. Use a render transform to resize, as required. For example:

CPP

auto mako = IJawsMako::create();
IJawsMako::enableAllFeatures(mako);
    
auto geometry = IDOMPathGeometry::create(mako, "F1 M 128,256 L 256,192 L 256,64 L 128,0 L 0,64 L 0,192 L 128,256 Z ");
auto redBrush = IDOMSolidColorBrush::create(mako, IDOMColor::create(mako, IDOMColorSpacesRGB::create(mako), 1.0f, 1.0f, 0.0f, 0.0f));
auto fillPath = IDOMPathNode::createFilled(mako, geometry, redBrush);

auto assembly = IDocumentAssembly::create(mako);
auto document = IDocument::create(mako);
auto page = IPage::create(mako);
document->appendPage(page);
assembly->appendDocument(document);

// Add the graphic to a new fixed page (Mako defaults to A4) then save as PDF
auto fixedPage = IDOMFixedPage::create(mako);
page->setContent(fixedPage);
fixedPage->appendChild(fillPath);
IPDFOutput::create(mako)->writeAssembly(assembly, "geometry.pdf");

A geometry is specified with an optional FillRule command followed by one or more figure definitions. Figure definitions are specified with a Move command, a set of one or more drawing commands to create segments, and an optional Close command to create a closing segment. Drawing commands include:

Line
Horizontal Line
Vertical Line
Cubic Bézier Curve
Quadratic Bézier Curve
Smooth Cubic Bézier Curve
Elliptical Arc

A command is represented by a single letter and is followed by zero or more whitespace characters, which are followed by command parameters. Parameters are whitespace-delimited. Points are specified as a comma-delimited pair with zero or more whitespace characters.

Uppercase letters denote absolute values, and lowercase letters denote relative values. When relative coordinate values are specified, each coordinate pair expresses an offset relative to the current endpoint (the previous command’s terminating coordinate pair). If a relative value is used for the first Move command, the current endpoint is, by definition, 0,0. If a relative value is used following a Close command, the current endpoint is the first point of the previous figure.

If entering more than one drawing command of the same type sequentially, the duplicate command entry MAY be omitted. For example: L 100,200 300,400 is equivalent to L 100,200 L 300,400. The current endpoint is determined as though each command appears individually.

Values specifying coordinates can be real numbers.

Name	Syntax	Description	Example
FillRule	`F FillRule`	Establishes the fill rule that you should use for this geometry. A value of `0` is equivalent to a `FillRule` value of `EvenOdd`; a value of `1` is equivalent to a `FillRule` value of `NonZero`. The default value if this command is omitted is `0`. This command MUST appear only as the first command in the abbreviated geometry syntax.	`F 0`
Move	`M x,y` or `m x,y`	Establishes a new current endpoint. Every geometry MAY specify one or more figures and MAY be preceded by a `FillRule` command where allowed. The first figure in a geometry MUST begin with a `Move` command. Subsequent `Move` commands indicate the start of a new figure but MAY be omitted, indicating the current endpoint for the subsequent figure is the same as the endpoint of the previous figure	`M 400,150`
Line	`L x,y` or `l x,y`	Draws a straight line from the current point to the specified point	`L 400,350`
Horizontal Line	`H x` or `h x`	Draws a horizontal line from the current endpoint to the specified `x` coordinate	`H 90`
Vertical Line	`V y` or `v y`	Draws a vertical line from the current endpoint to the specified `y` coordinate	`v 90`
Cubic Bézier Curve	`C x1,y1 x2,y2 x3,y3` or `c x1,y1 x2,y2 x3,y3`	Draws a cubic Bézier curve from the current endpoint to the specified point (`x3,y3`) using the two specified control points (`x1,y1` and `x2,y2`). The first control point determines the initial direction (tangent) of the curve, and the second determines the terminating direction (tangent) of the curve.	`C 100,200 200,400 300,200`
Quadratic Bézier Curve	`Q x1,y1 x2,y2` or `q x1,y1 x2,y2`	Draws a quadratic Bézier curve from the current endpoint to the specified point (`x2,y2`) using the specified control point (`x1,y1`)	`q 100,200 300,200`
Smooth Cubic Bézier Curve	`S x1,y1 x2,y2` or `s x1,y1 x2,y2`	Draws a cubic Bézier curve from the current endpoint to the specified point (`x2,y2`). The first control point is assumed to be the reflection of the second control point of the previous command, relative to the current endpoint. If there is no previous command or if the previous command was not a `Cubic Bézier Curve` command or `Smooth Cubic Bézier Curve` command, the first control point is assumed to be coincident with the current endpoint. The second control point is specified by `x1,y1`.	`S 100,200` `200,300`
Elliptical Arc	`A xr,yr rx fArc fSweep x,y` or `a xr,yr rx fArc fSweep x,y`	Draws an elliptical arc from the current endpoint to the specified point (`x,y`). The size and orientation of the ellipse are defined by `xr,yr`. `rx,xr` defines the x radius, `yr` defines the y radius, and `rx` defines the x-axis rotation in degrees, which indicates how the ellipse is rotated relative to the current coordinate system. The center of the ellipse is calculated automatically. In most situations, four different arcs satisfy the specified constraints. `fArc` and `fSweep` indicate which arc to use. Of the four candidate arc sweeps, two represent large arcs with sweeps of 180° or greater, and two represent smaller arcs with sweeps less than 180°. If `fArc` is `1`, one of the two larger arc sweeps is chosen. If `fArc` is `0`, one of the smaller arc sweeps is chosen. No other values of `fArc` are valid. If `fSweep` is `1`, the arc is drawn in a positive-angle (clockwise) direction. If `fSweep` is `0`, the arc is drawn in a negative angle (counter-clockwise) direction. No other values of `fSweep` are valid.	`a 200,70 10 0 1 100,100`
Close	`Z` or `z`	Draws a straight line from the current endpoint to the first point of the current figure and then ends the figure. If the command following a `Close` command is a `Move` command, the `Move` command specifies the initial point of the next figure. Otherwise, the next figure starts at the same initial point as the current figure.	`z`