Underline

Text in a Word document can be underlined in a variety of styles.

Protocol

The call protocol for underline is overloaded such that it works like .bold and .italic for single underline, but also allows an enumerated value to be assigned to specify more sophisticated underlining such as dashed, wavy, and double-underline:

>>> run = paragraph.add_run()
>>> run.underline
None
>>> run.underline = True
>>> run.underline
True
>>> run.underline = WD_UNDERLINE.SINGLE
>>> run.underline
True
>>> run.underline = WD_UNDERLINE.DOUBLE
>>> str(run.underline)
DOUBLE (3)
>>> run.underline = False
>>> run.underline
False
>>> run.underline = WD_UNDERLINE.NONE
>>> run.underline
False
>>> run.underline = None
>>> run.underline
None

Enumerations

• WdUnderline Enumeration on MSDN

Specimen XML

Baseline run:

<w:r>
  <w:t>underlining determined by inheritance</w:t>
</w:r>

Single underline:

<w:r>
  <w:rPr>
    <w:u w:val="single"/>
  </w:rPr>
  <w:t>single underlined</w:t>
</w:r>

Double underline:

<w:r>
  <w:rPr>
    <w:u w:val="double"/>
  </w:rPr>
  <w:t>single underlined</w:t>
</w:r>

Directly-applied no-underline, overrides inherited value:

<w:r>
  <w:rPr>
    <w:u w:val="none"/>
  </w:rPr>
  <w:t>not underlined</w:t>
</w:r>

Schema excerpt

Note that the w:val attribute on CT_Underline is optional. When it is not present no underline appears on the run.

<xsd:complexType name="CT_R">  <!-- flattened for readibility -->
  <xsd:sequence>
    <xsd:element name="rPr" type="CT_RPr" minOccurs="0"/>
    <xsd:group   ref="EG_RunInnerContent" minOccurs="0" maxOccurs="unbounded"/>
  </xsd:sequence>
  <xsd:attribute name="rsidRPr" type="ST_LongHexNumber"/>
  <xsd:attribute name="rsidDel" type="ST_LongHexNumber"/>
  <xsd:attribute name="rsidR"   type="ST_LongHexNumber"/>
</xsd:complexType>

<xsd:complexType name="CT_RPr">  <!-- flattened for readibility -->
  <xsd:sequence>
    <xsd:group   ref="EG_RPrBase" minOccurs="0" maxOccurs="unbounded"/>
    <xsd:element name="rPrChange" type="CT_RPrChange" minOccurs="0"/>
  </xsd:sequence>
</xsd:complexType>

<xsd:group name="EG_RPrBase">
  <xsd:choice>
    <xsd:element name="rStyle"          type="CT_String"/>
    <xsd:element name="b"               type="CT_OnOff"/>
    <xsd:element name="i"               type="CT_OnOff"/>
    <xsd:element name="color"           type="CT_Color"/>
    <xsd:element name="sz"              type="CT_HpsMeasure"/>
    <xsd:element name="u"               type="CT_Underline"/>
    <!-- 33 others -->
  </xsd:choice>
</xsd:group>

<xsd:complexType name="CT_Underline">
  <xsd:attribute name="val"        type="ST_Underline"/>
  <xsd:attribute name="color"      type="ST_HexColor"/>
  <xsd:attribute name="themeColor" type="ST_ThemeColor"/>
  <xsd:attribute name="themeTint"  type="ST_UcharHexNumber"/>
  <xsd:attribute name="themeShade" type="ST_UcharHexNumber"/>
</xsd:complexType>

<xsd:simpleType name="ST_Underline">
  <xsd:restriction base="xsd:string">
    <xsd:enumeration value="single"/>
    <xsd:enumeration value="words"/>
    <xsd:enumeration value="double"/>
    <xsd:enumeration value="thick"/>
    <xsd:enumeration value="dotted"/>
    <xsd:enumeration value="dottedHeavy"/>
    <xsd:enumeration value="dash"/>
    <xsd:enumeration value="dashedHeavy"/>
    <xsd:enumeration value="dashLong"/>
    <xsd:enumeration value="dashLongHeavy"/>
    <xsd:enumeration value="dotDash"/>
    <xsd:enumeration value="dashDotHeavy"/>
    <xsd:enumeration value="dotDotDash"/>
    <xsd:enumeration value="dashDotDotHeavy"/>
    <xsd:enumeration value="wave"/>
    <xsd:enumeration value="wavyHeavy"/>
    <xsd:enumeration value="wavyDouble"/>
    <xsd:enumeration value="none"/>
  </xsd:restriction>
</xsd:simpleType>