Font

Word supports a rich variety of character formatting. Character formatting can be applied at various levels in the style hierarchy. At the lowest level, it can be applied directly to a run of text content. Above that, it can be applied to character, paragraph and table styles. It can also be applied to an abstract numbering definition. At the highest levels it can be applied via a theme or document defaults.

Typeface name

Word allows multiple typefaces to be specified for character content in a single run. This allows different Unicode character ranges such as ASCII and Arabic to be used in a single run, each being rendered in the typeface specified for that range.

Up to eight distinct typefaces may be specified for a font. Four are used to specify a typeface for a distinct code point range. These are:

  • w:ascii - used for the first 128 Unicode code points
  • w:cs - used for complex script code points
  • w:eastAsia - used for East Asian code points
  • w:hAnsi - standing for high ANSI, but effectively the catch-all for any code points not specified by one of the other three.

The other four, w:asciiTheme, w:csTheme, w:eastAsiaTheme, and w:hAnsiTheme are used to indirectly specify a theme-defined font. This allows the typeface to be set centrally in the document. These four attributes have lower precedence than the first four, so for example the value of w:asciiTheme is ignored if a w:ascii attribute is also present.

The typeface name used for a run is specified in the w:rPr/w:rFonts element. There are 8 attributes that in combination specify the typeface to be used.

Protocol

Initially, only the base typeface name is supported by the API, using the name property. Its value is the that of the w:rFonts/@w:ascii attribute or None if not present. Assignment to this property sets both the w:ascii and the w:hAnsi attribute to the assigned string or removes them both if None is assigned:

>>> font = document.styles['Normal'].font
>>> font.name
None
>>> font.name = 'Arial'
>>> font.name
'Arial'

Boolean run properties

Character formatting that is either on or off, such as bold, italic, and small caps. Certain of these properties are toggle properties that may cancel each other out if they appear more than once in the style hierarchy. See §17.7.3 for more details on toggle properties. They don’t affect the API specified here.

The following run properties are boolean (tri-state) properties:

element spec name
<b/> §17.3.2.1 Bold
<bCs/> §17.3.2.2 Complex Script Bold
<caps/> §17.3.2.5 Display All Characters as Capital Letters
<cs/> §17.3.2.7 Use Complex Script Formatting on Run
<dstrike/> §17.3.2.9 Double Strikethrough
<emboss/> §17.3.2.13 Embossing
<i/> §17.3.2.16 Italics
<iCs/> §17.3.2.17 Complex Script Italics
<imprint/> §17.3.2.18 Imprinting
<noProof/> §17.3.2.21 Do Not Check Spelling or Grammar
<oMath/> §17.3.2.22 Office Open XML Math
<outline/> §17.3.2.23 Display Character Outline
<rtl/> §17.3.2.30 Right To Left Text
<shadow/> §17.3.2.31 Shadow
<smallCaps/> §17.3.2.33 Small Caps
<snapToGrid/> §17.3.2.34 Use Document Grid Settings For Inter- Character Spacing
<specVanish/> §17.3.2.36 Paragraph Mark is Always Hidden
<strike/> §17.3.2.37 Single Strikethrough
<vanish/> §17.3.2.41 Hidden Text
<webHidden/> §17.3.2.44 Web Hidden Text

Protocol

At the API level, each of the boolean run properties is a read/write ‘tri-state’ property, having the possible values True, False, and None.

The following interactive session demonstrates the protocol for querying and applying run-level properties:

>>> run = p.add_run()
>>> run.bold
None
>>> run.bold = True
>>> run.bold
True
>>> run.bold = False
>>> run.bold
False
>>> run.bold = None
>>> run.bold
None

The semantics of the three values are as follows:

value meaning
True The effective value of the property is unconditionally on. Contrary settings in the style hierarchy have no effect.
False The effective value of the property is unconditionally off. Contrary settings in the style hierarchy have no effect.
None The element is not present. The effective value is inherited from the style hierarchy. If no value for this property is present in the style hierarchy, the effective value is off.

Toggle properties

Certain of the boolean run properties are toggle properties. A toggle property is one that behaves like a toggle at certain places in the style hierarchy. Toggle here means that setting the property on has the effect of reversing the prior setting rather than unconditionally setting the property on.

