X Tutup
Skip to content

Commit bdef31d

Browse files
author
Steve Canny
committed
docs: add Working with Styles page
* Add some prerequisite content to Understanding Styles
1 parent 226b699 commit bdef31d

File tree

5 files changed

+249
-43
lines changed

5 files changed

+249
-43
lines changed

‎docs/conf.py‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,8 @@
8989
9090
.. |False| replace:: ``False``
9191
92+
.. |Font| replace:: :class:`.Font`
93+
9294
.. |InlineShape| replace:: :class:`.InlineShape`
9395
9496
.. |InlineShapes| replace:: :class:`.InlineShapes`
@@ -97,6 +99,8 @@
9799
98100
.. |int| replace:: :class:`int`
99101
102+
.. |LatentStyles| replace:: :class:`.LatentStyles`
103+
100104
.. |Length| replace:: :class:`.Length`
101105
102106
.. |OpcPackage| replace:: :class:`OpcPackage`
@@ -117,14 +121,18 @@
117121
118122
.. |_Rows| replace:: :class:`_Rows`
119123
120-
.. |Run| replace:: :class:`Run`
124+
.. |Run| replace:: :class:`.Run`
121125
122126
.. |Section| replace:: :class:`.Section`
123127
124128
.. |Sections| replace:: :class:`.Sections`
125129
126130
.. |str| replace:: :class:`str`
127131
132+
.. |Style| replace:: :class:`.Style`
133+
134+
.. |Styles| replace:: :class:`.Styles`
135+
128136
.. |StylesPart| replace:: :class:`.StylesPart`
129137
130138
.. |Table| replace:: :class:`.Table`

‎docs/index.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,8 @@ User Guide
7070
user/documents
7171
user/sections
7272
user/api-concepts
73-
user/styles
73+
user/styles-understanding
74+
user/styles-using
7475
user/shapes
7576
user/text
7677

‎docs/user/quickstart.rst‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -308,7 +308,9 @@ settings, Word has *character styles* which specify a group of run-level
308308
settings. In general you can think of a character style as specifying a font,
309309
including its typeface, size, color, bold, italic, etc.
310310

311-
Like paragraph styles, a character style must already be defined in the document you open with the ``Document()`` call (*see* :doc:`styles`).
311+
Like paragraph styles, a character style must already be defined in the
312+
document you open with the ``Document()`` call (*see*
313+
:ref:`understandingstyles`).
312314

313315
A character style can be specified when adding a new run::
314316

docs/user/styles.rst renamed to docs/user/styles-understanding.rst

Lines changed: 107 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
.. _understandingstyles:
12

23
Understanding Styles
34
====================
@@ -27,9 +28,9 @@ text, a table, and a list, respectively.
2728

2829
Experienced programmers will recognize styles as a level of indirection. The
2930
great thing about those is it allows you to define something once, then apply
30-
that definition many times. This saves the work of defining the same thing over
31-
an over; but more importantly it allows you to change it the definition and
32-
have that change reflected in all the places you originally applied it.
31+
that definition many times. This saves the work of defining the same thing
32+
over an over; but more importantly it allows you to change the definition and
33+
have that change reflected in all the places you have applied it.
3334

3435

3536
Why doesn't the style I applied show up?
@@ -49,11 +50,11 @@ work around it, so here it is up top.
4950
The file would get a little bloated if it contained all the style
5051
definitions you could use but haven't.
5152

52-
#. If you apply a style that's not defined in your file (in the styles.xml part
53-
if you're curious), Word just ignores it. It doesn't complain, it just
54-
doesn't change how things are formatted. I'm sure there's a good reason for
55-
this. But it can present as a bit of a puzzle if you don't understand how
56-
Word works that way.
53+
#. If you apply a style using |docx| that's not defined in your file (in the
54+
styles.xml part if you're curious), Word just ignores it. It doesn't
55+
complain, it just doesn't change how things are formatted. I'm sure
56+
there's a good reason for this. But it can present as a bit of a puzzle if
57+
you don't understand how Word works that way.
5758

5859
#. When you use a style, Word adds it to the file. Once there, it stays.
5960
I imagine there's a way to get rid of it, but you have to work at it. If
@@ -75,8 +76,74 @@ then deleting the paragraph works fine. That's how I got the ones below into
7576
the default template :).
7677

7778

