Path Markup Syntax

Articolo
11/03/2006

This topic describes the Extensible Application Markup Language (XAML) usage syntax for describing paths. WPF supports a powerful and complex mini-language that you can use to describe geometric paths.

This topic contains the following sections.

Prerequisites
StreamGeometry and PathFigureCollection Mini-Languages
Move Command
Draw Commands
The Close Command
Point Syntax
Special Values
Related Topics

Prerequisites

To understand this topic, you should be familiar with the basic features of Geometry objects. For more information, see the Geometry Overview.

StreamGeometry and PathFigureCollection Mini-Languages

WPF provides two classes that provide mini-languages for describing geometric paths: StreamGeometry and PathFigureCollection.

You use the StreamGeometry mini-language when setting a property of type Geometry, such as the Clip property of a UIElement or the Data property of a Path element. The following example uses attribute syntax to create a StreamGeometry.
```
<Path Stroke="Black" Fill="Gray"
      Data="M 10,100 C 10,300 300,-200 300,100" />
```
You use the PathFigureCollection mini-language when setting the Figures property of a PathGeometry. The following example uses a attribute syntax to create a PathFigureCollection for a PathGeometry.
```
<Path Stroke="Black" Fill="Gray">
  <Path.Data>
    <PathGeometry Figures="M 10,100 C 10,300 300,-200 300,100" />
  </Path.Data>
</Path>
```

As you can see from the preceding examples, the two mini-languages are very similar. It's always possible to use a PathGeometry in any situation where you could use a StreamGeometry; so which one should you use? Use a StreamGeometry when you don't need to modify the path after creating it; use a PathGeometry if you do need to modify the path.

For more information about the differences between PathGeometry and StreamGeometry objects, see the Geometry Overview.

A Note about 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 whitespace, 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 Extensible Application Markup Language (XAML) attribute usage syntax for a StreamGeometry is composed of an optional FillRule value and one or more figure descriptions.

StreamGeometry XAML Attribute Usage
`<` object property`="`[fillRule] figureDescription[ figureDescription]*`" ... />`

The Extensible Application Markup Language (XAML) attribute usage syntax for a PathFigureCollection is composed of one or more figure descriptions.

PathFigureCollection XAML Attribute Usage
`<` object property`="`figureDescription[ figureDescription]*`" ... />`

Term	Description
fillRule	System.Windows.Media.FillRule Specifies whether the StreamGeometry uses the EvenOdd or Nonzero FillRule. `F0` specifies the EvenOdd fill rule. `F1` specifies the Nonzero fill rule. If you omit this command, the subpath uses the default behavior, which is EvenOdd. If you specify this command, you must place it first.
figureDescription	A figure composed of a move command, draw commands, and an optional close command. moveCommand drawCommands `[` closeCommand `]`
moveCommand	A move command that specifies the start point of the figure. See the Move Command section.
drawCommands	One or more drawing commands that describe the figure's contents. See the Draw Commands section.
closeCommand	An optional close command that closes figure. See the Close Command section.

Move Command

Specifies the start point of a new figure.

Syntax

Syntax
`M` startPoint - or - `m` startPoint

M startPoint

- or -

m startPoint

Term	Description
startPoint	System.Windows.Point The start point of a new figure.

startPoint

System.Windows.Point

The start point of a new figure.

An uppercase M indicates that startPoint is an absolute value; a lowercase m indicates that startPoint is an offset to the previous point, or (0,0) if none exists. If you list multiple points after the move command, a line is drawn to those points though you specified the line command.

Draw Commands

A draw command can consist of several shape commands. The following shape commands are available: line, horizontal line, vertical line, cubic Bezier curve, quadratic Bezier curve, smooth cubic Bezier curve, smooth quadratic Bezier curve, and elliptical arc.

You enter each command by using either an uppercase or a lowercase letter: uppercase letters denote absolute values and lowercase letters denote relative values: the control points for that segment are relative to the end point of the preceding example. When sequentially entering more than one command of the same type, you can omit the duplicate command entry; for example, L 100,200 300,400 is equivalent to L 100,200 L 300,400. The following table describes the move and draw commands.

Line Command

Creates a straight line between the current point and the specified end point. l 20 30 and L 20,30 are examples of valid line commands.

Syntax

Syntax
`L` endPoint - or - `l` endPoint

L endPoint

- or -

l endPoint

Term	Description
endPoint	System.Windows.Point The end point of the line.

endPoint

System.Windows.Point

The end point of the line.

Horizontal Line Command

Creates a horizontal line between the current point and the specified x-coordinate. H 90 is an example of a valid horizontal line command.

Syntax

Syntax
`H` x - or - `h` x

H x

- or -

h x

Term	Description
x	System.Double The x-coordinate of the end point of the line.

Vertical Line Command

Creates a vertical line between the current point and the specified y-coordinate. v 90 is an example of a valid vertical line command.

Syntax

Syntax
`V` y - or - `v` y

V y

- or -

v y

Term	Description
y	System.Double The y-coordinate of the end point of the line.

Cubic Bezier Curve Command

Creates a cubic Bezier curve between the current point and the specified end point by using the two specified control points (controlPoint₁ and controlPoint₂). C 100,200 200,400 300,200 is an example of a valid curve command.

Syntax

Syntax
`C` controlPoint₁ controlPoint₂ endPoint - or - `c` controlPoint₁ controlPoint₂ endPoint

C controlPoint₁ controlPoint₂ endPoint

- or -

