The appobjects module

Release: 16/10/2001

Introduction

The appobjects module is a collection of objects which can be placed in windows to allow an application to display various forms of information and accept user input. As this library is a work in progress, many of these objects work as advertised, but some do not. This document should cover those that work, giving an idea of what they do and how to use them.

The objects

The objects are listed in the order in which they appear in the appobjects.py file.

Background

Purpose:

To provide a window background for windows which do not have one or wish to cover it up.

To create:

object = appobjects.Background(<x1>, <y1>, <x2>, <y2>, <colour>)

<colour> can be a desktop colour (0 to 15) or a tuple containing red, green and blue colour components, having values from 0 to 255.

Status: Works.

Square

Purpose:

A filled colour rectangle.

To create:

object = appobjects.Square(<x1>, <y1>, <x2>, <y2>, <colour>)

<colour> can be a desktop colour (0 to 15) or a tuple containing red, green and blue colour components having values from 0 to 255.

Status: Works.

Box

Purpose:

An outline colour rectangle.

To create:

object = appobjects.Box(<x1>, <y1>, <x2>, <y2>, <colour>)

<colour> can be a desktop colour (0 to 15) or a tuple containing red, green and blue colour components having values from 0 to 255.

Status: Works.

Text

Purpose:

Display coloured text in an outline font.

To create:

object = appobjects.Text(<x1>, <y1>, <x2>, <y2>)

Methods:

set_baseline(<y>)
Sets the vertical position of the imaginary line on which the text is written to the value given.
set_font(<font>)
Sets the font used to display the text.
set_foreground(<colour>)
Sets the foreground colour used to display the text.
set_background(<colour>)
Sets the background colour used to display the text.

Status: Works.

TextButton

Purpose:

Display coloured text in an outline font with a border.

To create:

object = appobjects.TextButton(<x1>, <y1>, <x2>, <y2>)

Methods:

set_border(<y>)
Sets the distance in work area units between the border and the text.
set_font(<font>)
Sets the font used to display the text.
set_foreground(<colour>)
Sets the foreground colour used to display the text.
set_background(<colour>)
Sets the background colour used to display the text.

Status: Works.

TextLine

Purpose:

Display coloured text in an outline font. Used for long text strings.

To create:

object = appobjects.TextLine(<x1>, <y1>, <x2>, <y2>)

Methods: As for Text.

Status: Works.

TextClickLine

Purpose:

Display coloured text in an outline font which allows actions to be associated with mouse clicks. Used for long text strings.

To create:

object = appobjects.TextClickLine(<x1>, <y1>, <x2>, <y2>)

Methods: As for TextLine with standard Object mouse click behaviour.

Status: Works.

TextClickMenu

Status: Unused and untested.

TextBox

Status: Unused and untested.

GeneralKeyHandler

Purpose:

Listen for key events and act on them.

To create:

object = appobjects.GeneralKeyHandler(<x1>, <y1>, <x2>, <y2>)

Methods: Standard Object key press behaviour. Note that key press events are not passed to internal objects.

Status: Works.

Picture

Purpose:

Display a sprite.

To create:

object = appobjects.Picture(<x1>, <y1>, <x2>, <y2>, <sprite area>, <name>)

<sprite area> is an instance of the app module's Sprite class; <name> is a name of a sprite in the sprite area specified.

Status: Works.

ClickPicture

Purpose:

Display a sprite which can associate actions with mouse clicks.

To create:

object = appobjects.ClickPicture(<x1>, <y1>, <x2>, <y2>, <sprite area>, <name>)

Methods: As for Picture with standard Object mouse click behaviour. Note that mouse click events are not passed to internal objects.

Status: Works.

Option

Purpose:

Display a standard option icon.

To create:

object = appobjects.Option(<x1>, <y1>, <x2>, <y2>, <text>)

<text> is the option text.

Status: Works.

Radio

Purpose:

Display a standard radio icon.

To create:

object = appobjects.Radio(<x1>, <y1>, <x2>, <y2>, <text>)

<text> is the option text.

Status: Works.

TextWrite

Purpose:

Display a line of plain text which can be edited by the user.

To create:

object = appobjects.TextWrite(<x1>, <y1>, <x2>, <y2>)

Methods: As for Text except that the click and key methods have been replaced for the purpose of text entry.

Status: Works.

TextArea

Purpose:

Display a paragraph of plain text which can be edited by the user.

To create:

object = appobjects.TextArea(<x1>, <y1>, <x2>, <y2>)

Methods: As for TextWrite.

Status: Works, but not thoroughly tested.

NewsTextArea

Purpose:

Display a paragraph of plain text which can be edited by the user. Lines beginning with a number of quotation symbols are coloured according to the level of quoting they represent.

To create:

object = appobjects.NewsTextArea(<x1>, <y1>, <x2>, <y2>, <font>, <line spacing>, <quoting>, <quote character>)

<font> is a Font object from the app module; <line spacing> is the vertical distance between lines of text measured in work area units; <quoting> is a list or tuple containing colours to use for each level of quoting, beginning with unquoted text; <quote character> is the character which determines whether a given line of text is quoted.

Methods: As for TextArea.

Status: Works, but not thoroughly tested.

SaveWindow

Status: Unused and untested.


David Boddie
david@boddie.org.uk