sam-t2/devtools/v9/html/python/lib/formatter-interface.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="lib.html" title='Python Library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="formatter-impls.html" />
<link rel="prev" href="module-formatter.html" />
<link rel="parent" href="module-formatter.html" />
<link rel="next" href="formatter-impls.html" />
<meta name='aesop' content='information' />
<title>12.1.1 The Formatter Interface </title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="12.1 formatter  "
  href="module-formatter.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="12.1 formatter  "
  href="module-formatter.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="12.1.2 Formatter Implementations"
  href="formatter-impls.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-formatter.html">12.1 formatter  </A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-formatter.html">12.1 formatter  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="formatter-impls.html">12.1.2 Formatter Implementations</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION0014110000000000000000"></A><A NAME="formatter-interface"></A>
<BR>
12.1.1 The Formatter Interface
</H2>

<P>
Interfaces to create formatters are dependent on the specific
formatter class being instantiated.  The interfaces described below
are the required interfaces which all formatters must support once
initialized.

<P>
One data element is defined at the module level:

<P>
<dl><dt><b><tt id='l2h-3791' xml:id='l2h-3791'>AS_IS</tt></b></dt>
<dd>
Value which can be used in the font specification passed to the
<code>push_font()</code> method described below, or as the new value to any
other <code>push_<var>property</var>()</code> method.  Pushing the <code>AS_IS</code>
value allows the corresponding <code>pop_<var>property</var>()</code> method to
be called without having to track whether the property was changed.
</dd></dl>

<P>
The following attributes are defined for formatter instance objects:

<P>
<dl><dt><b><tt id='l2h-3792' xml:id='l2h-3792' class="member">writer</tt></b></dt>
<dd>
The writer instance with which the formatter interacts.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3793' xml:id='l2h-3793' class="method">end_paragraph</tt></b>(</nobr></td>
  <td><var>blanklines</var>)</td></tr></table></dt>
<dd>
Close any open paragraphs and insert at least <var>blanklines</var>
before the next paragraph.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3794' xml:id='l2h-3794' class="method">add_line_break</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Add a hard line break if one does not already exist.  This does not
break the logical paragraph.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3795' xml:id='l2h-3795' class="method">add_hor_rule</tt></b>(</nobr></td>
  <td><var>*args, **kw</var>)</td></tr></table></dt>
<dd>
Insert a horizontal rule in the output.  A hard break is inserted if
there is data in the current paragraph, but the logical paragraph is
not broken.  The arguments and keywords are passed on to the writer's
<tt class="method">send_line_break()</tt> method.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3796' xml:id='l2h-3796' class="method">add_flowing_data</tt></b>(</nobr></td>
  <td><var>data</var>)</td></tr></table></dt>
<dd>
Provide data which should be formatted with collapsed whitespace.
Whitespace from preceding and successive calls to
<tt class="method">add_flowing_data()</tt> is considered as well when the whitespace
collapse is performed.  The data which is passed to this method is
expected to be word-wrapped by the output device.  Note that any
word-wrapping still must be performed by the writer object due to the
need to rely on device and font information.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3797' xml:id='l2h-3797' class="method">add_literal_data</tt></b>(</nobr></td>
  <td><var>data</var>)</td></tr></table></dt>
<dd>
Provide data which should be passed to the writer unchanged.
Whitespace, including newline and tab characters, are considered legal
in the value of <var>data</var>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3798' xml:id='l2h-3798' class="method">add_label_data</tt></b>(</nobr></td>
  <td><var>format, counter</var>)</td></tr></table></dt>
<dd>
Insert a label which should be placed to the left of the current left
margin.  This should be used for constructing bulleted or numbered
lists.  If the <var>format</var> value is a string, it is interpreted as a
format specification for <var>counter</var>, which should be an integer.
The result of this formatting becomes the value of the label; if
<var>format</var> is not a string it is used as the label value directly.
The label value is passed as the only argument to the writer's
<tt class="method">send_label_data()</tt> method.  Interpretation of non-string label
values is dependent on the associated writer.

