Share via


Path Class

Defines the Path Class.When the object is serialized out as xml, its qualified name is v:path.

Inheritance Hierarchy

System.Object
  DocumentFormat.OpenXml.OpenXmlElement
    DocumentFormat.OpenXml.OpenXmlLeafElement
      DocumentFormat.OpenXml.Vml.Path

Namespace:  DocumentFormat.OpenXml.Vml
Assembly:  DocumentFormat.OpenXml (in DocumentFormat.OpenXml.dll)

Syntax

'Declaration
Public Class Path _
    Inherits OpenXmlLeafElement
'Usage
Dim instance As Path
public class Path : OpenXmlLeafElement

Remarks

[ISO/IEC 29500-1 1st Edition]

14.1.2.14 path (Shape Path)

This element defines the path that makes up the shape. This is done through a string that contains a rich set of pen movement commands.  This element also describes the limo-stretch point, inscribed textbox rectangle locations and connection site locations.  The limo-stretch definition and the formulas element (§14.1.2.6) allow greater designer control of how the path scales.  [Example: They allow, for example, definition of a true rounded corner rectangle where the corners remain circular even though the rectangle is scaled anisotropically. end example]

Parent Elements

arc (§14.1.2.1); background (Part 1, §17.2.1); curve (§14.1.2.3); group (§14.1.2.7); image (§14.1.2.10); line (§14.1.2.12); object (Part 1, §17.3.3.19); oval (§14.1.2.13); pict (§9.2.2.2); pict (§9.5.1); polyline (§14.1.2.15); rect (§14.1.2.16); roundrect (§14.1.2.17); shape (§14.1.2.19); shapetype (§14.1.2.20)

Attributes

Description

arrowok (Arrowhead Display Toggle)

Specifies whether arrowheads are allowed to be displayed. This attribute overrides all other arrowhead attributes in the parent or the stroke element (§14.1.2.21). Default is false.

[Example:

<v:shape style="width:50;height:50">
  <v:stroke endarrow="block"/>
  <v:path arrowok="true" 
    v="m 0,0 l 1000,0 1000,1000 e"/>
</v:shape>
DocumentFormat.OpenXml.Vml.Path-image001

end example]

The possible values for this attribute are defined by the ST_TrueFalse simple type (§15.1.2.5).

connectangles (Connection Point Connect Angles)

Namespace: urn:schemas-microsoft-com:office:office

Specifies the angle at which curves connect to a shape's connection points. The connection angles are defined by a string consisting of angle values delimited by commas. Default is no value.

[Example: Connections are made along the horizontal and vertical axes:

<v:path … o:connectangles="0,90,180,270" … >
</v:path>

end example]

The possible values for this attribute are defined by the W3C XML Schema string datatype.

connectlocs (Connection Points)

Namespace: urn:schemas-microsoft-com:office:office

Specifies the location of connection points on a path. The connection points are defined by a string consisting of pairs of x and y values, delimited by commas. This is used if connecttype is custom. Default is no value.

[Example: Connection points exist at the midpoints of the sides of the square:

<v:path … v="m 0,0 l 100,0 100,100 0,100 x e"
  o:connectlocs="50,0;100,50;50,100;0,50" … >
</v:path>

end example]

The possible values for this attribute are defined by the W3C XML Schema string datatype.

connecttype (Connection Point Type)

Namespace: urn:schemas-microsoft-com:office:office

Specifies the kind ofconnection points used for attaching shapes to other shapes. Default is none. If set to custom, connectlocs is used. Allowed values are:

[Example:

<v:path … o:connecttype="custom"
  o:connectlocs="50,0;100,50;50,100;0,50" … >
</v:path>

end example]

The possible values for this attribute are defined by the ST_ConnectType simple type (§14.2.3.8).

extrusionok (Extrusion Toggle)

Namespace: urn:schemas-microsoft-com:office:office

Specifies whether an extrusion is allowed to be displayed. This attribute overrides all other extrusion attributes in the parent or the extrusion element (§14.2.2.11). Default is true.

[Example:

<v:rect fillcolor="lime"
  style="width:50;height:50">
  <v:extrusion on="true"/>
  <v:path o:extrusionok="false"/>
</v:rect>
DocumentFormat.OpenXml.Vml.Path-image002DocumentFormat.OpenXml.Vml.Path-image003

end example]

The possible values for this attribute are defined by the ST_TrueFalse simple type (§15.1.2.5).

fillok (Shape Fill Toggle)

Specifies whether a fill is allowed to be displayed. This attribute overrides all other fill attributes in the parent or fill element (§14.1.2.5). Default is true.

