Skip to content

Commit cb1ce72

Browse files
author
Steve Canny
committed
docs: document analysis for next_paragraph_style
1 parent 10c01d1 commit cb1ce72

File tree

4 files changed

+184
-0
lines changed

4 files changed

+184
-0
lines changed

‎docs/conf.py

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,8 @@
6969
rst_epilog = """
7070
.. |api-Document| replace:: :class:`docx.api.Document`
7171
72+
.. |AttributeError| replace:: :exc:`.AttributeError`
73+
7274
.. |BaseStyle| replace:: :class:`.BaseStyle`
7375
7476
.. |_Body| replace:: :class:`._Body`

‎docs/dev/analysis/features/styles/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ Styles
77

88
styles
99
style
10+
paragraph-style
1011
latent-styles
1112

1213
Word supports the definition of *styles* to allow a group of formatting

‎docs/dev/analysis/features/styles/paragraph-style.rst

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
2+
Paragraph Style
3+
===============
4+
5+
A paragraph style provides character formatting (font) as well as paragraph
6+
formatting properties. Character formatting is inherited from
7+
|_CharacterStyle| and is predominantly embodied in the :attr:`font` property.
8+
Likewise, most paragraph-specific properties come from the |ParagraphFormat|
9+
object available on the :attr:`paragraph_format` property.
10+
11+
A handful of other properties are specific to a paragraph style.
12+
13+
14+
next_paragraph_style
15+
--------------------
16+
17+
The `next_paragraph_style` property provides access to the style that will
18+
automatically be assigned by Word to a new paragraph inserted after
19+
a paragraph with this style. This property is most useful for a style that
20+
would normally appear only once in a sequence, such as a heading.
21+
22+
The default is to use the same style for an inserted paragraph. This
23+
addresses the most common case; for example, a body paragraph having `Body
24+
Text` style would normally be followed by a paragraph of the same style.
25+
26+
27+
Expected usage
28+
~~~~~~~~~~~~~~
29+
30+
The priority use case for this property is to provide a working style that
31+
can be assigned to a paragraph. The property will always provide a valid
32+
paragraph style, defaulting to the current style whenever a more specific one
33+
cannot be determined.
34+
35+
While this obscures some specifics of the situation from the API, it
36+
addresses the expected most common use case. Developers needing to detect,
37+
for example, missing styles can readily use the oxml layer to inspect the
38+
XML and further features can be added if those use cases turn out to be more
39+
common than expected.
40+
41+
42+
Behavior
43+
~~~~~~~~
44+
45+
**Default.** The default next paragraph style is the same paragraph style.
46+
47+
The default is used whenever the next paragraph style is not specified or is
48+
invalid, including these conditions:
49+
50+
* No `w:next` child element is present
51+
* A style having the styleId specified in `w:next/@w:val` is not present in
52+
the document.
53+
* The style specified in `w:next/@w:val` is not a paragraph style.
54+
55+
In all these cases the current style (`self`) is returned.
56+
57+
58+
Example XML
59+
~~~~~~~~~~~
60+
61+
.. highlight:: xml
62+
63+
paragraph_style.next_paragraph_style is styles['Bar']::
64+
65+
<w:style w:type="paragraph" w:styleId="Foo">
66+
<w:name w:val="Foo"/>
67+
<w:next w:val="Bar"/>
68+
</w:style>
69+
70+
**Semantics.** The `w:next` child element is optional.
71+
72+
* When omitted, the next style is the same as the current style.
73+
* If no style with a matching styleId exists, the `w:next` element is ignored
74+
and the next style is the same as the current style.
75+
* If a style is found but is of a style type other than paragraph, the
76+
`w:next` element is ignored and the next style is the same as the current
77+
style.
78+
79+
80+
Candidate protocol
81+
~~~~~~~~~~~~~~~~~~
82+
83+
.. highlight:: python
84+
85+
::
86+
87+
>>> styles = document.styles
88+
89+
>>> paragraph_style = styles['Foo']
90+
>>> paragraph_style.next_paragraph_style == paragraph_style
91+
True
92+
93+
>>> paragraph_style.next_paragraph_style = styles['Bar']
94+
>>> paragraph_style.next_paragraph_style == styles['Bar']
95+
True
96+
97+
>>> paragraph_style.next_paragraph_style = None
98+
>>> paragraph_style.next_paragraph_style == paragraph_style
99+
True
100+
101+
102+
Schema excerpt
103+
--------------
104+
105+
.. highlight:: xml
106+
107+
::
108+
109+
<xsd:complexType name="CT_Style">
110+
<xsd:sequence>
111+
<xsd:element name="name" type="CT_String" minOccurs="0"/>
112+
<xsd:element name="aliases" type="CT_String" minOccurs="0"/>
113+
<xsd:element name="basedOn" type="CT_String" minOccurs="0"/>
114+
<xsd:element name="next" type="CT_String" minOccurs="0"/>
115+
<xsd:element name="link" type="CT_String" minOccurs="0"/>
116+
<xsd:element name="autoRedefine" type="CT_OnOff" minOccurs="0"/>
117+
<xsd:element name="hidden" type="CT_OnOff" minOccurs="0"/>
118+
<xsd:element name="uiPriority" type="CT_DecimalNumber" minOccurs="0"/>
119+
<xsd:element name="semiHidden" type="CT_OnOff" minOccurs="0"/>
120+
<xsd:element name="unhideWhenUsed" type="CT_OnOff" minOccurs="0"/>
121+
<xsd:element name="qFormat" type="CT_OnOff" minOccurs="0"/>
122+
<xsd:element name="locked" type="CT_OnOff" minOccurs="0"/>
123+
<xsd:element name="personal" type="CT_OnOff" minOccurs="0"/>
124+
<xsd:element name="personalCompose" type="CT_OnOff" minOccurs="0"/>
125+
<xsd:element name="personalReply" type="CT_OnOff" minOccurs="0"/>
126+
<xsd:element name="rsid" type="CT_LongHexNumber" minOccurs="0"/>
127+
<xsd:element name="pPr" type="CT_PPrGeneral" minOccurs="0"/>
128+
<xsd:element name="rPr" type="CT_RPr" minOccurs="0"/>
129+
<xsd:element name="tblPr" type="CT_TblPrBase" minOccurs="0"/>
130+
<xsd:element name="trPr" type="CT_TrPr" minOccurs="0"/>
131+
<xsd:element name="tcPr" type="CT_TcPr" minOccurs="0"/>
132+
<xsd:element name="tblStylePr" type="CT_TblStylePr" minOccurs="0" maxOccurs="unbounded"/>
133+
</xsd:sequence>
134+
<xsd:attribute name="type" type="ST_StyleType"/>
135+
<xsd:attribute name="styleId" type="s:ST_String"/>
136+
<xsd:attribute name="default" type="s:ST_OnOff"/>
137+
<xsd:attribute name="customStyle" type="s:ST_OnOff"/>
138+
</xsd:complexType>
139+
140+
<xsd:complexType name="CT_String">
141+
<xsd:attribute name="val" type="s:ST_String" use="required"/>
142+
</xsd:complexType>

‎docs/user/styles-using.rst

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -225,6 +225,45 @@ indentation of 1/4 inch, 12 points spacing above, and widow/orphan control::
225225
>>> paragraph_format.widow_control = True
226226

227227

228+
Use paragraph-specific style properties
229+
---------------------------------------
230+
231+
A paragraph style has a :attr:`~._ParagraphStyle.next_paragraph_style`
232+
property that specifies the style to be applied to new paragraphs inserted
233+
after a paragraph of that style. This is most useful when the style would
234+
normally appear only once in a sequence, such as a heading. In that case, the
235+
paragraph style can automatically be set back to a body style after
236+
completing the heading.
237+
238+
In the most common case (body paragraphs), subsequent paragraphs should
239+
receive the same style as the current paragraph. The default handles this
240+
case well by applying the same style if a next paragraph style is not
241+
specified.
242+
243+
Here's an example of how you would change the next paragraph style of the
244+
*Heading 1* style to *Body Text*::
245+
246+
>>> from docx import Document
247+
>>> document = Document()
248+
>>> styles = document.styles
249+
250+
>>> styles['Heading 1'].next_paragraph_style = styles['Body Text']
251+
252+
The default behavior can be restored by assigning |None| or the style itself::
253+
254+
>>> heading_1_style = styles['Heading 1']
255+
>>> heading_1_style.next_paragraph_style.name
256+
'Body Text'
257+
258+
>>> heading_1_style.next_paragraph_style = heading_1_style
259+
>>> heading_1_style.next_paragraph_style.name
260+
'Heading 1'
261+
262+
>>> heading_1_style.next_paragraph_style = None
263+
>>> heading_1_style.next_paragraph_style.name
264+
'Heading 1'
265+
266+
228267
Control how a style appears in the Word UI
229268
------------------------------------------
230269

0 commit comments

Comments
 (0)