c controlPoint₁ controlPoint₂ endPoint

Term	Description
controlPoint ₁	System.Windows.Point The first control point of the curve, which determines the starting tangent of the curve.
controlPoint ₂	System.Windows.Point The second control point of the curve, which determines the ending tangent of the curve.
endPoint	System.Windows.Point The point to which the curve is drawn.

controlPoint ₁

System.Windows.Point

The first control point of the curve, which determines the starting tangent of the curve.

controlPoint ₂

System.Windows.Point

The second control point of the curve, which determines the ending tangent of the curve.

endPoint

System.Windows.Point

The point to which the curve is drawn.

Quadratic Bezier Curve Command

Creates a quadratic Bezier curve between the current point and the specified end point by using the specified control point (controlPoint). q 100,200 300,200 is an example of a valid quadratic Bezier curve command.

Syntax

Syntax
`Q` controlPoint endPoint - or - `q` contolPoint endPoint

Q controlPoint endPoint

- or -

q contolPoint endPoint

Term	Description
controlPoint	System.Windows.Point The control point of the curve, which determines the starting and ending tangents of the curve.
endPoint	System.Windows.Point The point to which the curve is drawn.

controlPoint

System.Windows.Point

The control point of the curve, which determines the starting and ending tangents of the curve.

endPoint

System.Windows.Point

The point to which the curve is drawn.

Smooth cubic Bezier curve Command

Creates a cubic Bezier curve between the current point and the specified end point. The first control point is assumed to be the reflection of the second control point of the previous command relative to the current point. If there is no previous command or if the previous command was not a cubic Bezier curve command or a smooth cubic Bezier curve command, assume the first control point is coincident with the current point. The second control point, the control point for the end of the curve, is specified by controlPoint₂. For example, S 100,200 200,300 is a valid smooth cubic Bezier curve command.

Syntax

Syntax
`S` controlPoint₂ endPoint - or - `s` controlPoint₂ endPoint

S controlPoint₂ endPoint

- or -

s controlPoint₂ endPoint

Term	Description
controlPoint ₂	System.Windows.Point The control point of the curve, which determines the ending tangent of the curve.
endPoint	System.Windows.Point The point to which the curve is drawn.

controlPoint ₂

System.Windows.Point

The control point of the curve, which determines the ending tangent of the curve.

endPoint

System.Windows.Point

The point to which the curve is drawn.

Smooth cubic Bezier curve Command

Creates a quadratic Bezier curve between the current point and the specified end point. The control point is assumed to be the reflection of the control point of the previous command relative to the current point. If there is no previous command or if the previous command was not a quadratic Bezier curve command or a smooth quadratic Bezier curve command, the control point is coincident with the current point.

Syntax

Syntax
`T` controlPoint endPoint - or - `t` controlPoint endPoint

T controlPoint endPoint

- or -

t controlPoint endPoint

Term	Description
controlPoint	System.Windows.Point The control point of the curve, which determines the starting and tangent of the curve.
endPoint	System.Windows.Point The point to which the curve is drawn.

controlPoint

System.Windows.Point

The control point of the curve, which determines the starting and tangent of the curve.

endPoint

System.Windows.Point

The point to which the curve is drawn.

Elliptical Arc Command

Creates an elliptical arc between the current point and the specified end point.

Syntax

Syntax
`A` size rotationAngle isLargeArcFlag sweepDirectionFlag endPoint - or - `a` size rotationAngle isLargeArcFlag sweepDirectionFlag endPoint

A size rotationAngle isLargeArcFlag sweepDirectionFlag endPoint

- or -

a size rotationAngle isLargeArcFlag sweepDirectionFlag endPoint

Term	Description
size	System.Windows.Size The x- and y-radius of the arc.
rotationAngle	System.Double The rotation of the ellipse, in degrees.
isLargeArcFlag	Set to 1 if the angle of the arc should be 180 degrees or greater; otherwise, set to 0.
sweepDirectionFlag	Set to 1 if the arc is drawn in a positive-angle direction; otherwise, set to 0.
endPoint	System.Windows.Point The point to which the arc is drawn.

The Close Command

Ends the current figure and creates a line that connects the current point to the starting point of the figure. This command creates a line-join (corner) between the last segment and the first segment of the figure.

Syntax

Syntax
`Z` - or - `z`

Z

- or -

z

Point Syntax

Describes the x- and y-coordinates of a point.

Syntax

Syntax
x `,` y - or - x y

x , y

- or -

x y

Term	Description
x	System.Double The x-coordinate of the point.
y	System.Double The y-coordinate of the point.

System.Double

The x-coordinate of the point.

System.Double

The y-coordinate of the point.

Special Values

Instead of a standard numerical value, you can also use the following special values. These values are case-sensitive.

Ininity
Represents System.Double.PositiveInfinity.

-Infinity
Represents System.Double.NegativeInfinity.

NaN
Represents System.Double.NaN.

You may also use scientific notation. For example, +1.e17 is a valid value.

Condividi tramite

Path Markup Syntax

Prerequisites

StreamGeometry and PathFigureCollection Mini-Languages

A Note about White Space

Syntax

Move Command

Draw Commands

Line Command

Horizontal Line Command

Vertical Line Command

Cubic Bezier Curve Command

Quadratic Bezier Curve Command

Smooth cubic Bezier curve Command

Smooth cubic Bezier curve Command

Elliptical Arc Command

The Close Command

Point Syntax

Special Values

See Also

Reference

Concepts

Other Resources

Risorse aggiuntive