Skip to content

Commit e7930e4

Browse files
author
Steve Canny
committed
docs: document analysis for latent styles
1 parent 3b3713c commit e7930e4

File tree

1 file changed

+114
-11
lines changed

1 file changed

+114
-11
lines changed

‎docs/dev/analysis/features/styles/latent-styles.rst

Lines changed: 114 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -2,28 +2,109 @@
22
Latent Styles
33
=============
44

5+
Latent style definitions are a "stub" style definition specifying behavioral
6+
(UI display) attributes for built-in styles.
57

6-
Latent style candidate protocol
7-
-------------------------------
88

9-
::
9+
Latent style collection
10+
-----------------------
11+
12+
The latent style collection for a document is accessed using the
13+
:attr:`~.Styles.latent_styles` property on |Styles|::
1014

1115
>>> latent_styles = document.styles.latent_styles
1216
>>> latent_styles
1317
<docx.styles.LatentStyles object at 0x1045dd550>
1418

15-
>>> latent_styles.default_locked_state
16-
False
17-
>>> latent_styles.default_locked_state = True
18-
>>> latent_styles.default_locked_state
19-
True
19+
**Iteration.** |LatentStyles| should support iteration of contained
20+
|_LatentStyle| objects in document order.
21+
22+
**Latent style access.** A latent style can be accessed by name using
23+
dictionary-style notation.
24+
25+
**len().** |LatentStyles| supports :meth:`len`, reporting the number of
26+
|_LatentStyle| objects it contains.
27+
28+
29+
|LatentStyles| properties
30+
-------------------------
31+
32+
33+
default_priority
34+
~~~~~~~~~~~~~~~~
35+
36+
**XML semantics**. According to ISO 29500, the default value if the
37+
`w:defUIPriority` attribute is omitted is 99. 99 is explictly set in the
38+
default Word `styles.xml`, so will generally be what one finds.
39+
40+
**Protocol**::
41+
42+
>>> # return None if attribute is omitted
43+
>>> latent_styles.default_priority
44+
None
45+
>>> # but expect is will almost always be explicitly 99
46+
>>> latent_styles.default_priority
47+
99
48+
>>> latent_styles.default_priority = 42
49+
>>> latent_styles.default_priority
50+
42
51+
52+
53+
load_count
54+
~~~~~~~~~~
55+
56+
**XML semantics**. No default is stated in the spec. Don't allow assignment
57+
of |None|.
58+
59+
**Protocol**::
60+
61+
>>> latent_styles.load_count
62+
276
63+
>>> latent_styles.load_count = 242
64+
>>> latent_styles.load_count
65+
242
66+
67+
68+
Boolean properties
69+
~~~~~~~~~~~~~~~~~~
2070

21-
>>> latent_styles.default_hidden
71+
There are four boolean properties that all share the same protocol:
72+
73+
* default_to_hidden
74+
* default_to_locked
75+
* default_to_quick_style
76+
* default_to_unhide_when_used
77+
78+
**XML semantics**. Defaults to |False| if the attribute is omitted. However,
79+
the attribute should always be written explicitly on update.
80+
81+
**Protocol**::
82+
83+
>>> latent_styles.default_to_hidden
2284
False
23-
>>> latent_styles.default_hidden = True
24-
>>> latent_styles.default_hidden
85+
>>> latent_styles.default_to_hidden = True
86+
>>> latent_styles.default_to_hidden
2587
True
2688

89+
90+
Specimen XML
91+
~~~~~~~~~~~~
92+
93+
.. highlight:: xml
94+
95+
The `w:latentStyles` element used in the default Word 2011 template::
96+
97+
<w:latentStyles w:defLockedState="0" w:defUIPriority="99" w:defSemiHidden="1"
98+
w:defUnhideWhenUsed="1" w:defQFormat="0" w:count="276">
99+
100+
101+
|_LatentStyle| properties
102+
-------------------------
103+
104+
.. highlight:: python
105+
106+
::
107+
27108
>>> latent_style = latent_styles.latent_styles[0]
28109

29110
>>> latent_style.name
@@ -109,9 +190,31 @@ Latent style behavior
109190
definition.
110191

111192

193+
Specimen XML
194+
------------
195+
196+
.. highlight:: xml
197+
198+
::
199+
200+
<w:latentStyles w:defLockedState="0" w:defUIPriority="99" w:defSemiHidden="1"
201+
w:defUnhideWhenUsed="1" w:defQFormat="0" w:count="276">
202+
<w:lsdException w:name="Normal" w:semiHidden="0" w:uiPriority="0"
203+
w:unhideWhenUsed="0" w:qFormat="1"/>
204+
<w:lsdException w:name="heading 1" w:semiHidden="0" w:uiPriority="9"
205+
w:unhideWhenUsed="0" w:qFormat="1"/>
206+
<w:lsdException w:name="caption" w:uiPriority="35" w:qFormat="1"/>
207+
<w:lsdException w:name="Default Paragraph Font" w:uiPriority="1"/>
208+
<w:lsdException w:name="Bibliography" w:uiPriority="37"/>
209+
<w:lsdException w:name="TOC Heading" w:uiPriority="39" w:qFormat="1"/>
210+
</w:latentStyles>
211+
212+
112213
Schema excerpt
113214
--------------
114215

216+
.. highlight:: xml
217+
115218
::
116219

117220
<xsd:complexType name="CT_Styles">

0 commit comments

Comments
 (0)