1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
|
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
:attr:`~.Styles.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 :meth:`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
~~~~~~~~~~~~
.. highlight:: 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
-------------------------
.. highlight:: python
::
>>> 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 to |True| 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
------------
.. highlight:: 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
--------------
.. highlight:: xml
::
<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>
|