This behavior allows these properties to be overridden (turned off) in inheriting styles. For example, consider a character style emphasized that sets bold on. Another style, strong inherits from emphasized, but should display in italic rather than bold. Setting bold off has no effect because it is overridden by the bold in strong (I think). Because bold is a toggle property, setting bold on in emphasized causes its value to be toggled, to False, achieving the desired effect. See §17.7.3 for more details on toggle properties.

The following run properties are toggle properties:

element spec name
<b/> §17.3.2.1 Bold
<bCs/> §17.3.2.2 Complex Script Bold
<caps/> §17.3.2.5 Display All Characters as Capital Letters
<emboss/> §17.3.2.13 Embossing
<i/> §17.3.2.16 Italics
<iCs/> §17.3.2.17 Complex Script Italics
<imprint/> §17.3.2.18 Imprinting
<outline/> §17.3.2.23 Display Character Outline
<shadow/> §17.3.2.31 Shadow
<smallCaps/> §17.3.2.33 Small Caps
<strike/> §17.3.2.37 Single Strikethrough
<vanish/> §17.3.2.41 Hidden Text

Specimen XML

<w:r>
  <w:rPr>
    <w:b/>
    <w:i/>
    <w:smallCaps/>
    <w:strike/>
    <w:sz w:val="28"/>
    <w:szCs w:val="28"/>
    <w:u w:val="single"/>
  </w:rPr>
  <w:t>bold, italic, small caps, strike, 14 pt, and underline</w:t>
</w:r>

Schema excerpt

It appears the run properties may appear in any order and may appear multiple times each. Not sure what the semantics of that would be or why one would want to do it, but something to note. Word seems to place them in the order below when it writes the file.:

<xsd:complexType name="CT_RPr">  <!-- denormalized -->
  <xsd:sequence>
    <xsd:choice minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="rStyle"          type="CT_String"/>
      <xsd:element name="rFonts"          type="CT_Fonts"/>
      <xsd:element name="b"               type="CT_OnOff"/>
      <xsd:element name="bCs"             type="CT_OnOff"/>
      <xsd:element name="i"               type="CT_OnOff"/>
      <xsd:element name="iCs"             type="CT_OnOff"/>
      <xsd:element name="caps"            type="CT_OnOff"/>
      <xsd:element name="smallCaps"       type="CT_OnOff"/>
      <xsd:element name="strike"          type="CT_OnOff"/>
      <xsd:element name="dstrike"         type="CT_OnOff"/>
      <xsd:element name="outline"         type="CT_OnOff"/>
      <xsd:element name="shadow"          type="CT_OnOff"/>
      <xsd:element name="emboss"          type="CT_OnOff"/>
      <xsd:element name="imprint"         type="CT_OnOff"/>
      <xsd:element name="noProof"         type="CT_OnOff"/>
      <xsd:element name="snapToGrid"      type="CT_OnOff"/>
      <xsd:element name="vanish"          type="CT_OnOff"/>
      <xsd:element name="webHidden"       type="CT_OnOff"/>
      <xsd:element name="color"           type="CT_Color"/>
      <xsd:element name="spacing"         type="CT_SignedTwipsMeasure"/>
      <xsd:element name="w"               type="CT_TextScale"/>
      <xsd:element name="kern"            type="CT_HpsMeasure"/>
      <xsd:element name="position"        type="CT_SignedHpsMeasure"/>
      <xsd:element name="sz"              type="CT_HpsMeasure"/>
      <xsd:element name="szCs"            type="CT_HpsMeasure"/>
      <xsd:element name="highlight"       type="CT_Highlight"/>
      <xsd:element name="u"               type="CT_Underline"/>
      <xsd:element name="effect"          type="CT_TextEffect"/>
      <xsd:element name="bdr"             type="CT_Border"/>
      <xsd:element name="shd"             type="CT_Shd"/>
      <xsd:element name="fitText"         type="CT_FitText"/>
      <xsd:element name="vertAlign"       type="CT_VerticalAlignRun"/>
      <xsd:element name="rtl"             type="CT_OnOff"/>
      <xsd:element name="cs"              type="CT_OnOff"/>
      <xsd:element name="em"              type="CT_Em"/>
      <xsd:element name="lang"            type="CT_Language"/>
      <xsd:element name="eastAsianLayout" type="CT_EastAsianLayout"/>
      <xsd:element name="specVanish"      type="CT_OnOff"/>
      <xsd:element name="oMath"           type="CT_OnOff"/>
    </xsd:choice>
    <xsd:element name="rPrChange" type="CT_RPrChange" minOccurs="0"/>
  </xsd:sequence>