[Example:

<v:shape style="width:50;height:50"
  fillcolor="red">
  <v:path fillok="false"
  v="m 0,0 l 0,1000, 1000,1000, 1000,0 x e"/>
</v:shape>
DocumentFormat.OpenXml.Vml.Path-image004

end example]

The possible values for this attribute are defined by the ST_TrueFalse simple type (§15.1.2.5).

gradientshapeok (Gradient Shape Toggle)

Specifies whether a gradient path is made up of repeated concentric paths. Default is false.

If true, a gradient fill can be produced by repeated drawing of scaled versions of the path - this shall only be set if it is possible to scale the path in such a way that a fill is always contained in the original path.  This controls the interpretation of the type="gradientradial" attribute of the fill element (§14.1.2.5).

[Example: In the first case, the radial gradient is aligned irrespective of the shape's path:

<v:shape style="width:50;height:50;rotation:45"
  path="m 0,0 l 0,1000, 1000,1000, 1000,0 x e">
  <v:path gradientshapeok="false"/>
  <v:fill type="gradientradial"
    color="red" color2="blue"/>
</v:shape>
DocumentFormat.OpenXml.Vml.Path-image005DocumentFormat.OpenXml.Vml.Path-image006

end example]

The possible values for this attribute are defined by the ST_TrueFalse simple type (§15.1.2.5).

id (Unique Identifier)

Specifies a unique identifier that can be used to reference a VML object.

Default is no value.

[Example:

<v:shape … id="myShape" … >
</v:shape>

end example]

The possible values for this attribute are defined by the W3C XML Schema string datatype.

insetpenok (Inset Stroke From Path Flag)

Specifies whether the stroke can be inset from the path. If this is false, it overrides the insetpen attribute and prevents the stroke from being inset.

[Example: The stroke is not inset:

<v:shape … insetpen="true">
  <v:path … insetpenok="false"/>
</v:shape>

end example]

The possible values for this attribute are defined by the ST_TrueFalse simple type (§15.1.2.5).

limo (Limo Stretch Point)

Specifies a stretch point on the shape's edge that defines where and how a shape is allowed to be stretched by a user in a graphical editor. Default is "0,0".

[Example:

<v:line from="20pt,20pt" to="100pt,20pt">
  <v:path limo="60pt,20pt"/>
</v:line>

end example]

The possible values for this attribute are defined by the W3C XML Schema string datatype.

shadowok (Shadow Toggle)

Specifies whether a shadow is allowed to be displayed. This attribute overrides all other shadow attributes in the parent or the shadow element (§14.1.2.18). Default is true.

[Example: The shape has no shadow:

<v:shape style="width:50;height:50">
  <v:path v="m 0,0 l 0,1000, 1000,1000, 1000,0 x e"
    shadowok="false"/>
  <v:shadow on="true"/>
</v:shape>

end example]

The possible values for this attribute are defined by the ST_TrueFalse simple type (§15.1.2.5).

strokeok (Stroke Toggle)

Specifies whether a stroke is displayed. This attribute overrides all other stroke attributes in the parent or the stroke element (§14.1.2.21). Default is true.

[Example: The shape's red stroke is not shown:

<v:shape style="width:50;height:50"
  fillcolor="blue" strokecolor="red">
  <v:path v="m 0,0 l 0,1000, 1000,1000, 1000,0 x e"
    strokeok="false"/>
</v:shape>
DocumentFormat.OpenXml.Vml.Path-image007

end example]

The possible values for this attribute are defined by the ST_TrueFalse simple type (§15.1.2.5).

textboxrect (Text Box Bounding Box)

Specifies one or more text boxes inside a shape. Default is the same as the geometry's bounding box.

A textbox is defined by one or more sets of numbers specifying (in order) the left, top, right, and bottom points of the rectangle. Multiple sets are delimited by a semicolon. The default value is the same dimension value as the containing rectangle. If more than one textbox is defined, the comma-delimited quadruple sets that define each textbox are separated by semicolons. Normally textboxes come in sets of 1, 2, 3, or 6 rectangles on a shape. The textboxrect dimensions clip any text that extends beyond its region.

[Example: The textbox is 25% down from the top and the exclamation point is clipped:

<v:shape style="width:60;height:50">
  <v:path v="m 0,0 l 0,1000, 1000,1000, 1000,0 x e"
    textboxrect="0,250,850,1000"/>
  <v:textbox>VML!</v:textbox>
</v:shape>
DocumentFormat.OpenXml.Vml.Path-image008

end example]

The possible values for this attribute are defined by the W3C XML Schema string datatype.

textpathok (Text Path Toggle)

Specifies whether a text path is displayed. Default is false.

If true, this indicates that the path is an appropriate warping path for the textpath element (§14.1.2.23).  Otherwise, the textpath element shall be ignored.

