1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
|
# encoding: utf-8
"""
Run-related proxy objects for python-docx, Run in particular.
"""
from __future__ import absolute_import, print_function, unicode_literals
from ..enum.style import WD_STYLE_TYPE
from ..enum.text import WD_BREAK
from .font import Font
from ..shape import InlineShape
from ..shared import Parented
class Run(Parented):
"""
Proxy object wrapping ``<w:r>`` element. Several of the properties on Run
take a tri-state value, |True|, |False|, or |None|. |True| and |False|
correspond to on and off respectively. |None| indicates the property is
not specified directly on the run and its effective value is taken from
the style hierarchy.
"""
def __init__(self, r, parent):
super(Run, self).__init__(parent)
self._r = self._element = self.element = r
def add_break(self, break_type=WD_BREAK.LINE):
"""
Add a break element of *break_type* to this run. *break_type* can
take the values `WD_BREAK.LINE`, `WD_BREAK.PAGE`, and
`WD_BREAK.COLUMN` where `WD_BREAK` is imported from `docx.enum.text`.
*break_type* defaults to `WD_BREAK.LINE`.
"""
type_, clear = {
WD_BREAK.LINE: (None, None),
WD_BREAK.PAGE: ('page', None),
WD_BREAK.COLUMN: ('column', None),
WD_BREAK.LINE_CLEAR_LEFT: ('textWrapping', 'left'),
WD_BREAK.LINE_CLEAR_RIGHT: ('textWrapping', 'right'),
WD_BREAK.LINE_CLEAR_ALL: ('textWrapping', 'all'),
}[break_type]
br = self._r.add_br()
if type_ is not None:
br.type = type_
if clear is not None:
br.clear = clear
def add_picture(self, image_path_or_stream, width=None, height=None):
"""
Return an |InlineShape| instance containing the image identified by
*image_path_or_stream*, added to the end of this run.
*image_path_or_stream* can be a path (a string) or a file-like object
containing a binary image. If neither width nor height is specified,
the picture appears at its native size. If only one is specified, it
is used to compute a scaling factor that is then applied to the
unspecified dimension, preserving the aspect ratio of the image. The
native size of the picture is calculated using the dots-per-inch
(dpi) value specified in the image file, defaulting to 72 dpi if no
value is specified, as is often the case.
"""
inline = self.part.new_pic_inline(image_path_or_stream, width, height)
self._r.add_drawing(inline)
return InlineShape(inline)
def add_tab(self):
"""
Add a ``<w:tab/>`` element at the end of the run, which Word
interprets as a tab character.
"""
self._r._add_tab()
def add_text(self, text):
"""
Returns a newly appended |_Text| object (corresponding to a new
``<w:t>`` child element) to the run, containing *text*. Compare with
the possibly more friendly approach of assigning text to the
:attr:`Run.text` property.
"""
t = self._r.add_t(text)
return _Text(t)
@property
def bold(self):
"""
Read/write. Causes the text of the run to appear in bold.
"""
return self.font.bold
@bold.setter
def bold(self, value):
self.font.bold = value
def clear(self):
"""
Return reference to this run after removing all its content. All run
formatting is preserved.
"""
self._r.clear_content()
return self
@property
def font(self):
"""
The |Font| object providing access to the character formatting
properties for this run, such as font name and size.
"""
return Font(self._element)
@property
def italic(self):
"""
Read/write tri-state value. When |True|, causes the text of the run
to appear in italics.
"""
return self.font.italic
@italic.setter
def italic(self, value):
self.font.italic = value
@property
def style(self):
"""
Read/write. A |_CharacterStyle| object representing the character
style applied to this run. The default character style for the
document (often `Default Character Font`) is returned if the run has
no directly-applied character style. Setting this property to |None|
removes any directly-applied character style.
"""
style_id = self._r.style
return self.part.get_style(style_id, WD_STYLE_TYPE.CHARACTER)
@style.setter
def style(self, style_or_name):
style_id = self.part.get_style_id(
style_or_name, WD_STYLE_TYPE.CHARACTER
)
self._r.style = style_id
@property
def text(self):
"""
String formed by concatenating the text equivalent of each run
content child element into a Python string. Each ``<w:t>`` element
adds the text characters it contains. A ``<w:tab/>`` element adds
a ``\\t`` character. A ``<w:cr/>`` or ``<w:br>`` element each add
a ``\\n`` character. Note that a ``<w:br>`` element can indicate
a page break or column break as well as a line break. All ``<w:br>``
elements translate to a single ``\\n`` character regardless of their
type. All other content child elements, such as ``<w:drawing>``, are
ignored.
Assigning text to this property has the reverse effect, translating
each ``\\t`` character to a ``<w:tab/>`` element and each ``\\n`` or
``\\r`` character to a ``<w:cr/>`` element. Any existing run content
is replaced. Run formatting is preserved.
"""
return self._r.text
@text.setter
def text(self, text):
self._r.text = text
@property
def underline(self):
"""
The underline style for this |Run|, one of |None|, |True|, |False|,
or a value from :ref:`WdUnderline`. A value of |None| indicates the
run has no directly-applied underline value and so will inherit the
underline value of its containing paragraph. Assigning |None| to this
property removes any directly-applied underline value. A value of
|False| indicates a directly-applied setting of no underline,
overriding any inherited value. A value of |True| indicates single
underline. The values from :ref:`WdUnderline` are used to specify
other outline styles such as double, wavy, and dotted.
"""
return self.font.underline
@underline.setter
def underline(self, value):
self.font.underline = value
class _Text(object):
"""
Proxy object wrapping ``<w:t>`` element.
"""
def __init__(self, t_elm):
super(_Text, self).__init__()
self._t = t_elm
|
