Style objects

A style is one of four types; character, paragraph, table, or numbering. All style objects have behavioral properties and formatting properties. The set of formatting properties varies depending on the style type. In general, formatting properties are inherited along this hierarchy: character -> paragraph -> table. A numbering style has no formatting properties and does not inherit.

Behavioral properties

There are six behavior properties:

hidden: Style operates to assign formatting properties, but does not appear in the UI under any circumstances. Used for internal styles assigned by an application that should not be under the control of an end-user.
priority: Determines the sort order of the style in sequences presented by the UI.
semi-hidden: The style is hidden from the so-called "main" user interface. In Word this means the recommended list and the style gallery. The style still appears in the all styles list.
unhide_when_used: Flag to the application to set semi-hidden False when the style is next used.
quick_style: Show the style in the style gallery when it is not hidden.
locked: Style is hidden and cannot be applied when document formatting protection is active.

hidden

The hidden attribute doesn't work on built-in styles and its behavior on custom styles is spotty. Skipping this attribute for now. Will reconsider if someone requests it and can provide a specific use case.

Behavior

Scope. hidden doesn't work at all on 'Normal' or 'Heading 1' style. It doesn't work on Salutation either. There is no w:defHidden attribute on w:latentStyles, lending credence to the hypothesis it is not enabled for built-in styles. Hypothesis: Doesn't work on built-in styles.

UI behavior. A custom style having w:hidden set |True| is hidden from the gallery and all styles pane lists. It does however appear in the "Current style of selected text" box in the styles pane when the cursor is on a paragraph of that style. The style can be modified by the user from this current style UI element. The user can assign a new style to a paragraph having a hidden style.

priority

The priority attribute is the integer primary sort key determining the position of a style in a UI list. The secondary sort is alphabetical by name. Negative values are valid, although not assigned by Word itself and appear to be treated as 0.

Behavior

Default. Word behavior appears to default priority to 0 for custom styles. The spec indicates the effective default value is conceptually infinity, such that the style appears at the end of the styles list, presumably alphabetically among other styles having no priority assigned.

Candidate protocol

>>> style = document.styles['Foobar']
>>> style.priority
None
>>> style.priority = 7
>>> style.priority
7
>>> style.priority = -42
>>> style.priority
0

semi-hidden

The w:semiHidden element specifies visibility of the style in the so-called main user interface. For Word, this means the style gallery and the recommended, styles-in-use, and in-current-document lists. The all-styles list and current-style dropdown in the styles pane would then be considered part of an advanced user interface.

Behavior

Default. If the w:semiHidden element is omitted, its effective value is |False|. There is no inheritance of this value.

Scope. Works on both built-in and custom styles.

Word behavior. Word does not use the @w:val attribute. It writes <w:semiHidden/> for |True| and omits the element for |False|.

Candidate protocol

>>> style = document.styles['Foo']
>>> style.hidden
False
>>> style.hidden = True
>>> style.hidden
True

Example XML

style.hidden = True:

<w:style w:type="paragraph" w:styleId="Foo">
  <w:name w:val="Foo"/>
  <w:semiHidden/>
</w:style>

style.hidden = False:

<w:style w:type="paragraph" w:styleId="Foo">
  <w:name w:val="Foo"/>
</w:style>

Alternate constructions should also report the proper value but not be used when writing XML:

<w:style w:type="paragraph" w:styleId="Foo">
  <w:name w:val="Foo"/>
  <w:semiHidden w:val="0"/>  <!-- style.hidden is False -->
</w:style>

<w:style w:type="paragraph" w:styleId="Foo">
  <w:name w:val="Foo"/>
  <w:semiHidden w:val="1"/>  <!-- style.hidden is True -->
</w:style>

unhide-when-used

The w:unhideWhenUsed element signals an application that this style should be made visibile the next time it is used.

Behavior

Default. If the w:unhideWhenUsed element is omitted, its effective value is |False|. There is no inheritance of this value.

