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
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
|
# encoding: utf-8
"""
Paragraph-related proxy types.
"""
from __future__ import (
absolute_import, division, print_function, unicode_literals
)
from ..enum.text import WD_LINE_SPACING
from ..shared import ElementProxy, Emu, lazyproperty, Length, Pt, Twips
from .tabstops import TabStops
class ParagraphFormat(ElementProxy):
"""
Provides access to paragraph formatting such as justification,
indentation, line spacing, space before and after, and widow/orphan
control.
"""
__slots__ = ('_tab_stops',)
@property
def alignment(self):
"""
A member of the :ref:`WdParagraphAlignment` enumeration specifying
the justification setting for this paragraph. A value of |None|
indicates paragraph alignment is inherited from the style hierarchy.
"""
pPr = self._element.pPr
if pPr is None:
return None
return pPr.jc_val
@alignment.setter
def alignment(self, value):
pPr = self._element.get_or_add_pPr()
pPr.jc_val = value
@property
def first_line_indent(self):
"""
|Length| value specifying the relative difference in indentation for
the first line of the paragraph. A positive value causes the first
line to be indented. A negative value produces a hanging indent.
|None| indicates first line indentation is inherited from the style
hierarchy.
"""
pPr = self._element.pPr
if pPr is None:
return None
return pPr.first_line_indent
@first_line_indent.setter
def first_line_indent(self, value):
pPr = self._element.get_or_add_pPr()
pPr.first_line_indent = value
@property
def keep_together(self):
"""
|True| if the paragraph should be kept "in one piece" and not broken
across a page boundary when the document is rendered. |None|
indicates its effective value is inherited from the style hierarchy.
"""
pPr = self._element.pPr
if pPr is None:
return None
return pPr.keepLines_val
@keep_together.setter
def keep_together(self, value):
self._element.get_or_add_pPr().keepLines_val = value
@property
def keep_with_next(self):
"""
|True| if the paragraph should be kept on the same page as the
subsequent paragraph when the document is rendered. For example, this
property could be used to keep a section heading on the same page as
its first paragraph. |None| indicates its effective value is
inherited from the style hierarchy.
"""
pPr = self._element.pPr
if pPr is None:
return None
return pPr.keepNext_val
@keep_with_next.setter
def keep_with_next(self, value):
self._element.get_or_add_pPr().keepNext_val = value
@property
def left_indent(self):
"""
|Length| value specifying the space between the left margin and the
left side of the paragraph. |None| indicates the left indent value is
inherited from the style hierarchy. Use an |Inches| value object as
a convenient way to apply indentation in units of inches.
"""
pPr = self._element.pPr
if pPr is None:
return None
return pPr.ind_left
@left_indent.setter
def left_indent(self, value):
pPr = self._element.get_or_add_pPr()
pPr.ind_left = value
@property
def line_spacing(self):
"""
|float| or |Length| value specifying the space between baselines in
successive lines of the paragraph. A value of |None| indicates line
spacing is inherited from the style hierarchy. A float value, e.g.
``2.0`` or ``1.75``, indicates spacing is applied in multiples of
line heights. A |Length| value such as ``Pt(12)`` indicates spacing
is a fixed height. The |Pt| value class is a convenient way to apply
line spacing in units of points. Assigning |None| resets line spacing
to inherit from the style hierarchy.
"""
pPr = self._element.pPr
if pPr is None:
return None
return self._line_spacing(pPr.spacing_line, pPr.spacing_lineRule)
@line_spacing.setter
def line_spacing(self, value):
pPr = self._element.get_or_add_pPr()
if value is None:
pPr.spacing_line = None
pPr.spacing_lineRule = None
elif isinstance(value, Length):
pPr.spacing_line = value
if pPr.spacing_lineRule != WD_LINE_SPACING.AT_LEAST:
pPr.spacing_lineRule = WD_LINE_SPACING.EXACTLY
else:
pPr.spacing_line = Emu(value * Twips(240))
pPr.spacing_lineRule = WD_LINE_SPACING.MULTIPLE
@property
def line_spacing_rule(self):
"""
A member of the :ref:`WdLineSpacing` enumeration indicating how the
value of :attr:`line_spacing` should be interpreted. Assigning any of
the :ref:`WdLineSpacing` members :attr:`SINGLE`, :attr:`DOUBLE`, or
:attr:`ONE_POINT_FIVE` will cause the value of :attr:`line_spacing`
to be updated to produce the corresponding line spacing.
"""
pPr = self._element.pPr
if pPr is None:
return None
return self._line_spacing_rule(
pPr.spacing_line, pPr.spacing_lineRule
)
@line_spacing_rule.setter
def line_spacing_rule(self, value):
pPr = self._element.get_or_add_pPr()
if value == WD_LINE_SPACING.SINGLE:
pPr.spacing_line = Twips(240)
pPr.spacing_lineRule = WD_LINE_SPACING.MULTIPLE
elif value == WD_LINE_SPACING.ONE_POINT_FIVE:
pPr.spacing_line = Twips(360)
pPr.spacing_lineRule = WD_LINE_SPACING.MULTIPLE
elif value == WD_LINE_SPACING.DOUBLE:
pPr.spacing_line = Twips(480)
pPr.spacing_lineRule = WD_LINE_SPACING.MULTIPLE
else:
pPr.spacing_lineRule = value
@property
def page_break_before(self):
"""
|True| if the paragraph should appear at the top of the page
following the prior paragraph. |None| indicates its effective value
is inherited from the style hierarchy.
"""
pPr = self._element.pPr
if pPr is None:
return None
return pPr.pageBreakBefore_val
@page_break_before.setter
def page_break_before(self, value):
self._element.get_or_add_pPr().pageBreakBefore_val = value
@property
def right_indent(self):
"""
|Length| value specifying the space between the right margin and the
right side of the paragraph. |None| indicates the right indent value
is inherited from the style hierarchy. Use a |Cm| value object as
a convenient way to apply indentation in units of centimeters.
"""
pPr = self._element.pPr
if pPr is None:
return None
return pPr.ind_right
@right_indent.setter
def right_indent(self, value):
pPr = self._element.get_or_add_pPr()
pPr.ind_right = value
@property
def space_after(self):
"""
|Length| value specifying the spacing to appear between this
paragraph and the subsequent paragraph. |None| indicates this value
is inherited from the style hierarchy. |Length| objects provide
convenience properties, such as :attr:`~.Length.pt` and
:attr:`~.Length.inches`, that allow easy conversion to various length
units.
"""
pPr = self._element.pPr
if pPr is None:
return None
return pPr.spacing_after
@space_after.setter
def space_after(self, value):
self._element.get_or_add_pPr().spacing_after = value
@property
def space_before(self):
"""
|Length| value specifying the spacing to appear between this
paragraph and the prior paragraph. |None| indicates this value is
inherited from the style hierarchy. |Length| objects provide
convenience properties, such as :attr:`~.Length.pt` and
:attr:`~.Length.cm`, that allow easy conversion to various length
units.
"""
pPr = self._element.pPr
if pPr is None:
return None
return pPr.spacing_before
@space_before.setter
def space_before(self, value):
self._element.get_or_add_pPr().spacing_before = value
@lazyproperty
def tab_stops(self):
"""
|TabStops| object providing access to the tab stops defined for this
paragraph format.
"""
pPr = self._element.get_or_add_pPr()
return TabStops(pPr)
@property
def widow_control(self):
"""
|True| if the first and last lines in the paragraph remain on the
same page as the rest of the paragraph when Word repaginates the
document. |None| indicates its effective value is inherited from the
style hierarchy.
"""
pPr = self._element.pPr
if pPr is None:
return None
return pPr.widowControl_val
@widow_control.setter
def widow_control(self, value):
self._element.get_or_add_pPr().widowControl_val = value
@staticmethod
def _line_spacing(spacing_line, spacing_lineRule):
"""
Return the line spacing value calculated from the combination of
*spacing_line* and *spacing_lineRule*. Returns a |float| number of
lines when *spacing_lineRule* is ``WD_LINE_SPACING.MULTIPLE``,
otherwise a |Length| object of absolute line height is returned.
Returns |None| when *spacing_line* is |None|.
"""
if spacing_line is None:
return None
if spacing_lineRule == WD_LINE_SPACING.MULTIPLE:
return spacing_line / Pt(12)
return spacing_line
@staticmethod
def _line_spacing_rule(line, lineRule):
"""
Return the line spacing rule value calculated from the combination of
*line* and *lineRule*. Returns special members of the
:ref:`WdLineSpacing` enumeration when line spacing is single, double,
or 1.5 lines.
"""
if lineRule == WD_LINE_SPACING.MULTIPLE:
if line == Twips(240):
return WD_LINE_SPACING.SINGLE
if line == Twips(360):
return WD_LINE_SPACING.ONE_POINT_FIVE
if line == Twips(480):
return WD_LINE_SPACING.DOUBLE
return lineRule
|
