Skip to content

Commit 93b990c

Browse files
author
Steve Canny
committed
docs: document analysis for style behavior props
1 parent 4ef1c51 commit 93b990c

File tree

1 file changed

+338
-0
lines changed

1 file changed

+338
-0
lines changed

‎docs/dev/analysis/features/styles/style.rst‎

Lines changed: 338 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,344 @@
22
Style objects
33
=============
44

5+
A style is one of four types; character, paragraph, table, or numbering. All
6+
style objects have behavioral properties and formatting properties. The set of
7+
formatting properties varies depending on the style type. In general,
8+
formatting properties are inherited along this hierarchy: character ->
9+
paragraph -> table. A numbering style has no formatting properties and does
10+
not inherit.
11+
12+
Behavioral properties
13+
---------------------
14+
15+
There are six behavior properties:
16+
17+
hidden
18+
Style operates to assign formatting properties, but does not appear in
19+
the UI under any circumstances. Used for *internal* styles assigned by an
20+
application that should not be under the control of an end-user.
21+
22+
priority
23+
Determines the sort order of the style in sequences presented by the UI.
24+
25+
semi-hidden
26+
The style is hidden from the so-called "main" user interface. In Word
27+
this means the *recommended list* and the style gallery. The style still
28+
appears in the *all styles* list.
29+
30+
unhide_when_used
31+
Flag to the application to set semi-hidden False when the style is next
32+
used.
33+
34+
quick_style
35+
Show the style in the style gallery when it is not hidden.
36+
37+
locked
38+
Style is hidden and cannot be applied when document formatting protection
39+
is active.
40+
41+
42+
hidden
43+
------
44+
45+
The `hidden` attribute doesn't work on built-in styles and its behavior on
46+
custom styles is spotty. Skipping this attribute for now. Will reconsider if
47+
someone requests it and can provide a specific use case.
48+
49+
Behavior
50+
~~~~~~~~
51+
52+
**Scope.** `hidden` doesn't work at all on 'Normal' or 'Heading 1' style. It
53+
doesn't work on Salutation either. There is no `w:defHidden` attribute on
54+
`w:latentStyles`, lending credence to the hypothesis it is not enabled for
55+
built-in styles. *Hypothesis:* Doesn't work on built-in styles.
56+
57+
**UI behavior.** A custom style having `w:hidden` set |True| is hidden from
58+
the gallery and all styles pane lists. It does however appear in the "Current
59+
style of selected text" box in the styles pane when the cursor is on
60+
a paragraph of that style. The style can be modified by the user from this
61+
current style UI element. The user can assign a new style to a paragraph
62+
having a hidden style.
63+
64+
65+
priority
66+
--------
67+
68+
The `priority` attribute is the integer primary sort key determining the
69+
position of a style in a UI list. The secondary sort is alphabetical by name.
70+
Negative values are valid, although not assigned by Word itself and appear to
71+
be treated as 0.
72+
73+
Behavior
74+
~~~~~~~~
75+
76+
**Default.** Word behavior appears to default priority to 0 for custom
77+
styles. The spec indicates the effective default value is conceptually
78+
infinity, such that the style appears at the end of the styles list,
79+
presumably alphabetically among other styles having no priority assigned.
80+
81+
Candidate protocol
82+
~~~~~~~~~~~~~~~~~~
83+
84+
::
85+
86+
>>> style = document.styles['Foobar']
87+
>>> style.priority
88+
None
89+
>>> style.priority = 7
90+
>>> style.priority
91+
7
92+
>>> style.priority = -42
93+
>>> style.priority
94+
0
95+
96+
97+
semi-hidden
98+
-----------
99+
100+
The `w:semiHidden` element specifies visibility of the style in the so-called
101+
*main* user interface. For Word, this means the style gallery and the
102+
recommended, styles-in-use, and in-current-document lists. The all-styles
103+
list and current-style dropdown in the styles pane would then be considered
104+
part of an *advanced* user interface.
105+
106+
Behavior
107+
~~~~~~~~
108+
109+
**Default.** If the `w:semiHidden` element is omitted, its effective value is
110+
|False|. There is no inheritance of this value.
111+
112+
**Scope.** Works on both built-in and custom styles.
113+
114+
**Word behavior.** Word does not use the `@w:val` attribute. It writes
115+
`<w:semiHidden/>` for |True| and omits the element for |False|.
116+
117+
Candidate protocol
118+
~~~~~~~~~~~~~~~~~~
119+
120+
::
121+
122+
>>> style = document.styles['Foo']
123+
>>> style.hidden
124+
False
125+
>>> style.hidden = True
126+
>>> style.hidden
127+
True
128+
129+
Example XML
130+
~~~~~~~~~~~
131+
132+
.. highlight:: xml
133+
134+
style.hidden = True::
135+
136+
<w:style w:type="paragraph" w:styleId="Foo">
137+
<w:name w:val="Foo"/>
138+
<w:semiHidden/>
139+
</w:style>
140+
141+
style.hidden = False::
142+
143+
<w:style w:type="paragraph" w:styleId="Foo">
144+
<w:name w:val="Foo"/>
145+
</w:style>
146+
147+
Alternate constructions should also report the proper value but not be
148+
used when writing XML::
149+
150+
<w:style w:type="paragraph" w:styleId="Foo">
151+
<w:name w:val="Foo"/>
152+
<w:semiHidden w:val="0"/> <!-- style.hidden is False -->
153+
</w:style>
154+
155+
<w:style w:type="paragraph" w:styleId="Foo">
156+
<w:name w:val="Foo"/>
157+
<w:semiHidden w:val="1"/> <!-- style.hidden is True -->
158+
</w:style>
159+
160+
161+
unhide-when-used
162+
----------------
163+
164+
The `w:unhideWhenUsed` element signals an application that this style should
165+
be made visibile the next time it is used.
166+
167+
Behavior
168+
~~~~~~~~
169+
170+
**Default.** If the `w:unhideWhenUsed` element is omitted, its effective
171+
value is |False|. There is no inheritance of this value.
172+
173+
**Word behavior.** The `w:unhideWhenUsed` element is not changed or removed
174+
when the style is next used. Only the `w:semiHidden` element is affected, if
175+
present. Presumably this is so a style can be re-hidden, to be unhidden on
176+
the subsequent use.
177+
178+
Note that this behavior in Word is only triggered by a user actually applying
179+
a style. Merely loading a document having the style applied somewhere in its
180+
contents does not cause the `w:semiHidden` element to be removed.
181+
182+
Candidate protocol
183+
~~~~~~~~~~~~~~~~~~
184+
185+
::
186+
187+
>>> style = document.styles['Foo']
188+
>>> style.unhide_when_used
189+
False
190+
>>> style.unhide_when_used = True
191+
>>> style.unhide_when_used
192+
True
193+
194+
Example XML
195+
~~~~~~~~~~~
196+
197+
.. highlight:: xml
198+
199+
style.unhide_when_used = True::
200+
201+
<w:style w:type="paragraph" w:styleId="Foo">
202+
<w:name w:val="Foo"/>
203+
<w:semiHidden/>
204+
<w:unhideWhenUsed/>
205+
</w:style>
206+
207+
style.unhide_when_used = False::
208+
209+
<w:style w:type="paragraph" w:styleId="Foo">
210+
<w:name w:val="Foo"/>
211+
</w:style>
212+
213+
Alternate constructions should also report the proper value but not be
214+
used when writing XML::
215+
216+
<w:style w:type="paragraph" w:styleId="Foo">
217+
<w:name w:val="Foo"/>
218+
<w:unhideWhenUsed w:val="0"/> <!-- style.unhide_when_used is False -->
219+
</w:style>
220+
221+
<w:style w:type="paragraph" w:styleId="Foo">
222+
<w:name w:val="Foo"/>
223+
<w:unhideWhenUsed w:val="1"/> <!-- style.unhide_when_used is True -->
224+
</w:style>
225+
226+
227+
quick-style
228+
-----------
229+
230+
The `w:qFormat` element specifies whether Word should display this style in
231+
the style gallery. In order to appear in the gallery, this attribute must be
232+
|True| and `hidden` must be |False|.
233+
234+
Behavior
235+
~~~~~~~~
236+
237+
**Default.** If the `w:qFormat` element is omitted, its effective value is
238+
|False|. There is no inheritance of this value.
239+
240+
**Word behavior.** If `w:qFormat` is |True| and the style is not hidden, it
241+
will appear in the gallery in the order specified by `w:uiPriority`.
242+
243+
Candidate protocol
244+
~~~~~~~~~~~~~~~~~~
245+
246+
::
247+
248+
>>> style = document.styles['Foo']
249+
>>> style.quick_style
250+
False
251+
>>> style.quick_style = True
252+
>>> style.quick_style
253+
True
254+
255+
Example XML
256+
~~~~~~~~~~~
257+
258+
.. highlight:: xml
259+
260+
style.quick_style = True::
261+
262+
<w:style w:type="paragraph" w:styleId="Foo">
263+
<w:name w:val="Foo"/>
264+
<w:qFormat/>
265+
</w:style>
266+
267+
style.quick_style = False::
268+
269+
<w:style w:type="paragraph" w:styleId="Foo">
270+
<w:name w:val="Foo"/>
271+
</w:style>
272+
273+
Alternate constructions should also report the proper value but not be
274+
used when writing XML::
275+
276+
<w:style w:type="paragraph" w:styleId="Foo">
277+
<w:name w:val="Foo"/>
278+
<w:qFormat w:val="0"/> <!-- style.quick_style is False -->
279+
</w:style>
280+
281+
<w:style w:type="paragraph" w:styleId="Foo">
282+
<w:name w:val="Foo"/>
283+
<w:qFormat w:val="1"/> <!-- style.quick_style is True -->
284+
</w:style>
285+
286+
287+
locked
288+
------
289+
290+
The `w:locked` element specifies whether Word should prevent this style from
291+
being applied to content. This behavior is only active if formatting
292+
protection is turned on.
293+
294+
Behavior
295+
~~~~~~~~
296+
297+
**Default.** If the `w:locked` element is omitted, its effective value is
298+
|False|. There is no inheritance of this value.
299+
300+
Candidate protocol
301+
~~~~~~~~~~~~~~~~~~
302+
303+
::
304+
305+
>>> style = document.styles['Foo']
306+
>>> style.locked
307+
False
308+
>>> style.locked = True
309+
>>> style.locked
310+
True
311+
312+
Example XML
313+
~~~~~~~~~~~
314+
315+
.. highlight:: xml
316+
317+
style.locked = True::
318+
319+
<w:style w:type="paragraph" w:styleId="Foo">
320+
<w:name w:val="Foo"/>
321+
<w:locked/>
322+
</w:style>
323+
324+
style.locked = False::
325+
326+
<w:style w:type="paragraph" w:styleId="Foo">
327+
<w:name w:val="Foo"/>
328+
</w:style>
329+
330+
Alternate constructions should also report the proper value but not be
331+
used when writing XML::
332+
333+
<w:style w:type="paragraph" w:styleId="Foo">
334+
<w:name w:val="Foo"/>
335+
<w:locked w:val="0"/> <!-- style.locked is False -->
336+
</w:style>
337+
338+
<w:style w:type="paragraph" w:styleId="Foo">
339+
<w:name w:val="Foo"/>
340+
<w:locked w:val="1"/> <!-- style.locked is True -->
341+
</w:style>
342+
5343

6344
Candidate protocols
7345
-------------------

0 commit comments

Comments
 (0)