Word behavior. The w:unhideWhenUsed element is not changed or removed when the style is next used. Only the w:semiHidden element is affected, if present. Presumably this is so a style can be re-hidden, to be unhidden on the subsequent use.

Note that this behavior in Word is only triggered by a user actually applying a style. Merely loading a document having the style applied somewhere in its contents does not cause the w:semiHidden element to be removed.

Candidate protocol

>>> style = document.styles['Foo']
>>> style.unhide_when_used
False
>>> style.unhide_when_used = True
>>> style.unhide_when_used
True

Example XML

style.unhide_when_used = True:

<w:style w:type="paragraph" w:styleId="Foo">
  <w:name w:val="Foo"/>
  <w:semiHidden/>
  <w:unhideWhenUsed/>
</w:style>

style.unhide_when_used = False:

<w:style w:type="paragraph" w:styleId="Foo">
  <w:name w:val="Foo"/>
</w:style>

Alternate constructions should also report the proper value but not be used when writing XML:

<w:style w:type="paragraph" w:styleId="Foo">
  <w:name w:val="Foo"/>
  <w:unhideWhenUsed w:val="0"/>  <!-- style.unhide_when_used is False -->
</w:style>

<w:style w:type="paragraph" w:styleId="Foo">
  <w:name w:val="Foo"/>
  <w:unhideWhenUsed w:val="1"/>  <!-- style.unhide_when_used is True -->
</w:style>

quick-style

The w:qFormat element specifies whether Word should display this style in the style gallery. In order to appear in the gallery, this attribute must be |True| and hidden must be |False|.

Behavior

Default. If the w:qFormat element is omitted, its effective value is |False|. There is no inheritance of this value.

Word behavior. If w:qFormat is |True| and the style is not hidden, it will appear in the gallery in the order specified by w:uiPriority.

Candidate protocol

>>> style = document.styles['Foo']
>>> style.quick_style
False
>>> style.quick_style = True
>>> style.quick_style
True

Example XML

style.quick_style = True:

<w:style w:type="paragraph" w:styleId="Foo">
  <w:name w:val="Foo"/>
  <w:qFormat/>
</w:style>

style.quick_style = False:

<w:style w:type="paragraph" w:styleId="Foo">
  <w:name w:val="Foo"/>
</w:style>

Alternate constructions should also report the proper value but not be used when writing XML:

<w:style w:type="paragraph" w:styleId="Foo">
  <w:name w:val="Foo"/>
  <w:qFormat w:val="0"/>  <!-- style.quick_style is False -->
</w:style>

<w:style w:type="paragraph" w:styleId="Foo">
  <w:name w:val="Foo"/>
  <w:qFormat w:val="1"/>  <!-- style.quick_style is True -->
</w:style>

locked

The w:locked element specifies whether Word should prevent this style from being applied to content. This behavior is only active if formatting protection is turned on.

Behavior

Default. If the w:locked element is omitted, its effective value is |False|. There is no inheritance of this value.

Candidate protocol

>>> style = document.styles['Foo']
>>> style.locked
False
>>> style.locked = True
>>> style.locked
True

Example XML

style.locked = True:

<w:style w:type="paragraph" w:styleId="Foo">
  <w:name w:val="Foo"/>
  <w:locked/>
</w:style>

style.locked = False:

<w:style w:type="paragraph" w:styleId="Foo">
  <w:name w:val="Foo"/>
</w:style>

Alternate constructions should also report the proper value but not be used when writing XML:

<w:style w:type="paragraph" w:styleId="Foo">
  <w:name w:val="Foo"/>
  <w:locked w:val="0"/>  <!-- style.locked is False -->
</w:style>

<w:style w:type="paragraph" w:styleId="Foo">
  <w:name w:val="Foo"/>
  <w:locked w:val="1"/>  <!-- style.locked is True -->
</w:style>

Candidate protocols

Identification:

>>> style = document.styles['Body Text']
>>> style.name
'Body Text'
>>> style.style_id
'BodyText'
>>> style.type
WD_STYLE_TYPE.PARAGRAPH (1)

