X Tutup
Skip to content

Commit 4564b33

Browse files
author
Steve Canny
committed
docs: document Paragraph.paragraph_format
1 parent 676612d commit 4564b33

File tree

3 files changed

+226
-20
lines changed

3 files changed

+226
-20
lines changed

‎docs/conf.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,8 @@
7373
7474
.. |_Cell| replace:: :class:`._Cell`
7575
76+
.. |Cm| replace:: :class:`.Cm`
77+
7678
.. |_Column| replace:: :class:`._Column`
7779
7880
.. |_Columns| replace:: :class:`._Columns`
@@ -93,6 +95,8 @@
9395
9496
.. |Font| replace:: :class:`.Font`
9597
98+
.. |Inches| replace:: :class:`.Inches`
99+
96100
.. |InlineShape| replace:: :class:`.InlineShape`
97101
98102
.. |InlineShapes| replace:: :class:`.InlineShapes`

‎docs/index.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -68,12 +68,12 @@ User Guide
6868
user/install
6969
user/quickstart
7070
user/documents
71+
user/text
7172
user/sections
7273
user/api-concepts
7374
user/styles-understanding
7475
user/styles-using
7576
user/shapes
76-
user/text
7777

7878

7979
API Documentation

‎docs/user/text.rst‎

Lines changed: 221 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,230 @@
11

2-
Low-level text API
3-
==================
2+
Working with Text
3+
=================
4+
5+
To work effectively with text, it's important to first understand a little
6+
about block-level elements like paragraphs and inline-level objects like
7+
runs.
48

5-
For the greatest control over inserted text, an understanding of the low-level
6-
text API is required.
79

810
Block-level vs. inline text objects
911
-----------------------------------
1012

