Latent Styles¶
Latent style definitions are a “stub” style definition specifying behavioral (UI display) attributes for built-in styles.
Latent style collection¶
The latent style collection for a document is accessed using the
latent_styles
property on Styles
:
>>> latent_styles = document.styles.latent_styles
>>> latent_styles
<docx.styles.LatentStyles object at 0x1045dd550>
Iteration. LatentStyles
should support iteration of contained
_LatentStyle
objects in document order.
Latent style access. A latent style can be accessed by name using dictionary-style notation.
len(). LatentStyles
supports len()
, reporting the number of
_LatentStyle
objects it contains.
LatentStyles
properties¶
default_priority¶
XML semantics. According to ISO 29500, the default value if the w:defUIPriority attribute is omitted is 99. 99 is explictly set in the default Word styles.xml, so will generally be what one finds.
Protocol:
>>> # return None if attribute is omitted
>>> latent_styles.default_priority
None
>>> # but expect is will almost always be explicitly 99
>>> latent_styles.default_priority
99
>>> latent_styles.default_priority = 42
>>> latent_styles.default_priority
42
load_count¶
XML semantics. No default is stated in the spec. Don’t allow assignment
of None
.
Protocol:
>>> latent_styles.load_count
276
>>> latent_styles.load_count = 242
>>> latent_styles.load_count
242
Boolean properties¶
There are four boolean properties that all share the same protocol:
- default_to_hidden
- default_to_locked
- default_to_quick_style
- default_to_unhide_when_used
XML semantics. Defaults to False
if the attribute is omitted. However,
the attribute should always be written explicitly on update.
Protocol:
>>> latent_styles.default_to_hidden
False
>>> latent_styles.default_to_hidden = True
>>> latent_styles.default_to_hidden
True
Specimen XML¶
The w:latentStyles element used in the default Word 2011 template:
<w:latentStyles w:defLockedState="0" w:defUIPriority="99" w:defSemiHidden="1"
w:defUnhideWhenUsed="1" w:defQFormat="0" w:count="276">
_LatentStyle
properties¶
>>> latent_style = latent_styles.latent_styles[0]
>>> latent_style.name
'Normal'
>>> latent_style.priority
None
>>> latent_style.priority = 10
>>> latent_style.priority
10
>>> latent_style.locked
None
>>> latent_style.locked = True
>>> latent_style.locked
True
>>> latent_style.quick_style
None
>>> latent_style.quick_style = True
>>> latent_style.quick_style
True
Latent style behavior¶
A style has two categories of attribute, behavioral and formatting. Behavioral attributes specify where and when the style should appear in the user interface. Behavioral attributes can be specified for latent styles using the
<w:latentStyles>
element and its<w:lsdException>
child elements. The 5 behavioral attributes are:- locked
- uiPriority
- semiHidden
- unhideWhenUsed
- qFormat
locked. The locked attribute specifies that the style should not appear in any list or the gallery and may not be applied to content. This behavior is only active when restricted formatting is turned on.
Locking is turned on via the menu: Developer Tab > Protect Document > Formatting Restrictions (Windows only).
uiPriority. The uiPriority attribute acts as a sort key for sequencing style names in the user interface. Both the lists in the styles panel and the Style Gallery are sensitive to this setting. Its effective value is 0 if not specified.
semiHidden. The semiHidden attribute causes the style to be excluded from the recommended list. The notion of semi in this context is that while the style is hidden from the recommended list, it still appears in the “All Styles” list. This attribute is removed on first application of the style if an unhideWhenUsed attribute set
True
is also present.unhideWhenUsed. The unhideWhenUsed attribute causes any semiHidden attribute to be removed when the style is first applied to content. Word does not remove the semiHidden attribute just because there exists an object in the document having that style. The unhideWhenUsed attribute is not removed along with the semiHidden attribute when the style is applied.
The semiHidden and unhideWhenUsed attributes operate in combination to produce hide-until-used behavior.
Hypothesis. The persistance of the unhideWhenUsed attribute after removing the semiHidden attribute on first application of the style is necessary to produce appropriate behavior in style inheritance situations. In that case, the semiHidden attribute may be explictly set to
False
to override an inherited value. Or it could allow the semiHidden attribute to be re-set toTrue
later while preserving the hide-until-used behavior.qFormat. The qFormat attribute specifies whether the style should appear in the Style Gallery when it appears in the recommended list. A style will never appear in the gallery unless it also appears in the recommended list.
Latent style attributes are only operative for latent styles. Once a style is defined, the attributes of the definition exclusively determine style behavior; no attributes are inherited from its corresponding latent style definition.
Specimen XML¶
<w:latentStyles w:defLockedState="0" w:defUIPriority="99" w:defSemiHidden="1"
w:defUnhideWhenUsed="1" w:defQFormat="0" w:count="276">
<w:lsdException w:name="Normal" w:semiHidden="0" w:uiPriority="0"
w:unhideWhenUsed="0" w:qFormat="1"/>
<w:lsdException w:name="heading 1" w:semiHidden="0" w:uiPriority="9"
w:unhideWhenUsed="0" w:qFormat="1"/>
<w:lsdException w:name="caption" w:uiPriority="35" w:qFormat="1"/>
<w:lsdException w:name="Default Paragraph Font" w:uiPriority="1"/>
<w:lsdException w:name="Bibliography" w:uiPriority="37"/>
<w:lsdException w:name="TOC Heading" w:uiPriority="39" w:qFormat="1"/>
</w:latentStyles>
Schema excerpt¶
<xsd:complexType name="CT_Styles">
<xsd:sequence>
<xsd:element name="docDefaults" type="CT_DocDefaults" minOccurs="0"/>
<xsd:element name="latentStyles" type="CT_LatentStyles" minOccurs="0"/>
<xsd:element name="style" type="CT_Style" minOccurs="0" maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="CT_LatentStyles">
<xsd:sequence>
<xsd:element name="lsdException" type="CT_LsdException" minOccurs="0" maxOccurs="unbounded"/>
</xsd:sequence>
<xsd:attribute name="defLockedState" type="s:ST_OnOff"/>
<xsd:attribute name="defUIPriority" type="ST_DecimalNumber"/>
<xsd:attribute name="defSemiHidden" type="s:ST_OnOff"/>
<xsd:attribute name="defUnhideWhenUsed" type="s:ST_OnOff"/>
<xsd:attribute name="defQFormat" type="s:ST_OnOff"/>
<xsd:attribute name="count" type="ST_DecimalNumber"/>
</xsd:complexType>
<xsd:complexType name="CT_LsdException">
<xsd:attribute name="name" type="s:ST_String" use="required"/>
<xsd:attribute name="locked" type="s:ST_OnOff"/>
<xsd:attribute name="uiPriority" type="ST_DecimalNumber"/>
<xsd:attribute name="semiHidden" type="s:ST_OnOff"/>
<xsd:attribute name="unhideWhenUsed" type="s:ST_OnOff"/>
<xsd:attribute name="qFormat" type="s:ST_OnOff"/>
</xsd:complexType>
<xsd:complexType name="CT_OnOff">
<xsd:attribute name="val" type="s:ST_OnOff"/>
</xsd:complexType>
<xsd:complexType name="CT_String">
<xsd:attribute name="val" type="s:ST_String" use="required"/>
</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>