delete():

>>> len(styles)
6
>>> style.delete()
>>> len(styles)
5
>>> styles['Citation']
KeyError: no style with id or name 'Citation'

Style.base_style:

>>> style = styles.add_style('Citation', WD_STYLE_TYPE.PARAGRAPH)
>>> style.base_style
None
>>> style.base_style = styles['Normal']
>>> style.base_style
<docx.styles.style._ParagraphStyle object at 0x10a7a9550>
>>> style.base_style.name
'Normal'

Example XML

<w:styles>

  <!-- ... -->

  <w:style w:type="paragraph" w:default="1" w:styleId="Normal">
    <w:name w:val="Normal"/>
    <w:qFormat/>
  </w:style>
  <w:style w:type="character" w:default="1" w:styleId="DefaultParagraphFont">
    <w:name w:val="Default Paragraph Font"/>
    <w:uiPriority w:val="1"/>
    <w:semiHidden/>
    <w:unhideWhenUsed/>
  </w:style>
  <w:style w:type="table" w:default="1" w:styleId="TableNormal">
    <w:name w:val="Normal Table"/>
    <w:uiPriority w:val="99"/>
    <w:semiHidden/>
    <w:unhideWhenUsed/>
    <w:tblPr>
      <w:tblInd w:w="0" w:type="dxa"/>
      <w:tblCellMar>
        <w:top w:w="0" w:type="dxa"/>
        <w:left w:w="108" w:type="dxa"/>
        <w:bottom w:w="0" w:type="dxa"/>
        <w:right w:w="108" w:type="dxa"/>
      </w:tblCellMar>
    </w:tblPr>
  </w:style>
  <w:style w:type="numbering" w:default="1" w:styleId="NoList">
    <w:name w:val="No List"/>
    <w:uiPriority w:val="99"/>
    <w:semiHidden/>
    <w:unhideWhenUsed/>
  </w:style>

  <w:style w:type="paragraph" w:customStyle="1" w:styleId="Foobar">
    <w:name w:val="Foobar"/>
    <w:basedOn w:val="Normal"/>
    <w:qFormat/>
  </w:style>

</w:styles>

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_OnOff">
  <xsd:attribute name="val" type="s:ST_OnOff"/>
</xsd:complexType>

<xsd:complexType name="CT_String">
  <xsd:attribute name="val" type="s:ST_String" use="required"/>
</xsd:complexType>

<xsd:simpleType name="ST_OnOff">
  <xsd:union memberTypes="xsd:boolean ST_OnOff1"/>
</xsd:simpleType>

<xsd:simpleType name="ST_OnOff1">
  <xsd:restriction base="xsd:string">
    <xsd:enumeration value="on"/>
    <xsd:enumeration value="off"/>
  </xsd:restriction>
</xsd:simpleType>

<xsd:simpleType name="ST_StyleType">
  <xsd:restriction base="xsd:string">
    <xsd:enumeration value="paragraph"/>
    <xsd:enumeration value="character"/>
    <xsd:enumeration value="table"/>
    <xsd:enumeration value="numbering"/>
  </xsd:restriction>
</xsd:simpleType>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Style objects

Behavioral properties

hidden

Behavior

priority

Behavior

Candidate protocol

semi-hidden

Behavior

Candidate protocol

Example XML

unhide-when-used

Behavior

Candidate protocol

Example XML

quick-style

Behavior

Candidate protocol

Example XML

locked

Behavior

Candidate protocol

Example XML

Candidate protocols

Example XML

Schema excerpt

FilesExpand file tree

style.rst

Latest commit

History

style.rst

File metadata and controls

Style objects

Behavioral properties

hidden

Behavior

priority

Behavior

Candidate protocol

semi-hidden

Behavior

Candidate protocol

Example XML

unhide-when-used

Behavior

Candidate protocol

Example XML

quick-style

Behavior

Candidate protocol

Example XML

locked

Behavior

Candidate protocol

Example XML

Candidate protocols

Example XML

Schema excerpt