Edit

VML Object Model Reference

  • Article

This topic describes VML, a feature that is deprecated as of Windows Internet Explorer 9. Webpages and applications that rely on VML should be migrated to SVG or other widely supported standards.

Note

As of December 2011, this topic has been archived. As a result, it is no longer actively maintained. For more information, see Archived Content. For information, recommendations, and guidance regarding the current version of Windows Internet Explorer, see Internet Explorer Developer Center.

In this topic:

Introduction

Vector Markup Language (VML) is a text-based language that uses XML to extend HTML for the purpose of displaying vector graphic information. The VML Document Object Model (DOM) defines a programmatic interface for the manipulation of the document elements. This enables the user to dynamically create and modify vector graphics through a platform- and language-neutral interface. The VML DOM conforms to the Document Object Model specification.

VML uses the Shape element as the basic building block for vector graphic images. Once a shape is created, you can modify the shape through attributes or by attached subelements. For example, to change the color of a shape, assign a color value to the FillColor attribute.

myshape.fillcolor = "red"

Several of the attributes of a shape are also subelements and have their own attributes, including the following:

The VML OM uses several data types to define parameters. Datatypes prefixed with "Vg" are enumerations and those prefixed with "IVg" are objects. Click here for a list. Minor datatypes are listed with specific parameters.

Example

The following VBScript code shows how to create a simple shape:

        Set MyRect = Document.CreateElement("v:Rect")
        Set R = MyDiv.AppendChild(MyRect)
        R.Style.Position = "absolute"
        R.Style.Width = 20
        R.Style.Height = 20
        R.Style.Top = 50
        R.Style.Left = 50
        R.FillColor = "red"

In the above example, a shape is created by using the Document Object Model method CreateElement. The shape is a VML predefined Rect shape. Even though the object exists, it cannot be part of the document until it is attached to the document. Using the AppendChild method, the Rect is made a child of a DIV element called MyDiv. A few minimum style attributes (Position, Width, Height, Top, Left) are set to give the shape a specific size. Finally, a color is assigned with the FillColor attribute. Note that any scripting language or any language that can work with Document Object Model interfaces can be used.

Setting up VML

One implementation of VML is through Microsoft Internet Explorer 5.0 or greater. To set up the rendering object correctly in a Web page, the following additions must be made:

  1. The schema must be set up in the initial <HTML> tag as follows:

    <HTML xmlns:v="urn:schemas-microsoft-com:vml">

  2. The rendering behavior must be part of the document's style:

    <STYLE>
