Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
2 | <html> | |
3 | <head> | |
4 | <link rel="STYLESHEET" href="lib.css" type='text/css' /> | |
5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> | |
6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> | |
7 | <link rel="first" href="lib.html" title='Python Library Reference' /> | |
8 | <link rel='contents' href='contents.html' title="Contents" /> | |
9 | <link rel='index' href='genindex.html' title='Index' /> | |
10 | <link rel='last' href='about.html' title='About this document...' /> | |
11 | <link rel='help' href='about.html' title='About this document...' /> | |
12 | <link rel="next" href="formatter-impls.html" /> | |
13 | <link rel="prev" href="module-formatter.html" /> | |
14 | <link rel="parent" href="module-formatter.html" /> | |
15 | <link rel="next" href="formatter-impls.html" /> | |
16 | <meta name='aesop' content='information' /> | |
17 | <title>12.1.1 The Formatter Interface </title> | |
18 | </head> | |
19 | <body> | |
20 | <DIV CLASS="navigation"> | |
21 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> | |
22 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
23 | <tr> | |
24 | <td class='online-navigation'><a rel="prev" title="12.1 formatter " | |
25 | href="module-formatter.html"><img src='../icons/previous.png' | |
26 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
27 | <td class='online-navigation'><a rel="parent" title="12.1 formatter " | |
28 | href="module-formatter.html"><img src='../icons/up.png' | |
29 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
30 | <td class='online-navigation'><a rel="next" title="12.1.2 Formatter Implementations" | |
31 | href="formatter-impls.html"><img src='../icons/next.png' | |
32 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
33 | <td align="center" width="100%">Python Library Reference</td> | |
34 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
35 | href="contents.html"><img src='../icons/contents.png' | |
36 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
37 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' | |
38 | border='0' height='32' alt='Module Index' width='32' /></a></td> | |
39 | <td class='online-navigation'><a rel="index" title="Index" | |
40 | href="genindex.html"><img src='../icons/index.png' | |
41 | border='0' height='32' alt='Index' width='32' /></A></td> | |
42 | </tr></table> | |
43 | <div class='online-navigation'> | |
44 | <b class="navlabel">Previous:</b> | |
45 | <a class="sectref" rel="prev" href="module-formatter.html">12.1 formatter </A> | |
46 | <b class="navlabel">Up:</b> | |
47 | <a class="sectref" rel="parent" href="module-formatter.html">12.1 formatter </A> | |
48 | <b class="navlabel">Next:</b> | |
49 | <a class="sectref" rel="next" href="formatter-impls.html">12.1.2 Formatter Implementations</A> | |
50 | </div> | |
51 | <hr /></div> | |
52 | </DIV> | |
53 | <!--End of Navigation Panel--> | |
54 | ||
55 | <H2><A NAME="SECTION0014110000000000000000"></A><A NAME="formatter-interface"></A> | |
56 | <BR> | |
57 | 12.1.1 The Formatter Interface | |
58 | </H2> | |
59 | ||
60 | <P> | |
61 | Interfaces to create formatters are dependent on the specific | |
62 | formatter class being instantiated. The interfaces described below | |
63 | are the required interfaces which all formatters must support once | |
64 | initialized. | |
65 | ||
66 | <P> | |
67 | One data element is defined at the module level: | |
68 | ||
69 | <P> | |
70 | <dl><dt><b><tt id='l2h-3791' xml:id='l2h-3791'>AS_IS</tt></b></dt> | |
71 | <dd> | |
72 | Value which can be used in the font specification passed to the | |
73 | <code>push_font()</code> method described below, or as the new value to any | |
74 | other <code>push_<var>property</var>()</code> method. Pushing the <code>AS_IS</code> | |
75 | value allows the corresponding <code>pop_<var>property</var>()</code> method to | |
76 | be called without having to track whether the property was changed. | |
77 | </dd></dl> | |
78 | ||
79 | <P> | |
80 | The following attributes are defined for formatter instance objects: | |
81 | ||
82 | <P> | |
83 | <dl><dt><b><tt id='l2h-3792' xml:id='l2h-3792' class="member">writer</tt></b></dt> | |
84 | <dd> | |
85 | The writer instance with which the formatter interacts. | |
86 | </dl> | |
87 | ||
88 | <P> | |
89 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
90 | <td><nobr><b><tt id='l2h-3793' xml:id='l2h-3793' class="method">end_paragraph</tt></b>(</nobr></td> | |
91 | <td><var>blanklines</var>)</td></tr></table></dt> | |
92 | <dd> | |
93 | Close any open paragraphs and insert at least <var>blanklines</var> | |
94 | before the next paragraph. | |
95 | </dl> | |
96 | ||
97 | <P> | |
98 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
99 | <td><nobr><b><tt id='l2h-3794' xml:id='l2h-3794' class="method">add_line_break</tt></b>(</nobr></td> | |
100 | <td><var></var>)</td></tr></table></dt> | |
101 | <dd> | |
102 | Add a hard line break if one does not already exist. This does not | |
103 | break the logical paragraph. | |
104 | </dl> | |
105 | ||
106 | <P> | |
107 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
108 | <td><nobr><b><tt id='l2h-3795' xml:id='l2h-3795' class="method">add_hor_rule</tt></b>(</nobr></td> | |
109 | <td><var>*args, **kw</var>)</td></tr></table></dt> | |
110 | <dd> | |
111 | Insert a horizontal rule in the output. A hard break is inserted if | |
112 | there is data in the current paragraph, but the logical paragraph is | |
113 | not broken. The arguments and keywords are passed on to the writer's | |
114 | <tt class="method">send_line_break()</tt> method. | |
115 | </dl> | |
116 | ||
117 | <P> | |
118 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
119 | <td><nobr><b><tt id='l2h-3796' xml:id='l2h-3796' class="method">add_flowing_data</tt></b>(</nobr></td> | |
120 | <td><var>data</var>)</td></tr></table></dt> | |
121 | <dd> | |
122 | Provide data which should be formatted with collapsed whitespace. | |
123 | Whitespace from preceding and successive calls to | |
124 | <tt class="method">add_flowing_data()</tt> is considered as well when the whitespace | |
125 | collapse is performed. The data which is passed to this method is | |
126 | expected to be word-wrapped by the output device. Note that any | |
127 | word-wrapping still must be performed by the writer object due to the | |
128 | need to rely on device and font information. | |
129 | </dl> | |
130 | ||
131 | <P> | |
132 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
133 | <td><nobr><b><tt id='l2h-3797' xml:id='l2h-3797' class="method">add_literal_data</tt></b>(</nobr></td> | |
134 | <td><var>data</var>)</td></tr></table></dt> | |
135 | <dd> | |
136 | Provide data which should be passed to the writer unchanged. | |
137 | Whitespace, including newline and tab characters, are considered legal | |
138 | in the value of <var>data</var>. | |
139 | </dl> | |
140 | ||
141 | <P> | |
142 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
143 | <td><nobr><b><tt id='l2h-3798' xml:id='l2h-3798' class="method">add_label_data</tt></b>(</nobr></td> | |
144 | <td><var>format, counter</var>)</td></tr></table></dt> | |
145 | <dd> | |
146 | Insert a label which should be placed to the left of the current left | |
147 | margin. This should be used for constructing bulleted or numbered | |
148 | lists. If the <var>format</var> value is a string, it is interpreted as a | |
149 | format specification for <var>counter</var>, which should be an integer. | |
150 | The result of this formatting becomes the value of the label; if | |
151 | <var>format</var> is not a string it is used as the label value directly. | |
152 | The label value is passed as the only argument to the writer's | |
153 | <tt class="method">send_label_data()</tt> method. Interpretation of non-string label | |
154 | values is dependent on the associated writer. | |
155 | ||
156 | <P> | |
157 | Format specifications are strings which, in combination with a counter | |
158 | value, are used to compute label values. Each character in the format | |
159 | string is copied to the label value, with some characters recognized | |
160 | to indicate a transform on the counter value. Specifically, the | |
161 | character "<tt class="character">1</tt>" represents the counter value formatter as an | |
162 | Arabic number, the characters "<tt class="character">A</tt>" and "<tt class="character">a</tt>" | |
163 | represent alphabetic representations of the counter value in upper and | |
164 | lower case, respectively, and "<tt class="character">I</tt>" and "<tt class="character">i</tt>" | |
165 | represent the counter value in Roman numerals, in upper and lower | |
166 | case. Note that the alphabetic and roman transforms require that the | |
167 | counter value be greater than zero. | |
168 | </dl> | |
169 | ||
170 | <P> | |
171 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
172 | <td><nobr><b><tt id='l2h-3799' xml:id='l2h-3799' class="method">flush_softspace</tt></b>(</nobr></td> | |
173 | <td><var></var>)</td></tr></table></dt> | |
174 | <dd> | |
175 | Send any pending whitespace buffered from a previous call to | |
176 | <tt class="method">add_flowing_data()</tt> to the associated writer object. This | |
177 | should be called before any direct manipulation of the writer object. | |
178 | </dl> | |
179 | ||
180 | <P> | |
181 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
182 | <td><nobr><b><tt id='l2h-3800' xml:id='l2h-3800' class="method">push_alignment</tt></b>(</nobr></td> | |
183 | <td><var>align</var>)</td></tr></table></dt> | |
184 | <dd> | |
185 | Push a new alignment setting onto the alignment stack. This may be | |
186 | <tt class="constant">AS_IS</tt> if no change is desired. If the alignment value is | |
187 | changed from the previous setting, the writer's <tt class="method">new_alignment()</tt> | |
188 | method is called with the <var>align</var> value. | |
189 | </dl> | |
190 | ||
191 | <P> | |
192 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
193 | <td><nobr><b><tt id='l2h-3801' xml:id='l2h-3801' class="method">pop_alignment</tt></b>(</nobr></td> | |
194 | <td><var></var>)</td></tr></table></dt> | |
195 | <dd> | |
196 | Restore the previous alignment. | |
197 | </dl> | |
198 | ||
199 | <P> | |
200 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
201 | <td><nobr><b><tt id='l2h-3802' xml:id='l2h-3802' class="method">push_font</tt></b>(</nobr></td> | |
202 | <td><var><code>(</code>size, italic, bold, teletype<code>)</code></var>)</td></tr></table></dt> | |
203 | <dd> | |
204 | Change some or all font properties of the writer object. Properties | |
205 | which are not set to <tt class="constant">AS_IS</tt> are set to the values passed in | |
206 | while others are maintained at their current settings. The writer's | |
207 | <tt class="method">new_font()</tt> method is called with the fully resolved font | |
208 | specification. | |
209 | </dl> | |
210 | ||
211 | <P> | |
212 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
213 | <td><nobr><b><tt id='l2h-3803' xml:id='l2h-3803' class="method">pop_font</tt></b>(</nobr></td> | |
214 | <td><var></var>)</td></tr></table></dt> | |
215 | <dd> | |
216 | Restore the previous font. | |
217 | </dl> | |
218 | ||
219 | <P> | |
220 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
221 | <td><nobr><b><tt id='l2h-3804' xml:id='l2h-3804' class="method">push_margin</tt></b>(</nobr></td> | |
222 | <td><var>margin</var>)</td></tr></table></dt> | |
223 | <dd> | |
224 | Increase the number of left margin indentations by one, associating | |
225 | the logical tag <var>margin</var> with the new indentation. The initial | |
226 | margin level is <code>0</code>. Changed values of the logical tag must be | |
227 | true values; false values other than <tt class="constant">AS_IS</tt> are not | |
228 | sufficient to change the margin. | |
229 | </dl> | |
230 | ||
231 | <P> | |
232 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
233 | <td><nobr><b><tt id='l2h-3805' xml:id='l2h-3805' class="method">pop_margin</tt></b>(</nobr></td> | |
234 | <td><var></var>)</td></tr></table></dt> | |
235 | <dd> | |
236 | Restore the previous margin. | |
237 | </dl> | |
238 | ||
239 | <P> | |
240 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
241 | <td><nobr><b><tt id='l2h-3806' xml:id='l2h-3806' class="method">push_style</tt></b>(</nobr></td> | |
242 | <td><var>*styles</var>)</td></tr></table></dt> | |
243 | <dd> | |
244 | Push any number of arbitrary style specifications. All styles are | |
245 | pushed onto the styles stack in order. A tuple representing the | |
246 | entire stack, including <tt class="constant">AS_IS</tt> values, is passed to the | |
247 | writer's <tt class="method">new_styles()</tt> method. | |
248 | </dl> | |
249 | ||
250 | <P> | |
251 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
252 | <td><nobr><b><tt id='l2h-3807' xml:id='l2h-3807' class="method">pop_style</tt></b>(</nobr></td> | |
253 | <td><var></var><big>[</big><var>n<code> = 1</code></var><big>]</big><var></var>)</td></tr></table></dt> | |
254 | <dd> | |
255 | Pop the last <var>n</var> style specifications passed to | |
256 | <tt class="method">push_style()</tt>. A tuple representing the revised stack, | |
257 | including <tt class="constant">AS_IS</tt> values, is passed to the writer's | |
258 | <tt class="method">new_styles()</tt> method. | |
259 | </dl> | |
260 | ||
261 | <P> | |
262 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
263 | <td><nobr><b><tt id='l2h-3808' xml:id='l2h-3808' class="method">set_spacing</tt></b>(</nobr></td> | |
264 | <td><var>spacing</var>)</td></tr></table></dt> | |
265 | <dd> | |
266 | Set the spacing style for the writer. | |
267 | </dl> | |
268 | ||
269 | <P> | |
270 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
271 | <td><nobr><b><tt id='l2h-3809' xml:id='l2h-3809' class="method">assert_line_data</tt></b>(</nobr></td> | |
272 | <td><var></var><big>[</big><var>flag<code> = 1</code></var><big>]</big><var></var>)</td></tr></table></dt> | |
273 | <dd> | |
274 | Inform the formatter that data has been added to the current paragraph | |
275 | out-of-band. This should be used when the writer has been manipulated | |
276 | directly. The optional <var>flag</var> argument can be set to false if | |
277 | the writer manipulations produced a hard line break at the end of the | |
278 | output. | |
279 | </dl> | |
280 | ||
281 | <P> | |
282 | ||
283 | <DIV CLASS="navigation"> | |
284 | <div class='online-navigation'> | |
285 | <p></p><hr /> | |
286 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
287 | <tr> | |
288 | <td class='online-navigation'><a rel="prev" title="12.1 formatter " | |
289 | href="module-formatter.html"><img src='../icons/previous.png' | |
290 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
291 | <td class='online-navigation'><a rel="parent" title="12.1 formatter " | |
292 | href="module-formatter.html"><img src='../icons/up.png' | |
293 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
294 | <td class='online-navigation'><a rel="next" title="12.1.2 Formatter Implementations" | |
295 | href="formatter-impls.html"><img src='../icons/next.png' | |
296 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
297 | <td align="center" width="100%">Python Library Reference</td> | |
298 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
299 | href="contents.html"><img src='../icons/contents.png' | |
300 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
301 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' | |
302 | border='0' height='32' alt='Module Index' width='32' /></a></td> | |
303 | <td class='online-navigation'><a rel="index" title="Index" | |
304 | href="genindex.html"><img src='../icons/index.png' | |
305 | border='0' height='32' alt='Index' width='32' /></A></td> | |
306 | </tr></table> | |
307 | <div class='online-navigation'> | |
308 | <b class="navlabel">Previous:</b> | |
309 | <a class="sectref" rel="prev" href="module-formatter.html">12.1 formatter </A> | |
310 | <b class="navlabel">Up:</b> | |
311 | <a class="sectref" rel="parent" href="module-formatter.html">12.1 formatter </A> | |
312 | <b class="navlabel">Next:</b> | |
313 | <a class="sectref" rel="next" href="formatter-impls.html">12.1.2 Formatter Implementations</A> | |
314 | </div> | |
315 | </div> | |
316 | <hr /> | |
317 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> | |
318 | </DIV> | |
319 | <!--End of Navigation Panel--> | |
320 | <ADDRESS> | |
321 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. | |
322 | </ADDRESS> | |
323 | </BODY> | |
324 | </HTML> |