X Tutup
Skip to content

Commit 6674d3c

Browse files
author
Steve Canny
committed
docs: document inline shapes analysis
1 parent 320496b commit 6674d3c

File tree

5 files changed

+417
-44
lines changed

5 files changed

+417
-44
lines changed

‎docs/dev/analysis/features/picture.rst‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
2+
Picture
3+
=======
4+
5+
6+
Overview
7+
--------
8+
9+
Word allows a picture to be placed in a graphical object container, either an
10+
inline shape or a floating shape.
11+
12+
13+
Candidate protocol
14+
------------------
15+
16+
::
17+
18+
>>> run = body.add_paragraph().add_run()
19+
>>> shape = run.add_picture(
20+
... image, width=None, height=None, MIME_type=None
21+
... )
22+
23+
24+
Specimen XML
25+
------------
26+
27+
.. highlight:: xml
28+
29+
This XML represents a picture inserted inline on a paragraph by itself::
30+
31+
<a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/picture">
32+
<pic:pic xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture">
33+
<pic:nvPicPr>
34+
<pic:cNvPr id="1" name="python-powered.png"/>
35+
<pic:cNvPicPr/>
36+
</pic:nvPicPr>
37+
<pic:blipFill>
38+
<a:blip r:embed="rId7">
39+
<a:alphaModFix/>
40+
<a:extLst>
41+
<a:ext uri="{28A0092B-C50C-407E-A947-70E740481C1C}">
42+
<a14:useLocalDpi xmlns:a14="http://schemas.microsoft.com/office/drawing/2010/main" val="0"/>
43+
</a:ext>
44+
</a:extLst>
45+
</a:blip>
46+
<a:stretch>
47+
<a:fillRect/>
48+
</a:stretch>
49+
</pic:blipFill>
50+
<pic:spPr>
51+
<a:xfrm>
52+
<a:off x="0" y="0"/>
53+
<a:ext cx="859536" cy="343814"/>
54+
</a:xfrm>
55+
<a:prstGeom prst="rect">
56+
<a:avLst/>
57+
</a:prstGeom>
58+
</pic:spPr>
59+
</pic:pic>
60+
</a:graphicData>
61+
62+
63+
Schema definitions
64+
------------------
65+
66+
.. highlight:: xml
67+
68+
::
69+
70+
<xsd:complexType name="CT_GraphicalObjectData">
71+
<xsd:sequence>
72+
<xsd:any minOccurs="0" maxOccurs="unbounded" processContents="strict"/>
73+
</xsd:sequence>
74+
<xsd:attribute name="uri" type="xsd:token" use="required"/>
75+
</xsd:complexType>
76+
77+
<xsd:element name="pic" type="CT_Picture"/>
78+
79+
<xsd:complexType name="CT_Picture">
80+
<xsd:sequence>
81+
<xsd:element name="nvPicPr" type="CT_PictureNonVisual"/>
82+
<xsd:element name="blipFill" type="a:CT_BlipFillProperties"/>
83+
<xsd:element name="spPr" type="a:CT_ShapeProperties"/>
84+
</xsd:sequence>
85+
</xsd:complexType>
86+
87+
<xsd:complexType name="CT_PictureNonVisual">
88+
<xsd:sequence>
89+
<xsd:element name="cNvPr" type="a:CT_NonVisualDrawingProps"/>
90+
<xsd:element name="cNvPicPr" type="a:CT_NonVisualPictureProperties"/>
91+
</xsd:sequence>
92+
</xsd:complexType>
93+
94+
<xsd:complexType name="CT_BlipFillProperties">
95+
<xsd:sequence>
96+
<xsd:element name="blip" type="CT_Blip" minOccurs="0"/>
97+
<xsd:element name="srcRect" type="CT_RelativeRect" minOccurs="0"/>
98+
<xsd:group ref="EG_FillModeProperties" minOccurs="0" maxOccurs="1"/>
99+
</xsd:sequence>
100+
<xsd:attribute name="dpi" type="xsd:unsignedInt" use="optional"/>
101+
<xsd:attribute name="rotWithShape" type="xsd:boolean" use="optional"/>
102+
</xsd:complexType>
103+
104+
<xsd:complexType name="CT_ShapeProperties">
105+
<xsd:sequence>
106+
<xsd:element name="xfrm" type="CT_Transform2D" minOccurs="0"/>
107+
<xsd:group ref="EG_Geometry" minOccurs="0"/>
108+
<xsd:group ref="EG_FillProperties" minOccurs="0"/>
109+
<xsd:element name="ln" type="CT_LineProperties" minOccurs="0"/>
110+
<xsd:group ref="EG_EffectProperties" minOccurs="0"/>
111+
<xsd:element name="scene3d" type="CT_Scene3D" minOccurs="0"/>
112+
<xsd:element name="sp3d" type="CT_Shape3D" minOccurs="0"/>
113+
<xsd:element name="extLst" type="CT_OfficeArtExtensionList" minOccurs="0"/>
114+
</xsd:sequence>
115+
<xsd:attribute name="bwMode" type="ST_BlackWhiteMode" use="optional"/>
116+
</xsd:complexType>
117+
118+
<xsd:complexType name="CT_NonVisualDrawingProps">
119+
<xsd:sequence>
120+
<xsd:element name="hlinkClick" type="CT_Hyperlink" minOccurs="0"/>
121+
<xsd:element name="hlinkHover" type="CT_Hyperlink" minOccurs="0"/>
122+
<xsd:element name="extLst" type="CT_OfficeArtExtensionList" minOccurs="0"/>
123+
</xsd:sequence>
124+
<xsd:attribute name="id" type="ST_DrawingElementId" use="required"/>
125+
<xsd:attribute name="name" type="xsd:string" use="required"/>
126+
<xsd:attribute name="descr" type="xsd:string" use="optional" default=""/>
127+
<xsd:attribute name="hidden" type="xsd:boolean" use="optional" default="false"/>
128+
<xsd:attribute name="title" type="xsd:string" use="optional" default=""/>
129+
</xsd:complexType>

