Skip to content

Commit 0984e9a

Browse files
author
Steve Canny
committed
docs: elaborate Table feature analysis
1 parent 457159f commit 0984e9a

File tree

4 files changed

+456
-161
lines changed

4 files changed

+456
-161
lines changed

‎docs/dev/analysis/features/table-cell.rst‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
2+
Table Cell
3+
==========
4+
5+
All content in a table is contained in a cell. A cell also has several
6+
properties affecting its size, appearance, and how the content it contains is
7+
formatted.
8+
9+
10+
MS API - Partial Summary
11+
------------------------
12+
13+
* Merge()
14+
* Split()
15+
* Borders
16+
* BottomPadding (and Left, Right, Top)
17+
* Column
18+
* ColumnIndex
19+
* FitText
20+
* Height
21+
* HeightRule (one of WdRowHeightRule_ enumeration)
22+
* Preferred Width
23+
* Row
24+
* RowIndex
25+
* Shading
26+
* Tables
27+
* VerticalAlignment
28+
* Width
29+
* WordWrap
30+
31+
32+
Specimen XML
33+
------------
34+
35+
.. highlight:: xml
36+
37+
::
38+
39+
<w:tc>
40+
<w:tcPr>
41+
<w:tcW w:w="7038" w:type="dxa"/>
42+
</w:tcPr>
43+
<w:p>
44+
<w:pPr>
45+
<w:pStyle w:val="ListBullet"/>
46+
</w:pPr>
47+
<w:r>
48+
<w:t>Amy earned her BA in American Studies</w:t>
49+
</w:r>
50+
</w:p>
51+
</w:tc>
52+
53+
54+
Schema Definitions
55+
------------------
56+
57+
.. highlight:: xml
58+
59+
::
60+
61+
<xsd:complexType name="CT_Tc"> <!-- denormalized -->
62+
<xsd:sequence>
63+
<xsd:element name="tcPr" type="CT_TcPr" minOccurs="0"/>
64+
<xsd:choice minOccurs="1" maxOccurs="unbounded">
65+
<xsd:element name="p" type="CT_P"/>
66+
<xsd:element name="tbl" type="CT_Tbl"/>
67+
<xsd:element name="customXml" type="CT_CustomXmlBlock"/>
68+
<xsd:element name="sdt" type="CT_SdtBlock"/>
69+
<xsd:element name="proofErr" type="CT_ProofErr"/>
70+
<xsd:element name="permStart" type="CT_PermStart"/>
71+
<xsd:element name="permEnd" type="CT_Perm"/>
72+
<xsd:element name="ins" type="CT_RunTrackChange"/>
73+
<xsd:element name="del" type="CT_RunTrackChange"/>
74+
<xsd:element name="moveFrom" type="CT_RunTrackChange"/>
75+
<xsd:element name="moveTo" type="CT_RunTrackChange"/>
76+
<xsd:element ref="m:oMathPara" type="CT_OMathPara"/>
77+
<xsd:element ref="m:oMath" type="CT_OMath"/>
78+
<xsd:element name="bookmarkStart" type="CT_Bookmark"/>
79+
<xsd:element name="bookmarkEnd" type="CT_MarkupRange"/>
80+
<xsd:element name="moveFromRangeStart" type="CT_MoveBookmark"/>
81+
<xsd:element name="moveFromRangeEnd" type="CT_MarkupRange"/>
82+
<xsd:element name="moveToRangeStart" type="CT_MoveBookmark"/>
83+
<xsd:element name="moveToRangeEnd" type="CT_MarkupRange"/>
84+
<xsd:element name="commentRangeStart" type="CT_MarkupRange"/>
85+
<xsd:element name="commentRangeEnd" type="CT_MarkupRange"/>
86+
<xsd:element name="customXmlInsRangeStart" type="CT_TrackChange"/>
87+
<xsd:element name="customXmlInsRangeEnd" type="CT_Markup"/>
88+
<xsd:element name="customXmlDelRangeStart" type="CT_TrackChange"/>
89+
<xsd:element name="customXmlDelRangeEnd" type="CT_Markup"/>
90+
<xsd:element name="customXmlMoveFromRangeStart" type="CT_TrackChange"/>
91+
<xsd:element name="customXmlMoveFromRangeEnd" type="CT_Markup"/>
92+
<xsd:element name="customXmlMoveToRangeStart" type="CT_TrackChange"/>
93+
<xsd:element name="customXmlMoveToRangeEnd" type="CT_Markup"/>
94+
<xsd:element name="altChunk" type="CT_AltChunk"/>
95+
</xsd:choice>
96+
</xsd:sequence>
97+
<xsd:attribute name="id" type="s:ST_String" use="optional"/>
98+
</xsd:complexType>
99+
100+
<xsd:complexType name="CT_TcPr"> <!-- denormalized -->
101+
<xsd:sequence>
102+
<xsd:element name="cnfStyle" type="CT_Cnf" minOccurs="0"/>
103+
<xsd:element name="tcW" type="CT_TblWidth" minOccurs="0"/>
104+
<xsd:element name="gridSpan" type="CT_DecimalNumber" minOccurs="0"/>
105+
<xsd:element name="hMerge" type="CT_HMerge" minOccurs="0"/>
106+
<xsd:element name="vMerge" type="CT_VMerge" minOccurs="0"/>
107+
<xsd:element name="tcBorders" type="CT_TcBorders" minOccurs="0"/>
108+
<xsd:element name="shd" type="CT_Shd" minOccurs="0"/>
109+
<xsd:element name="noWrap" type="CT_OnOff" minOccurs="0"/>
110+
<xsd:element name="tcMar" type="CT_TcMar" minOccurs="0"/>
111+
<xsd:element name="textDirection" type="CT_TextDirection" minOccurs="0"/>
112+
<xsd:element name="tcFitText" type="CT_OnOff" minOccurs="0"/>
113+
<xsd:element name="vAlign" type="CT_VerticalJc" minOccurs="0"/>
114+
<xsd:element name="hideMark" type="CT_OnOff" minOccurs="0"/>
115+
<xsd:element name="headers" type="CT_Headers" minOccurs="0"/>
116+
<xsd:choice minOccurs="0"/>
117+
<xsd:element name="cellIns" type="CT_TrackChange"/>
118+
<xsd:element name="cellDel" type="CT_TrackChange"/>
119+
<xsd:element name="cellMerge" type="CT_CellMergeTrackChange"/>
120+
</xsd:choice>
121+
<xsd:element name="tcPrChange" type="CT_TcPrChange" minOccurs="0"/>
122+
</xsd:sequence>
123+
</xsd:complexType>
124+
125+
<xsd:complexType name="CT_TblWidth">
126+
<xsd:attribute name="w" type="ST_MeasurementOrPercent"/>
127+
<xsd:attribute name="type" type="ST_TblWidth"/>
128+
</xsd:complexType>
129+
130+
<xsd:simpleType name="ST_MeasurementOrPercent">
131+
<xsd:union memberTypes="ST_DecimalNumberOrPercent s:ST_UniversalMeasure"/>
132+
</xsd:simpleType>
133+
134+
<xsd:simpleType name="ST_DecimalNumberOrPercent">
135+
<xsd:union memberTypes="ST_UnqualifiedPercentage s:ST_Percentage"/>
136+
</xsd:simpleType>
137+
138+
<xsd:simpleType name="ST_UniversalMeasure">
139+
<xsd:restriction base="xsd:string">
140+
<xsd:pattern value="-?[0-9]+(\.[0-9]+)?(mm|cm|in|pt|pc|pi)"/>
141+
</xsd:restriction>
142+
</xsd:simpleType>
143+
144+
<xsd:simpleType name="ST_UnqualifiedPercentage">
145+
<xsd:restriction base="xsd:integer"/>
146+
</xsd:simpleType>
147+
148+
<xsd:simpleType name="ST_Percentage">
149+
<xsd:restriction base="xsd:string">
150+
<xsd:pattern value="-?[0-9]+(\.[0-9]+)?%"/>
151+
</xsd:restriction>
152+
</xsd:simpleType>
153+
154+
<xsd:simpleType name="ST_TblWidth">
155+
<xsd:restriction base="xsd:string">
156+
<xsd:enumeration value="nil"/>
157+
<xsd:enumeration value="pct"/>
158+
<xsd:enumeration value="dxa"/>
159+
<xsd:enumeration value="auto"/>
160+
</xsd:restriction>
161+
</xsd:simpleType>
162+
163+
164+
.. _`WdRowHeightRule`:
165+
http://msdn.microsoft.com/en-us/library/office/ff193620(v=office.15).aspx

‎docs/dev/analysis/features/table-props.rst‎

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

0 commit comments

Comments
 (0)