<P>
Format specifications are strings which, in combination with a counter
value, are used to compute label values.  Each character in the format
string is copied to the label value, with some characters recognized
to indicate a transform on the counter value.  Specifically, the
character "<tt class="character">1</tt>" represents the counter value formatter as an
Arabic number, the characters "<tt class="character">A</tt>" and "<tt class="character">a</tt>"
represent alphabetic representations of the counter value in upper and
lower case, respectively, and "<tt class="character">I</tt>" and "<tt class="character">i</tt>"
represent the counter value in Roman numerals, in upper and lower
case.  Note that the alphabetic and roman transforms require that the
counter value be greater than zero.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3799' xml:id='l2h-3799' class="method">flush_softspace</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Send any pending whitespace buffered from a previous call to
<tt class="method">add_flowing_data()</tt> to the associated writer object.  This
should be called before any direct manipulation of the writer object.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3800' xml:id='l2h-3800' class="method">push_alignment</tt></b>(</nobr></td>
  <td><var>align</var>)</td></tr></table></dt>
<dd>
Push a new alignment setting onto the alignment stack.  This may be
<tt class="constant">AS_IS</tt> if no change is desired.  If the alignment value is
changed from the previous setting, the writer's <tt class="method">new_alignment()</tt>
method is called with the <var>align</var> value.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3801' xml:id='l2h-3801' class="method">pop_alignment</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Restore the previous alignment.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3802' xml:id='l2h-3802' class="method">push_font</tt></b>(</nobr></td>
  <td><var><code>(</code>size, italic, bold, teletype<code>)</code></var>)</td></tr></table></dt>
<dd>
Change some or all font properties of the writer object.  Properties
which are not set to <tt class="constant">AS_IS</tt> are set to the values passed in
while others are maintained at their current settings.  The writer's
<tt class="method">new_font()</tt> method is called with the fully resolved font
specification.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3803' xml:id='l2h-3803' class="method">pop_font</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Restore the previous font.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3804' xml:id='l2h-3804' class="method">push_margin</tt></b>(</nobr></td>
  <td><var>margin</var>)</td></tr></table></dt>
<dd>
Increase the number of left margin indentations by one, associating
the logical tag <var>margin</var> with the new indentation.  The initial
margin level is <code>0</code>.  Changed values of the logical tag must be
true values; false values other than <tt class="constant">AS_IS</tt> are not
sufficient to change the margin.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3805' xml:id='l2h-3805' class="method">pop_margin</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Restore the previous margin.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3806' xml:id='l2h-3806' class="method">push_style</tt></b>(</nobr></td>
  <td><var>*styles</var>)</td></tr></table></dt>
<dd>
Push any number of arbitrary style specifications.  All styles are
pushed onto the styles stack in order.  A tuple representing the
entire stack, including <tt class="constant">AS_IS</tt> values, is passed to the
writer's <tt class="method">new_styles()</tt> method.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3807' xml:id='l2h-3807' class="method">pop_style</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>n<code> = 1</code></var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Pop the last <var>n</var> style specifications passed to
<tt class="method">push_style()</tt>.  A tuple representing the revised stack,
including <tt class="constant">AS_IS</tt> values, is passed to the writer's
<tt class="method">new_styles()</tt> method.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3808' xml:id='l2h-3808' class="method">set_spacing</tt></b>(</nobr></td>
  <td><var>spacing</var>)</td></tr></table></dt>
<dd>
Set the spacing style for the writer.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3809' xml:id='l2h-3809' class="method">assert_line_data</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>flag<code> = 1</code></var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Inform the formatter that data has been added to the current paragraph
out-of-band.  This should be used when the writer has been manipulated
directly.  The optional <var>flag</var> argument can be set to false if
the writer manipulations produced a hard line break at the end of the
output.
</dl>

<P>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="12.1 formatter  "
  href="module-formatter.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="12.1 formatter  "
  href="module-formatter.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="12.1.2 Formatter Implementations"
  href="formatter-impls.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-formatter.html">12.1 formatter  </A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-formatter.html">12.1 formatter  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="formatter-impls.html">12.1.2 Formatter Implementations</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>