Partager via


ImageFile Class

Image File.When the object is serialized out as xml, its qualified name is v:image.

Inheritance Hierarchy

System.Object
  DocumentFormat.OpenXml.OpenXmlElement
    DocumentFormat.OpenXml.OpenXmlCompositeElement
      DocumentFormat.OpenXml.Vml.ImageFile

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

Syntax

'Declaration
<ChildElementInfoAttribute(GetType(ClipPath))> _
<ChildElementInfoAttribute(GetType(ShapeHandles))> _
<ChildElementInfoAttribute(GetType(Stroke))> _
<ChildElementInfoAttribute(GetType(Shadow))> _
<ChildElementInfoAttribute(GetType(TextBox))> _
<ChildElementInfoAttribute(GetType(TextPath))> _
<ChildElementInfoAttribute(GetType(ImageData))> _
<ChildElementInfoAttribute(GetType(Skew))> _
<ChildElementInfoAttribute(GetType(Extrusion))> _
<ChildElementInfoAttribute(GetType(Callout))> _
<ChildElementInfoAttribute(GetType(Lock))> _
<ChildElementInfoAttribute(GetType(Path))> _
<ChildElementInfoAttribute(GetType(SignatureLine))> _
<ChildElementInfoAttribute(GetType(TextWrap))> _
<ChildElementInfoAttribute(GetType(AnchorLock))> _
<ChildElementInfoAttribute(GetType(TopBorder))> _
<ChildElementInfoAttribute(GetType(BottomBorder))> _
<ChildElementInfoAttribute(GetType(LeftBorder))> _
<ChildElementInfoAttribute(GetType(RightBorder))> _
<ChildElementInfoAttribute(GetType(ClientData))> _
<ChildElementInfoAttribute(GetType(TextData))> _
<ChildElementInfoAttribute(GetType(Fill))> _
<ChildElementInfoAttribute(GetType(Formulas))> _
Public Class ImageFile _
    Inherits OpenXmlCompositeElement
'Usage
Dim instance As ImageFile
[ChildElementInfoAttribute(typeof(ClipPath))]
[ChildElementInfoAttribute(typeof(ShapeHandles))]
[ChildElementInfoAttribute(typeof(Stroke))]
[ChildElementInfoAttribute(typeof(Shadow))]
[ChildElementInfoAttribute(typeof(TextBox))]
[ChildElementInfoAttribute(typeof(TextPath))]
[ChildElementInfoAttribute(typeof(ImageData))]
[ChildElementInfoAttribute(typeof(Skew))]
[ChildElementInfoAttribute(typeof(Extrusion))]
[ChildElementInfoAttribute(typeof(Callout))]
[ChildElementInfoAttribute(typeof(Lock))]
[ChildElementInfoAttribute(typeof(Path))]
[ChildElementInfoAttribute(typeof(SignatureLine))]
[ChildElementInfoAttribute(typeof(TextWrap))]
[ChildElementInfoAttribute(typeof(AnchorLock))]
[ChildElementInfoAttribute(typeof(TopBorder))]
[ChildElementInfoAttribute(typeof(BottomBorder))]
[ChildElementInfoAttribute(typeof(LeftBorder))]
[ChildElementInfoAttribute(typeof(RightBorder))]
[ChildElementInfoAttribute(typeof(ClientData))]
[ChildElementInfoAttribute(typeof(TextData))]
[ChildElementInfoAttribute(typeof(Fill))]
[ChildElementInfoAttribute(typeof(Formulas))]
public class ImageFile : OpenXmlCompositeElement

Remarks

The following table lists the possible child types:

  • Path <v:path>

  • Formulas <v:formulas>

  • ShapeHandles <v:handles>

  • Fill <v:fill>

  • Stroke <v:stroke>

  • Shadow <v:shadow>

  • TextBox <v:textbox>

  • TextPath <v:textpath>

  • ImageData <v:imagedata>

  • DocumentFormat.OpenXml.Vml.Office.Skew <o:skew>

  • DocumentFormat.OpenXml.Vml.Office.Extrusion <o:extrusion>

  • DocumentFormat.OpenXml.Vml.Office.Callout <o:callout>

  • DocumentFormat.OpenXml.Vml.Office.Lock <o:lock>

  • DocumentFormat.OpenXml.Vml.Office.ClipPath <o:clippath>

  • DocumentFormat.OpenXml.Vml.Office.SignatureLine <o:signatureline>

  • DocumentFormat.OpenXml.Vml.Wordprocessing.TextWrap <w10:wrap>

  • DocumentFormat.OpenXml.Vml.Wordprocessing.AnchorLock <w10:anchorlock>

  • DocumentFormat.OpenXml.Vml.Wordprocessing.TopBorder <w10:bordertop>

  • DocumentFormat.OpenXml.Vml.Wordprocessing.BottomBorder <w10:borderbottom>

  • DocumentFormat.OpenXml.Vml.Wordprocessing.LeftBorder <w10:borderleft>

  • DocumentFormat.OpenXml.Vml.Wordprocessing.RightBorder <w10:borderright>

  • DocumentFormat.OpenXml.Vml.Spreadsheet.ClientData <xvml:ClientData>

  • DocumentFormat.OpenXml.Vml.Presentation.TextData <pvml:textdata>

