X Tutup
Skip to content

Commit faabd7b

Browse files
author
Steve Canny
committed
docs: document analysis for add/remove style
* organize feature analysis for styles into a hierarchy
1 parent d9a47b4 commit faabd7b

File tree

6 files changed

+607
-165
lines changed

6 files changed

+607
-165
lines changed

docs/dev/analysis/features/doc-styles.rst renamed to docs/dev/analysis/features/styles/index.rst

Lines changed: 8 additions & 149 deletions
Original file line numberDiff line numberDiff line change
@@ -2,121 +2,21 @@
22
Styles
33
======
44

5+
.. toctree::
6+
:titlesonly:
7+
8+
styles
9+
style
10+
latent-styles
11+
512
Word supports the definition of *styles* to allow a group of formatting
613
properties to be easily and consistently applied to a paragraph, run, table,
7-
or numbering scheme; all at once. The mechanism is similar to how Cascading
14+
or numbering scheme, all at once. The mechanism is similar to how Cascading
815
Style Sheets (CSS) works with HTML.
916

1017
Styles are defined in the ``styles.xml`` package part and are keyed to
1118
a paragraph, run, or table using the `styleId` string.
1219

13-
14-
Latent style candidate protocol
15-
-------------------------------
16-
17-
::
18-
19-
>>> latent_styles = document.styles.latent_styles
20-
>>> latent_styles
21-
<docx.styles.LatentStyles object at 0x1045dd550>
22-
23-
>>> latent_styles.default_locked_state
24-
False
25-
>>> latent_styles.default_locked_state = True
26-
>>> latent_styles.default_locked_state
27-
True
28-
29-
>>> latent_styles.default_hidden
30-
False
31-
>>> latent_styles.default_hidden = True
32-
>>> latent_styles.default_hidden
33-
True
34-
35-
>>> exception = latent_styles.exceptions[0]
36-
37-
>>> exception.name
38-
'Normal'
39-
40-
>>> exception.priority
41-
None
42-
>>> exception.priority = 10
43-
>>> exception.priority
44-
True
45-
46-
>>> exception.locked
47-
None
48-
>>> exception.locked = True
49-
>>> exception.locked
50-
True
51-
52-
>>> exception.quick_style
53-
None
54-
>>> exception.quick_style = True
55-
>>> exception.quick_style
56-
True
57-
58-
59-
Latent style behavior
60-
---------------------
61-
62-
* A style has two categories of attribute, *behavioral* and *formatting*.
63-
Behavioral attributes specify where and when the style should appear in the
64-
user interface. Behavioral attributes can be specified for latent styles
65-
using the ``<w:latentStyles>`` element and its ``<w:lsdException>`` child
66-
elements. The 5 behavioral attributes are:
67-
68-
+ locked
69-
+ uiPriority
70-
+ semiHidden
71-
+ unhideWhenUsed
72-
+ qFormat
73-
74-
* **locked**. The `locked` attribute specifies that the style should not
75-
appear in any list or the gallery and may not be applied to content. This
76-
behavior is only active when restricted formatting is turned on.
77-
78-
Locking is turned on via the menu: Developer Tab > Protect Document >
79-
Formatting Restrictions (Windows only).
80-
81-
* **uiPriority**. The `uiPriority` attribute acts as a sort key for
82-
sequencing style names in the user interface. Both the lists in the styles
83-
panel and the Style Gallery are sensitive to this setting. Its effective
84-
value is 0 if not specified.
85-
86-
* **semiHidden**. The `semiHidden` attribute causes the style to be excluded
87-
from the recommended list. The notion of *semi* in this context is that
88-
while the style is hidden from the recommended list, it still appears in
89-
the "All Styles" list. This attribute is removed on first application of
90-
the style if an `unhideWhenUsed` attribute set |True| is also present.
91-
92-
* **unhideWhenUsed**. The `unhideWhenUsed` attribute causes any `semiHidden`
93-
attribute to be removed when the style is first applied to content. Word
94-
does *not* remove the `semiHidden` attribute just because there exists an
95-
object in the document having that style. The `unhideWhenUsed` attribute is
96-
not removed along with the `semiHidden` attribute when the style is
97-
applied.
98-
99-
The `semiHidden` and `unhideWhenUsed` attributes operate in combination to
100-
produce *hide-until-used* behavior.
101-
102-
*Hypothesis.* The persistance of the `unhideWhenUsed` attribute after
103-
removing the `semiHidden` attribute on first application of the style is
104-
necessary to produce appropriate behavior in style inheritance situations.
105-
In that case, the `semiHidden` attribute may be explictly set to |False| to
106-
override an inherited value. Or it could allow the `semiHidden` attribute
107-
to be re-set to |True| later while preserving the hide-until-used behavior.
108-
109-
* **qFormat**. The `qFormat` attribute specifies whether the style should
110-
appear in the Style Gallery when it appears in the recommended list.
111-
A style will never appear in the gallery unless it also appears in the
112-
recommended list.
113-
114-
* Latent style attributes are only operative for latent styles. Once a style
115-
is defined, the attributes of the definition exclusively determine style
116-
behavior; no attributes are inherited from its corresponding latent style
117-
definition.
118-
119-
12020
Style visual behavior
12121
---------------------
12222