79+
Glossary
80+
--------
81+
82+
style definition
83+
A ``<w:style>`` element in the styles part of a document that explicitly
84+
defines the attributes of a style.
85+
86+
defined style
87+
A style that is explicitly defined in a document. Contrast with *latent
88+
style*.
89+
90+
built-in style
91+
One of the set of 276 pre-set styles built into Word, such as "Heading
92+
1". A built-in style can be either defined or latent. A built-in style
93+
that is not yet defined is known as a *latent style*. Both defined and
94+
latent built-in styles may appear as options in Word's style panel and
95+
style gallery.
96+
97+
custom style
98+
Also known as a *user defined style*, any style defined in a Word
99+
document that is not a built-in style. Note that a custom style cannot be
100+
a latent style.
101+
102+
latent style
103+
A built-in style having no definition in a particular document is known
104+
as a *latent style* in that document. A latent style can appear as an
105+
option in the Word UI depending on the settings in the |LatentStyles|
106+
object for the document.
107+
108+
recommended style list
109+
A list of styles that appears in the styles toolbox or panel when
110+
"Recommended" is selected from the "List:" dropdown box.
111+
112+
Style Gallery
113+
The selection of example styles that appear in the ribbon of the Word UI
114+
and which may be applied by clicking on one of them.
115+
116+
117+
Identifying a style
118+
-------------------
119+
120+
A style has three identifying properties, `name`, `style_id`, and `type`.
121+
122+
Each style's :attr:`name` property is its stable, unique identifier for
123+
access purposes.
124+
125+
A style's :attr:`style_id` is used internally to key a content object such as
126+
a paragraph to its style. However this value is generated automatically by
127+
Word and is not guaranteed to be stable across saves. In general, the style
128+
id is formed simply by removing spaces from the *localized* style name,
129+
however there are exceptions. Users of |docx| should generally avoid using
130+
the style id unless they are confident with the internals involved.
131+
132+
A style's :attr:`type` is set at creation time and cannot be changed.
133+
134+
135+
Style inheritance
136+
-----------------
137+
138+
A style can inherit properties from another style, somewhat similarly to how
139+
Cascading Style Sheets (CSS) works. Inheritance is specified using the
140+
:attr:`~.BaseStyle.base_style` attribute. By basing one style on another, an
141+
inheritance hierarchy of arbitrary depth can be formed. A style having no
142+
base style inherits properties from the document defaults.
143+
144+
78145
Paragraph styles in default template
79-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
146+
------------------------------------
80147

81148
* Normal
82149
* BodyText
@@ -114,8 +181,38 @@ Paragraph styles in default template
114181
* Title
115182

116183

184+
Character styles in default template
185+
------------------------------------
186+
187+
* BodyTextChar
188+
* BodyText2Char
189+
* BodyText3Char
190+
* BookTitle
191+
* DefaultParagraphFont
192+
* Emphasis
193+
* Heading1Char
194+
* Heading2Char
195+
* Heading3Char
196+
* Heading4Char
197+
* Heading5Char
198+
* Heading6Char
199+
* Heading7Char
200+
* Heading8Char
201+
* Heading9Char
202+
* IntenseEmphasis
203+
* IntenseQuoteChar
204+
* IntenseReference
205+
* MacroTextChar
206+
* QuoteChar
207+
* Strong
208+
* SubtitleChar
209+
* SubtleEmphasis
210+
* SubtleReference
211+
* TitleChar
212+
213+
117214
Table styles in default template
118-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
215+
--------------------------------
119216

120217
* TableNormal
121218
* ColorfulGrid
@@ -217,33 +314,3 @@ Table styles in default template
217314
* MediumShading2-Accent5
218315
* MediumShading2-Accent6
219316
* TableGrid
220-
221-
222-
Character styles in default template
223-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
224-
225-
* BodyText2Char
226-
* BodyText3Char
227-
* BodyTextChar
228-
* BookTitle
229-
* DefaultParagraphFont
230-
* Emphasis
231-
* Heading1Char
232-
* Heading2Char
233-
* Heading3Char
234-
* Heading4Char
235-
* Heading5Char
236-
* Heading6Char
237-
* Heading7Char
238-
* Heading8Char
239-
* Heading9Char
240-
* IntenseEmphasis
241-
* IntenseQuoteChar
242-
* IntenseReference
243-
* MacroTextChar
244-
* QuoteChar
245-
* Strong
246-
* SubtitleChar
247-
* SubtleEmphasis
248-
* SubtleReference
249-
* TitleChar

