The Datafile PD-CD 5/DATAFILE_PDCD5.iso/utilities/p/python/pyhtmldoc/t/the_format

Text File | 1996-11-14 | 7.0 KB | 133 lines

<TITLE>The Formatter Interface -- Python library reference</TITLE>
Next: <A HREF="../f/formatter_implementations" TYPE="Next">Formatter Implementations</A>
Prev: <A HREF="../f/formatter" TYPE="Prev">formatter</A>
Up: <A HREF="../f/formatter" TYPE="Up">formatter</A>
Top: <A HREF="../t/top" TYPE="Top">Top</A>
<H2>10.10.1. The Formatter Interface</H2>
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>AS_IS</B> -- data of module formatter<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.
</DL>
The following attributes are defined for formatter instance objects:
<P>
<DL><DT><B>writer</B> -- data of formatter object data<DD>
The writer instance with which the formatter interacts.
</DL>
<DL><DT><B>end_paragraph</B> (<VAR>blanklines</VAR>) -- Method on formatter object<DD>
Close any open paragraphs and insert at least <CODE>blanklines</CODE>
before the next paragraph.
</DL>
<DL><DT><B>add_line_break</B> () -- Method on formatter object<DD>
Add a hard line break if one does not already exist.  This does not
break the logical paragraph.
</DL>
<DL><DT><B>add_hor_rule</B> (*<VAR>args</VAR>, **<VAR>kw</VAR>) -- Method on formatter object<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
<CODE>send_line_break()</CODE> method.
</DL>
<DL><DT><B>add_flowing_data</B> (<VAR>data</VAR>) -- Method on formatter object<DD>
Provide data which should be formatted with collapsed whitespaces.
Whitespace from preceeding and successive calls to
<CODE>add_flowing_data()</CODE> 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>
<DL><DT><B>add_literal_data</B> (<VAR>data</VAR>) -- Method on formatter object<DD>
Provide data which should be passed to the writer unchanged.
Whitespace, including newline and tab characters, are considered legal
in the value of <CODE>data</CODE>.
</DL>
<DL><DT><B>add_label_data</B> (<VAR>format</VAR>, <VAR>counter</VAR>) -- Method on formatter object<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 <CODE>format</CODE> value is a string, it is interpreted as a
format specification for <CODE>counter</CODE>, which should be an integer.
The result of this formatting becomes the value of the label; if
<CODE>format</CODE> 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
<CODE>send_label_data()</CODE> 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 ``<CODE>1</CODE>'' represents the counter value formatter as an
arabic number, the characters ``<CODE>A</CODE>'' and ``<CODE>a</CODE>'' represent
alphabetic representations of the counter value in upper and lower
case, respectively, and ``<CODE>I</CODE>'' and ``<CODE>i</CODE>'' 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>
<DL><DT><B>flush_softspace</B> () -- Method on formatter object<DD>
Send any pending whitespace buffered from a previous call to
<CODE>add_flowing_data()</CODE> to the associated writer object.  This
should be called before any direct manipulation of the writer object.
</DL>
<DL><DT><B>push_alignment</B> (<VAR>align</VAR>) -- Method on formatter object<DD>
Push a new alignment setting onto the alignment stack.  This may be
<CODE>AS_IS</CODE> if no change is desired.  If the alignment value is
changed from the previous setting, the writer's <CODE>new_alignment()</CODE>
method is called with the <CODE>align</CODE> value.
</DL>
<DL><DT><B>pop_alignment</B> () -- Method on formatter object<DD>
Restore the previous alignment.
</DL>
<DL><DT><B>push_font</B> ((<VAR>size</VAR>, <VAR>italic</VAR>, <VAR>bold</VAR>, <VAR>teletype</VAR>)) -- Method on formatter object<DD>
Change some or all font properties of the writer object.  Properties
which are not set to <CODE>AS_IS</CODE> are set to the values passed in
while others are maintained at their current settings.  The writer's
<CODE>new_font()</CODE> method is called with the fully resolved font
specification.
</DL>
<DL><DT><B>pop_font</B> () -- Method on formatter object<DD>
Restore the previous font.
</DL>
<DL><DT><B>push_margin</B> (<VAR>margin</VAR>) -- Method on formatter object<DD>
Increase the number of left margin indentations by one, associating
the logical tag <CODE>margin</CODE> 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 <CODE>AS_IS</CODE> are not sufficient
to change the margin.
</DL>
<DL><DT><B>pop_margin</B> () -- Method on formatter object<DD>
Restore the previous margin.
</DL>
<DL><DT><B>push_style</B> (*<VAR>styles</VAR>) -- Method on formatter object<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 <CODE>AS_IS</CODE> values, is passed to the writer's
<CODE>new_styles()</CODE> method.
</DL>
<DL><DT><B>pop_style</B> ([<VAR>n</VAR>@varcode = 1]) -- Method on formatter object<DD>
Pop the last <CODE>n</CODE> style specifications passed to
<CODE>push_style()</CODE>.  A tuple representing the revised stack,
including <CODE>AS_IS</CODE> values, is passed to the writer's
<CODE>new_styles()</CODE> method.
</DL>
<DL><DT><B>set_spacing</B> (<VAR>spacing</VAR>) -- Method on formatter object<DD>
Set the spacing style for the writer.
</DL>
<DL><DT><B>assert_line_data</B> ([<VAR>flag</VAR>@varcode = 1]) -- Method on formatter object<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 <CODE>flag</CODE> argument can be set to false if
the writer manipulations produced a hard line break at the end of the
output.
</DL>