Skip to content

bool-run-props.rst

Latest commit

 

History

History
273 lines (235 loc) · 12.9 KB

bool-run-props.rst

File metadata and controls

273 lines (235 loc) · 12.9 KB

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.

Specimen XML

<w:r w:rsidRPr="00FA3070">
  <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, size, and underline, applied in
    reverse order but not to paragraph mark</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_R">  <!-- denormalized -->
  <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">
  <xsd:sequence>
    <xsd:group ref="EG_RPrContent" minOccurs="0"/>
  </xsd:sequence>
</xsd:complexType>

<xsd:group name="EG_RPrContent">
  <xsd:sequence>
    <xsd:group   ref="EG_RPrBase" minOccurs="0" maxOccurs="unbounded"/>
    <xsd:element name="rPrChange" type="CT_RPrChange" minOccurs="0"/>
  </xsd:sequence>
</xsd:group>

<xsd:group name="EG_RPrBase">
  <xsd:choice>
    <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:group>

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

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

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

Resources