11-
The paragraph is the primary block-level object in Word. A table is also
12-
a block-level object, however its acts primarily as a container rather than
13-
content. Each cell of a table is a block-level container, much like the
14-
document body itself. Its rows and columns simply provide structure to the
15-
cells.
13+
The paragraph is the primary block-level object in Word.
14+
15+
A block-level item flows the text it contains between its left and right
16+
edges, adding an additional line each time the text extends beyond its right
17+
boundary. For a paragraph, the boundaries are generally the page margins, but
18+
they can also be column boundaries if the page is laid out in columns, or
19+
cell boundaries if the paragraph occurs inside a table cell.
20+
21+
A table is also a block-level object.
22+
23+
An inline object is a portion of the content that occurs inside a block-level
24+
item. An example would be a word that appears in bold or a sentence in
25+
all-caps. The most common inline object is a *run*. All content within
26+
a block container is inside of an inline object. Typically, a paragraph
27+
contains one or more runs, each of which contain some part of the paragraph's
28+
text.
29+
30+
The attributes of a block-level item specify its placement on the page, such
31+
items as indentation and space before and after a paragraph. The attributes
32+
of an inline item generally specify the font in which the content appears,
33+
things like typeface, font size, bold, and italic.
34+
35+
36+
Paragraph properties
37+
--------------------
38+
39+
A paragraph has a variety of properties that specify its placement within its
40+
container (typically a page) and the way it divides its content into separate
41+
lines.
42+
43+
In general, it's best to define a *paragraph style* collecting these
44+
attributes into a meaningful group and apply the appropriate style to each
45+
paragraph, rather than repeatedly apply those properties directly to each
46+
paragraph. This is analogous to how Cascading Style Sheets (CSS) work with
47+
HTML. All the paragraph properties described here can be set using a style as
48+
well as applied directly to a paragraph.
49+
50+
The formatting properties of a paragraph are accessed using the
51+
|ParagraphFormat| object available using the paragraph's
52+
:attr:`~.Paragraph.paragraph_format` property.
53+
54+
55+
Horizontal alignment (justification)
56+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
57+
58+
Also known as *justification*, the horizontal alignment of a paragraph can be
59+
set to left, centered, right, or fully justified (aligned on both the left
60+
and right sides) using values from the enumeration
61+
:ref:`WdParagraphAlignment`::
62+
63+
>>> from docx.enum.text import WD_ALIGN_PARAGRAPH
64+
>>> document = Document()
65+
>>> paragraph = document.add_paragraph()
66+
>>> paragraph_format = paragraph.paragraph_format
67+
68+
>>> paragraph_format.alignment
69+
None # indicating alignment is inherited from the style hierarchy
70+
>>> paragraph_format.alignment = WD_ALIGN_PARAGRAPH.CENTER
71+
>>> paragraph_format.alignment
72+
CENTER (1)
73+
74+
75+
Indentation
76+
~~~~~~~~~~~
77+
78+
Indentation is the horizontal space between a paragraph and edge of its
79+
container, typically the page margin. A paragraph can be indented separately
80+
on the left and right side. The first line can also have a different
81+
indentation than the rest of the paragraph. A first line indented further
82+
than the rest of the paragraph has *first line indent*. A first line indented
83+
less has a *hanging indent*.
84+
85+
Indentation is specified using a |Length| value, such as |Inches|, |Pt|, or
86+
|Cm|. Negative values are valid and cause the paragraph to overlap the margin
87+
by the specified amount. A value of |None| indicates the indentation value is
88+
inherited from the style hierarchy. Assigning |None| to an indentation
89+
property removes any directly-applied indentation setting and restores
90+
inheritance from the style hierarchy::
91+
92+
>>> from docx.shared import Inches
93+
>>> paragraph = document.add_paragraph()
94+
>>> paragraph_format = paragraph.paragraph_format
95+
96+
>>> paragraph.left_indent
97+
None # indicating indentation is inherited from the style hierarchy
98+
>>> paragraph.left_indent = Inches(0.5)
99+
>>> paragraph.left_indent
100+
457200
101+
>>> paragraph.left_indent.inches
102+
0.5
103+
104+
105+
Right-side indent works in a similar way::
106+
107+
>>> from docx.shared import Pt
108+
>>> paragraph.right_indent
109+
None
110+
>>> paragraph.right_indent = Pt(24)
111+
>>> paragraph.right_indent
112+
304800
113+
>>> paragraph.right_indent.pt
114+
24.0
115+
116+
117+
First-line indent is specified using the
118+
:attr:`~.ParagraphFormat.first_line_indent` property and is interpreted
119+
relative to the left indent. A negative value indicates a hanging indent::
120+
121+
>>> paragraph.first_line_indent
122+
None
123+
>>> paragraph.first_line_indent = Inches(-0.25)
124+
>>> paragraph.first_line_indent
125+
-228600
126+
>>> paragraph.first_line_indent.inches
127+
-0.25
128+
129+
130+
Paragraph spacing
131+
~~~~~~~~~~~~~~~~~
132+
133+
The :attr:`~.ParagraphFormat.space_before` and
134+
:attr:`~.ParagraphFormat.space_after` properties control the spacing between
135+
subsequent paragraphs, controlling the spacing before and after a paragraph,
136+
respectively. Inter-paragraph spacing is *collapsed* during page layout,
137+
meaning the spacing between two paragraphs is the maximum of the
138+
`space_after` for the first paragraph and the `space_before` of the second
139+
paragraph. Paragraph spacing is specified as a |Length| value, often using
140+
|Pt|::
141+
142+
>>> paragraph_format.space_before, paragraph_format.space_after
143+
(None, None) # inherited by default
144+
145+
>>> paragraph_format.space_before = Pt(18)
146+
>>> paragraph_format.space_before.pt
147+
18.0
148+
149+
>>> paragraph_format.space_after = Pt(12)
150+
>>> paragraph_format.space_after.pt
151+
12.0
152+
153+
154+
Line spacing
155+
~~~~~~~~~~~~
156+
157+
Line spacing is the distance between subsequent baselines in the lines of
158+
a paragraph. Line spacing can be specified either as an absolute distance or
159+
relative to the line height (essentially the point size of the font used).
160+
A typical absolute measure would be 18 points. A typical relative measure
161+
would be double-spaced (2.0 line heights). The default line spacing is
162+
single-spaced (1.0 line heights).
163+
164+
Line spacing is controlled by the interaction of the
165+
:attr:`~.ParagraphFormat.line_spacing` and
166+
:attr:`~.ParagraphFormat.line_spacing_rule` properties.
167+
:attr:`~.ParagraphFormat.line_spacing` is either a |Length| value,
168+
a (small-ish) |float|, or None. A |Length| value indicates an absolute
169+
distance. A |float| indicates a number of line heights. |None| indicates line
170+
spacing is inherited. :attr:`~.ParagraphFormat.line_spacing_rule` is a member
171+
of the :ref:`WdLineSpacing` enumeration or |None|::
172+
173+
>>> from docx.shared import Length
174+
>>> paragraph_format.line_spacing
175+
None
176+
>>> paragraph_format.line_spacing_rule
177+
None
178+
179+
>>> paragraph_format.line_spacing = Pt(18)
180+
>>> isinstance(Length, paragraph_format.line_spacing)
181+
True
182+
>>> paragraph_format.line_spacing.pt
183+
18.0
184+
>>> paragraph_format.line_spacing_rule
185+
EXACTLY (4)
186+
187+
>>> paragraph_format.line_spacing = 1.75
188+
>>> paragraph_format.line_spacing
189+
1.75
190+
>>> paragraph_format.line_spacing_rule
191+
MULTIPLE (5)
192+
193+
194+
Pagination properties
195+
~~~~~~~~~~~~~~~~~~~~~
196+
197+
Four paragraph properties, :attr:`~.ParagraphFormat.keep_together`,
198+
:attr:`~.ParagraphFormat.keep_with_next`,
199+
:attr:`~.ParagraphFormat.page_break_before`, and
200+
:attr:`~.ParagraphFormat.widow_control` control aspects of how the paragraph
201+
behaves near page boundaries.
202+
203+
:attr:`~.ParagraphFormat.keep_together` causes the entire paragraph to appear
204+
on the same page, issuing a page break before the paragraph if it would
205+
otherwise be broken across two pages.
206+
207+
:attr:`~.ParagraphFormat.keep_with_next` keeps a paragraph on the same page
208+
as the subsequent paragraph. This can be used, for example, to keep a section
209+
heading on the same page as the first paragraph of the section.
210+
211+
:attr:`~.ParagraphFormat.page_break_before` causes a paragraph to be placed
212+
at the top of a new page. This could be used on a chapter heading to ensure
213+
chapters start on a new page.
16214

