The Viewer Object Interface in Grail

Introduction

A Viewer object is an instance of the Viewer class, defined in the Viewer module. A Viewer can display formatted text using a variety of fonts and styles. This is accomplished mostly through the power of the Tk text widget, but a Viewer has a particular interface that better matches the requirements of formatted HTML display.

The Viewer interface is used by two types of extensions: HTML extensions and file type extensions. Both have roughly the same needs (displaying the output of a parser), so this interface description applies to both cases. It is important that the Viewer interface is only used while a parser is active; once the parser has been closed, the viewer should not be touched.

Viewer Instance Variables

A Viewer object has two data attributes that are relevant to parsers:

viewer.text: The Tk text widget that contains the actual text. This should only be used to provide a parent for subwidgets that will be passed to the add_subwindow() method.
viewer.browser: The Browser object containing the viewer, if any. This variable may be set to None. See the Browser Object Interface.

Viewer Methods

A Viewer object has several methods that are relevant to parsers. These all either insert data, which may be a text string or a subwindow, into the text stream, or change settings that affect the way subsequent elements are formatted.

viewer.new_font((fonttag, italic, bold, tt))

Specify a new font. The fontag argument is either the empty string or a header tag in lowercase, i.e.. 'h1', 'h2', ..., 'h6'. The italic, bold and tt arguments are boolean flags specifying whether the font should be modified to be italic, bold and/or teletype (fixed width).

viewer.new_margin(margin, level)

Specify a new left indentation margin. The margin argument is the tag name in lowercase that caused the call (e.g. 'blockquote', 'ul', 'ol' etc.), and level is the accumulated nesting level (an integer). The first level is 1.

viewer.new_spacing(spacing)

Specify a new vertical spacing style. Currently not used.

viewer.new_styles(style_tuple)

Specify a new character style. The argument is a tuple of styles that should be accumulated; each style is tag whose meaning is defined by the viewer's style sheet.

viewer.send_paragraph(blankline)

End a paragraph. If blankline is nonzero, a blank line is inserted after the paragraph.

viewer.send_line_break()

Insert a hard line break which does not represent a paragraph break.

viewer.send_hor_rule()

Insert a horizontal rule. This terminates the current paragraph without inserting a blank line. Four keyword arguments are provided:

abswidth: Specifies an absolute width for the rule in pixels. The rule will maintain a width which is no larger than the number specified here. If the viewer is resized, the rule may take a width narrower than this width to fit within the displayed document.
percentwidth: Specifies a width as a percentage of the available horizontal width. This is used only is abswidth is not specified.
height: Specifies the height of the rule in pixels. A minimum value of 1 will be enforced.
align: Specifies horizontal alignment of the rule. The value may be 'left', 'center', or 'right'. If this argument is omitted, the rule is left aligned.

viewer.send_label_data(data)

Insert a string to be displayed as the ``label'' for a labeled paragraph (usually generated by a <LI> tag). This should be done at the start of a paragraph only.

viewer.send_flowing_data(data)

Insert a string to be displayed as normal, word-wrapped text.

viewer.send_literal_data(data)

Insert a string to be displayed as non-wordwrapped text.

viewer.add_subwindow(widget)

Insert a widget in the stream. The widget should have been created with the viewer.text widget as its parent.