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 font property. Likewise, most paragraph-specific properties come from the ParagraphFormat object available on the 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

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

>>> 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

<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>