[ISO/IEC 29500-1 1st Edition]

14.1.2.10 image (Image File)

This element is used to draw an image that has been loaded from an external source. There is an implied rectangle that is the same size as the image. Any stroke or fill is applied to this implied rectangle.  The stroke is drawn on top of the image.  The fill is behind the image and therefore only visible through transparent areas of the image. Image transparency is either encoded in the file or defined via a color value using the chromakey attribute. Unlike the imagedata element (§14.1.2.11), the image element does not have a parent element.

[Example:

<v:image src="myimage.gif" 
  style="position:relative;top:1;left:1;width:50;height:45"
  cropbottom="10%" gamma="0.5" gain="2">
</v:image>

DocumentFormat.OpenXml.Vml.ImageFile-image001DocumentFormat.OpenXml.Vml.ImageFile-image002

end example]

Parent Elements

background (Part 1, §17.2.1); group (§14.1.2.7); object (Part 1, §17.3.3.19); pict (§9.2.2.2); pict (§9.5.1)

Child Elements

Subclause

anchorlock (Anchor Location Is Locked)

§14.3.2.1

borderbottom (Bottom Border)

§14.3.2.2

borderleft (Left Border)

§14.3.2.3

borderright (Right Border)

§14.3.2.4

bordertop (Top Border)

§14.3.2.5

callout (Callout)

§14.2.2.2

ClientData (Attached Object Data)

§14.4.2.12

clippath (Shape Clipping Path)

§14.2.2.3

extrusion (3D Extrusion)

§14.2.2.11

fill (Shape Fill Properties)

§14.1.2.5

formulas (Set of Formulas)

§14.1.2.6

handles (Set of Handles)

§14.1.2.9

imagedata (Image Data)

§14.1.2.11

lock (Shape Protections)

§14.2.2.18

path (Shape Path)

§14.1.2.14

shadow (Shadow Effect)

§14.1.2.18

signatureline (Digital Signature Line)

§14.2.2.30

skew (Skew Transform)

§14.2.2.31

stroke (Line Stroke Settings)

§14.1.2.21

textbox (Text Box)

§14.1.2.22

textdata (VML Diagram Text)

§14.5.2.2

textpath (Text Layout Path)

§14.1.2.23

wrap (Text Wrapping)

§14.3.2.6

Attributes

Description

allowincell (Allow in Table Cell)

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

Specifies whether a shape can be placed in a table. Default is false.

[Example:

<v:shape  o:allowincell="true"  >
</v:shape>

end example]

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

allowoverlap (Allow Shape Overlap)

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

Specifies whether a shape can overlap another shape. Default is true. If false, the shape shifts left or right so as not to overlap another shape, similar to the behavior of the HTML float attribute.

[Example:

<v:shape  o:allowoverlap="false"  >
</v:shape>

end example]

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

alt (Alternate Text)

Specifies alternative text describing the graphical object. This text should provide a brief description of the shape for use by accessibility tools. Default is no value.

[Example: The alt text describes the basic shape:

<v:shape  fillcolor="red" 
  alt="Red rectangle">
</v:shape>

The alt text describes the contents of a shape displaying an image:

<v:shape  alt="Picture of a sunset">
</v:shape>

end example]

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

bilevel (Image Bilevel Toggle)

Specifies that all colors in the picture shall be converted to either 0 or full intensity component values. This converts a color bitmap to 8 colors and a grayscale bitmap to black and white. Default is false.

[Example:

<v:image  bilevel="true" >
</v:image>
DocumentFormat.OpenXml.Vml.ImageFile-image003

end example]

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

blacklevel (Image Brightness)

Specifies the image brightness. Default is 0.

[Example:

<v:image  blacklevel="0.1" >
</v:image>
DocumentFormat.OpenXml.Vml.ImageFile-image004

end example]

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

borderbottomcolor (Bottom Border Color)

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

Specifies the bottom border color of an inline shape. Default is no value.

[Example:

<v:shape  o:borderbottomcolor="red"  >
</v:shape>

end example]

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

borderleftcolor (Border Left Color)

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

Specifies the left border color of an inline shape. Default is no value.

[Example:

<v:shape  o:borderleftcolor="red"  >
</v:shape>

end example]

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

borderrightcolor (Border Right Color)

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

Specifies the right border color of an inline shape. Default is no value.

[Example:

<v:shape  o:borderrightcolor="red"  >
</v:shape>

end example]

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

bordertopcolor (Border Top Color)

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

Specifies the top border color of an inline shape. Default is no value.

[Example:

<v:shape  o:bordertopcolor="red"  >
</v:shape>

end example]

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

bullet (Graphical Bullet)

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

Specifies whether the shape is a graphical bullet. Default is false.

[Example:

<v:shape  o:bullet="true"  >
</v:shape>

end example]

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