@@ -217,34 +117,6 @@ definition if it is no longer applied to any content. The definition of each
217117
of the styles ever used in a document are accumulated in its ``styles.xml``.
218118

219119

220-
Candidate protocol
221-
------------------
222-
223-
::
224-
225-
>>> styles = document.styles # default styles part added if not present
226-
>>> list_styles = [s for s in styles if s.type == WD_STYLE_TYPE.LIST]
227-
>>> list_styles[0].type
228-
WD_STYLE_TYPE.LIST (4)
229-
230-
>>> style = styles.add_style('Citation', WD_STYLE_TYPE.PARAGRAPH)
231-
232-
>>> document.add_paragraph(style='undefined-style')
233-
KeyError: no style with id 'undefined-style'
234-
235-
236-
Feature Notes
237-
-------------
238-
239-
* could add a default builtin style from known specs on first access via
240-
WD_BUILTIN_STYLE enumeration::
241-
242-
>>> style = document.styles['Heading1']
243-
KeyError: no style with id or name 'Heading1'
244-
>>> style = document.styles[WD_STYLE.HEADING_1]
245-
>>> assert style == document.styles['Heading1']
246-
247-
248120
Related MS API *(partial)*
249121
--------------------------
250122

@@ -280,19 +152,6 @@ Enumerations
280152
* WdBuiltinStyle
281153

282154