</xsd:group>

<xsd:complexType name="CT_Fonts">
  <xsd:attribute name="hint"          type="ST_Hint"/>
  <xsd:attribute name="ascii"         type="s:ST_String"/>
  <xsd:attribute name="hAnsi"         type="s:ST_String"/>
  <xsd:attribute name="eastAsia"      type="s:ST_String"/>
  <xsd:attribute name="cs"            type="s:ST_String"/>
  <xsd:attribute name="asciiTheme"    type="ST_Theme"/>
  <xsd:attribute name="hAnsiTheme"    type="ST_Theme"/>
  <xsd:attribute name="eastAsiaTheme" type="ST_Theme"/>
  <xsd:attribute name="cstheme"       type="ST_Theme"/>
</xsd:complexType>

<xsd:complexType name="CT_HpsMeasure">
  <xsd:attribute name="val" type="ST_HpsMeasure" use="required"/>
</xsd:complexType>

<xsd:complexType name="CT_OnOff">
  <xsd:attribute name="val" type="s:ST_OnOff"/>
</xsd:complexType>

<xsd:complexType name="CT_SignedHpsMeasure">
  <xsd:attribute name="val" type="ST_SignedHpsMeasure" use="required"/>
</xsd:complexType>

<xsd:complexType name="CT_String">
  <xsd:attribute name="val" type="s:ST_String" use="required"/>
</xsd:complexType>

<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:complexType name="CT_VerticalAlignRun">
  <xsd:attribute name="val" type="s:ST_VerticalAlignRun" use="required"/>
</xsd:complexType>

<!-- simple types -->

<xsd:simpleType name="ST_Hint">
  <xsd:restriction base="xsd:string">
    <xsd:enumeration value="default"/>
    <xsd:enumeration value="eastAsia"/>
    <xsd:enumeration value="cs"/>
  </xsd:restriction>
</xsd:simpleType>

<xsd:simpleType name="ST_HpsMeasure">
  <xsd:union memberTypes="s:ST_UnsignedDecimalNumber
                          s:ST_PositiveUniversalMeasure"/>
</xsd:simpleType>

<xsd:simpleType name="ST_OnOff">
  <xsd:union memberTypes="xsd:boolean ST_OnOff1"/>
</xsd:simpleType>

<xsd:simpleType name="ST_OnOff1">
  <xsd:restriction base="xsd:string">
    <xsd:enumeration value="on"/>
    <xsd:enumeration value="off"/>
  </xsd:restriction>
</xsd:simpleType>

<xsd:simpleType name="ST_PositiveUniversalMeasure">
  <xsd:restriction base="ST_UniversalMeasure">
    <xsd:pattern value="[0-9]+(\.[0-9]+)?(mm|cm|in|pt|pc|pi)"/>
  </xsd:restriction>
</xsd:simpleType>

<xsd:simpleType name="ST_SignedHpsMeasure">
  <xsd:union memberTypes="xsd:integer s:ST_UniversalMeasure"/>
</xsd:simpleType>

<xsd:simpleType name="ST_Theme">
  <xsd:restriction base="xsd:string">
    <xsd:enumeration value="majorEastAsia"/>
    <xsd:enumeration value="majorBidi"/>
    <xsd:enumeration value="majorAscii"/>
    <xsd:enumeration value="majorHAnsi"/>
    <xsd:enumeration value="minorEastAsia"/>
    <xsd:enumeration value="minorBidi"/>
    <xsd:enumeration value="minorAscii"/>
    <xsd:enumeration value="minorHAnsi"/>
  </xsd:restriction>
</xsd:simpleType>

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

<xsd:simpleType name="ST_UnsignedDecimalNumber">
  <xsd:restriction base="xsd:unsignedLong"/>
</xsd:simpleType>

<xsd:simpleType name="ST_VerticalAlignRun">
  <xsd:restriction base="xsd:string">
    <xsd:enumeration value="baseline"/>
    <xsd:enumeration value="superscript"/>
    <xsd:enumeration value="subscript"/>
  </xsd:restriction>
</xsd:simpleType>