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.
There are six behavior properties:
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.
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.
>>> style = document.styles['Foobar']
>>> style.priority
None
>>> style.priority = 7
>>> style.priority
7
>>> style.priority = -42
>>> style.priority
0
The w:unhideWhenUsed element signals an application that this style should be made visibile the next time it is used.
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.
>>> style = document.styles['Foo']
>>> style.unhide_when_used
False
>>> style.unhide_when_used = True
>>> style.unhide_when_used
True
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>
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.
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.
>>> style = document.styles['Foo']
>>> style.quick_style
False
>>> style.quick_style = True
>>> style.quick_style
True
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>
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.
Default. If the w:locked element is omitted, its effective value is False. There is no inheritance of this value.
>>> style = document.styles['Foo']
>>> style.locked
False
>>> style.locked = True
>>> style.locked
True
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>
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'
<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>
<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>