Version 1.4 Reference Manual
By Chris Koeritz (koeritz@gruntose.com)
(Part of the HOOPLE Library)
1: Introduction
This document describes the WOOF windowing system (an acronym for
Windows for Object Oriented Freaks). This system is a set of C++
components that attempt to provide a friendly interface layer for
building programs based on a windowing system interface. WOOF hides
many details of interacting with the underlying windowing system. The
intent is to allow the user to think in terms of high level constructs,
rather than in particular implementation details. WOOF also permits
programs to be ported to different windowing systems without requiring
major changes in the programs based on it.
WOOF is designed to allow flexibility as well; details of the
underlying interface can still be accessed when necessary. Thus it is
still possible to use functionality specific to one particular
windowing system, although the cost of this is that the programs is
less (or not) portable.
2: Passive Window Parts
The passive window parts do not require that the user provide any
function for responding to windowing system events. Either the passive
part will provide that functionality itself in such a way that the user
does not need to know about it, or the part will not be affected by
system events.
The passive parts that are currently supported are depicted below in
the relationship diagram. Each arrow represents either the "builds on"
relationship or the "derives from" relationship.
2.1: System Level Objects
These objects are used within WOOF for low-level interaction with the
windowing system. They are generally never a concern to the WOOF user,
and in fact should be avoided since they are in some cases dependent on
a particular window system. However, they are accessible for the
situations when an underlying system action is desired and it is not
supported directly by the WOOF system.
2.1.1: argument_list
The argument_list is a fairly straightforward object that contains a
list of X windows arguments. An X windows argument is a 2-tuple
containing a string for the argument name and a value for the argument.
These arguments are passed to certain X windows functions to control
aspects of the appearance or behavior of certain X windows objects.
Having said that, it may help to point out that the argument_list is
only a concern when the programmer wishes to directly interact with X
windows function calls.
The standard method of passing the X windows arguments is quite
disgusting (using a fixed size array and incrementing a counter as
arguments are added), and the argument_string just provides a cleaner
(albeit dynamically allocated) method of storing arguments and passing
them to X.
2.1.2: low_level
The low_level group is a set of aliases for the names of data types
that are defined by most window systems. This collection allows the
objects in WOOF to adopt a unified naming scheme for the system objects
that it manipulates.
2.1.3: nub
The nub provides a system independent method for managing the unique
identifier for certain kinds of system objects. It encapsulates the
underlying window system's addressing scheme for these objects. For
example, in X windows the nub is hiding a widget ID and other
characteristics of the widget. In other systems, the nub will
encapsulate different details of the windowing system.
2.1.4: resources
The resources object contains system dependent information that governs
various aspects of the appearance or behavior of objects when they are
placed on the screen.
2.1.5: system_string
The system_string provides a wrapper around the X windows string
format, which is a potentially error prone data structure. The
system_string provides conversion functions between a variety of
strings, including regular C/C++ character strings and various forms of
the underlying windows format.
2.2: Basic Objects
These objects are widely used within the WOOF system and programs based
on it. In general, they represent abstract concepts that are found
within (or can be simulated within) most underlying window systems.
2.2.1: color
The color object represents the capability to shade pixels on the
screen in a visible color. It has internal characteristics that depend
on the underlying window system, but the abstract interface permits
colors to be constructed from red, green and blue values. A color
object is not valid for use on the screen until it has been added to
the window's pallette object.
2.2.2: desktop
The desktop class translates between the physical device coordinates
and your chosen coordinate system for the screen. The figure below
depicts the device coordinates (the outer scale ranging from 0 to 640
in the x direction and 0 to 480 in the y direction) as having an origin
at the upper left.
This is the situation in Microsoft Windows and X windows. The desktop
class provides a way to reconfigure the location of the origin and the
scale used to measure the screen. The user-chosen coordinate system is
called the view coordinate system. The figure shows how the user might
want to have view coordinates with an origin in the lower left corner
of the display. It also shows how the hardware scale is being mapped
onto a range of 0 to 100 on the y axis and 0 to 180 on the x axis.
All objects that have an extent measured in desktop coordinates (such
as the manager) will be located according to the chosen view coordinate
system. This allows the user to construct a program with a personalized
screen scale that will not have to be modified when the program is
ported to a different screen size. Instead, the available device
coordinates are scaled to the chosen measurements.
2.2.3: dimensionable
The dimensionable class models all screen objects that can be bounded
by a rectangle. The objects derived from dimensionable must provide the
function that returns this rectangle.
2.2.4: drawable
A drawable object is a pure virtual class based on the dimensionable
object, meaning that every object derived from drawable must be able to
return a rectangle that bounds its own extent. Drawable objects also
must provide draw and erase functions that cause the drawable to appear
and disappear from the screen. The mechanism involved in doing that
depends utterly on the characteristics of the actual object derived
from drawable.
2.3: manager
The manager is the main object that must be instantiated before the
rest of the WOOF windowing system can be used. It manages the many
details involved in interfacing with the windowing system to create a
basic window and allocate the necessary system resources.
The manager also serves as a container for the graphical objects
created by the user. The objects attached to a manager are called
workers. Like the desktop, the manager provides a configurable frame of
reference within which workers can be placed, as depicted in the figure
below.
This is called the universal coordinate system, where the universe is
limited to the realm of that particular manager. The universal system
exists inside the manager, while the manager's size is measured in the
desktop's view coordinates.
2.3.1: pallette
A pallette object contains a list of the colors that can currently be
displayed. The pallette does not affect the entire screen; it is a
characteristic that is local to the window to which the pallette is
attached. Some windows use the system's default colormap for the
pallette, while others define their own colors dynamically by adding
them to the pallette.
2.4: The drawable objects
Many objects are drawable within the WOOF system. The two main
hierarchies of worker objects and paintable objects are both derived
from the drawable class. These will be documented separately.
2.4.1: picture
The picture class is a drawable collection. The picture is itself a
drawable and it can also contain a list of drawable objects. All of the
drawables contained in the picture can be drawn or erased as a group,
and the entire collection can be relocated while maintaining the
relative placements of the objects with each other.
2.5: The worker objects
Workers can be placed on a manager. The worker is derived from both the
drawable and the nub objects.
2.5.1: canvas
A canvas is an example of a worker object. It is placed on a manager
using the universal coordinates. The canvas provides another nested
frame of reference to the objects that are placed on it, as depicted in
the figure.
This frame of reference is called the world coordinate system, because
many different worlds can be placed in the same manager's universe.
Objects that can be drawn on canvasses are called paintable objects.
They define a virtual function called "plot" that is responsible for
interacting with the canvas to draw the object on it.
2.5.2: label
The label object provides a method for placing strips of text on a
manager.
2.6: The Paintable Objects
The paintable objects are those that can be drawn upon a canvas. The
paintable class is derived from both the drawable class and the
resources class.
2.6.1: box
A box is the visible version of a rectangle. Boxes can be filled or
non-filled.
2.6.2: dot
A dot is a visible point. A dot's bounding rectangle has its position
as both vertices.
2.6.3: oval
The oval allows ellipses to be drawn on the screen. Ovals can be filled
or non-filled.
2.6.4: ring
The ring is a visible circle. Rings may not appear circular if the
canvas's dimensions are not uniformly scaled to the screen coordinates.
Rings can be filled or non-filled.
2.6.5: visible_line
The visible_line allows line segments to be drawn on the screen.
3: Active Window Parts
The active parts are generally expected to respond to user input events
and to process the input in an application specific manner. These
window parts have event functions associated with them. An event
function is invoked by the window system when a particular event
occurs, such as a button being selected with the mouse. The programmer
must provide an event function for the active part in order to cause
the appropriate action when the event occurs.
As the figure below depicts, all of the current active parts are
implemented as worker objects, allowing them to be attached to a
manager object.
3.1: aimer
An aimer is a component that allows the user to input two values
simultaneously by clicking the mouse at a particular place on the
aimer. These two values are processed by the event function of the
aimer. This part is currently unimplemented.
3.2: button
A button is a component that can trigger an action when the user
selects it. The appearance is a rectangular raised button on the screen
with a label describing the button's action.
3.3: dialog
A dialog box allows the user to pass numeric or alphabetic data to the
program by typing into different fields in the box. This part is
currently unimplemented.
3.4: menu
The menu object encapsulates the window system's pull-down menu
functions. Each item in the menu is a separate object that performs
some action when its corresponding visible form is selected by the
user.
3.5: message_box
A message_box is a popup window that asks the user a question and
offers them from one to three choices. There are multiple formats for
the message_box that changes its appearance and the number of choices
offered to the user.
3.6: quit_button
The quit_button is a specialized type of button that offers the user
the choice of leaving the program or not. If the user selects the exit
choice, then the windowing system shuts down and control is returned to
the point of invocation of the manager's polling function. The main
program is usually implemented to exit once control is returned to it.
3.7: radio_box
The radio_box is a component that contains multiple selectable entries,
of which exactly one may be selected at a time. Each entry in the
radio_box is a text label next to a small box that has two different
appearances, selected and unselected. The radio_box allows the
programmer to offer the user the choice of one item in a set of
mutually exclusive choices. This part is currently unimplemented.
3.8: slider
The slider is a control that allows the user to pass a value to the
program that is based on the position of a small bar on the slider's
visible form. The bar's position must reside in the range defined for
the slider. This part is not perfect yet.
3.9: thermometer
A thermometer shows the progress of a particular action by
progressively filling itself in as the process is carried out. This
part is not perfect yet.
