20.4.2.3 anchor

20 DrawingML - Framework Reference Material

20.4 DrawingML - WordprocessingML Drawing

20.4.2.3 anchor

This element specifies that the DrawingML object located at this position in the document is a floating object. Within a WordprocessingML document, drawing objects can exist in two states:

Inline - The drawing object is in line with the text, and affects the line height and layout of its line (like a
character glyph of similar size).
Floating - The drawing object is anchored within the text, but can be absolutely positioned in the
document relative to the page.

When this element encapsulates the DrawingML object’s information, then all child elements shall dictate the positioning of this object as a floating object on the page.

[Example: Consider a WordprocessingML document where the anchor for a floating DrawingML object must be the first piece of run content within a paragraph. That paragraph’s content would be specified as follows:

<w:p>
  <w:r>
    <w:drawing>
      <wp:anchor … >
        …
      </wp:anchor>
    </w:drawing>
  </w:r>
</w:p>

The anchor element, when present as the child element of the drawing element, specifies that this DrawingML object must be positioned as a floating object based on the values of its child elements. end example]

Attributes

behindDoc (Display Behind Document Text)

Specifies whether this floating DrawingML object is displayed behind the text of the document when the document is displayed. When a DrawingML object is displayed within a WordprocessingML document, that object can intersect with text in the document. This attribute shall determine whether the text or the object is rendered on top in case of overlapping.

[Example: Consider a floating DrawingML object which must be displayed above any text which it intersects within the document’s content. This setting would be specified as follows:

    <wp:anchor behindDoc="false" … >
        …
    </wp:anchor>

The behindDoc attribute has a value of false, which specifies that the DrawingML object is displayed above the text of the document in z-order. end example]

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

allowOverlap (Allow Objects to Overlap)

Specifies whether a DrawingML object which intersects another DrawingML object at display time is allowed to overlap the contents of the other DrawingML object. If a DrawingML object cannot overlap other DrawingML object, it shall be repositioned when displayed to prevent this overlap as needed.

[Example: Consider a document with two DrawingML objects which are allowed to overlap each other. This would be specified as follows within each object’s anchor markup:

    <wp:anchor allowOverlap="true" … >
        …
    </wp:anchor>

The allowOverlap attribute has a value of true, which specifies that this object must be allowed to overlap other objects when it is displayed on the document. end example]

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

distL (Distance From Text on Left Edge)

Specifies the minimum distance which shall be maintained between the left edge of this drawing object and any subsequent text within the document when this graphical object is displayed within the document’s contents.

The distance shall be measured in EMUs (English Metric Units).

If this object is an inline object (i.e. has a parent element of inline), then this value shall not have any effect when displaying the object in line with text, but can be maintained and used if the object is subsequently changed to floating. If the wrapping element [Example: wrapThrough or wrapSquare end example] present as a child element also has a distance from text, then this value shall be ignored.

[Example: Consider a floating DrawingML object which must have one-quarter of an inch of padding between its left edge and the nearest text. This setting would be specified as follows:

    <wp:anchor distL="228600" … >
        …
    </wp:anchor>

The distL attribute specifies that the padding distance must be 228600 EMUs or one- quarter of an inch. end example]

The possible values for this attribute are defined by the ST_WrapDistance simple type (20.4.3.6).

distB (Distance From Text on Bottom Edge)

Specifies the minimum distance which shall be maintained between the bottom edge of this drawing object and any subsequent text within the document when this graphical object is displayed within the document’s contents.

The distance shall be measured in EMUs (English Metric Units).

[Example: Consider a floating DrawingML object which must have one-half of an inch of padding between its bottom edge and the nearest text. This setting would be specified as follows:

    <wp:anchor distB="457200" … >
        …
    </wp:anchor>

The distB attribute specifies that the padding distance must be 457200 EMUs or one-half of an inch. end example]

The possible values for this attribute are defined by the ST_WrapDistance simple type (20.4.3.6).

distT (Distance From Text on Top Edge)

Specifies the minimum distance which shall be maintained between the top edge of this drawing object and any subsequent text within the document when this graphical object is displayed within the document’s contents.

The distance shall be measured in EMUs (English Metric Units).

[Example: Consider a floating DrawingML object which must have one-half of an inch of padding between its top edge and the nearest text. This setting would be specified as follows:

    <wp:anchor distT="457200" … >
        …
    </wp:anchor>

The distT attribute specifies that the padding distance must be 457200 EMUs or one-half of an inch. end example]

The possible values for this attribute are defined by the ST_WrapDistance simple type (20.4.3.6).

distR (Distance From Text on Right Edge)