v\:* { behavior: url(#default#VML); display:inline-block}
</STYLE>

The following shows a sample HTML Web page set up correctly for VML showing the dynamic creation of a shape.

<HTML xmlns:v="urn:schemas-microsoft-com:vml">
<HEAD>
<STYLE>
v\:* { behavior: url(#default#VML); display:inline-block}
</STYLE>
<TITLE>VML Sample</TITLE>
</HEAD>
<BODY>
<DIV id="MyDiv"></DIV>
<SCRIPT ID="MYSCRIPT" LANGUAGE="VBScript">
<!--
Set MyRect = Document.CreateElement("v:Rect")
Set R = MyDiv.AppendChild(MyRect)
R.Style.Position = "absolute"
R.Style.Width = 20
R.Style.Height = 20
R.Style.Top = 50
R.Style.Left = 50
R.FillColor = "red"
-->
</SCRIPT>
</BODY>
</HTML>

Note that in beta versions, an ActiveX object tag and a different behavior style was required.

VML OM Reference

This reference defines the Shape element, subelements, and data types that are used by the object model of VML.

Shape element

Shapes are the building blocks of graphical images defined by Vector Markup Language (VML). The shape is the top-level element and several subelements help define the nature of each shape.

VML provides predefined shapes:

Shape Attributes

  • Arc
  • Curve
  • Line
  • PolyLine
  • Rect
  • RoundRect
Subelement Description
Adj IVgAdjustments. A comma-delimited list of numbers that are the parameters for the guide formulas that define the path of the shape. Values may be omitted to allow for using defaults. There can be up to 8 adjustment values.
Alt String. Alternative text associated with shape. Used for non-graphical browsing.
Button VgTriState. Displays button behavior on click.
BWMode VgBlackWhiteMode. Determines how shape will render in black-and-white view in apps or when printed to black-and-white printers. Values include: Color, Auto, GrayScale, LightGrayScale, InverseGray, GrayOutline, BlackTextAndLines, HighContrast, Black, White, Undrawn. Default: Auto.
BWNormal VgBlackWhiteMode. When BWMode is Auto, this property is consulted for how to render the shape in normal black and white. Values include: Color, Auto, GrayScale, LightGrayScale, InverseGray, GrayOutline, BlackTextAndLines, HighContrast, Black, White, Undrawn. Default: Auto.
BWPure VgBlackWhiteMode. When BWMode is Auto, this property is consulted for how to render the shape in pure B/W. Values include: Color, Auto, GrayScale, LightGrayScale, InverseGray, GrayOutline, BlackTextAndLines, HighContrast, Black, White, Undrawn. Default: Auto.
ChildShapes IVgGroupShapes. A collection of other shapes in this group. This collection supports the standard Length and Item methods.
Chromakey IVgColor. A color value that will be transparent and show anything behind the shape.
Control1 Vector2D. Control point for curve.
Control2 Vector2D. Control point for curve.
CoordOrigin Vector2D The coordinates at the top left corner of the container rectangle. Range from 0 to infinity.
CoordSize Vector2D. The width and height of the coordinate space inside the reference rectangle of this shape. If it is not specified, it is the same as the width and height of the rectangle. Range from 0 to infinity. Default: "1000,1000".
EndAngle VgAngleInDegrees. End angle of shape.
Extrusion IVgExtrusion. Specifies the Extrusion object value for this shape. See the Extrusion element for details.
Fill VgFillFormat. Specifies the fill value for this shape. See the Fill element for more details.
FillColor IVgColor. The primary color of the brush to use to fill the path of this shape.
Filled VgTriState. If True, the path defining the shape will be filled. By default, it will be filled using a solid color unless there is a Fill subelement that specifies more complex fill properties. If False, the fill is transparent.
Flip VgFlipOrientation. Values are: X Y XY YX
ForceDash VgTriState. Indication that a dashed outline should be rendered when there is no line and no fill for a shape. This behavior is generally useful for making invisible shapes visible in editing applications so they can be selected and operated on, such as in an image map.
Formulas IVgFormulas. An array of formulas that defines a shape.
From Vector2D. Starting point of line.
HRef String. The URL to jump to if this shape is clicked.
ImageData IVgImageData. Image information if the shape is a picture. See the ImageData element for more information.
OnEd VgTriState. Hides all handles except the top left and bottom right, as in the handles for a straight line segment.
Opacity VgFraction. The opacity of the entire shape. A number between 0.0 and 1.0.
Path IVgPath. A string containing the commands that define the path.
Points IVgPoints. A collection of points defining a shape.
Print VgTriState. If True, this shape is meant to be printed.
Rotation VgAngleInDegrees. Sets rotation of shape. Value is propagated to the shape style.
Scale Vector2D. Scale of shape.
Shadow IVgShadow. Specifies the shadow for this shape. See the Shadow element for details.
Spt Reserved.
StartAngle VgAngleInDegrees. Start angle of shape.
Stroke VgStrokeFormat. See Stroke element for details.
StrokeColor IVgColor. The primary color of the brush to use to stroke the path of this shape.
Stroked VgTriState. If True, the path defining the shape will be stroked.
StrokeWeight VGLength. The width of the brush to use to stroke the path. Ranges between 0 and 1584.
TextPath IVgTextPath. Specifies the TextPath object of the shape. See the TextPath element for more information.
To Vector2D. End point of line.
Type String. Type of shape.

Subelements of the Shape Element

The following subelements are part of the VML object model.

Background element

Describes the fill of the background of a page using VML fills.

Attribute Description
BWMode VgBlackWhiteMode. Determines how shape will render in black-and-white view in applications or when printed.
BWNormal VgBlackWhiteMode. When BWMode is Auto, this property is consulted for how to render the shape in normal black and white.
BWPure VgBlackWhiteMode. When BWMode is Auto, this property is consulted for how to render the shape in pure black and white.
Fill VgFillFormat. Specifies the fill for this shape. See Fill element for more information.
FillColor IVgColor. The primary color of the brush to use to fill the path of this shape. Duplicate of the Color value in the Fill element. The default is white.

Extrusion element

Describes a 3-D extrusion of the shape.

Attributes

AutoRotationCenter VgTriState. If True, the center of rotation of the group of 3-D objects (in fact there is only ever one object in the group) is determined automatically to be the center of the group; otherwise it is determined by the RotationCenter parameters, which are a fraction of the shape with 0,0,0 being the center.
BackDepth VgLength. Amount of backward extrusion. Ranges from 0 to 32767.
Brightness VgPositiveNumber. Overall brightness of the scene. Default is "20,000".
Color IVgColor. The color of the extrusion. Only used if ColorMode is Custom. Otherwise, Auto sets the extrusion effect color to the same as FillColor.
ColorMode Vg3DColorMode. Values are:
  • Auto (default)
  • Custom
Diffusity VgPositiveNumber. The ratio of incident to diffusely reflected light. Values less than 1.0 are normal but values higher than one can generate interesting effects.
Edge VgLength. Sets the size of a simulated rounded beveled edge. Ranges from 0 to 32767 in floating point pts. Default is "1pt".
Facet VgPositiveNumber. Sets the facet of the scene. Default is "30,000".
ForeDepth VgLength. Amount of forward extrusion. Ranges from 0 to 32767.
LightFace VgTriState. Determimes whether the front face of the object will respond to changes in the 3-D lighting, e.g., when an object rotates.
LightHarsh VgTriState. Harsh lighting for the primary light source. Default is False.
LightHarsh2 VgTriState. Harsh lighting for the secondary light source. Default is False.
LightLevel VgNumber. Intensity of the primary light source. Default is "38000".
LightLevel2 VgNumber. Intensity of the secondary light source. Default is "38000".
LightPosition Vector3D. Position of the primary light source. Default is "50000,0,10000".
LightPosition2 Vector3D. Position of the secondary light source. Default is "-50000,0,10000".
LockRotationCenter VgTriState. "Lockrotationcenter" means that the rotation of the group is defined to be by rotation-angle[1] degrees about the y-axis on the page followed by rotation-angle[0] degrees about the x-axis. When LockRotationCenter is False, the rotation is defined to be by orientation-angle degrees about the vector defined by orientation. So, for example, lockrotationcenter=false orientationangle=45 orientation=(0,1,0) is equivalent to lockrotationcenter=true rotationangle=(0,45).
Metal VgTriState. Causes specularly reflected light to be the material color instead of the light source color, making the object seem more metallic.
On VgTriState. Turns the display of the extrusion effect on and off.
Orientation Vector3D. Orientation of the camera.
OrientationAngle VgAngleInDegrees. Angle between the orientation of the camera and the xy plane.
Plane Vg3DExtrudePlane. Allows extrusion from planes orthogonal to the screen plane. Requires ForeDepth and BackDepth to be specified in drawing units instead of emus. Values are:
  • XY
  • ZX
  • YZ
Render Vg3DRenderMode. Values are:
  • Solid (default)
  • WireFrame
  • BoundingCube
RotationAngle Vector2D. AngleX, AngleY, or AngleZ is controlled by the ShapeRotation attribute.
RotationCenter Vector3D. Center of rotation.
Shininess VgPositiveNumber. Determines how concentrated or spread out specular reflection is. A high value would be 8 to 10 and would approximate a mirror, and a low value would be 2 to 3 and would approximate sequined clothing. Values of 3 to 7 are recommended. High values will reflect pinpoint light sources.
SkewAmt VgPercentage. If Type is Parallel, attribute determines the amount of skew. Ranges from 0 to 100.
SkewAngle VgAngleInDegrees. If Type is Parallel, attribute determines the degree of skew. Default is "-45".
Specularity VgPositiveNumber. The ratio of incident to specularly reflected light. Values less than 1.0 are normal but values higher than one can generate interesting effects.
Type VgExtrusionType. Values are:
  • Parallel (default)
  • Perspective
Viewpoint Vector3D. The point where the scene is being viewed from.
ViewpointOrigin Vector2D. Can have values from 0.5 to -0.5 to position the origin of the viewpoint within the shape bounding box.

Fill element

Describes how a path should be filled for fills more complex than a solid color.

Attributes

AlignShape VgTriState. Align the image with the shape. If False, align image with window.
Angle VgAngleInDegrees. The angle along which the gradient goes. 0 degrees is along the horizontal axis from left to right.
Aspect VgAspectType. ImageSize attribute will be adjusted to preserve the aspect of the image. Values include:
Value Description
Ignore Ignore aspect issues.
AtLeast Image is at least as big as the image size.
AtMost Image is no bigger than image size.

Color IVgColor The main fill color. Same as FillColor attribute in shape.
Color2 IVgColor. The secondary color for a fill when image type is Pattern or a gradient fill.
Colors IVgGradientColorArray. Intermediate colors in the gradient and their relative positions along the gradient, e.g., "30% red, 70% blue, 90% green". Primary color (Color attribute in shape) is 0% and secondary color (Color2 attribute) is 100%.
Focus VgSignedPercentage. Focal point for linear gradient fill. Values go from -100 to +100.
FocusPosition Vector2D. Position of the innermost rectangle for radial gradients. The vector is a fraction (0.0 - 1.0) of the shape's width and height.
FocusSize Vector2D Size of the innermost rectangle for radial gradients. The vector is a fraction (0.0 to 1.0) of the shape's width and height.
Method VgSigmaType. Values include:
  • None
  • Linear
  • Sigma
  • Any

Default is Sigma.
On VgTriState. Turns fill display on. Same as Fill attribute in shape.
Opacity VgFraction. Opacity of the fill.
Opacity2 VgFraction. The secondary opacity for gradients.
Origin Vector2D. Point relative to upper left corner of the image that is treated as the origin of the image. Default is the center of the image. The vector is a fraction (from 0.0 to 1.0) of the image's width and height.
Position Vector2D. Point in the reference rectangle of the shape to position the origin of the image. Default is the center of the container rectangle. The vector is a fraction (0.0 - 1.0) of the image's width and height.
Size Vector2D. The size of the image. Default is pixel size of the image. May be specified in absolute coordinates or percentage.
Src String. URL to an image to load for image and pattern fills. This attribute must always be present and point to valid image data for a picture to appear.
Type VgFillType. May be one of the following types:
  • Background
  • Frame
  • Gradient
  • GradientCenter
  • GradientRadial
  • GradientTitle
  • GradientUnscaled
  • Pattern
  • Solid
  • Tile
Tile, Pattern, and Frame require the image attributes to be supplied. Gradient and GradientRadial require the gradient attributes to be supplied.

Group element

A group is a collection of individual shapes that can be positioned and transformed as a unit.

Attribute Description
Item IVgShape. Specified item in the array of shapes.
Length Integer. Number of shapes in this group.

Imagedata element

Describes a picture to be rendered on top of a shape.

Attribute Description
BiLevel VgTriState. Display picture in only two colors (usually black and white).
BlackLevel VgFraction. Allows adjustment to set the level so that blacks appear as true blacks, and all other colors are visible as shades above black.
Chromakey IVgColor. Transparent color of picture.
CropBottom VgNumber. Crop distance from bottom of picture expressed as a percentage of picture size.
CropLeft VgNumber. Crop distance from left edge of picture expressed as a fraction of picture size (from 0.0 to 1.0). However, "out-cropping" is supported and thus values of less than 0 and greater than 1 are supported; e.g., -5, 20 would out-crop the bounds 25X the picture size with 4/5 on one side of the picture.
CropRight VgNumber. Crop distance from right of picture expressed as a percentage of picture size.
CropTop VgNumber. Crop distance from top of picture expressed as a percentage of picture size.
EmbossColor IVgColor. This is set to a percentage of the shadow color to create an embossed picture effect.
Gain VgPositiveNumber. Adjusts the intensity of all colors. Essentially sets how bright white will be. Ranges from 0 to 32767.
Gamma VgFraction. Gamma correction. Increasing it gives an image more contrast.
GrayScale VgTriState. Display picture in grayscale colors.
Src String. URL to an image to load for image and pattern fills. This attribute must always be present and point to valid image data for a picture to appear.

Path element

Defines the path that makes up the shape, using a string that contains a rich set of "pen movement" commands.

Limo IVgVector2D. Defines the point where the shape is stretched; e.g., for a giraffe shape, the limo point would be on the neck so when the shape is resized, the neck will stretch and the rest of the shape will maintain its dimensions.
TextBoxRect IVgFixedRectangleArray. Array containing the rectangles that define where text should go.
V String. Matches the v attribute on the Path tag. Note that path may correspond to Path attribute or element.
Value String. A text representation of the commands that define the path. X or y-coordinate values can be a reference to a formula in the form "@#" where # is the formula's ordinal number, e.g., "@2". This attribute string is made up of a rich set of commands including the following:
Command Description
ae (angleellipseto) center(x,y) size(w,h) start-angle, end-angle
Draw a segment of an ellipse. A straight line is drawn from the current point to the start point of the segment.
al (angleelipse) Same as ae except that there is an implied m to the starting point of the segment.
ar (arc) Same as at. However, a new subpath is started by an implied m to the start point of the arc.
at (arcto) 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. A segment of the ellipse is drawn that 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.
c (curveto) control1(x,y) control2(x,y) to(x,y)
Draw a cubic bezier curve from the current point to the coordinate given by the final two parameters, the control points given by the first four parameters. The current point becomes the endpoint of the bezier.
e (end) End the current set of subpaths. A given set of subpaths (as delimited by end) are filled using eofill. Subsequent sets of subpaths are filled independently and superimposed on existing ones.
l (lineto) x,y
Draw a line from the current point to the given x,y-coordinate, which becomes the new current point. Additional coordinate pairs may be specified to form a polyline, e.g., "l 10,13,45,27,89,-12".
m (moveto) x,y
Start a new subpath at the given x,y-coordinate.
nf (nofill) The current set of subpaths (delimited by end) will not be filled.
ns (nostroke) The current set of subpaths (delimited by end) will not be stroked.
qb (quadraticbezier) (controlpoint(x, y))*,end(x,y)
Defines one or more quadratic bezier curves by means of control points and an endpoint. Intermediate (on-curve) points are obtained by interpolation between successive control points similar to TrueType fonts. The subpath need not be a start, in which case the subpath is closed and the last point defines the start point.
qx (ellipticalquadrantx) end(x,y)
A quarter ellipse is drawn from the current point to the given endpoint. The elliptical segment is initially tangential to a line parallel to the x-axis; i.e., the segment starts out horizontal.
qy (ellipticalquadranty) end(x,y)
Same as qx except that the elliptical segment is initially tangential to a line parallel to the y-axis; i.e., the segment starts out vertical.
r (rlineto) x,y
Draw a line from the current point to the relative coordinate (cpx + x, cpy + y). If additional coordinate pairs are given, each new point is computed relative to the last one.
t (rmoveto) x,y
Start a new subpath at the relative coordinates ( cpx + x, cpy + y) where cpx, cpy is the current position.
v (curveto) control1(x,y) control2(x,y) to (x,y)
Cubic bezier curve using the given coordinates relative to the current point. All the points are computed relative to the same starting point.
wa (clockwisearcto) Same as at but the arc is drawn in a clockwise direction.
wr (clockwisearc) Same as ar but is drawn in a clockwise direction.
x (close) Close the current subpath by drawing a straight line from the current point to the original moveto point.

Shadow element

Describes a shadow effect on a shape.

Color IVgColor. Color of the primary shadow. Default is RGB(128,128,128)
Color2 IVgColor. Color of the second shadow, or highlight in an embossed or engraved shadow. Default is RGB(203,203,203).
Matrix IvgSkewMatrix. A perspective transform matrix in the form, "sxx,sxy,syx,syy,px,py" [s=scale, p=perspective]. The s items specify how the shadow should scale with respect to the shape, and the p items specify how the shadow should skew with respect to the shape. For example, the following matrix resizes the shape by a factor of 2 and skews it by a factor of 4 in all directions:
"2,2,2,2,4,4"
This matrix is only used if the type of the shadow is set to perspective.
Obscured VgTriState. The shadow can be seen through if there is no fill on the shape. Default is False.
Offset IVgSkewOffset. Amount of x,y offset from the shape's location. Default is "2pt,2pt".
Offset2 Vector2D. Amount of x,y second offset from the shape?s location. Values are either an absolute measurement, or a fractional value of shape (-0.5 to +0.5).
On VgTriState. Turns the display of the shadow on and off.
Opacity VgFraction. Opacity of the shadow effect.
Origin Vector2D A pair of fractional values of shape from -0.5 to +0.5.
Type VgShadowType. Values are:
  • Single (default)
  • Double
  • Perspective
  • ShapeRelative
  • DrawingRelative
  • Emboss

Skew element

Describes a perspective skew effect on a shape. The skew is applied to vector graphic data, not image data.

Attribute Description
Matrix IVgSkewMatrix. A perspective transform matrix in the form, "sxx,sxy,syx,syy,px,py" [ s=scale, p=perspective]. If offset is in absolute units then px,py are in emu ^ -1 units; otherwise they are an inverse fraction of shape size.
Offset IvgSkewOffset. Amount of x,y offset from the shape's location. Default is "2pt,2pt".
On VgTriState. Turns the display of the skew on or off.
Origin Vector2D. A pair of fractional values of shape from -0.5 to +0.5.

Stroke element

Describes how to draw the path if something beyond a solid line with a solid color is desired.

Color VgTriState. The color of the line. Same as StrokeColor attribute in Shape but overrides it.
Color2 IVgColor. Secondary color. Used when FillType is Pattern.
DashStyle VgLineDashStyle. Dash style format. May be a specific value or a sequence of numbers with a user-defined dash pattern. Values are:
  • Solid (default)
  • ShortDash
  • ShortDot
  • ShortDashDot
  • ShortDashDotDot
  • Dot
  • Dash
  • DashDot
  • LongDash
  • LongDashDot
  • LongDashDotDot
EndArrow VgArrowheadStyle. Arrowhead for the end of the line. Values are:
  • None (default)
  • Block
  • Classic
  • Diamond
  • Oval
  • Open
  • Chevron
  • DoubleChevron
EndArrowLength VgArrowHeadLength. Arrowhead length for the end of the line. Values are:
  • Short
  • Medium (default)
  • Long
EndArrowWidth VgArrowheadWidth. Arrowhead width for the end of the line. Values are:
  • Narrow
  • Medium (default)
  • Wide
EndCap VgLineEndCapStyle. Values are:
  • Flat
  • Square
  • Round
FillType VgLineFillType. Values are:
  • Solid (default)
  • Tile
  • Pattern
  • Frame
ImageAlignShape VgTriState. Align the image with the shape. If False, align image with window.
ImageAspect VgAspectType. ImageSize attribute will be adjusted to preserve the aspect of the image. Values include:
Value Description
Ignore Ignore aspect issues.
AtLeast Image is at least as big as the image size.
AtMost Image is no bigger than image size.

ImageSize Vector2D. Size of the image to form the brush with. Default is the size of the image.
JoinStyle VgLineJoinStyle. Values are:
  • Round (rounded joint)
  • Bevel (beveled joint)
  • Miter (miter joint)
LineStyle VgLineStyle. Values are:
  • Single
  • ThinThin (1:1:1)
  • ThinThick (1:1:2)
  • ThickThin (2:1:1)
  • ThickBetweenThin (1:1:2:1:1)
MiterLimit Length. The maximum distance between the inner point and outer point of a joint. This number is a multiple of the thickness of the line. Ranges from 0 to 32,767.
On VgTriState. Turns the display of the line on and off. Same as Stroke attribute in Shape but overrides it.
Opacity VgFraction. Opacity of the stroke.
Src String. URL to an image to load for image and pattern fills. This attribute must always be present and point to valid image data for a picture to appear.
StartArrow VgArrowheadStyle. Arrowhead for the start of the line. Values are:
  • None (default)
  • Block
  • Classic
  • Diamond
  • Oval
  • Open
  • Chevron
  • DoubleChevron
StartArrowLength VgArrowHeadLength. Arrowhead length for the start of the line. Values are:
  • Short
  • Medium (default)
  • Long
StartArrowWidth VgArrowheadWidth. Arrowhead width for the start of the line. Values are:
  • Narrow Medium (default) Wide
Weight VgLength. Width of line. Ranges from 0 to 1584.

Note:
The DashStyle attribute allows the user to specify a custom-defined dash pattern. This is done using a series of numbers. Dash styles are defined in terms of the length of the dash (the drawn part of the stroke) and the length of the space between the dashes. The lengths are relative to the line width; a length of "1" is equal to the line width. The EndCap style is applied to each dash, arrow styles are not. The string first defines the length of the dash then the length of the space. This may be repeated to form complex dash styles. The string should always contain a pair of numbers; if it contains an odd number of numbers the last may be disregarded. The following table lists some typical values and a description of the intended effect. "0" implies a dot that should be fourfold symmetrical (with round endcaps it should be a circle). If the line endcap is Flat, a viewer should choose a built-in operating system dash where possible (i.e., something that is fast to draw). The following shows some examples.

"2 2" short-dashes (each dash and the space in between is twice the width of the line)
"1 2" dot (each dash is the width of the line while each space is twice the width of the line)
"4 2" dash (each dash is four times the width of the line while each space is twice the width of the line)
"8 2" long-dash
"4 2 1 2" dash dot
"8 2 1 2" long-dash dot
"8 2 1 2 1 2" long-dash dot dot

TextPath element

Describes a vector path based on the text data, font, and styles supplied. The text path is warped to conform to a Path element if supplied.

Attribute Description
FitPath VgTriState. Sizes the text to fill the path it lies out on.
FitShape VgTriState. Stretches the text path out to the edges of the shape box.
On VgTriState. Determines whether the character paths are displayed or not.
String String. The text to render as a text path.
Trim VgTriState. Removes any additional space reserved for ascenders and descenders if not used.
XScale VgTriState. Use straight x measurement instead of measuring along the path.

Data Types Used in the VML Object Model

The following data types are used by the VML Object Model.

Double data type

A double precision integer with range from -infinity to infinity.

Fixed data type

Floating point number with range from -32,766.0 to 32,766.0.

Integer data type

An integer with a range from -infinity to infinity.

IVgAdjustments data type

Collection of adjustments to a shape that can be used to change the dimensions of a shape. Adjustments can be used as temporary placeholders or for any reason you would use variables. There are only 8 adjustments in the collection.

Attribute Description
Exists IVgTriState. Determines whether a specified adjustment exists. Note that an index must be used; that is, exists( item ) must be used to retrieve the existence of an item.
Item Long. Array of adjustments indexed from 0 to 7. Note that adjustments may be sparcely specified; that is, intermediate array values may not always be filled. For example, item 1, 3, and 5 could have values for a length of 3, with item(0), item(2), and item(4) specified. To see if an item exists, use the Exists attribute.
Length Integer. Number of adjustments. Can be no greater than 8.
Value String. Text representation of numeric values, with commas between each number.

IVgColor

Specifies a color.

Attributes Description
RGB VgRGBType. RGB value (Long) of the color. Only valid if Type is RGB.
R Integer. Red component of the color. Can range between 0 and 255.
G Integer. Green component of the color. Can range between 0 and 255.
B Integer. Blue component of the color. Can range between 0 and 255.
String String. Text representation of the color. The following named color types are supported:
  • Black (#000000)
  • Silver (#C0C0C0)
  • Gray (#808080)
  • White (#FFFFFF)
  • Maroon (#800000)
  • Red (#FF0000)
  • Purple (#800080)
  • Fuchsia (#FF00FF)
  • Green (#008000)
  • Lime (#00FF00)
  • Olive (#808000)
  • Yellow (#FFFF00)
  • Navy (#000080)
  • Blue (#0000FF)
  • Teal (#008080)
  • Aqua (#00FFFF)
Type VgColorType. Type of color. One of the following types:
  • Mixed
  • Named
  • RGB
  • Scheme

IVgEquation

Equations used for formulas.

Operation VgEquationOperationType Name of operation to perform on the parameters. The following operations can be used in an equation:
Operation Description
Abs Absolute value.
abs(v)
Atan2 Polar arithmetic--results in fd units (degrees multiplied by 65536).
atan2(p1,v)
Cos Cosine, argument in fd units (degrees multiplied by 65536).
v * cos(p1)
Cosatan2 Preserves full accuracy in intermediate calculation.
v * cos(atan2( p2,p1 ))
Ellipse Ellipse
If If Condition test. v > 0 ? p1 : p2
Max The greater of two values.
max(v,p1)
Mid Average ( v + p1)/2
Min The lesser of two values. min(v,p1)
Mod Modulus.
Product Used for multiplication and division. v * p1 / p2
Sin Sine, argument in fd units (degrees multiplied by 65536).
v * sin(p1)
Sinatan2 Preserves full accuracy in intermediate calculation. v * sin(atan2(p2,p1))
Sqrt Result is positive and rounds down.
sqrt(v)
Sum Used for addition and subtraction.
v + p1 p2
Sumangle Existing angle (scaled by 65536), where p1 and p2 are in degrees.
v + p1 * 65536 + p2 * 65536
Tan Tangent, argument is in fd units (degrees multiplied by 65536).
v * tan( p1 )
Val Defines a guide value from some other value.

Param1 Integer. The first parameter.
Paramtype1 VgFormulaParamType. The type of the first parameter. The following values are supported:
Type Description
Value Parameter is simple value.
AdjustmentReference Parameter is a reference to an adjustment. For example, if the first parameter is 1, then the value of the first adjustment will be used.
FormulaReference Parameter is the result of a reference to the result of a previous formula. For example, if the first parameter is 2, then the result of formula 2 will be used.

Param2 Integer. The second parameter.
Paramtype2 VgFormulaParamType The type of parameter 2.
Val Integer. The result.
Valtype2 VgFormulaParamType. The type of the result.

IVgFixedRectangle

Specifies a fixed rectangle.

Attribute Description
Value String. Text value specifying the path.
Left Double. Leftmost coordinate of the rectangle.
Top Double. Topmost coordinate of the rectangle.
Right Double. Rightmost coordinate of the rectangle.
Bottom Double. Bottommost coordinate of the rectangle.

IVgFixedRectangleArray

Array of fixed rectangles.

Attribute Description
Value String. Text representation of array.
Length Integer. Number of rectangles in this array.
Item IVgFixedRectangle. The rectangle object at the specified index.

IVgFormula data type

Definitions for formulas that can vary the path of a shape or be used for other calculation purposes. Formulas can be based on the Adj attribute of a shape, which can change. Formulas can reference other formulas as well.

Attribute Description
Eqn IVgEquation. Each formula defines a single value as the result of the evaluation of the expression. The expression is defined by this attribute and has the general form of an operation followed by up to three arguments, which may be adjustment values (e.g., #2), the results of earlier formulas (e.g., @2), fixed numbers, or predefined values.

IVgFormulas data type

A collection of formula objects.

Attribute Description
Length Integer. Number of formula objects in collection.
Item IVgFormula. A specific formula. Note that the formula array may be inherited fom the shape type.

IVgGradientColorArray

An array of colors that define a gradient (blended range of colors).

Attribute Description
Value String. Specifies the array of colors; for example, "red .2; green .4; black .7"
Length Integer. Number of colors in the array.
Method Description
AddColor VgFraction. Adds new color at endpoint specified by fraction. The new color is white by default and is the return value. The color can then be changed by reference.
RemoveColor VgFraction. Removes a color at endpoint specified by fraction. Note: if 0.0 or 1.0 does not exist, it is implied and the color white is used at that point.

IVgPoints datatype

Array of points that define a shape.

Attribute Description
Value String. Text representation of array.
Length Integer. Number of points in this array.
Item IVgVector2D. The point at the specified index.

IVgSkewMatrix datatype

A matrix used for skewing shapes, a perspective transform matrix in the form, "sxx,sxy,syx,syy,px,py " [s =scale, p =perspective]. If offset is in absolute units, then px,py are in emu ^-1 units; otherwise they are an inverse fraction of shape size.

Attribute Description
XtoX Double.
YtoX Double.
XtoY Double.
YtoY Double.
PerspectiveX Double.
PerspectiveY Double.

IVgSkewOffset

Specifies the offset of the skew.

Attributes Description
Value String. Text representation of offset.
X Double. X component. Percentage or measure. If no units, then ShapeRelative type is implied; otherwise Absolute type is implied.
Y Double. Y component.
Type VgSkewTransformType. Specifies the type of transformation. Valid values are integer points ranging between -infinity and infinity.
Type Description
ShapeRelative The values of the offset are percentages (ratios) of the original shape's size; e.g., a value of 0.5 means an offset half the size of the shape.
Absolute The values are absolute units.

IVgVector2D data type

Specifies a two-dimensional vector consisting of two Double numbers.

Attributes Description
Value String. Text representation of both vector numbers separated by a space.
X Double. X component of this vector.
Y Double. Y component of this vector.
Type VgVectorType. Expected units for this vector. Values are:
  • Measure
  • Length
  • AngleInDegrees
  • Fraction
  • Number Percentage Integer

IVgVector3D data type

Specifies a three-dimensional vector consisting of three Double numbers.

Value String. Text representation of three vector numbers separated by a space.
X Double. X component of this vector.
Y Double. Y component of this vector.
Z Double. Z component of this vector.
Type VgVectorType. Expected units for this vector. Values are:
  • Measure
  • Length
  • AngleInDegrees
  • Fraction
  • Number
  • Percentage
  • Integer

Length data type

A floating point number with a range from 0 to infinity.

Measure data type

A floating point number from -infinity to infinity.

String data type

Character data of any length.

VgBlackWhiteMode

Rendering mode for black and white. Possible values are:

  • Color
  • Auto
  • GrayScale
  • LightGrayScale
  • InverseGray
  • GrayOutline
  • BlackTextAndLines
  • HighContrast
  • Black
  • White
  • Undrawn

VgFraction data type

Floating point number with range from 0.0 to 1.0. Fractions can also be specified as a percentage; e.g., "50%".

VgTriState datatype

Enumeration used for values that can be one of three states:

  • TRUE
  • FALSE
  • MIXED