button (Button Behavior Toggle)

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

Specifies whether a shape exhibits button press behavior on click. Default is false.

[Example:

<v:shape  o:button="true"  >
</v:shape>

end example]

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

bwmode (Black-and-White Mode)

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

Specifies how a shape renders for black-and-white output devices. When a shape is printed on a black-and-white printer or displayed in a black-and-white view in an application, several options are possible. Default is auto, which uses o:bwnormal for normal black-and-white rendering and o:bwpure for pure black-and-white rendering.

bwnormal and bwpure are subordinate to bwmode.  If bwmode is "auto" then the value for bwnormal or bwpure is used depending on what the output format is.  An application can define for itself what, if any, difference there is between normal B&W and pure B&W.  [Example: Normal B&W might allow greyscale and pure B&W might not. end example]

[Example: This shape renders in grayscale in a black-and-white environment:

<v:shape  o:bwmode="grayscale"  >
</v:shape>

end example]

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

bwnormal (Normal Black-and-White Mode)

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

Specifies the black-and-white mode for normal black-and-white output devices. Default is auto.

[Example: This shape renders in a pale grayscale in a normal black-and-white environment:

<v:shape   o:bwmode="auto" o:bwnormal="lightgrayscale"  >
</v:shape>

end example]

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

bwpure (Pure Black-and-White Mode)

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

Specifies the black-and-white mode for pure black-and-white output devices. Default is auto.

[Example: This shape renders in high contrast when in a pure black-and-white environment:

<v:shape  o:bwmode="auto" o:bwpure="highcontrast"  >
</v:shape>

end example]

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

chromakey (Image Transparency Color)

Specifies a color value that is transparent and show anything behind the shape. Default is no value.

[Example:

<v:image  chromakey="white" >
</v:image>

end example]

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

class (CSS Reference)

Specifies a reference to the definition of a CSS style. Default is no value.

[Example: The snippets below are equivalent:


.narrowstyle {width:50;height:100}

<v:shape  class="narrowstyle"
  style="top:1;left:1">
</v:shape>
<v:shape  style="top:1;left:1;
  width:50;height:100">
</v:shape>

end example]

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

clip (Clipping Toggle)

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

Specifies that the clipping region is active. This is used in conjunction with the clippath (§14.2.2.3) element to create a clipping region.

[Example:

<v:shape  o:clip="true">
</v:shape>

end example]

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

cliptowrap (Clip to Wrapping Polygon)

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