283-
Spec text
284-
---------
285-
286-
This element specifies all of the style information stored in the
287-
WordprocessingML document: style definitions as well as latent style
288-
information.
289-
290-
Example: The Normal paragraph style in a word processing document can have
291-
any number of formatting properties, e.g. font face = Times New Roman; font
292-
size = 12pt; paragraph justification = left. All paragraphs which reference
293-
this paragraph style would automatically inherit these properties.
294-
295-
296155
Example XML
297156
-----------
298157

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

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
2+
Latent Styles
3+
=============
4+
5+
6+
Latent style candidate protocol
7+
-------------------------------
8+
9+
::
10+
11+
>>> latent_styles = document.styles.latent_styles
12+
>>> latent_styles
13+
<docx.styles.LatentStyles object at 0x1045dd550>
14+
15+
>>> latent_styles.default_locked_state
16+
False
17+
>>> latent_styles.default_locked_state = True
18+
>>> latent_styles.default_locked_state
19+
True
20+
21+
>>> latent_styles.default_hidden
22+
False
23+
>>> latent_styles.default_hidden = True
24+
>>> latent_styles.default_hidden
25+
True
26+
27+
>>> latent_style = latent_styles.latent_styles[0]
28+
29+
>>> latent_style.name
30+
'Normal'
31+
32+
>>> latent_style.priority
33+
None
34+
>>> latent_style.priority = 10
35+
>>> latent_style.priority
36+
10
37+
38+
>>> latent_style.locked
39+
None
40+
>>> latent_style.locked = True
41+
>>> latent_style.locked
42+
True
43+
44+
>>> latent_style.quick_style
45+
None
46+
>>> latent_style.quick_style = True
47+
>>> latent_style.quick_style
48+
True
49+
50+
51+
Latent style behavior
52+
---------------------
53+
54+
* A style has two categories of attribute, *behavioral* and *formatting*.
55+
Behavioral attributes specify where and when the style should appear in the
56+
user interface. Behavioral attributes can be specified for latent styles
57+
using the ``<w:latentStyles>`` element and its ``<w:lsdException>`` child
58+
elements. The 5 behavioral attributes are:
59+
60+
+ locked
61+
+ uiPriority
62+
+ semiHidden
63+
+ unhideWhenUsed
64+
+ qFormat
65+
66+
* **locked**. The `locked` attribute specifies that the style should not
67+
appear in any list or the gallery and may not be applied to content. This
68+
behavior is only active when restricted formatting is turned on.
69+
70+
Locking is turned on via the menu: Developer Tab > Protect Document >
71+
Formatting Restrictions (Windows only).
72+
73+
* **uiPriority**. The `uiPriority` attribute acts as a sort key for
74+
sequencing style names in the user interface. Both the lists in the styles
75+
panel and the Style Gallery are sensitive to this setting. Its effective
76+
value is 0 if not specified.
77+
78+
* **semiHidden**. The `semiHidden` attribute causes the style to be excluded
79+
from the recommended list. The notion of *semi* in this context is that
80+
while the style is hidden from the recommended list, it still appears in
81+
the "All Styles" list. This attribute is removed on first application of
82+
the style if an `unhideWhenUsed` attribute set |True| is also present.
83+
84+
* **unhideWhenUsed**. The `unhideWhenUsed` attribute causes any `semiHidden`
85+
attribute to be removed when the style is first applied to content. Word
86+
does *not* remove the `semiHidden` attribute just because there exists an
87+
object in the document having that style. The `unhideWhenUsed` attribute is
88+
not removed along with the `semiHidden` attribute when the style is
89+
applied.
90+
91+
The `semiHidden` and `unhideWhenUsed` attributes operate in combination to
92+
produce *hide-until-used* behavior.
93+
94+
*Hypothesis.* The persistance of the `unhideWhenUsed` attribute after
95+
removing the `semiHidden` attribute on first application of the style is
96+
necessary to produce appropriate behavior in style inheritance situations.
97+
In that case, the `semiHidden` attribute may be explictly set to |False| to
98+
override an inherited value. Or it could allow the `semiHidden` attribute
99+
to be re-set to |True| later while preserving the hide-until-used behavior.
100+
101+
* **qFormat**. The `qFormat` attribute specifies whether the style should
102+
appear in the Style Gallery when it appears in the recommended list.
103+
A style will never appear in the gallery unless it also appears in the
104+
recommended list.
105+
106+
* Latent style attributes are only operative for latent styles. Once a style
107+
is defined, the attributes of the definition exclusively determine style
108+
behavior; no attributes are inherited from its corresponding latent style
109+
definition.
110+
111+
112+
Schema excerpt
113+
--------------
114+
115+
::
116+
117+
<xsd:complexType name="CT_Styles">
118+
<xsd:sequence>
119+
<xsd:element name="docDefaults" type="CT_DocDefaults" minOccurs="0"/>
120+
<xsd:element name="latentStyles" type="CT_LatentStyles" minOccurs="0"/>
121+
<xsd:element name="style" type="CT_Style" minOccurs="0" maxOccurs="unbounded"/>
122+
</xsd:sequence>
123+
</xsd:complexType>
124+
125+
<xsd:complexType name="CT_LatentStyles">
126+
<xsd:sequence>
127+
<xsd:element name="lsdException" type="CT_LsdException" minOccurs="0" maxOccurs="unbounded"/>
128+
</xsd:sequence>
129+
<xsd:attribute name="defLockedState" type="s:ST_OnOff"/>
130+
<xsd:attribute name="defUIPriority" type="ST_DecimalNumber"/>
131+
<xsd:attribute name="defSemiHidden" type="s:ST_OnOff"/>
132+
<xsd:attribute name="defUnhideWhenUsed" type="s:ST_OnOff"/>
133+
<xsd:attribute name="defQFormat" type="s:ST_OnOff"/>
134+
<xsd:attribute name="count" type="ST_DecimalNumber"/>
135+
</xsd:complexType>
136+
137+
<xsd:complexType name="CT_LsdException">
138+
<xsd:attribute name="name" type="s:ST_String" use="required"/>
139+
<xsd:attribute name="locked" type="s:ST_OnOff"/>
140+
<xsd:attribute name="uiPriority" type="ST_DecimalNumber"/>
141+
<xsd:attribute name="semiHidden" type="s:ST_OnOff"/>
142+
<xsd:attribute name="unhideWhenUsed" type="s:ST_OnOff"/>
143+
<xsd:attribute name="qFormat" type="s:ST_OnOff"/>
144+
</xsd:complexType>
145+
146+
<xsd:complexType name="CT_OnOff">
147+
<xsd:attribute name="val" type="s:ST_OnOff"/>
148+
</xsd:complexType>
149+
150+
<xsd:complexType name="CT_String">
151+
<xsd:attribute name="val" type="s:ST_String" use="required"/>
152+
</xsd:complexType>
153+
154+
<xsd:simpleType name="ST_OnOff">
155+
<xsd:union memberTypes="xsd:boolean ST_OnOff1"/>
156+
</xsd:simpleType>
157+
158+
<xsd:simpleType name="ST_OnOff1">
159+
<xsd:restriction base="xsd:string">
160+
<xsd:enumeration value="on"/>
161+
<xsd:enumeration value="off"/>
162+
</xsd:restriction>
163+
</xsd:simpleType>

0 commit comments

Comments
 (0)
X Tutup