17-
A paragraph contains one or more inline elements called *runs*. It is the
18-
run that actually contains text content.
215+
:attr:`~.ParagraphFormat.widow_control` breaks a page to avoid placing the
216+
first or last line of the paragraph on a separate page from the rest of the
217+
paragraph.
19218

20-
The main purpose of a run it to carry character formatting information, such as
21-
font typeface and size. Bold, italic, and underline formatting are also
22-
examples. All text within a run shares the same character formatting. So
23-
a three-word paragraph having the middle word bold would require three runs.
219+
All four of these properties are *tri-state*, meaning they can take the value
220+
|True|, |False|, or |None|. |None| indicates the property value is inherited
221+
from the style hierarchy. |True| means "on" and |False| means "off"::
24222

25-
Producing paragraphs containing so-called "rich" text requires building the
26-
paragraph up out of multiple runs. Runs can also contain other content objects
27-
such as line breaks and fields, so there are other reasons you may need to use
28-
the low-level text API.
223+
>>> paragraph_format.keep_together
224+
None # all four inherit by default
225+
>>> paragraph_format.keep_with_next = True
226+
>>> paragraph_format.keep_with_next
227+
True
228+
>>> paragraph_format.page_break_before = False
229+
>>> paragraph_format.page_break_before
230+
False

0 commit comments

Comments
 (0)
X Tutup