Specifies the minimum distance which shall be maintained between the right edge of this drawing object and any subsequent text within the document when this graphical object is displayed within the document’s contents.

The distance shall be measured in EMUs (English Metric Units).

[Example: Consider a floating DrawingML object which must have one-quarter of an inch of padding between its right edge and the nearest text. This setting would be specified as follows:

    <wp:anchor distR="228600" … >
        …
    </wp:anchor>

The distR attribute specifies that the padding distance must be 228600 EMUs or one- quarter of an inch. end example]

The possible values for this attribute are defined by the ST_WrapDistance simple type (20.4.3.6).

layoutInCell (Layout In Table Cell)

Specifies how this DrawingML object behaves when its anchor is located in a table cell; and its specified position would cause it to intersect with a table cell displayed in the document. That behavior shall be as follows:

When this attribute has a value of true, then the object shall be positioned within the existing table cell, causing the cell to be resized as needed. This means that all positioning shall be relative to the cell and not the line on which the table appears.
When this attribute has a value of false, then the object shall be positioned as specified, but the table shall be resized and/or relocated within the document as needed to accommodate the object. This means that all positioning shall be

relative to the line on which the table appears and not the cell in which the anchor is present.

[Example: Consider a DrawingML picture which must be displayed in the center of the document. If the object is contained within a table and is defined as follows:

    <wp:anchor layoutInCell="true" … >
        …
    </wp:anchor>

The layoutInCell attribute has a value of true, which specifies that the object can be placed within the cell if needed, for example:

If the layoutInCell attribute was now set to false, the object must be laid out outside of the cell, causing the table to be repositioned:

end example]

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

hidden (Hidden)

Specifies whether this floating DrawingML object is displayed. When a DrawingML object is displayed within a WordprocessingML document, that object can be hidden (i.e. present, but not visible). This attribute shall determine whether the object is rendered or made hidden. [Note: An application can have settings which allow this object to be viewed. end note]

If this attribute is omitted, then the parent DrawingML object shall be displayed (i.e. not hidden).

[Example: Consider a floating DrawingML object which must be hidden within the document’s content. This setting would be specified as follows:

    <wp:anchor hidden="true" … >
        …
    </wp:anchor>

The hidden attribute has a value of true, which specifies that the DrawingML object is hidden and not displayed when the document is displayed. end example]

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

locked (Lock

Specifies that the anchor location for this object shall not be modified at runtime when

simplePos (Page

Specifies that this object shall be positioned using the positioning information in the

relativeHeight (Relative Z-Ordering Position)

Specifies the relative Z-ordering of all DrawingML objects in this document. Each floating DrawingML object shall have a Z-ordering value, which determines which object is displayed when any two objects intersect. Higher values shall indicate higher Z-order; lower values shall indicate lower Z-order.

This attribute shall only indicate the Z-order with respect to other objects in the document which have an identical behindDoc attribute value. All objects with a behindDoc value of false shall be displayed above elements with a value of true.

[Example: Consider

two floating DrawingML objects as follows:

    <wp:anchor relativeHeight="5" … >
        …
    </wp:anchor>
    …
    <wp:anchor
                  relativeHeight="8" … >
        …
    </wp:anchor>

The relativeHeight attribute of the second object is 8, which specifies that the second DrawingML object must be at a higher Z-order than the first and must be displayed whenever the two overlap. end example]

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

Anchor)

an application edits the contents of this document. [Guidance: An application might have automatic behaviors which reposition the anchor for a DrawingML object based on user interaction - for example, moving it from one page to another as needed. This element must tell applications not to perform any such behaviors. end guidance]

[Example: Consider a floating DrawingML object which must have its anchor locked at the current location. This setting would be specified as follows:

    <wp:anchor locked="true" … >
        …
    </wp:anchor>

The locked attribute has a value of true, which specifies that the DrawingML object’s current anchor location must not be changed by applications editing this content. end example]

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

Positioning)

simplePos child element (20.4.2.13). This positioning, when specified, positions the object on the page by placing its top left point at the x-y coordinates specified by that element.

If this element is omitted, then this object shall not use the simple positioning information in the simplePos element, even when present. [Example: Consider a floating DrawingML object which must be positioned at the top left corner of the page using simple positioning. This setting would be specified as follows:

    <wp:anchor simplePos="true" … >
        <wp:simplePos x="0" y="0" />
        …
    </wp:anchor>

The simplePos attribute has a value of true, which specifies that the DrawingML object’s current position must be dictated by the simplePos element, and hence placed at 0,0. end example]

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

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

Last updated on March 14, 2025

20.4.3.2 ST_AlignV 20.4.3.3 ST_PositionOffset