Skip to content

Commit 0d0501b

Browse files
author
Steve Canny
committed
docs: document InlineShape size analysis
1 parent 945ffb5 commit 0d0501b

File tree

2 files changed

+145
-0
lines changed

2 files changed

+145
-0
lines changed

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

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
2+
Inline shape size
3+
=================
4+
5+
6+
Overview
7+
--------
8+
9+
The position of an inline shape is completely determined by the text it is
10+
inline with, however its dimensions can be specified. For some shape types,
11+
both the contained shape and the shape container specify a width and height.
12+
13+
14+
Acceptance tests
15+
----------------
16+
17+
Feature: Query and change dimensions of inline shape
18+
In order to adjust the display size of an inline shape
19+
As a python-docx developer
20+
I need to query and change the width and height of an inline shape
21+
22+
Scenario: Query inline shape dimensions
23+
Given an inline shape of known dimensions
24+
Then the dimensions of the inline shape match the known values
25+
26+
Scenario: Change inline shape dimensions
27+
Given an inline shape of known dimensions
28+
When I change the dimensions of the inline shape
29+
Then the dimensions of the inline shape match the new values
30+
31+
32+
Unit tests
33+
----------
34+
35+
DescribeInlineShape
36+
37+
* it_knows_its_display_dimensions
38+
* it_can_change_its_display_dimensions
39+
40+
41+
Code sketches
42+
-------------
43+
44+
::
45+
46+
@property
47+
def InlineShape.width(self):
48+
assert isinstance(self._inline.extent.cx, _BaseLength)
49+
return self._inline.extent.cx
50+
51+
@width.setter
52+
def width(self, emu):
53+
self._inline.extent = emu
54+
55+
56+
Candidate protocol -- inline shape access
57+
-----------------------------------------
58+
59+
The following interactive session illustrates the protocol for accessing and
60+
changing the size of an inline shape::
61+
62+
>>> inline_shape = inline_shapes[0]
63+
>>> assert inline_shape.type == MSO_SHAPE_TYPE.PICTURE
64+
>>> inline_shape.width
65+
914400
66+
>>> inline_shape.height
67+
457200
68+
>>> inline_shape.width = 457200
69+
>>> inline_shape.height = 228600
70+
>>> inline_shape.width, inline_shape.height
71+
457200, 228600
72+
73+
74+
Resources
75+
---------
76+
77+
* `InlineShape Members (Word) on MSDN`_
78+
* `Shape Members (Word) on MSDN`_
79+
80+
.. _InlineShape Members (Word) on MSDN:
81+
http://msdn.microsoft.com/en-us/library/office/ff840794.aspx
82+
83+
.. _Shape Members (Word) on MSDN:
84+
http://msdn.microsoft.com/en-us/library/office/ff195191.aspx
85+
86+
87+
Specimen XML
88+
------------
89+
90+
.. highlight:: xml
91+
92+
This XML represents an inline shape inserted inline on a paragraph by itself::
93+
94+
<w:p>
95+
<w:r>
96+
<w:rPr/>
97+
<w:noProof/>
98+
</w:rPr>
99+
<w:drawing>
100+
<wp:inline distT="0" distB="0" distL="0" distR="0" wp14:anchorId="1BDE1558" wp14:editId="31E593BB">
101+
<wp:extent cx="859536" cy="343814"/>
102+
<wp:effectExtent l="0" t="0" r="4445" b="12065"/>
103+
<wp:docPr id="1" name="Picture 1"/>
104+
<wp:cNvGraphicFramePr>
105+
<a:graphicFrameLocks xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" noChangeAspect="1"/>
106+
</wp:cNvGraphicFramePr>
107+
<a:graphic xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main">
108+
<a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/picture">
109+
110+
<pic:pic xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture">
111+
<pic:nvPicPr>
112+
<pic:cNvPr id="1" name="python-powered.png"/>
113+
<pic:cNvPicPr/>
114+
</pic:nvPicPr>
115+
<pic:blipFill>
116+
<a:blip r:embed="rId7">
117+
<a:alphaModFix/>
118+
<a:extLst>
119+
<a:ext uri="{28A0092B-C50C-407E-A947-70E740481C1C}">
120+
<a14:useLocalDpi xmlns:a14="http://schemas.microsoft.com/office/drawing/2010/main" val="0"/>
121+
</a:ext>
122+
</a:extLst>
123+
</a:blip>
124+
<a:stretch>
125+
<a:fillRect/>
126+
</a:stretch>
127+
</pic:blipFill>
128+
<pic:spPr>
129+
<a:xfrm>
130+
<a:off x="0" y="0"/>
131+
<a:ext cx="859536" cy="343814"/>
132+
</a:xfrm>
133+
<a:prstGeom prst="rect">
134+
<a:avLst/>
135+
</a:prstGeom>
136+
</pic:spPr>
137+
</pic:pic>
138+
139+
</a:graphicData>
140+
</a:graphic>
141+
</wp:inline>
142+
</w:drawing>
143+
</w:r>
144+
</w:p>

‎docs/dev/analysis/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ Feature Analysis
1313
features/table
1414
features/shapes
1515
features/shapes-inline
16+
features/shapes-inline-size
1617
features/picture
1718

1819

0 commit comments

Comments
 (0)