[Example: The defined textpath is ignored:

<v:curve from="50,100" to="400,100"
control1="200,200" control2="300,200">
  <v:path textpathok="false"/>
  <v:textpath on="false" style="font:normal normal 
    normal 36pt Arial" string="textpath"/>
</v:curve>
DocumentFormat.OpenXml.Vml.Path-image009

end example]

The possible values for this attribute are defined by the ST_TrueFalse simple type (§15.1.2.5).

v (Path Definition)

Specifies a string containing the commands that define the shape's path. This value consists of commands followed by zero or more parameters. Default is no value.

The following rules apply to path strings:

  • Commas or spaces delimit parameters for each command.  Both "m 0,0" and "m0 0" are acceptable.

  • A parameter that is omitted using commas is treated as having a value of zero. Thus, "c 10,10,0,0,25,13" and "c 10,10,,,25,13" are equivalent.

  • Parameterized paths are also allowed. In this case, the shape shall also have a formulas element (§14.1.2.6) with a list of formulas that are substituted into the path using the @ symbol followed by the number of the formula. The adj property of the shape contains the input parameters for these formulas.  [Example: For example, "moveto @1@4". end example]   The evaluations of the formulas are substituted into the appropriate positions.  The @ character also serves as a delimiter.

The allowed commands are given below. An asterisk (*) indicates that the command is allowed to be repeated. For the qb command, the controlpoint parameter is also allowed to be repeated.

Command

Name

Parameters

Description

m

moveto

2

Start a new sub-path at the given (x,y) coordinate.

l

lineto

2*

Draw a line from the current point to the given (x,y) coordinate which becomes the new current point. Specifying a number of coordinate pairs forms a polyline.

c

curveto

6*

Draw a cubic bézier curve from the current point to the coordinate given by the final two parameters. The control points are given by the first four parameters.

x

close

0

Close the current sub-path by drawing a straight line from the current point to the original moveto point.

e

end

0

End the current set of sub-paths. A given set of sub-paths (as delimited by end) is filled. Subsequent sets of sub-paths are filled independently and superimposed on existing ones.

t

rmoveto

2*

Start a new sub-path at a coordinate relative to the current point, cp (cpx+x, cpy+y).

r

rlineto

2*

Draw a line from the current point to the given relative coordinate (cpx+x, cpy+y).

v

rcurveto

6*

Cubic bézier curve using the given coordinate relative to the current point.

nf

nofill

0

The current set of sub-paths (delimited by e) is not filled.

ns

nostroke

0

The current set of sub-paths (delimited by e) is not stroked.

ae

angleellipseto

6*

Draws a segment of an ellipse as described using these parameters. A straight line is drawn from the current point to the start point of the segment. The parameters are: center (x,y), size(w,h), start angle, end angle.

al

angleellipse

6*

Same as angleellipseto except that there is an implied moveto the starting point of the segment.

at

arcto

8*

A segment of the ellipse is drawn which starts at the angle defined by the start radius vector and ends at the angle defined by the end vector. A straight line is drawn from the current point to the start of the arc. The arc is always drawn in a counterclockwise direction. The parameters are: left, top, right, bottom, start(x,y), end(x,y). The first four values define the bounding box of an ellipse. The last four define two radial vectors.

ar

arc

8*

Same as arcto except there is an implied moveto the start point of the arc.

wa

clockwisearcto

8*

Same as arcto but the arc is drawn in a clockwise direction.

wr

clockwisearc

8*

Same as arc but the arc is drawn in a clockwise direction

qx

ellipticalqaudrantx

2*

A quarter ellipse is drawn from the current point to the given end point. The elliptical segment is initially tangential to a line parallel to the x-axis. (i.e. the segment starts out horizontal). The parameters are: end(x,y).

qy

ellipticalquadranty

2*

Same as ellipticalquadrantx except that the elliptical segment is initially tangential to a line parallel to the y-axis (i.e. the segment starts out vertical).

qb

quadraticbezier

2+2*

Defines one or more quadratic bézier curves by means of control points and an end point.  Intermediate (on-curve) points are obtained by interpolation between successive control points as in the OpenType font specification.  The sub-path need not be started in which case the sub-path is closed.  In this case the last point of the sub-path defines the start point of the quadratic bézier. The parameters are: controlpoint(x,y)*, end(x,y).

The possible values for this attribute are defined by the W3C XML Schema string datatype.

[Note: The W3C XML Schema definition of this element’s content model (CT_Path) is located in §A.6.1. end note]

© ISO/IEC29500: 2008.

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

See Also

Reference

Path Members

DocumentFormat.OpenXml.Vml Namespace