1
2Table Properties
3================
4
5
6Alignment
7---------
8
9Word allows a table to be aligned between the page margins either left,
10right, or center.
11
12The read/write :attr:`Table.alignment` property specifies the alignment for
13a table::
14
15    >>> table = document.add_table(rows=2, cols=2)
16    >>> table.alignment
17    None
18    >>> table.alignment = WD_TABLE_ALIGNMENT.RIGHT
19    >>> table.alignment
20    RIGHT (2)
21
22
23Autofit
24-------
25
26Word has two algorithms for laying out a table, *fixed-width* or *autofit*.
27The default is autofit. Word will adjust column widths in an autofit table
28based on cell contents. A fixed-width table retains its column widths
29regardless of the contents. Either algorithm will adjust column widths
30proportionately when total table width exceeds page width.
31
32The read/write :attr:`Table.allow_autofit` property specifies which algorithm
33is used::
34
35    >>> table = document.add_table(rows=2, cols=2)
36    >>> table.allow_autofit
37    True
38    >>> table.allow_autofit = False
39    >>> table.allow_autofit
40    False
41
42
43Specimen XML
44------------
45
46.. highlight:: xml
47
48The following XML represents a 2x2 table::
49
50    <w:tbl>
51      <w:tblPr>
52        <w:tblStyle w:val="TableGrid"/>
53        <w:tblW w:type="auto" w:w="0"/>
54        <w:jc w:val="right"/>
55        <w:tblLook w:firstColumn="1" w:firstRow="1" w:lastColumn="0"
56                   w:lastRow="0" w:noHBand="0" w:noVBand="1" w:val="04A0"/>
57      </w:tblPr>
58      <w:tblGrid>
59        <w:gridCol w:w="4788"/>
60        <w:gridCol w:w="4788"/>
61      </w:tblGrid>
62      <w:tr>
63        <w:tc/>
64          <w:tcPr>
65            <w:tcW w:type="dxa" w:w="4788"/>
66          </w:tcPr>
67          <w:p/>
68        </w:tc>
69        <w:tc>
70          <w:tcPr>
71            <w:tcW w:type="dxa" w:w="4788"/>
72          </w:tcPr>
73          <w:p/>
74        </w:tc>
75      </w:tr>
76      <w:tr>
77        <w:tc>
78          <w:tcPr>
79            <w:tcW w:type="dxa" w:w="4788"/>
80          </w:tcPr>
81          <w:p/>
82        </w:tc>
83        <w:tc>
84          <w:tcPr>
85            <w:tcW w:type="dxa" w:w="4788"/>
86          </w:tcPr>
87          <w:p/>
88        </w:tc>
89      </w:tr>
90    </w:tbl>
91
92
93Layout behavior
94---------------
95
96Auto-layout causes actual column widths to be both unpredictable and
97unstable. Changes to the content can make the table layout shift.
98
99
100Semantics of CT_TblWidth element
101--------------------------------
102
103e.g. ``tcW``::
104
105    <w:tcW w:w="42.4mm"/>
106
107    <w:tcW w:w="1800" w:type="dxa"/>
108
109    <w:tcW w:w="20%" w:type="pct"/>
110
111    <w:tcW w:w="0" w:type="auto"/>
112
113    <w:tcW w:type="nil"/>
114
115
116    ST_MeasurementOrPercent
117    |
118    +-- ST_DecimalNumberOrPercent
119    |   |
120    |   +-- ST_UnqualifiedPercentage
121    |   |   |
122    |   |   +-- XsdInteger e.g. '1440'
123    |   |
124    |   +-- ST_Percentage e.g. '-07.43%'
125    |
126    +-- ST_UniversalMeasure  e.g. '-04.34mm'
127
128
129Schema Definitions
130------------------
131
132.. highlight:: xml
133
134::
135
136  <xsd:complexType name="CT_Tbl">  <!-- denormalized -->
137    <xsd:sequence>
138      <xsd:group    ref="EG_RangeMarkupElements"        minOccurs="0" maxOccurs="unbounded"/>
139      <xsd:element name="tblPr"       type="CT_TblPr"/>
140      <xsd:element name="tblGrid"     type="CT_TblGrid"/>
141      <xsd:choice                                       minOccurs="0" maxOccurs="unbounded">
142        <xsd:element name="tr"        type="CT_Row"/>
143        <xsd:element name="customXml" type="CT_CustomXmlRow"/>
144        <xsd:element name="sdt"       type="CT_SdtRow"/>
145        <xsd:group    ref="EG_RunLevelElts"             minOccurs="0" maxOccurs="unbounded"/>
146      </xsd:choice>
147    </xsd:sequence>
148  </xsd:complexType>
149
150  <xsd:complexType name="CT_TblPr">  <!-- denormalized -->
151    <xsd:sequence>
152      <xsd:element name="tblStyle"            type="CT_String"        minOccurs="0"/>
153      <xsd:element name="tblpPr"              type="CT_TblPPr"        minOccurs="0"/>
154      <xsd:element name="tblOverlap"          type="CT_TblOverlap"    minOccurs="0"/>
155      <xsd:element name="bidiVisual"          type="CT_OnOff"         minOccurs="0"/>
156      <xsd:element name="tblStyleRowBandSize" type="CT_DecimalNumber" minOccurs="0"/>
157      <xsd:element name="tblStyleColBandSize" type="CT_DecimalNumber" minOccurs="0"/>
158      <xsd:element name="tblW"                type="CT_TblWidth"      minOccurs="0"/>
159      <xsd:element name="jc"                  type="CT_JcTable"       minOccurs="0"/>
160      <xsd:element name="tblCellSpacing"      type="CT_TblWidth"      minOccurs="0"/>
161      <xsd:element name="tblInd"              type="CT_TblWidth"      minOccurs="0"/>
162      <xsd:element name="tblBorders"          type="CT_TblBorders"    minOccurs="0"/>
163      <xsd:element name="shd"                 type="CT_Shd"           minOccurs="0"/>
164      <xsd:element name="tblLayout"           type="CT_TblLayoutType" minOccurs="0"/>
165      <xsd:element name="tblCellMar"          type="CT_TblCellMar"    minOccurs="0"/>
166      <xsd:element name="tblLook"             type="CT_TblLook"       minOccurs="0"/>
167      <xsd:element name="tblCaption"          type="CT_String"        minOccurs="0"/>
168      <xsd:element name="tblDescription"      type="CT_String"        minOccurs="0"/>
169      <xsd:element name="tblPrChange"         type="CT_TblPrChange"   minOccurs="0"/>
170    </xsd:sequence>
171
172  <!-- table alignment --------------------------------- -->
173
174  <xsd:complexType name="CT_JcTable">
175    <xsd:attribute name="val" type="ST_JcTable" use="required"/>
176  </xsd:complexType>
177
178  <xsd:simpleType name="ST_JcTable">
179    <xsd:restriction base="xsd:string">
180      <xsd:enumeration value="center"/>
181      <xsd:enumeration value="end"/>
182      <xsd:enumeration value="left"/>
183      <xsd:enumeration value="right"/>
184      <xsd:enumeration value="start"/>
185    </xsd:restriction>
186  </xsd:simpleType>
187
188  <!-- table width ------------------------------------- -->
189
190  <xsd:complexType name="CT_TblWidth">
191    <xsd:attribute name="w"    type="ST_MeasurementOrPercent"/>
192    <xsd:attribute name="type" type="ST_TblWidth"/>
193  </xsd:complexType>
194
195  <xsd:simpleType name="ST_MeasurementOrPercent">
196    <xsd:union memberTypes="ST_DecimalNumberOrPercent s:ST_UniversalMeasure"/>
197  </xsd:simpleType>
198
199  <xsd:simpleType name="ST_DecimalNumberOrPercent">
200    <xsd:union memberTypes="ST_UnqualifiedPercentage s:ST_Percentage"/>
201  </xsd:simpleType>
202
203  <xsd:simpleType name="ST_UniversalMeasure">
204    <xsd:restriction base="xsd:string">
205      <xsd:pattern value="-?[0-9]+(\.[0-9]+)?(mm|cm|in|pt|pc|pi)"/>
206    </xsd:restriction>
207  </xsd:simpleType>
208
209  <xsd:simpleType name="ST_UnqualifiedPercentage">
210    <xsd:restriction base="xsd:integer"/>
211  </xsd:simpleType>
212
213  <xsd:simpleType name="ST_Percentage">
214    <xsd:restriction base="xsd:string">
215      <xsd:pattern value="-?[0-9]+(\.[0-9]+)?%"/>
216    </xsd:restriction>
217  </xsd:simpleType>
218
219  <xsd:simpleType name="ST_TblWidth">
220    <xsd:restriction base="xsd:string">
221      <xsd:enumeration value="nil"/>
222      <xsd:enumeration value="pct"/>
223      <xsd:enumeration value="dxa"/>
224      <xsd:enumeration value="auto"/>
225    </xsd:restriction>
226  </xsd:simpleType>
227
228  <!-- table layout ------------------------------------ -->
229
230  <xsd:complexType name="CT_TblLayoutType">
231    <xsd:attribute name="type" type="ST_TblLayoutType"/>
232  </xsd:complexType>
233
234  <xsd:simpleType name="ST_TblLayoutType">
235    <xsd:restriction base="xsd:string">
236      <xsd:enumeration value="fixed"/>
237      <xsd:enumeration value="autofit"/>
238    </xsd:restriction>
239  </xsd:simpleType>
240
241  <!-- table look -------------------------------------- -->
242
243  <xsd:complexType name="CT_TblLook">
244    <xsd:attribute name="firstRow"    type="s:ST_OnOff"/>
245    <xsd:attribute name="lastRow"     type="s:ST_OnOff"/>
246    <xsd:attribute name="firstColumn" type="s:ST_OnOff"/>
247    <xsd:attribute name="lastColumn"  type="s:ST_OnOff"/>
248    <xsd:attribute name="noHBand"     type="s:ST_OnOff"/>
249    <xsd:attribute name="noVBand"     type="s:ST_OnOff"/>
250    <xsd:attribute name="val"         type="ST_ShortHexNumber"/>
251  </xsd:complexType>
252