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
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
|
Font
====
Word supports a rich variety of character formatting. Character formatting
can be applied at various levels in the *style hierarchy*. At the lowest
level, it can be applied directly to a run of text content. Above that, it
can be applied to character, paragraph and table styles. It can also be
applied to an abstract numbering definition. At the highest levels it can be
applied via a theme or document defaults.
Typeface name
-------------
Word allows multiple typefaces to be specified for character content in
a single run. This allows different Unicode character ranges such as ASCII
and Arabic to be used in a single run, each being rendered in the typeface
specified for that range.
Up to eight distinct typefaces may be specified for a font. Four are used to
specify a typeface for a distinct code point range. These are:
* `w:ascii` - used for the first 128 Unicode code points
* `w:cs` - used for complex script code points
* `w:eastAsia` - used for East Asian code points
* `w:hAnsi` - standing for *high ANSI*, but effectively the catch-all for any
code points not specified by one of the other three.
The other four, `w:asciiTheme`, `w:csTheme`, `w:eastAsiaTheme`, and
`w:hAnsiTheme` are used to indirectly specify a theme-defined font. This
allows the typeface to be set centrally in the document. These four attributes
have lower precedence than the first four, so for example the value of
`w:asciiTheme` is ignored if a `w:ascii` attribute is also present.
The typeface name used for a run is specified in the `w:rPr/w:rFonts`
element. There are 8 attributes that in combination specify the typeface to
be used.
Protocol
~~~~~~~~
Initially, only the base typeface name is supported by the API, using the
:attr:`~.Font.name` property. Its value is the that of the `w:rFonts/@w:ascii`
attribute or |None| if not present. Assignment to this property sets both the
`w:ascii` and the `w:hAnsi` attribute to the assigned string or removes them
both if |None| is assigned::
>>> font = document.styles['Normal'].font
>>> font.name
None
>>> font.name = 'Arial'
>>> font.name
'Arial'
Boolean run properties
----------------------
Character formatting that is either on or off, such as bold, italic, and
small caps. Certain of these properties are *toggle properties* that may
cancel each other out if they appear more than once in the style hierarchy.
See §17.7.3 for more details on toggle properties. They don't affect the API
specified here.
The following run properties are boolean (tri-state) properties:
+-----------------+------------+-------------------------------------------+
| element | spec | name |
+=================+============+===========================================+
| `<b/>` | §17.3.2.1 | Bold |
+-----------------+------------+-------------------------------------------+
| `<bCs/>` | §17.3.2.2 | Complex Script Bold |
+-----------------+------------+-------------------------------------------+
| `<caps/>` | §17.3.2.5 | Display All Characters as Capital Letters |
+-----------------+------------+-------------------------------------------+
| `<cs/>` | §17.3.2.7 | Use Complex Script Formatting on Run |
+-----------------+------------+-------------------------------------------+
| `<dstrike/>` | §17.3.2.9 | Double Strikethrough |
+-----------------+------------+-------------------------------------------+
| `<emboss/>` | §17.3.2.13 | Embossing |
+-----------------+------------+-------------------------------------------+
| `<i/>` | §17.3.2.16 | Italics |
+-----------------+------------+-------------------------------------------+
| `<iCs/>` | §17.3.2.17 | Complex Script Italics |
+-----------------+------------+-------------------------------------------+
| `<imprint/>` | §17.3.2.18 | Imprinting |
+-----------------+------------+-------------------------------------------+
| `<noProof/>` | §17.3.2.21 | Do Not Check Spelling or Grammar |
+-----------------+------------+-------------------------------------------+
| `<oMath/>` | §17.3.2.22 | Office Open XML Math |
+-----------------+------------+-------------------------------------------+
| `<outline/>` | §17.3.2.23 | Display Character Outline |
+-----------------+------------+-------------------------------------------+
| `<rtl/>` | §17.3.2.30 | Right To Left Text |
+-----------------+------------+-------------------------------------------+
| `<shadow/>` | §17.3.2.31 | Shadow |
+-----------------+------------+-------------------------------------------+
| `<smallCaps/>` | §17.3.2.33 | Small Caps |
+-----------------+------------+-------------------------------------------+
| `<snapToGrid/>` | §17.3.2.34 | Use Document Grid Settings For Inter- |
| | | Character Spacing |
+-----------------+------------+-------------------------------------------+
| `<specVanish/>` | §17.3.2.36 | Paragraph Mark is Always Hidden |
+-----------------+------------+-------------------------------------------+
| `<strike/>` | §17.3.2.37 | Single Strikethrough |
+-----------------+------------+-------------------------------------------+
| `<vanish/>` | §17.3.2.41 | Hidden Text |
+-----------------+------------+-------------------------------------------+
| `<webHidden/>` | §17.3.2.44 | Web Hidden Text |
+-----------------+------------+-------------------------------------------+
Protocol
--------
At the API level, each of the boolean run properties is a read/write
'tri-state' property, having the possible values |True|, |False|, and |None|.
The following interactive session demonstrates the protocol for querying and
applying run-level properties::
>>> run = p.add_run()
>>> run.bold
None
>>> run.bold = True
>>> run.bold
True
>>> run.bold = False
>>> run.bold
False
>>> run.bold = None
>>> run.bold
None
The semantics of the three values are as follows:
+-------+---------------------------------------------------------------+
| value | meaning |
+=======+===============================================================+
| True | The effective value of the property is unconditionally *on*. |
| | Contrary settings in the style hierarchy have no effect. |
+-------+---------------------------------------------------------------+
| False | The effective value of the property is unconditionally *off*. |
| | Contrary settings in the style hierarchy have no effect. |
+-------+---------------------------------------------------------------+
| None | The element is not present. The effective value is |
| | inherited from the style hierarchy. If no value for this |
| | property is present in the style hierarchy, the effective |
| | value is *off*. |
+-------+---------------------------------------------------------------+
Toggle properties
-----------------
Certain of the boolean run properties are *toggle properties*. A toggle
property is one that behaves like a *toggle* at certain places in the style
hierarchy. Toggle here means that setting the property on has the effect of
reversing the prior setting rather than unconditionally setting the property
on.
This behavior allows these properties to be overridden (turned off) in
inheriting styles. For example, consider a character style `emphasized` that
sets bold on. Another style, `strong` inherits from `emphasized`, but should
display in italic rather than bold. Setting bold off has no effect because it
is overridden by the bold in `strong` (I think). Because bold is a toggle
property, setting bold on in `emphasized` causes its value to be toggled, to
False, achieving the desired effect. See §17.7.3 for more details on toggle
properties.
The following run properties are toggle properties:
+----------------+------------+-------------------------------------------+
| element | spec | name |
+================+============+===========================================+
| `<b/>` | §17.3.2.1 | Bold |
+----------------+------------+-------------------------------------------+
| `<bCs/>` | §17.3.2.2 | Complex Script Bold |
+----------------+------------+-------------------------------------------+
| `<caps/>` | §17.3.2.5 | Display All Characters as Capital Letters |
+----------------+------------+-------------------------------------------+
| `<emboss/>` | §17.3.2.13 | Embossing |
+----------------+------------+-------------------------------------------+
| `<i/>` | §17.3.2.16 | Italics |
+----------------+------------+-------------------------------------------+
| `<iCs/>` | §17.3.2.17 | Complex Script Italics |
+----------------+------------+-------------------------------------------+
| `<imprint/>` | §17.3.2.18 | Imprinting |
+----------------+------------+-------------------------------------------+
| `<outline/>` | §17.3.2.23 | Display Character Outline |
+----------------+------------+-------------------------------------------+
| `<shadow/>` | §17.3.2.31 | Shadow |
+----------------+------------+-------------------------------------------+
| `<smallCaps/>` | §17.3.2.33 | Small Caps |
+----------------+------------+-------------------------------------------+
| `<strike/>` | §17.3.2.37 | Single Strikethrough |
+----------------+------------+-------------------------------------------+
| `<vanish/>` | §17.3.2.41 | Hidden Text |
+----------------+------------+-------------------------------------------+
Specimen XML
------------
.. highlight:: xml
::
<w:r>
<w:rPr>
<w:b/>
<w:i/>
<w:smallCaps/>
<w:strike/>
<w:sz w:val="28"/>
<w:szCs w:val="28"/>
<w:u w:val="single"/>
</w:rPr>
<w:t>bold, italic, small caps, strike, 14 pt, and underline</w:t>
</w:r>
Schema excerpt
--------------
.. highlight:: xml
It appears the run properties may appear in any order and may appear multiple
times each. Not sure what the semantics of that would be or why one would
want to do it, but something to note. Word seems to place them in the order
below when it writes the file.::
<xsd:complexType name="CT_RPr"> <!-- denormalized -->
<xsd:sequence>
<xsd:choice minOccurs="0" maxOccurs="unbounded"/>
<xsd:element name="rStyle" type="CT_String"/>
<xsd:element name="rFonts" type="CT_Fonts"/>
<xsd:element name="b" type="CT_OnOff"/>
<xsd:element name="bCs" type="CT_OnOff"/>
<xsd:element name="i" type="CT_OnOff"/>
<xsd:element name="iCs" type="CT_OnOff"/>
<xsd:element name="caps" type="CT_OnOff"/>
<xsd:element name="smallCaps" type="CT_OnOff"/>
<xsd:element name="strike" type="CT_OnOff"/>
<xsd:element name="dstrike" type="CT_OnOff"/>
<xsd:element name="outline" type="CT_OnOff"/>
<xsd:element name="shadow" type="CT_OnOff"/>
<xsd:element name="emboss" type="CT_OnOff"/>
<xsd:element name="imprint" type="CT_OnOff"/>
<xsd:element name="noProof" type="CT_OnOff"/>
<xsd:element name="snapToGrid" type="CT_OnOff"/>
<xsd:element name="vanish" type="CT_OnOff"/>
<xsd:element name="webHidden" type="CT_OnOff"/>
<xsd:element name="color" type="CT_Color"/>
<xsd:element name="spacing" type="CT_SignedTwipsMeasure"/>
<xsd:element name="w" type="CT_TextScale"/>
<xsd:element name="kern" type="CT_HpsMeasure"/>
<xsd:element name="position" type="CT_SignedHpsMeasure"/>
<xsd:element name="sz" type="CT_HpsMeasure"/>
<xsd:element name="szCs" type="CT_HpsMeasure"/>
<xsd:element name="highlight" type="CT_Highlight"/>
<xsd:element name="u" type="CT_Underline"/>
<xsd:element name="effect" type="CT_TextEffect"/>
<xsd:element name="bdr" type="CT_Border"/>
<xsd:element name="shd" type="CT_Shd"/>
<xsd:element name="fitText" type="CT_FitText"/>
<xsd:element name="vertAlign" type="CT_VerticalAlignRun"/>
<xsd:element name="rtl" type="CT_OnOff"/>
<xsd:element name="cs" type="CT_OnOff"/>
<xsd:element name="em" type="CT_Em"/>
<xsd:element name="lang" type="CT_Language"/>
<xsd:element name="eastAsianLayout" type="CT_EastAsianLayout"/>
<xsd:element name="specVanish" type="CT_OnOff"/>
<xsd:element name="oMath" type="CT_OnOff"/>
</xsd:choice>
<xsd:element name="rPrChange" type="CT_RPrChange" minOccurs="0"/>
</xsd:sequence>
</xsd:group>
<xsd:complexType name="CT_Fonts">
<xsd:attribute name="hint" type="ST_Hint"/>
<xsd:attribute name="ascii" type="s:ST_String"/>
<xsd:attribute name="hAnsi" type="s:ST_String"/>
<xsd:attribute name="eastAsia" type="s:ST_String"/>
<xsd:attribute name="cs" type="s:ST_String"/>
<xsd:attribute name="asciiTheme" type="ST_Theme"/>
<xsd:attribute name="hAnsiTheme" type="ST_Theme"/>
<xsd:attribute name="eastAsiaTheme" type="ST_Theme"/>
<xsd:attribute name="cstheme" type="ST_Theme"/>
</xsd:complexType>
<xsd:complexType name="CT_HpsMeasure">
<xsd:attribute name="val" type="ST_HpsMeasure" use="required"/>
</xsd:complexType>
<xsd:complexType name="CT_OnOff">
<xsd:attribute name="val" type="s:ST_OnOff"/>
</xsd:complexType>
<xsd:complexType name="CT_SignedHpsMeasure">
<xsd:attribute name="val" type="ST_SignedHpsMeasure" use="required"/>
</xsd:complexType>
<xsd:complexType name="CT_String">
<xsd:attribute name="val" type="s:ST_String" use="required"/>
</xsd:complexType>
<xsd:complexType name="CT_Underline">
<xsd:attribute name="val" type="ST_Underline"/>
<xsd:attribute name="color" type="ST_HexColor"/>
<xsd:attribute name="themeColor" type="ST_ThemeColor"/>
<xsd:attribute name="themeTint" type="ST_UcharHexNumber"/>
<xsd:attribute name="themeShade" type="ST_UcharHexNumber"/>
</xsd:complexType>
<xsd:complexType name="CT_VerticalAlignRun">
<xsd:attribute name="val" type="s:ST_VerticalAlignRun" use="required"/>
</xsd:complexType>
<!-- simple types -->
<xsd:simpleType name="ST_Hint">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="default"/>
<xsd:enumeration value="eastAsia"/>
<xsd:enumeration value="cs"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="ST_HpsMeasure">
<xsd:union memberTypes="s:ST_UnsignedDecimalNumber
s:ST_PositiveUniversalMeasure"/>
</xsd:simpleType>
<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>
<xsd:simpleType name="ST_PositiveUniversalMeasure">
<xsd:restriction base="ST_UniversalMeasure">
<xsd:pattern value="[0-9]+(\.[0-9]+)?(mm|cm|in|pt|pc|pi)"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="ST_SignedHpsMeasure">
<xsd:union memberTypes="xsd:integer s:ST_UniversalMeasure"/>
</xsd:simpleType>
<xsd:simpleType name="ST_Theme">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="majorEastAsia"/>
<xsd:enumeration value="majorBidi"/>
<xsd:enumeration value="majorAscii"/>
<xsd:enumeration value="majorHAnsi"/>
<xsd:enumeration value="minorEastAsia"/>
<xsd:enumeration value="minorBidi"/>
<xsd:enumeration value="minorAscii"/>
<xsd:enumeration value="minorHAnsi"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="ST_Underline">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="single"/>
<xsd:enumeration value="words"/>
<xsd:enumeration value="double"/>
<xsd:enumeration value="thick"/>
<xsd:enumeration value="dotted"/>
<xsd:enumeration value="dottedHeavy"/>
<xsd:enumeration value="dash"/>
<xsd:enumeration value="dashedHeavy"/>
<xsd:enumeration value="dashLong"/>
<xsd:enumeration value="dashLongHeavy"/>
<xsd:enumeration value="dotDash"/>
<xsd:enumeration value="dashDotHeavy"/>
<xsd:enumeration value="dotDotDash"/>
<xsd:enumeration value="dashDotDotHeavy"/>
<xsd:enumeration value="wave"/>
<xsd:enumeration value="wavyHeavy"/>
<xsd:enumeration value="wavyDouble"/>
<xsd:enumeration value="none"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="ST_UnsignedDecimalNumber">
<xsd:restriction base="xsd:unsignedLong"/>
</xsd:simpleType>
<xsd:simpleType name="ST_VerticalAlignRun">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="baseline"/>
<xsd:enumeration value="superscript"/>
<xsd:enumeration value="subscript"/>
</xsd:restriction>
</xsd:simpleType>
|