‎docs/user/styles-using.rst‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
2+
Working with Styles
3+
===================
4+
5+
This page uses concepts developed in the prior page without introduction. If
6+
a term is unfamiliar, consult the prior page :ref:`understandingstyles` for
7+
a definition.
8+
9+
10+
Accessing a style
11+
-----------------
12+
13+
Styles are accessed using the :attr:`.Document.styles` attribute::
14+
15+
>>> document = Document()
16+
>>> styles = document.styles
17+
>>> styles
18+
<docx.styles.styles.Styles object at 0x10a7c4f50>
19+
20+
The |Styles| object provides dictionary-style access to defined styles by
21+
name::
22+
23+
>>> styles['Normal']
24+
<docx.styles.style._ParagraphStyle object at <0x10a7c4f6b>
25+
26+
.. note:: Built-in styles are stored in a WordprocessingML file using their
27+
English name, e.g. 'Heading 1', even though users working on a localized
28+
version of Word will see native language names in the UI, e.g. 'Kop 1'.
29+
Because |docx| operates on the WordprocessingML file, style lookups must
30+
use the English name. A document available on this external site allows
31+
you to create a mapping between local language names and English style
32+
names:
33+
http://www.thedoctools.com/index.php?show=mt_create_style_name_list
34+
35+
User-defined styles, also known as *custom styles*, are not localized and
36+
are accessed with the name exactly as it appears in the Word UI.
37+
38+
The |Styles| object is also iterable. By using the identification properties
39+
on |Style|, various subsets of the defined styles can be generated. For
40+
example, this code will produce a list of the defined paragraph styles::
41+
42+
>>> from docx.enum.style import WD_STYLE_TYPE
43+
>>> styles = document.styles
44+
>>> paragraph_styles = [
45+
... s for s in styles if s.type == WD_STYLE_TYPE.PARAGRAPH
46+
... ]
47+
>>> for style in paragraph_styles:
48+
... print(style.name)
49+
...
50+
Normal
51+
Body Text
52+
List Bullet
53+
54+
55+
Applying a style
56+
----------------
57+
58+
The |Paragraph|, |Run|, and |Table| objects each have a :attr:`style`
59+
attribute. Assigning a |Style| object of the appropriate type to this
60+
attribute applies that style::
61+
62+
>>> document = Document()
63+
>>> paragraph = document.add_paragraph()
64+
>>> paragraph.style
65+
None # inherits the default style, usually 'Normal' for a paragraph
66+
>>> paragraph.style = document.styles['Heading 1']
67+
>>> paragraph.style.name
68+
'Heading 1'
69+
70+
A style name can also be assigned directly, in which case |docx| will do the
71+
lookup for you::
72+
73+
>>> paragraph.style = 'List Bullet'
74+
>>> paragraph.style
75+
<docx.styles.style._ParagraphStyle object at <0x10a7c4f84>
76+
>>> paragraph.style.name
77+
'List Bullet'
78+
79+
A style can also be applied at creation time using either the |Style| object
80+
or its name::
81+
82+
>>> paragraph = document.add_paragraph(style='Heading 1')
83+
>>> paragraph.style.name
84+
'Heading 1'
85+
>>> heading_1_style = document.styles['Heading 1']
86+
>>> paragraph = document.add_paragraph(style=heading_1_style)
87+
>>> paragraph.style.name
88+
'Heading 1'
89+
90+
91+
Controlling how a style appears in the Word UI
92+
----------------------------------------------
93+
94+
The properties of a style fall into two categories, *behavioral properties*
95+
and *formatting properties*. Its behavioral properties control when and where
96+
the style appears in the Word UI. Its formatting properties determine the
97+
formatting of content to which the style is applied, such as the size of the
98+
font and its paragraph indentation.
99+
100+
There are five behavioral properties of a style:
101+
102+
* :attr:`~.Style.hidden`
103+
* :attr:`~.Style.unhide_when_used`
104+
* :attr:`~.Style.priority`
105+
* :attr:`~.Style.quick_style`
106+
* :attr:`~.Style.locked`
107+
108+
The key notion to understanding the behavioral properties is the *recommended
109+
list*. In the style pane in Word, the user can select which list of styles
110+
they want to see. One of those is named *Recommended*. All five behavior
111+
properties affect some aspect of the style's appearance in this list and in
112+
the style gallery.
113+
114+
In brief, a style appears in the recommended list if its `hidden` property is
115+
|False|. If a style is not hidden and its `quick_style` property is |True|,
116+
it also appears in the style gallery. The style's `priority` value (|int|)
117+
determines its position in the sequence of styles. If a styles's `locked`
118+
property is |True| and formatting restrictions are turned on for the
119+
document, the style will not appear in any list or the style gallery and
120+
cannot be applied to content.
121+
122+
123+
Working with Latent Styles
124+
--------------------------
125+
126+
... describe latent styles in Understanding page ...
127+
128+
Let's illustrate these behaviors with a few examples.

0 commit comments

Comments
 (0)
X Tutup