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
|
Paragraph Style
===============
A paragraph style provides character formatting (font) as well as paragraph
formatting properties. Character formatting is inherited from
|_CharacterStyle| and is predominantly embodied in the :attr:`font` property.
Likewise, most paragraph-specific properties come from the |ParagraphFormat|
object available on the :attr:`paragraph_format` property.
A handful of other properties are specific to a paragraph style.
next_paragraph_style
--------------------
The `next_paragraph_style` property provides access to the style that will
automatically be assigned by Word to a new paragraph inserted after
a paragraph with this style. This property is most useful for a style that
would normally appear only once in a sequence, such as a heading.
The default is to use the same style for an inserted paragraph. This
addresses the most common case; for example, a body paragraph having `Body
Text` style would normally be followed by a paragraph of the same style.
Expected usage
~~~~~~~~~~~~~~
The priority use case for this property is to provide a working style that
can be assigned to a paragraph. The property will always provide a valid
paragraph style, defaulting to the current style whenever a more specific one
cannot be determined.
While this obscures some specifics of the situation from the API, it
addresses the expected most common use case. Developers needing to detect,
for example, missing styles can readily use the oxml layer to inspect the
XML and further features can be added if those use cases turn out to be more
common than expected.
Behavior
~~~~~~~~
**Default.** The default next paragraph style is the same paragraph style.
The default is used whenever the next paragraph style is not specified or is
invalid, including these conditions:
* No `w:next` child element is present
* A style having the styleId specified in `w:next/@w:val` is not present in
the document.
* The style specified in `w:next/@w:val` is not a paragraph style.
In all these cases the current style (`self`) is returned.
Example XML
~~~~~~~~~~~
.. highlight:: xml
paragraph_style.next_paragraph_style is styles['Bar']::
<w:style w:type="paragraph" w:styleId="Foo">
<w:name w:val="Foo"/>
<w:next w:val="Bar"/>
</w:style>
**Semantics.** The `w:next` child element is optional.
* When omitted, the next style is the same as the current style.
* If no style with a matching styleId exists, the `w:next` element is ignored
and the next style is the same as the current style.
* If a style is found but is of a style type other than paragraph, the
`w:next` element is ignored and the next style is the same as the current
style.
Candidate protocol
~~~~~~~~~~~~~~~~~~
.. highlight:: python
::
>>> styles = document.styles
>>> paragraph_style = styles['Foo']
>>> paragraph_style.next_paragraph_style == paragraph_style
True
>>> paragraph_style.next_paragraph_style = styles['Bar']
>>> paragraph_style.next_paragraph_style == styles['Bar']
True
>>> paragraph_style.next_paragraph_style = None
>>> paragraph_style.next_paragraph_style == paragraph_style
True
Schema excerpt
--------------
.. highlight:: xml
::
<xsd:complexType name="CT_Style">
<xsd:sequence>
<xsd:element name="name" type="CT_String" minOccurs="0"/>
<xsd:element name="aliases" type="CT_String" minOccurs="0"/>
<xsd:element name="basedOn" type="CT_String" minOccurs="0"/>
<xsd:element name="next" type="CT_String" minOccurs="0"/>
<xsd:element name="link" type="CT_String" minOccurs="0"/>
<xsd:element name="autoRedefine" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="hidden" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="uiPriority" type="CT_DecimalNumber" minOccurs="0"/>
<xsd:element name="semiHidden" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="unhideWhenUsed" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="qFormat" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="locked" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="personal" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="personalCompose" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="personalReply" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="rsid" type="CT_LongHexNumber" minOccurs="0"/>
<xsd:element name="pPr" type="CT_PPrGeneral" minOccurs="0"/>
<xsd:element name="rPr" type="CT_RPr" minOccurs="0"/>
<xsd:element name="tblPr" type="CT_TblPrBase" minOccurs="0"/>
<xsd:element name="trPr" type="CT_TrPr" minOccurs="0"/>
<xsd:element name="tcPr" type="CT_TcPr" minOccurs="0"/>
<xsd:element name="tblStylePr" type="CT_TblStylePr" minOccurs="0" maxOccurs="unbounded"/>
</xsd:sequence>
<xsd:attribute name="type" type="ST_StyleType"/>
<xsd:attribute name="styleId" type="s:ST_String"/>
<xsd:attribute name="default" type="s:ST_OnOff"/>
<xsd:attribute name="customStyle" type="s:ST_OnOff"/>
</xsd:complexType>
<xsd:complexType name="CT_String">
<xsd:attribute name="val" type="s:ST_String" use="required"/>
</xsd:complexType>
|