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
|
Tab Stops
=========
WordprocessingML allows for custom specification of tab stops at the
paragraph level. Tab stop spacing is a subset of paragraph formatting in
this system, so will be implemented within the
docx.text.parfmt.ParagraphFormatting object. Tab stops will be handled as
a List-like TabStops object made up of TabStop objects.
A TabStop object has three properties, alignment, leader, and position.
Alignment is a WD_TAB_ALIGNMENT member and position is a Length() object.
Tab stops are always sorted in position order. Alignment defaults to
WD_TAB_ALIGNMENT.LEFT, and leader defaults to WD_TAB_LEADER.SPACES.
Tab stops specify how tab characters in a paragraph are rendered. Insertion
of tab characters is accomplished using the Run object.
Protocol
--------
.. highlight:: python
Getting and setting tab stops::
>>> tab_stops = paragraph.paragraph_format.tab_stops
>>> tab_stops
<docx.text.parfmt.TabStops object at 0x104ea8c30>
>>> tab_stop = tab_stops.add_tab_stop(Inches(2), WD_TAB_ALIGNMENT.LEFT, WD_TAB_LEADER.DOTS)
# add_tab_stop defaults to WD_TAB_ALIGNMENT.LEFT, WD_TAB_LEADER.SPACES
>>> tab_stop = tab_stops.add_tab_stop(Inches(0.5))
>>> tab_stop.alignment
WD_TAB_ALIGNMENT.LEFT
>>> tab_stop.leader
WD_TAB_LEADER.SPACES
# TabStop properties are read/write
>>> tab_stop.position = Inches(2.5)
>>> tab_stop.alignment = WD_TAB_ALIGNMENT.CENTER
>>> tab_stop.leader = WD_TAB_LEADER.DASHES
# Tab stops are sorted into position order as created or modified
>>> [(t.position, t.alignment) for t in tab_stops]
[(914400, WD_TAB_ALIGNMENT.LEFT), (2286000, WD_TAB_ALIGNMENT.CENTER)]
# A tab stop is deleted using del statement
>>> len(tab_stops)
2
>>> del tab_stops[1]
>>> len(tab_stops)
1
# Restore default tabs
>>> tab_stops.clear()
Word Behavior
-------------
When the w:tabs element is empty or not present, Word uses default tab stops
(typically every half inch).
Word resumes using default tab stops following the last specified tab stop.
TabStops must be in position order within the XML. If they are not, the out-
of-order tab stop will appear in the ruler and in the properties dialog, but
will not actually be used by Word.
XML Semantics
-------------
* Both "num" and "list" alignment are a legacy from early versions of Word
before hanging indents were available. Both are deprecated.
* "start" alignment is equivalent to "left", and "end" alignment are equivalent
to "right". (Confirmed with manually edited XML.)
* A "clear" tab stop is not shown in Word's tab bar and default tab behavior
is followed in the document. That is, Word ignores that tab stop
specification completely, acting as if it were not there at all. This
allows a tab stop inherited from a style, for example, to be ignored.
* The w:pos attribute uses twips rather than EMU.
* The w:tabs element must be removed when empty. If present, it must contain
at least one w:tab element.
Specimen XML
------------
.. highlight:: xml
::
<w:pPr>
<w:tabs>
<w:tab w:val="left" w:leader="dot" w:pos="2880"/>
<w:tab w:val="decimal" w:pos="6480"/>
</w:tabs>
</w:pPr>
Enumerations
------------
* `WdTabAlignment Enumeration on MSDN`_
.. _WdTabAlignment Enumeration on MSDN:
https://msdn.microsoft.com/EN-US/library/office/ff195609.aspx
================= ======== =====
Name XML Value
================= ======== =====
wdAlignTabBar bar 4
wdAlignTabCenter center 1
wdAlignTabDecimal decimal 3
wdAlignTabLeft left 0
wdAlignTabList list 6
wdAlignTabRight right 2
================= ======== =====
Additional Enumeration values not appearing in WdTabAlignment
=============== ======== =====
Name XML Value
=============== ======== =====
wdAlignTabClear clear 101
wdAlignTabEnd end 102
wdAlignTabNum num 103
wdAlignTabStart start 104
=============== ======== =====
* `WdTabLeader Enumeration on MSDN`_
.. _WdTabLeader Enumeration on MSDN:
https://msdn.microsoft.com/en-us/library/office/ff845050.aspx
==================== ========== =====
Name XML Value
==================== ========== =====
wdTabLeaderDashes hyphen 2
wdTabLeaderDots dot 1
wdTabLeaderHeavy heavy 4
wdTabLeaderLines underscore 3
wdTabLeaderMiddleDot middleDot 5
wdTabLeaderSpaces none 0
==================== ========== =====
MS API Protocol
---------------
The MS API defines a `TabStops object`_ which is a collection of
`TabStop objects`_.
.. _TabStops object:
https://msdn.microsoft.com/EN-US/library/office/ff192806.aspx
.. _TabStop objects:
https://msdn.microsoft.com/EN-US/library/office/ff195736.aspx
Schema excerpt
--------------
::
<xsd:complexType name="CT_PPr"> <!-- denormalized -->
<xsd:sequence>
<xsd:element name="pStyle" type="CT_String" minOccurs="0"/>
<xsd:element name="keepNext" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="keepLines" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="pageBreakBefore" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="framePr" type="CT_FramePr" minOccurs="0"/>
<xsd:element name="widowControl" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="numPr" type="CT_NumPr" minOccurs="0"/>
<xsd:element name="suppressLineNumbers" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="pBdr" type="CT_PBdr" minOccurs="0"/>
<xsd:element name="shd" type="CT_Shd" minOccurs="0"/>
<xsd:element name="tabs" type="CT_Tabs" minOccurs="0"/>
<xsd:element name="suppressAutoHyphens" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="kinsoku" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="wordWrap" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="overflowPunct" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="topLinePunct" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="autoSpaceDE" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="autoSpaceDN" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="bidi" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="adjustRightInd" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="snapToGrid" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="spacing" type="CT_Spacing" minOccurs="0"/>
<xsd:element name="ind" type="CT_Ind" minOccurs="0"/>
<xsd:element name="contextualSpacing" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="mirrorIndents" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="suppressOverlap" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="jc" type="CT_Jc" minOccurs="0"/>
<xsd:element name="textDirection" type="CT_TextDirection" minOccurs="0"/>
<xsd:element name="textAlignment" type="CT_TextAlignment" minOccurs="0"/>
<xsd:element name="textboxTightWrap" type="CT_TextboxTightWrap" minOccurs="0"/>
<xsd:element name="outlineLvl" type="CT_DecimalNumber" minOccurs="0"/>
<xsd:element name="divId" type="CT_DecimalNumber" minOccurs="0"/>
<xsd:element name="cnfStyle" type="CT_Cnf" minOccurs="0"/>
<xsd:element name="rPr" type="CT_ParaRPr" minOccurs="0"/>
<xsd:element name="sectPr" type="CT_SectPr" minOccurs="0"/>
<xsd:element name="pPrChange" type="CT_PPrChange" minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="CT_Tabs">
<xsd:sequence>
<xsd:element name="tab" type="CT_TabStop" maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="CT_TabStop">
<xsd:attribute name="val" type="ST_TabJc" use="required"/>
<xsd:attribute name="leader" type="ST_TabTlc" use="optional"/>
<xsd:attribute name="pos" type="ST_SignedTwipsMeasure" use="required"/>
</xsd:complexType>
<xsd:simpleType name="ST_TabJc">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="clear"/>
<xsd:enumeration value="start"/>
<xsd:enumeration value="center"/>
<xsd:enumeration value="end"/>
<xsd:enumeration value="decimal"/>
<xsd:enumeration value="bar"/>
<xsd:enumeration value="num"/>
<xsd:enumeration value="left"/>
<xsd:enumeration value="right"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="ST_TabTlc">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="none"/>
<xsd:enumeration value="dot"/>
<xsd:enumeration value="hyphen"/>
<xsd:enumeration value="underscore"/>
<xsd:enumeration value="heavy"/>
<xsd:enumeration value="middleDot"/>
</xsd:restriction>
</xsd:simpleType>
|
