<listItem> (Drop-Down List Item)

This element specifies a single list item within the parent drop-down list structured document tag. Each list item shall be displayed in the list displayed for the parent structured document tag (if a user interface is present).

example: 
<w:sdt>
  <w:sdtPr>
    <w:dropDownList>
      <w:listItem w:displayText="The Letter A" w:value="a"/>
      <w:listItem w:displayText="The Letter B" w:value="b"/>
    </w:dropDownList>
  </w:sdtPr>
  …
</w:sdt>

Each <listItem> element within the <dropDownList> element specifies a single list item entry, in this case resulting in two list items within the parent drop-down list structured document tag. ]

Parent Elements

<dropDownList> (§2.5.2.15)

Attributes

Description

<displayText> (List Entry Display Text)

Specifies the text to display in the run content (as well as any supplied user interface) in place of the @value attribute contents for this drop-down list entry.

This value shall be used as follows:

  • If the parent structured document tag is mapped to a custom XML element, the value in that custom XML element shall be mapped the content of the @value attribute, and the resulting @displayText attribute value (if one is present) shall be displayed in the run content. If no @displayText attribute is present, then the @value shall be displayed.

  • If the corresponding entry is selected via a user interface, this value shall be stored in the parent element's run content in the document (this is the value that shall be shown in the document's WordprocessingML content).

If this attribute is omitted, then the content of the @value attribute shall be used as the display text for the current list item entry.

<w:sdt>
  <w:sdtPr>
    <w:dropDownList>
      <w:listItem w:displayText="The Letter A" w:value="a"/>
      <w:listItem w:displayText="The Letter B" w:value="b"/>
    </w:dropDownList>
  </w:sdtPr>
  …
</w:sdt>

The @displayText attribute for the first entry is The Letter A and the second is The Letter B, therefore, these values will be used to determine the display text if the parent structured document tag is mapped to custom XML data in a custom XML data part. ]

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

<value> (List Entry Value)

Specifies the value for the current list item entry.

This value shall be used as follows:

  • If the parent structured document tag is mapped to a custom XML element, the value in that custom XML element shall be mapped to this value, and the resulting @displayText attribute value (if one is present) shall be displayed in the run content. If no @displayText attribute is present, then the value shall be displayed.

  • If the corresponding entry is selected via a user interface, this value shall be stored in the parent element's @listItem attribute value.

<w:sdt>
  <w:sdtPr>
    <w:comboBox>
      <w:listItem w:displayText="Zero" w:value="0"/>
      <w:listItem w:displayText="One" w:value="1"/>
    </w:comboBox>
  </w:sdtPr>
  …
</w:sdt>

The @value attribute for the first entry is 0 and the second is 1, therefore, these values will be used to determine the display text if the parent structured document tag is mapped to custom XML data in a custom XML data part. ]

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

The following XML Schema fragment defines the contents of this element:

<complexType name="CT_SdtListItem">
	<attribute name="displayText" type="ST_String"/>
	<attribute name="value" type="ST_String"/>
</complexType>