Skip to content

Commit 2d752b7

Browse files
author
Steve Canny
committed
docs: elaborate add_picture analysis
1 parent f85ab04 commit 2d752b7

File tree

2 files changed

+105
-12
lines changed

2 files changed

+105
-12
lines changed

‎docs/conf.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,8 @@
7171
7272
.. |_Document| replace:: :class:`_Document`
7373
74+
.. |InlineShapes| replace:: :class:`InlineShapes`
75+
7476
.. |OpcPackage| replace:: :class:`OpcPackage`
7577
7678
.. |Paragraph| replace:: :class:`Paragraph`

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

Lines changed: 103 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -15,10 +15,47 @@ Candidate protocol
1515

1616
::
1717

18-
>>> run = body.add_paragraph().add_run()
19-
>>> shape = run.add_picture(
20-
... image, width=None, height=None, MIME_type=None
21-
... )
18+
>>> run = paragraph.add_run()
19+
>>> inline_shape = run.add_inline_picture(file_like_image, MIME_type=None)
20+
>>> inline_shape.width = width
21+
>>> inline_shape.height = height
22+
23+
24+
Minimal XML
25+
-----------
26+
27+
.. highlight:: xml
28+
29+
This XML represents the working hypothesis of the minimum XML that must be
30+
inserted to add a working picture to a document::
31+
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:stretch>
40+
<a:fillRect/>
41+
</a:stretch>
42+
</pic:blipFill>
43+
<pic:spPr>
44+
<a:xfrm>
45+
<a:off x="0" y="0"/>
46+
<a:ext cx="859536" cy="343814"/>
47+
</a:xfrm>
48+
<a:prstGeom prst="rect"/>
49+
</pic:spPr>
50+
</pic:pic>
51+
52+
53+
Required parameters:
54+
55+
* unique DrawingML object id (document-wide, pretty sure it's just the part)
56+
* name, either filename or generic if file-like object.
57+
* rId for rel to image part
58+
* size (cx, cy)
2259

2360

2461
Specimen XML
@@ -67,13 +104,6 @@ Schema definitions
67104

68105
::
69106

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-
77107
<xsd:element name="pic" type="CT_Picture"/>
78108

79109
<xsd:complexType name="CT_Picture">
@@ -95,12 +125,51 @@ Schema definitions
95125
<xsd:sequence>
96126
<xsd:element name="blip" type="CT_Blip" minOccurs="0"/>
97127
<xsd:element name="srcRect" type="CT_RelativeRect" minOccurs="0"/>
98-
<xsd:group ref="EG_FillModeProperties" minOccurs="0" maxOccurs="1"/>
128+
<xsd:group ref="EG_FillModeProperties" minOccurs="0"/>
99129
</xsd:sequence>
100130
<xsd:attribute name="dpi" type="xsd:unsignedInt" use="optional"/>
101131
<xsd:attribute name="rotWithShape" type="xsd:boolean" use="optional"/>
102132
</xsd:complexType>
103133

134+
<xsd:complexType name="CT_Blip">
135+
<xsd:sequence>
136+
<xsd:choice minOccurs="0" maxOccurs="unbounded">
137+
<xsd:element name="alphaBiLevel" type="CT_AlphaBiLevelEffect"/>
138+
<xsd:element name="alphaCeiling" type="CT_AlphaCeilingEffect"/>
139+
<xsd:element name="alphaFloor" type="CT_AlphaFloorEffect"/>
140+
<xsd:element name="alphaInv" type="CT_AlphaInverseEffect"/>
141+
<xsd:element name="alphaMod" type="CT_AlphaModulateEffect"/>
142+
<xsd:element name="alphaModFix" type="CT_AlphaModulateFixedEffect"/>
143+
<xsd:element name="alphaRepl" type="CT_AlphaReplaceEffect"/>
144+
<xsd:element name="biLevel" type="CT_BiLevelEffect"/>
145+
<xsd:element name="blur" type="CT_BlurEffect"/>
146+
<xsd:element name="clrChange" type="CT_ColorChangeEffect"/>
147+
<xsd:element name="clrRepl" type="CT_ColorReplaceEffect"/>
148+
<xsd:element name="duotone" type="CT_DuotoneEffect"/>
149+
<xsd:element name="fillOverlay" type="CT_FillOverlayEffect"/>
150+
<xsd:element name="grayscl" type="CT_GrayscaleEffect"/>
151+
<xsd:element name="hsl" type="CT_HSLEffect"/>
152+
<xsd:element name="lum" type="CT_LuminanceEffect"/>
153+
<xsd:element name="tint" type="CT_TintEffect"/>
154+
</xsd:choice>
155+
<xsd:element name="extLst" type="CT_OfficeArtExtensionList" minOccurs="0"/>
156+
</xsd:sequence>
157+
<xsd:attributeGroup ref="AG_Blob"/>
158+
<xsd:attribute name="cstate" type="ST_BlipCompression" use="optional" default="none"/>
159+
</xsd:complexType>
160+
161+
<xsd:attributeGroup name="AG_Blob">
162+
<xsd:attribute ref="r:embed" use="optional" default=""/>
163+
<xsd:attribute ref="r:link" use="optional" default=""/>
164+
</xsd:attributeGroup>
165+
166+
<xsd:group name="EG_FillModeProperties">
167+
<xsd:choice>
168+
<xsd:element name="tile" type="CT_TileInfoProperties"/>
169+
<xsd:element name="stretch" type="CT_StretchInfoProperties"/>
170+
</xsd:choice>
171+
</xsd:group>
172+
104173
<xsd:complexType name="CT_ShapeProperties">
105174
<xsd:sequence>
106175
<xsd:element name="xfrm" type="CT_Transform2D" minOccurs="0"/>
@@ -115,6 +184,20 @@ Schema definitions
115184
<xsd:attribute name="bwMode" type="ST_BlackWhiteMode" use="optional"/>
116185
</xsd:complexType>
117186

187+
<xsd:group name="EG_Geometry">
188+
<xsd:choice>
189+
<xsd:element name="custGeom" type="CT_CustomGeometry2D"/>
190+
<xsd:element name="prstGeom" type="CT_PresetGeometry2D"/>
191+
</xsd:choice>
192+
</xsd:group>
193+
194+
<xsd:complexType name="CT_PresetGeometry2D">
195+
<xsd:sequence>
196+
<xsd:element name="avLst" type="CT_GeomGuideList" minOccurs="0"/>
197+
</xsd:sequence>
198+
<xsd:attribute name="prst" type="ST_ShapeType" use="required"/>
199+
</xsd:complexType>
200+
118201
<xsd:complexType name="CT_NonVisualDrawingProps">
119202
<xsd:sequence>
120203
<xsd:element name="hlinkClick" type="CT_Hyperlink" minOccurs="0"/>
@@ -127,3 +210,11 @@ Schema definitions
127210
<xsd:attribute name="hidden" type="xsd:boolean" use="optional" default="false"/>
128211
<xsd:attribute name="title" type="xsd:string" use="optional" default=""/>
129212
</xsd:complexType>
213+
214+
<xsd:complexType name="CT_NonVisualPictureProperties">
215+
<xsd:sequence>
216+
<xsd:element name="picLocks" type="CT_PictureLocking" minOccurs="0"/>
217+
<xsd:element name="extLst" type="CT_OfficeArtExtensionList" minOccurs="0"/>
218+
</xsd:sequence>
219+
<xsd:attribute name="preferRelativeResize" type="xsd:boolean" use="optional" default="true"/>
220+
</xsd:complexType>

0 commit comments

Comments
 (0)