‎docs/dev/analysis/features/shapes-inline.rst‎

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
1+
2+
Inline shape
3+
============
4+
5+
6+
Overview
7+
--------
8+
9+
Word allows a graphical object to be placed into a document as an inline
10+
object. An inline shape appears as a ``<w:drawing>`` element as a child of
11+
a ``<w:r>`` element.
12+
13+
14+
Candidate protocol -- inline shape access
15+
-----------------------------------------
16+
17+
The following interactive session illustrates the protocol for accessing an
18+
inline shape::
19+
20+
>>> inline_shapes = document.body.inline_shapes
21+
>>> inline_shape = inline_shapes[0]
22+
>>> assert inline_shape.type == MSO_SHAPE_TYPE.PICTURE
23+
24+
25+
Acceptance test
26+
---------------
27+
28+
shp-inline-shape-access.feature::
29+
30+
Feature: Access inline shapes in document
31+
In order to query or manipulate inline shapes in a document
32+
As an python-docx developer
33+
I need the ability to access the inline shapes in a document
34+
35+
Scenario: Access inline shapes collection of document
36+
Given a document having two inline shapes
37+
Then I can access the inline shape collection of the document
38+
And the length of the inline shape collection is 2
39+
40+
Scenario: Access shape in inline shape collection
41+
Given an inline shape collection containing two shapes
42+
Then I can iterate over the inline shape collection
43+
And I can access an inline shape by index
44+
45+
46+
Resources
47+
---------
48+
49+
* `Document Members (Word) on MSDN`_
50+
* `InlineShape Members (Word) on MSDN`_
51+
* `Shape Members (Word) on MSDN`_
52+
53+
.. _Document Members (Word) on MSDN:
54+
http://msdn.microsoft.com/en-us/library/office/ff840898.aspx
55+
56+
.. _InlineShape Members (Word) on MSDN:
57+
http://msdn.microsoft.com/en-us/library/office/ff840794.aspx
58+
59+
.. _Shape Members (Word) on MSDN:
60+
http://msdn.microsoft.com/en-us/library/office/ff195191.aspx
61+
62+
63+
MS API
64+
------
65+
66+
The Shapes and InlineShapes properties on Document hold references to things
67+
like pictures in the MS API.
68+
69+
* Height and Width
70+
* Borders
71+
* Shadow
72+
* Hyperlink
73+
* PictureFormat (providing brightness, color, crop, transparency, contrast)
74+
* ScaleHeight and ScaleWidth
75+
* HasChart
76+
* HasSmartArt
77+
* Type (Chart, LockedCanvas, Picture, SmartArt, etc.)
78+
79+
80+
Spec references
81+
---------------
82+
83+
* 17.3.3.9 drawing (DrawingML Object)
84+
* 20.4.2.8 inline (Inline DrawingML Object)
85+
* 20.4.2.7 extent (Drawing Object Size)
86+
87+
88+
Minimal XML
89+
-----------
90+
91+
.. highlight:: xml
92+
93+
This XML represents my best guess of the minimal inline shape container that
94+
Word will load::
95+
96+
<w:r>
97+
<w:drawing>
98+
<wp:inline>
99+
<wp:extent cx="914400" cy="914400"/>
100+
<wp:docPr id="1" name="Picture 1"/>
101+
<a:graphic xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main">
102+
<a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/picture">
103+
104+
<!-- might not have to put anything here for a start -->
105+
106+
</a:graphicData>
107+
</a:graphic>
108+
</wp:inline>
109+
</w:drawing>
110+
</w:r>
111+
112+
113+
Specimen XML
114+
------------
115+
116+
.. highlight:: xml
117+
118+
A ``CT_Drawing`` (``<w:drawing>``) element can appear in a run, as a peer of,
119+
for example, a ``<w:t>`` element. This element contains a DrawingML object.
120+
WordprocessingML drawings are discussed in section 20.4 of the ISO/IEC spec.
121+
122+
This XML represents an inline shape inserted inline on a paragraph by itself.
123+
The particulars of the graphical object itself are redacted::
124+
125+
<w:p>
126+
<w:r>
127+
<w:rPr/>
128+
<w:noProof/>
129+
</w:rPr>
130+
<w:drawing>
131+
<wp:inline distT="0" distB="0" distL="0" distR="0" wp14:anchorId="1BDE1558" wp14:editId="31E593BB">
132+
<wp:extent cx="859536" cy="343814"/>
133+
<wp:effectExtent l="0" t="0" r="4445" b="12065"/>
134+
<wp:docPr id="1" name="Picture 1"/>
135+
<wp:cNvGraphicFramePr>
136+
<a:graphicFrameLocks xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" noChangeAspect="1"/>
137+
</wp:cNvGraphicFramePr>
138+
<a:graphic xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main">
139+
<a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/picture">
140+
141+
<!-- graphical object, such as pic:pic, goes here -->
142+
143+
</a:graphicData>
144+
</a:graphic>
145+
</wp:inline>
146+
</w:drawing>
147+
</w:r>
148+
</w:p>
149+
150+
151+
Schema definitions
152+
------------------
153+
154+
.. highlight:: xml
155+
156+
::
157+
158+
<xsd:complexType name="CT_Drawing">
159+
<xsd:choice minOccurs="1" maxOccurs="unbounded">
160+
<xsd:element ref="wp:anchor" minOccurs="0"/>
161+
<xsd:element ref="wp:inline" minOccurs="0"/>
162+
</xsd:choice>
163+
</xsd:complexType>
164+
165+
<xsd:complexType name="CT_Inline">
166+
<xsd:sequence>
167+
<xsd:element name="extent" type="a:CT_PositiveSize2D"/>
168+
<xsd:element name="effectExtent" type="CT_EffectExtent" minOccurs="0"/>
169+
<xsd:element name="docPr" type="a:CT_NonVisualDrawingProps"/>
170+
<xsd:element name="cNvGraphicFramePr" type="a:CT_NonVisualGraphicFrameProperties" minOccurs="0"/>
171+
<xsd:element name="graphic" type="CT_GraphicalObject"/>
172+
</xsd:sequence>
173+
<xsd:attribute name="distT" type="ST_WrapDistance" use="optional"/>
174+
<xsd:attribute name="distB" type="ST_WrapDistance" use="optional"/>
175+
<xsd:attribute name="distL" type="ST_WrapDistance" use="optional"/>
176+
<xsd:attribute name="distR" type="ST_WrapDistance" use="optional"/>
177+
</xsd:complexType>
178+
179+
<xsd:complexType name="CT_PositiveSize2D">
180+
<xsd:attribute name="cx" type="ST_PositiveCoordinate" use="required"/>
181+
<xsd:attribute name="cy" type="ST_PositiveCoordinate" use="required"/>
182+
</xsd:complexType>
183+
184+
<xsd:complexType name="CT_EffectExtent">
185+
<xsd:attribute name="l" type="a:ST_Coordinate" use="required"/>
186+
<xsd:attribute name="t" type="a:ST_Coordinate" use="required"/>
187+
<xsd:attribute name="r" type="a:ST_Coordinate" use="required"/>
188+
<xsd:attribute name="b" type="a:ST_Coordinate" use="required"/>
189+
</xsd:complexType>
190+
191+
<xsd:complexType name="CT_NonVisualDrawingProps">
192+
<xsd:sequence>
193+
<xsd:element name="hlinkClick" type="CT_Hyperlink" minOccurs="0"/>
194+
<xsd:element name="hlinkHover" type="CT_Hyperlink" minOccurs="0"/>
195+
<xsd:element name="extLst" type="CT_OfficeArtExtensionList" minOccurs="0"/>
196+
</xsd:sequence>
197+
<xsd:attribute name="id" type="ST_DrawingElementId" use="required"/>
198+
<xsd:attribute name="name" type="xsd:string" use="required"/>
199+
<xsd:attribute name="descr" type="xsd:string" use="optional" default=""/>
200+
<xsd:attribute name="hidden" type="xsd:boolean" use="optional" default="false"/>
201+
<xsd:attribute name="title" type="xsd:string" use="optional" default=""/>
202+
</xsd:complexType>
203+
204+
<xsd:complexType name="CT_NonVisualGraphicFrameProperties">
205+
<xsd:sequence>
206+
<xsd:element name="graphicFrameLocks" type="CT_GraphicalObjectFrameLocking" minOccurs="0"/>
207+
<xsd:element name="extLst" type="CT_OfficeArtExtensionList" minOccurs="0"/>
208+
</xsd:sequence>
209+
</xsd:complexType>
210+
211+
<xsd:complexType name="CT_GraphicalObject">
212+
<xsd:sequence>
213+
<xsd:element name="graphicData" type="CT_GraphicalObjectData"/>
214+
</xsd:sequence>
215+
</xsd:complexType>
216+
217+
<xsd:complexType name="CT_GraphicalObjectData">
218+
<xsd:sequence>
219+
<xsd:any minOccurs="0" maxOccurs="unbounded" processContents="strict"/>
220+
</xsd:sequence>
221+
<xsd:attribute name="uri" type="xsd:token" use="required"/>
222+
</xsd:complexType>

0 commit comments

Comments
 (0)
X Tutup