Specifies that the clipping region for the shape aligns with the wrapping polygon that tightly surrounds the entire shape (essentially, that the shape shall not be drawn beyond its wrapping polygon's extents – if it does, the shape shall be clipped). Default is false.

[Example:

<v:shape  o:cliptowrap="true">
</v:shape>

end example]

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

connectortype (Shape Connector Type)

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

Specifies the kind of connector used for joining shapes. Default is straight.

[Example:

<v:shape  o:connectortype="elbow"  >
</v:shape>

end example]

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

coordorigin (Coordinate Space Origin)

Specifies the coordinate of the top left corner of the shape's coordinate space. This determines the position of the (0,0) coordinate space origin within the shape's bounding box. Default is "0,0", which places the (0,0) origin at the top left corner of the bounding box.

This affects shape properties that specify coordinate positions, such as the path attribute. Thus a path can be defined against a generic (0,0) origin and the coordorigin value translates the entire path within the shape's bounding space.

[Example: The horizontal and vertical coordinate space ranges from -100 to +100 because the coordinate space (coordsize) is 200 by 200 and the top left coordinate is (-100,-100). The (0,0) origin lies at the center of the shape's bounding box, as evidenced by the position of the shape's path within the coordinate space:

<v:shape  coordsize="200,200"
  coordorigin="-100,-100"
  path="m 0,0 l 0,50, 50,50, 50,0 x e">
</v:shape>

DocumentFormat.OpenXml.Vml.ImageFile-image005

end example]

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

coordsize (Coordinate Space Size)

Specifies the size of the shape's coordinate space in coordinate units. Default is "1000,1000".

The physical size of a coordinate unit length is determined by both the size of the coordinate space (coordsize) and the size of the shape (style width and height). The coordsize attribute defines the number of horizontal and vertical subdivisions into which the shape's bounding box is divided. The combination of coordsize and style width/height effective scales the shape anisotropically.

[Example: The path is 50 units wide and tall, which is 25% of the size of the coordinate space:

<v:shape  coordsize="200,200"
  coordorigin="-100,-100"
  path="m 0,0 l 0,50, 50,50, 50,0 x e">
</v:shape>

DocumentFormat.OpenXml.Vml.ImageFile-image005

end example]

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

cropbottom (Image Bottom Crop)

Specifies the how much to crop the image from the bottom up as a fraction of picture size. Default is 0. This numeric value can also be specified in 1/65536-ths if a trailing "f" is supplied. For example, a value of "52429f" represents 52429/65536 or 0.8.

[Example:

<v:image  cropbottom="10%" >
</v:image>
DocumentFormat.OpenXml.Vml.ImageFile-image006

end example]

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

cropleft (Image Left Crop)

Specifies how much to crop the image from the left in as a fraction of picture size. Default is 0. This numeric value can also be specified in 1/65536-ths if a trailing "f" is supplied. For example, a value of "52429f" represents 52429/65536 or 0.8.

[Example:

<v:image  cropleft="10%" >
</v:image>
DocumentFormat.OpenXml.Vml.ImageFile-image007

end example]

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

cropright (Image Right Crop)

Specifies how much to crop the image from the right in as a fraction of picture size. Default is 0. This numeric value can also be specified in 1/65536-ths if a trailing "f" is supplied. [Example: For example, a value of "52429f" represents 52429/65536 or 0.8. end example]

[Example:

<v:image  cropright="10%" >
</v:image>
DocumentFormat.OpenXml.Vml.ImageFile-image007

end example]

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

croptop (Image Top Crop)

Specifies how much to crop the image from the top down as a fraction of picture size. Default is 0. This numeric value can also be specified in 1/65536-ths if a trailing "f" is supplied. [Example: For example, a value of "52429f" represents 52429/65536 or 0.8. end example]

[Example:

<v:image  croptop="10%" >
</v:image>
DocumentFormat.OpenXml.Vml.ImageFile-image007

end example]

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

dgmlayout (Diagram Node Layout Identifier)

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

Specifies the kind of automatic layout to apply to the diagram node. This is only meaningful if the shape is a node in an organization chart, which is denoted by the orgchart value of the editas attribute of the group element.

[Example:

<v:shape  dgmlayout="1">
</v:shape>

end example]

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

dgmlayoutmru (Diagram Node Recent Layout Identifier)

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

Specifies the kind of automatic layout most recently used on the child elements of the diagram node. This is only meaningful if the shape is a node in anorganization chart, which is denoted by the orgchart value of the editas attribute of the group element.

[Example:

<v:shape  dgmlayout="1">
</v:shape>

end example]

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

dgmnodekind (Diagram Node Identifier)

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

Specifies an optional, application-defined parameter that is intended to be used by the application to tag different types of nodes in a diagram.

[Example:

<v:shape  dgmnodekind="1">
</v:shape>

end example]

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

doubleclicknotify (Double-click Notification Toggle)

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

Specifies that an event message is sent when a shape is double-clicked. Default is false.

[Example:

<v:shape  o:doubleclicknotify="true"  >
</v:shape>

end example]

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

fillcolor (Fill Color)

Specifies the color to use for the fill. Default is white. If the fill element (§14.1.2.5) is present, its color attribute takes precedence. Colors are typically specified as either a named color, such as red, or six hexadecimal digits representing the red, green and blue values of the color, such as #00FF30. Full details are specified in the simple type description.

[Example: This shape is red if its fill is visible:

<v:shape  fillcolor="red"  >
</v:shape>

This is equivalent to:

<v:shape  fillcolor="#ff0000"  >
</v:shape>

end example]

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

filled (Shape Fill Toggle)

Specifies whether the closed path is filled. Default is true. This attribute is overridden by the fill on attribute.

[Example:

<v:shape  filled="f" 
  fillcolor="red" >
</v:shape>
DocumentFormat.OpenXml.Vml.ImageFile-image008

end example]

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

forcedash (Force Dashed Outline)

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

Specifies whether a dashed outline is used to draw a shape when a shape has no line or fill. Default is false.

Used by PresentationML placeholders to draw a dashed outline when there is no line and no fill for a shape.

[Example:

<v:shape  o:forcedash="true"  >
</v:shape>

end example]

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

gain (Image Intensity)

Specifies an adjustment for the intensity of all colors. Essentially sets how bright white is. Default is 1.

[Example:

<v:image  gain="0.5" >
</v:image>
DocumentFormat.OpenXml.Vml.ImageFile-image009

end example]

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

gamma (Image Gamma Correction)

Specifies the gamma correction. Default is 1.

Gamma correction is a factor by which the intended target display gamma differs from the sRGB profile. It can be used to correct for images not prepared for sRGB displays and to adjust overall image contrast.  Decreasing it below 1 gives a higher contrast image.

[Example:

<v:image  gamma="0.5" >
</v:image>
DocumentFormat.OpenXml.Vml.ImageFile-image010

end example]

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

grayscale (Image Grayscale Toggle)

Specifies to display the image in grayscale. Default is false.

[Example:

<v:image  gamma="0.5" >
</v:image>
DocumentFormat.OpenXml.Vml.ImageFile-image011

end example]

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

hr (Horizontal Rule Toggle)

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

Specifies that a shape is a horizontal rule. Default is false.

[Example:

<v:shape  o:hr="true"  >
</v:shape>

end example]

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

hralign (Horizontal Rule Alignment)

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

Specifies the alignment of a horizontal rule. Default is left.

[Example:

<v:shape  o:hralign="center"  >
</v:shape>

end example]

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

href (Hyperlink Target)

Specifies a hyperlink URL target for the shape. Default is no value.

[Example:

<v:shape  href="http://www.openxmlformats.org"  >
</v:shape>

end example]

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

hrnoshade (Horizontal Rule 3D Shading Toggle)

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

Specifies that the horizontal rule does not have 3-D shading. Default is false.

[Example:

<v:shape  o:hrnoshade="true"  >
</v:shape>

end example]

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

hrpct (Horizontal Rule Length Percentage)

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

Specifies the length of a horizontal rule as a percentage of page width. Default is 0.

[Example:

<v:shape  o:hrpct="85"  >
</v:shape>

end example]

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

hrstd (Horizontal Rule Standard Display Toggle)

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

Specifies whether a shape is displayed as a standard horizontal rule. Only applies if hr is true. Default is false.

[Example:

<v:shape  o:hrstd="true"  >
</v:shape>

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.

insetmode (Text Inset Mode)

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

Specifies whether the application calculates the internal text margin instead of using the inset attribute. Default is custom. This attribute is only meaningful for text boxes.

[Example:

<v:shape  o:insetmode="auto"  >
</v:shape>

end example]

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

insetpen (Inset Border From Path)

Specifies that the border shall be displayed inside of the path defining the shape, rather than along the path (the default border placement), or outside of the path as might be done with an image.

[Example:

<v:shape  insetpen="true"  >
</v:shape>

end example]

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

ole (Embedded Object Toggle)

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

Specifies whether the shape is an embedded object. Default is false.

[Example:

<v:shape  o:ole="true"  >
</v:shape>

end example]

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

oleicon (Embedded Object Icon Toggle)

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

Specifies whether an embedded object is displayed as an icon. Default is false.

[Example:

<v:shape  o:oleicon="true"  >
</v:shape>

end example]

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

oned (Shape Handle Toggle)

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

Specifies whether the extra handles of a shape are hidden. If true, hides all shape handles except the top left and bottom right; that is, the same handles that are used for a straight line segment. Default is false.

[Example:

<v:shape  o:oned="true"  >
</v:shape>

end example]

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

opacity (Fill Color Opacity)

Specifies the opacity of the primary fill color. Default is 1.0. This numeric value can also be specified in 1/65536-ths if a trailing "f" is supplied. [Example: A value of "52429f" represents 52429/65536 or 0.8. end example]

[Example: The red color is 25% opaque:

<v:fill type="gradient" color="red"
  color2="blue" opacity=".25">
</v:fill>
DocumentFormat.OpenXml.Vml.ImageFile-image012DocumentFormat.OpenXml.Vml.ImageFile-image013

end example]

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

preferrelative (Relative Resize Toggle)

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

Specifies whether the original size of an object is saved after reformatting. Default is false. If true, the original size of the object is stored and all resizing is based on a percentage of that original size. Otherwise, each resizing resets the scale to 100%.

[Example:

<v:shape  o:preferrelative="true"  >
</v:shape>

end example]

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

print (Print Toggle)

Specifies whether the shape is printed. Default is true.

[Example:

<v:shape  print="false"  >
</v:shape>

end example]

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

regroupid (Regroup ID)

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

Specifies a previous group for a shape. An ID number is used to identify groups of shapes that are no longer grouped. This allows shapes to be regrouped programmatically.

[Example: The shape was part of a group identified by the ID 040754:

<v:shape  o:regroupid="040754"  >
</v:shape>

end example]

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

spid (Optional String)

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

Specifies an optional string that an application can use to Identify the particular shape. Default is no value.

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

spt (Optional Number)

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

Specifies an optional number that an application can use to associate the particular shape with a defined shape type. Default is 0.

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

src (Image Source)

Specifies the URL of the image to use.

[Example:

<v:image  src="myimage.gif" >
</v:image>
DocumentFormat.OpenXml.Vml.ImageFile-image001

end example]

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

strokecolor (Shape Stroke Color)

Specifies the primary color of the brush to use to stroke the path of the shape. Default is black. The color attribute of the stroke element (§14.1.2.21) overrides this. Colors are typically specified as either a named color, such as red, or six hexadecimal digits representing the red, green and blue values of the color, such as #00FF30. Full details are specified in the simple type description.

[Example:

<v:shape  strokecolor="red" >
</v:shape>
DocumentFormat.OpenXml.Vml.ImageFile-image014

end example]

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

stroked (Shape Stroke Toggle)

Specifies whether the path defining the shape is stroked with a solid line. The stroke element (§14.1.2.21) defines other strokes. The on attribute of the stroke element overrides this attribute. Default is true.

[Example:

<v:shape  fillcolor="red"
  stroked="false" strokecolor="blue">
</v:shape>
DocumentFormat.OpenXml.Vml.ImageFile-image015

end example]

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

strokeweight (Shape Stroke Weight)

Specifies the width of the brush to use to stroke the path. Default is 1 point. If a number is given without units, the emu is used. The weight attribute of the stroke element (§14.1.2.21) overrides this attribute.

[Example:

<v:shape  strokeweight="3pt"  >
</v:shape>
DocumentFormat.OpenXml.Vml.ImageFile-image016

end example]

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

style (Shape Styling Properties)

Specifies the CSS2 styling properties of the shape. The CSS2 (Cascading Style Sheets, Level 2) specification, a Recommendation of the World Wide Web Consortium, is available here: http://www.w3.org/TR/REC-CSS2.

This attribute uses a semi-colon delimited list of “name:value” pairs, the syntax defined by section 4.1.8 of the CSS2 specification for grouped declarations (without the surrounding braces). The following tables define the allowed properties and the VML treatment of each.

[Example:

<v:shape  style=’position:absolute;width:100pt;height:50pt’  >
</v:shape>

end example]

Property

Description

flip

Specifies that the orientation of a shape is flipped. Default is no value. Allowed values are:

  • x - Flip along the y-axis, reversing the x-coordinates.

  • y - Flip along the x-axis, reversing the y-coordinates.

  • xy - Flip along both the y- and x-axis.

  • yx - Flip along both the x- and y-axis.

height

Specifies the height of the containing block of the shape.  Default is 0. It is specified in CSS units or, for elements in a group, in the coordinate system of the parent element. Allowed values are:

  • auto - Default position of an element in the flow of the page.

  • <units>- A number with an absolute units designator (cm, mm, in, pt, pc, or px) or a relative units designator (em or ex). If no units are given, pixels (px) is assumed.

  • <percentage>- Value expressed as a percentage of the parent object's height.

left

Specifies the position of the left of the containing block of the shape relative to the element left of it in the flow of the page. Default is 0. It is specified in CSS units or, for elements in a group, in the coordinate system of the parent element. This property shall not be used for shapes anchored inline. Allowed values are:

  • auto - Default position of an element in the flow of the page.

  • <units> - A number with an absolute units designator (cm, mm, in, pt, pc, or px) or a relative units designator (em or ex). If no units are given, pixels (px) is assumed.

  • <percentage>- Value expressed as a percentage of the parent object's width.

margin-bottom

Specifies the position of the bottom of the containing block of the shape relative to the shape anchor. Default is 0. It is specified in CSS units or, for elements in a group, in the coordinate system of the parent element. Allowed values are:

  • auto - Default position of an element in the flow of the page.

  • <units>- A number with an absolute units designator (cm, mm, in, pt, pc, or px) or a relative units designator (em or ex). If no units are given, pixels (px) is assumed.

  • <percentage>- Value expressed as a percentage of the parent object's height.

margin-left

Specifies the position of the left of the containing block of the shape relative to the shape anchor. Default is 0. It is specified in CSS units or, for elements in a group, in the coordinate system of the parent element. Allowed values are:

  • auto - Default position of an element in the flow of the page.

  • <units>- A number with an absolute units designator (cm, mm, in, pt, pc, or px) or a relative units designator (em or ex). If no units are given, pixels (px) is assumed.

  • <percentage>- Value expressed as a percentage of the parent object's width.

margin-right

Specifies the position of the right of the containing block of the shape relative to the shape anchor. Default is 0. It is specified in CSS units or, for elements in a group, in the coordinate system of the parent element. Allowed values are:

  • auto - Default position of an element in the flow of the page.

  • <units> - A number with an absolute units designator (cm, mm, in, pt, pc, or px) or a relative units designator (em or ex). If no units are given, pixels (px) is assumed.

  • <percentage>- Value expressed as a percentage of the parent object's width.

margin-top

Specifies the position of the top of the containing block of the shape relative to the shape anchor. Default is 0. It is specified in CSS units or, for elements in a group, in the coordinate system of the parent element. Allowed values are:

  • auto - Default position of an element in the flow of the page.

  • <units>- A number with an absolute units designator (cm, mm, in, pt, pc, or px) or a relative units designator (em or ex). If no units are given, pixels (px) is assumed.

  • <percentage>- Value expressed as a percentage of the parent object's height.

mso-position-horizontal

Specifies the horizontal positioning data for objects in WordprocessingML documents. Default is absolute. Allowed values are:

  • absolute

  • left

  • center

  • right

  • inside

  • outside

mso-position-horizontal-relative

Specifies relative horizontal position data for objects in WordprocessingML documents. This modifies the mso-position-horizontal property. Default is text. Allowed values are:

  • margin

  • page

  • text

  • char

mso-position-vertical

Specifies the vertical positioning data for objects in WordprocessingML documents. Default is absolute. Allowed values are:

  • absolute

  • top

  • center

  • bottom

  • inside

  • outside

mso-position-vertical-relative

Specifies relative vertical position data for objects in WordprocessingML documents. This modifies the mso-position-vertical property. Default is text. Allowed values are:

  • margin

  • page

  • text

  • line

mso-wrap-distance-bottom

Specifies the distance from the bottom of the shape to the text that wraps around it. Default is 0 pt. This property is different from the CSS margin property, which changes the origin of the shape to include the margin areas. This property does not change the origin.

mso-wrap-distance-left

Specifies the distance from the left side of the shape to the text that wraps around it. Default is 0 pt. This property is different from the CSS margin property, which changes the origin of the shape to include the margin areas. This property does not change the origin.

mso-wrap-distance-right

Specifies the distance from the right side of the shape to the text that wraps around it. Default is 0 pt. This property is different from the CSS margin property, which changes the origin of the shape to include the margin areas. This property does not change the origin.

mso-wrap-distance-top

Specifies the distance from the top of the shape to the text that wraps around it. Default is 0 pt. This property is different from the CSS margin property, which changes the origin of the shape to include the margin areas. This property does not change the origin.

mso-wrap-edited

Specifies whether the wrap coordinates were customized by the user. If the wrap coordinates are generated by an editor, this property is true; otherwise they were customized by a user. Default is false.

mso-wrap-style

Specifies the wrapping mode for text in shapes in WordprocessingML documents. Default is square. Allowed values are:

  • square - Wraps text inside the shape in a square.

  • none - Text does not wrap.

position

Specifies the kind of positioning used to place an element. Default is static. When the element is contained inside a group, this property shall be absolute. Allowed values are:

  • static - The element is positioned according to the normal flow of the page. The top and left properties are ignored. If the object is anchored inline, this value is used.

  • absolute - The element is positioned relative to the parent, using the top and left properties.

  • relative - The element is positioned according to the normal flow of the page, but the top and left properties are used. The overlap of overlapping elements is governed by the z-index property.

rotation

Specifies the angle that a shape is rotated, in degrees. Default is 0. Positive angles are clockwise.

top

Specifies the position of the top of the containing block of the shape relative to the element above it in the flow of the page. Default is 0. It is specified in CSS units or, for elements in a group, in the coordinate system of the parent element. This property shall not be used for shapes anchored inline. Allowed values are:

  • auto - Default position of an element in the flow of the page.

  • <units>- A number with an absolute units designator (cm, mm, in, pt, pc, or px) or a relative units designator (em or ex). If no units are given, pixels (px) is assumed.

  • <percentage>- Value expressed as a percentage of the parent object's height.

visibility

Specifies whether a shape is displayed. Only inherit and hidden are used; any other values are mapped to inherit. Default is inherit. Allowed values are:

  • hidden - The shape is not visible, but is still part of the flow of the objects in the browser. Mouse events are not processed.

  • inherit - The visibility state is inherited from the parent of the shape.

width

Specifies the width of the containing block of the shape.  Default is 0. It is specified in CSS units or, for elements in a group, in the coordinate system of the parent element. Allowed values are:

  • auto - Default position of an element in the flow of the page.

  • <units>- A number with an absolute units designator (cm, mm, in, pt, pc, or px) or a relative units designator (em or ex). If no units are given, pixels (px) is assumed.

  • <percentage>- Value expressed as a percentage of the parent object's width.

z-index

Specifies the display order of overlapping shapes. Default is 0. This property shall not be used for shapes anchored inline. Allowed values are:

  • auto - Uses the order that the shapes appear in the page, bottom to top.

  • <order>- A number that represents the stacking precedence. Shapes with higher numbers are placed on top of those with lower numbers. Negative numbers are allowed.

The following properties are only used by the textbox element (§14.1.2.22):

Property

Description

direction

Specifies the direction of the text in the textbox. Default is ltr. This property is superceded by the mso-direction-alt property if that is specified. Allowed values are:

  • ltr - Text is displayed left-to-right.

  • rtl - Text is displayed right-to-left.

layout-flow

Determines the flow of the text layout in a textbox. Default is horizontal. Allowed values are:

  • horizontal - Text is displayed horizontally.

  • vertical - Text is displayed vertically.

  • vertical-ideographic - Ideographic text is displayed vertically.

  • horizontal-ideographic - Ideographic text is displayed horizontally.

mso-direction-alt

Specifies an alternate direction for text in textboxes. Overrides the direction property. The only allowed value is context.

mso-fit-shape-to-text

Specifies whether the shape stretches to fit the text in the textbox. Default is false.

mso-fit-text-to-shape

Specifies whether the text stretches to fit the textbox. Default is false.

mso-layout-flow-alt

Specifies the alternate layout flow for text in textboxes. This property is used instead of layout-flow when the layout flow is from bottom to top for non-ideographic languages.  Its only value is bottom-to-top.

mso-next-textbox

Specifies the ID of the next textbox in a series. Used to keep track of a set of linked textboxes. Default is no value.

mso-rotate

Specifies a specific rotation value for text in a textbox. Default is 0. Allowed values are:

  • 0

  • 90

  • 180

  • -90

mso-text-scale

Specifies the scaling factor for fitting text to shapes. Default is 0. This property is only used if mso-fit-text-to-shape is true.

v-text-anchor

Specifies the vertical anchoring of text in a textbox. Default is top. The alignment of a text anchor only becomes evident if mso-fit-text-to-shape is false. This property is different from the vertical-align CSS property, which is used for ideographic languages. Allowed values are:

  • top

  • middle

  • bottom

  • top-center

  • middle-center

  • bottom-center

  • top-baseline

  • bottom-baseline

  • top-center-baseline

  • bottom-center-baseline

The following properties are only used by the textpath element (§14.1.2.23):

Property

Description

font

Specifies a compound value of font settings. Default is no value. The values are the same as those of the CSS font property. The order of definitions in the string is: font-style, font-variant, font-weight, font-size, line-height, font-family.

font-family

Specifies the family of the font. Default is no value. The values are the same as those of the CSS font-family property.

font-size

Specifies the size of the font. Default is no value. The font size is defined in points. The values are the same as those of the CSS font-size property.

font-style

Specifies the amount of slant for a font. Default is normal. The values are the same as those of the CSS font-style property. Allowed values are:

  • normal

  • italic

  • oblique - Treated the same as italic.

font-variant

Specifies the variant style of a font. Default is normal. The values are the same as those of the CSS font-variant property. Allowed values are:

  • normal

  • small-caps

font-weight

Specifies the thickness of the letters of the font. Default is normal. The values are the same as those of the CSS font-weight property. Allowed values are:

Value

Description

normal

lighter

100

200

300

400

Treated as non-bold.

bold

bolder

500

600

700

800

900

Treated as bold.

mso-text-shadow

Specifies whether a shadow is applied to the text on a text path. Default is false.

text-decoration

Specifies the style of text decoration. Default is none. The values are the same as those of the CSS text-decoration property. Allowed values are:

  • none

  • underline

  • overline

  • line-through

  • blink

v-rotate-letters

Specifies whether the letters of the text are rotated counterclockwise by 90 degrees. Default is false.

v-same-letter-heights

Specifies whether all letters are the same height regardless of initial case. If true, the lowercase letters are stretched to the height of the uppercase letters. Default is false.

v-text-align

Specifies the alignment of text. Default is left. Allowed values are:

  • left

  • right

  • center

  • justify

  • letter-justify - Distributes the extra space between the letters.

  • stretch-justify - Stretches the letters to fill in the space.

v-text-kern

Specifies whether kerning is turned on. Default is false.

v-text-reverse

Specifies whether the layout order of rows is reversed. Default is false. This is used for vertical text layout.

v-text-spacing-mode

Specifies the mode for letter spacing. Default is tightening. This property determines whether space is removed between each letter (tightening) or added between each letter (tracking). The amount of letter spacing change is defined by the v-text-spacing property. Allowed values are:

  • tightening

  • tracking

v-text-spacing

Specifies the amount of spacing for text in 100ths of single line spacing. Default is 100.

The line (§14.1.2.12), polyline (§14.1.2.15) and curve (§14.1.2.3) elements ignore the following properties:

  • top

  • left

  • width

  • height

The following properties are not inherited by an element that references a shapetype element (§14.1.2.20) via the id attribute:

  • flip

  • height

  • left

  • margin-left

  • margin-top

  • position

  • rotation

  • top

  • visibility

  • width

  • z-index

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

target (Hyperlink Display Target)

Specifies a frame or window that a URL is displayed in. Default is no value. Allowed values are:

Value

Description

<targetname>

String containing the name of the frame or window in which to load the document.

_blank

Specifies that the linked document is loaded into a new blank window. This window is not named.

_media

Specifies that the linked document is loaded into the browser’s multimedia pane.

_parent

Specifies that the linked document is loaded into the immediate parent of the document containing the link.

_search

Specifies that the linked document is loaded into the browser's search pane.

_self

Specifies that the linked document is loaded into the window in which the link was clicked (the active window).

_top

Specifies that the linked document is loaded into the topmost window.

[Example:

<v:shape 
  href="http://www.openxmlformats.org" 
  target="_self"  >
</v:shape>

end example]

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

title (Shape Title)

Specifies the text displayed when the mouse pointer moves over the shape. Default is no value.

[Example:

<v:shape  title="tooltip"  >
</v:shape>

end example]

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

userdrawn (Exists In Master Slide)

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

Specifies whether the user has added the shape to a master slide. Default is false. Used by PresentationML.

[Example:

<v:shape  o:userdrawn="true"  >
</v:shape>

end example]

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

userhidden (Hide Script Anchors)

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

Specifies whether a script anchor is hidden. Default is false. If true, script anchors stay hidden even if the shape is otherwise visible. A script anchor is the visual representation of a script that when displayed in an application.

[Example:

<v:shape  o:userhidden="true"  >
</v:shape>

end example]

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

wrapcoords (Shape Bounding Polygon)

Specifies the bounding polygon that surrounds a shape. This is specified using a comma-delimited list of x and y coordinates: "x1,y1,x2,y2,x3,y3,…" This is used when text is tightly wrapped around a shape. Default is no value until the mso-wrap-mode style attribute is set to tight or through.

[Example:

<v:shape  
  wrapcoords="0,0 0,200, 200,200, 200,0"  >
</v:shape>

end example]

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_Image) 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

ImageFile Members

DocumentFormat.OpenXml.Vml Namespace