\chapter{Class summary descriptions}		\label{sec:summary}

This appendix provides a complete overview of all built-in classes of
\product{}. For each class, it presents the name, arguments needed to create
an instance, place in the inheritance and delegation hierarchies as well
as a summary description. For many classes we added a small illustrative
example of typical usage of the class.

The summaries stress on describing what the class is commonly used for
and what other classes are designed to cooperate with the class.

The classes are presented in alphabetical order.  Some classes that
are closely related and have symbol-names (\verb$>, +$) are combined
into one description, sometimes violating the alphabetical order.

\begin{description}
#class := "name := value" binding
Instances of this class are used to specify named arguments, see
\secref{namedargs}.  Example:
\begin{code}
...,
send(Editor, style,
     sensitive, style(underline := @on,
		      colour := dark_green)),
...,
\end{code}

#class  == "any|function  == any|function" equal
#class \== "any|function \== any|function" notequal
Conditional code object that succeeds if both arguments evaluate to the
same object. Normally used to specify the conditions of \class{if} or
\class{while}. The following example yields the names of all
user-defined classes:
\begin{code}
?- new(UDC, chain),
   send(@classes, for_all,
	if(@arg2?creator \== built_in,
	   message(UDC, append, @arg1))).
\end{code}

#class ? "?(object, name, any ...)" obtainer
Class \class{?}, pronounced as `obtainer', represents a `dormant'
get-operation.  Obtainers are commonly used to `obtain' arguments for
other code objects.  For example:
\begin{code}
...,
send(Dialog, append,
     new(TI, text_item(name))),
send(Dialog, append,
     button(ok, message(Dialog, return, TI?selection))),
\end{code}

#class @= "name @= object" assoc
Class \class{@=} assigns a symbolic reference name to the argument
object. It is used to define global objects in the class-variable
display.initialise. See the system defaults file
\metafile{<pcehome>/Defaults}. The following example from \file{Defaults}
creates the objects @_dialog_bg and @_win_pen depending on whether or
not the display is monochrome or colour.
\begin{code}
display.initialise: \
	and(_dialog_bg @= when(@colour_display, \
			       grey80, white), \
	    _win_pen   @= when(@colour_display, \
			       0, 1))
\end{code}

#class and "and(statement ...)"
Code object that executes its arguments one by one.  It fails as soon as
one of the arguments fails and succeeds otherwise.  Commonly used to
specify multiple actions for controllers.  For example:
\begin{code}
...,
get(Dialog, frame, Frame),
send(Dialog, append,
     new(Function, text_item(function))),
send(Dialog, append,
     button(switch_to,
	    and(message(Frame, switch_to,
			Function?selection),
		message(Function, clear)))),
...,
\end{code}

#class application "application(name)"
An application object is a \class{visual} object used to combine
multiple \classs{frame}.  See \secref{application} for a discussion
on its usage.

#class arc "arc(radius, start_angle, size_angle)"
Graphical primitive describing a section from a circle.  It may be
used to create a \idx{pie-chart} segment.
\begin{code}
?- new(A, arc(100, 20, 50)),
   send(A, close, pie_slice).
\end{code}

#class area "area(x, y, width, height)"
Combination of {\em X}, {\em Y}, {\em Width} and {\em Height} used by
\class{graphical} to store the bounding box of the graphical. Also used
to communicate with graphical objects and frames about their dimension.
\begin{code}
...,
get(Box, area, area(X, Y, W, H)),
...,
\end{code}

#class arrow "arrow(length, wing)"
Arrow-head. Normally only used implicitly to attach arrows to a
\class{line}, \class{arc} or \class{path}, the subclasses of class
\class{joint}. See `joint ->arrows'. \class{arrow} can be used directory
to create fancy arrows.

\begin{code}
?- new(L, line(0, 0, 100, 50, second))
\end{code}

#class assign "assign(var, value, scope)"
Assign a value to an instance of class \class{var}, an \product{} variable.
Used to realise variables in compound executable objects.
\begin{code}
and(assign(new(C, var), @arg1?controller),
    message(C, ...),
    message(C, ...),
    ...)
\end{code}

#class attribute "attribute(name, value)"
Attributes can be associated with any object to store data related
to that object without the need to create a subclass. Normally
attribute objects are used implicitly through the method
`object <->attribute'.
\begin{code}
send(Frame, attribute, visualises, bicycle24)
\end{code}

#class behaviour "behaviour(name, context)"
Super class of \class{method} and \class{variable}, representing the
two types of objects that can realise behaviour in classes.  Not useful
for the application programmer.

#class bezier_curve "bezier_curve(start, end, control1, control2)"
Create a Bezier curve from \arg{start} to \arg{end} using one or two
control-points (quadradic or cubic Bezier curve).  Bezier curves are
nice smooth curves departing and arriving in a specified direction.
See also \class{path}.

#class binary_condition "binary_condition(left, right)"
#class <  "expression  < expression" lt
#class =  "expression  = expression" eq
#class =< "expression =< expression" le
#class >  "expression  > expression" gt
#class >= "expression >= expression" ge
Arithmetic conditional code objects.  These objects are normally used to
specify the conditions of \class{if} or \class{while}.  The following
example creates a \class{chain} holding all graphicals on a device that
either have <-width $<$ 5 or <-height $<$ 5.
\begin{code}
...,
get(Device?graphicals, find_all,
    or(@arg1?width < 5,
       @arg1?height < 5),
    SmallGraphicals),
...,
\end{code}

#class binary_expression "binary_expression(left, right)"
#class * "expression * expression" mul
#class + "expression + expression" plus
#class - "[expression] - expression" minus
#class / "expression / expression" divide
Arithmetic functions, commonly used for computation of graphical
dimensions or to specify spatial relations using class \class{spatial}
or for simple functional computation from Prolog.  For example:
\begin{code}
...
send(Box, height, Text?height + 10),
...
\end{code}

#class bitmap "bitmap(image)"
A bitmap turns an \class{image} or \class{pixmap} into a graphical
object that can be displayed on a \class{device}.
\begin{code}
?- new(I, image('pce.bm')),
   new(B, bitmap(I)).
\end{code}

#class block "block(var ..., statement ...)"
A \class{block} is similar to \class{and}, but provides formal
parameters.
\begin{code}
?- send(block(new(A, var),
	      new(B, var),
	      message(@pce, write_ln, A, B)),
	forward, hello, world).

hello world
\end{code}

#class bool "bool(self)"
Class \class{bool} defines two instances: @on and @off, representing
`true' and `false'.  The use cannot create instances of this class.
\begin{code}
...,
send(Image, transparent, @on)
...
\end{code}

#class box "box(width, height)"
Graphical representing a rectangle. Corners can be rounded, the interior
can be filled, the texture and thickness of the line can be controlled
and a shadow can be defined.
\begin{code}
?- new(B, box(100, 50)),
   send(B, radius, 10).
\end{code}

#class browser "browser(label)"
A \class{browser} is a window version of a \class{list_browser}. A
browser visualises a list of \class{dict_item} objects.  The items
are organised in a \class{dict}, providing fast access to browser
items, even if there are many items in the browser.  Individual items
may be coloured, underlined, etc.\ using the \class{style} mechanism
also available for \class{editor}.  Columns can be realised using
tab_stops on the \class{text_image} object that displays the actual
text of the browser.
\begin{code}
?- new(B, browser),
   send_list(B, append, [gnu, gnat]).
\end{code}

#class browser_select_gesture "browser_select_gesture()"
Internal class dealing with selection handling in class
\class{list_browser}.

#class button "button(label, message, accelerator)"
A button is a push-button controller. It has an associated
\class{message} that is executed if the button is activated using the
mouse.  Inside a \class{dialog}, one button can be assigned as `default'
button.
\begin{code}
?- new(B, button(hello,
		 message(@pce, write_ln, hello))).
\end{code}

#class c "c(system)"
Class \class{c} is a subclass of class \class{host}, providing
communication to C and C++ code. It is not used directly by the
application programmer.

#class c_pointer "c_pointer(print_name)"
Class \class{c_pointer} encapsulates an anonymous C pointer ({\tt void
*}).  It is used to register references to Prolog predicates with \product{}
methods.  See also \chapref{udc}.
\begin{code}
?- pce_predicate_reference(gnat:gnu(_,_), X).
X = @1190997/c_pointer
\end{code}

#class chain "chain(any...)"
Class \class{chain} represents a single-linked list of arbitrary
objects.  Chains are commonly used inside \product{} to represent collections.
Chains have methods to find elements, sort the chain, delete elements,
etc. The predicate chain_list/2 converts between an \product{} chain and a
Prolog list. It also provides methods to run code on all elements of the
list, which is generally faster than translating the chain to a Prolog
list and using Prolog iteration.  In the example, `device<-graphicals'
returns a chain holding the graphicals displayed on the device.  The
example changes the font of all objects of class \class{text} to `bold'.
\begin{code}
...,
send(Device?graphicals, for_all,
     if(message(@arg1, instance_of, text),
	message(@arg1, font, bold))),
...
\end{code}
 
#class chain_hyper "chain_hyper(from, to, forward, backward)"
Link two objects with a `chain'.  If either dies, the other will die
with it.  See also the library \pllib{hyper} and \secref{hyper}.

#class chain_table "chain_table(buckets)"
Version of a \class{hash_table} that allows multiple values to be
associated with the same key.  The key can be any object.  If the
value for a key is requested, a chain of values associated with this
key is returned.

#class char_array "char_array(text)"
Class \class{char_array} is a super-class of the classes \class{string},
representing modifiable text and \class{name}, representing read-only
unique textual constants.  Class \class{char_array} defines most of the
analysis methods for its two subclasses.  Almost the only usage of this
class for application programmers is as type specifier for methods in
user-defined classes that do not modify textual arguments.
\begin{code}
insert_bold_text(Editor, Text:char_array) :->
	"Insert text with fragment of bold text"::
	get(Editor, caret, Start),
	send(Editor, insert, Text),
	get(Editor, caret, End),
	Len is End-Start,
	new(_, fragment(Editor, Start, Len, bold)).
\end{code}

#class circle "circle(diameter)"
Equivalent to an ellipse with the same <-width and <-height. Not used
frequently.

#class class "class(name, super_class_name)"
All \product{} classes are represented by an instance of class \class{class}.
A class is a normal object and can thus be manipulated using
send/[2-12], get/[3-13] and new/2.  Classes are normally only created
and modified through the user-defined class layer described in
\chapref{udc}. Get methods on classes are used to extract
meta-information about its instances, as exploited by the online manual
tools.
\begin{code}
?- get(@pce, convert, box, class, ClassBox),
   get(ClassBox, super_class, X).
X = @graphical_class/class.
\end{code}

#class class_variable "class_variable(class, name, default, type, summary)"

A \class{class_variable} provides can be used to describe class
properties as well as to provide access to the \product{}
\file{Defaults} database.  Typically, class-variables are defined
similar to instance-variables in the \product{}/Prolog class definition:

\begin{code}
:- pce_begin_class(title_text, text).

class_variable(font, font, huge, "Default font for titles").

...
\end{code}

#class click_gesture "click_gesture(button, mod, multi, execute, preview, cancel)"
Class \class{click_gesture} is a \class{recogniser} that parses button-events
to a click.  If the click is detected, it will execute the associated message.
This class is normally used to make graphical objects sensitive to clicks.
\begin{code}
...,
send(Bitmap, recogniser,
     click_gesture(left, double, message(Bitmap, open))),
...
\end{code}

#class code "code()"
Class \class{code} is a super-class for all `executable' objects.  An
important sub-class is class \class{function}, representing executable
objects that yield a value.  The method `code ->forward: any ...' pushes
the \class{var} objects @arg1, \ldots and then executes the code object.
Code objects are often associated with controllers to describe the action
the controller should perform.  They also serve the role of \idx{lambda}
functions.  See also \secref{exeobjects}.

\begin{code}
?- send(message(@prolog, format, 'Hello ~w.', @arg1),
	forward, world).
Hello world.
\end{code}

#class code_vector "code_vector(any|function...)"
A \class{code_vector} is a subclass of class \class{vector} that can
represent functions as well as normal objects.  It is used for packing
multiple arguments passed to a variable-argument method.  Do not use
this class directly.  See \secref{varargs}.

#class colour "colour(name, [r], [g], [b])"
A \class{colour} represents an `RGB' triple.%
	\footnote{Colour screens create their colour by mixing the `primary'
		  colours `red', `green' and `blue'.  With an `RBG' triple,
		  we refer to a triple of three numeric values representing
		  the intensities of the three primary colours}
Colours are used as attributes to graphicals, windows, \classs{style} and
\classs{pixmap}

#class colour_map "colour_map(name, colours)"
Manipulate the colourmap.  Colourmaps are normally left untouched, but
using a 256 entries colour palette in MS-Windows they can be used to
improve full-colour image rendering.  See also \secref{colour}.

#class connect_gesture "connect_gesture(button, modifier, link)"
A \class{connect_gesture} allows the user to connect two graphicals
by dragging from the first to the second.  This requires two graphicals
with \classs{handle}s attached, a \class{link} that is compatible with the
handles and a \class{connect_gesture} associated width the graphical at
which the connection should start.  The demo program PceDraw as well
as the \product{} Dialog Editor described in \chapref{dialogeditor} exploit
connections and connect_gestures.

#class connection "connection(from, to, link, from_handle, to_handle)"
A \class{connection} is a line between two graphical objects that
automatically updates on geometry, device and displayed-status changes
to either of the connected graphicals.  Both of the graphicals must
have one or more \classs{handle} associated with them.  The connection
can be attached to a specific handle, or to any handle of the proper
`handle <-kind'.  In the latter case, the system will automatically
choose the `best-looking' handle.

#class constant "constant(name, [summary])"
A \class{constant} is a unique handle.  \product{} predefines the following
constants: @nil, @default, and from the subclass \class{bool}, @on
and @off.  The use can define additional constants and give them their
own unique meaning.  The most obvious usage is to indicate a slot
that can hold arbitrary data including @nil and @default is in
a special state.
\begin{code}
?- new(@uninitialised,
       constant(uninitialised,
		'Not yet initialised slot')).
\end{code}

#class constraint "constraint(from, to, relation)"
A constraint is a relation between 2 objects that has to be maintained
if either of the objects is changed. The `constraint <-relation' is a
description of the relation maintained by the constrained. The system
defines the relations \class{identity} (both objects have an attribute
that has same value) and \class{spatial} (general purpose
geometry-relation between two (graphical) objects.  It is possible
to define new \class{relation} classes.  Constraints are getting out
of fashion as \product{} lacks a good mechanism to detect when an object
has been changed and therefore evaluates the relation far too often.
User-defined classes, possibly combined with \class{hyper} objects
form an attractive alternative.  The following keeps a text centered
in a box.

\begin{code}
...,
new(_, constraint(Box, Text, identity(center))),
...
\end{code}

#class create "create(class, unchecked ...)"
Function that creates an instance of a class.  It is often required if
a code fragment executed by an `iterator' method such as `chain ->for_all'
has to create objects.  The following code generates \classs{dict_item}
from all \class{send_method}s of the specified class
and displays them to a \class{browser}.

\begin{code}
send_methods_of_class(ClassName) :-
	new(B, browser(ClassName)),
        get(@pce, convert, ClassName, class, Class),
	get(Class, send_methods, SendMethods),
	send(SendMethods, for_all,
	     message(B, append,
		     create(dict_item,
			    @arg1?name,
			    @default,
			    @arg1))),
	send(B, open).
\end{code}

#class cursor "cursor(name)"
A \class{cursor} defines the shape that indicates the position of the
\idx{pointer} (also called \idx{mouse}).  The system provides a large
set of predefined cursors from \idx{X11}.  The Win32 version adds the
standard Windows cursors to this set.  Cursors can also be created from
an \class{image}. The demo program \demo{Cursors} displays all defined
cursors.

Cursors can be associated with graphicals and windows using the ->cursor
method.  They are also associated to \classs{gesture}, where they define
the cursor that is visible while the gesture is active (i.e.\ while the
mouse-button that activated the gesture is down).

Type-conversion converts names into cursor objects.  Explicit creation
of cursors is rarely used.

\begin{code}
...,
send(Box, cursor, gobbler),
...
\end{code}

#class date "date(second, minute, hour, day, month, year)"
A \class{date} objects represents a point in time. The underlying
representation is the POSIX file time-stamp: seconds elapsed since
00.00, Jan 1-st, 1970.  This limits the applicability of this class
to time-stamps of computer resources (files), agenda systems and other
domains that do not require a granularity below 1 second or have to
represent time-stamps in far history or future.  Class \class{date}
can parse various textual representations into date objects.

\begin{code}
?- send(@pce, format, 'It is now "%s"\n',
	new(date)?string).
It is now "Tue Jan 30 14:07:05 1996"
\end{code}

#class device "device()"
A graphical \class{device} is a \idx{compound graphical}.  It is the
super-class of class \class{window}.  It is a sub-class of \class{graphical},
which implies devices can be used to create a consist-of structure of
graphical objects, giving structure to a diagram.  Devices are commonly
refined to establish \idx{user-defined graphics}, see \secref{ugraphics}.
See also class \class{figure}.

\begin{code}
make_icon(Icon, Image, Label) :-
	new(Icon, device),
	send(Icon, display,
	     new(BM, bitmap(Image))),
	send(Icon, display,
	     new(T, text(Label, center))),
	send(T, y, BM?bottom_side),
	send(T, center_x, BM?center_x).
\end{code}

#class dialog "dialog(label)"
A \class{dialog} is a \class{window} specialised for the layout and
message handling required by \classs{dialog_item}, the super-class of
the \product{} \idx{controller}s. In most cases, controller-windows are
created by simply ->append{}ing a number of controllers to a dialog
window. The \class{frame}- and \class{dialog}-layout services take care
of proper window sizes and layout of the controllers. Dialog windows are
also involved in forwarding ->report messages (see \secref{report}) and
keyboard accelerators, handling the default button.

\begin{code}
:- pce_autoload(file_item, library(file_item)).

edit_file_dialog :-
	new(D, dialog('Edit File')),
	send(D, append,
	     file_item(edit_file, '')),
	send(D, append,
	     button(edit, message(@prolog, emacs, @arg1))),
	send(D, append,
	     button(cancel, message(D, destroy))),
	send(D, open).
\end{code}

#class dialog_group "dialog_group(name, kind)"
A \class{dialog_group} is a collection of \classs{dialog_item}. Dialog
groups may be used to realise a (labeled) box around a group of
controllers, or to combine multiple controllers into a compound
one for technical or layout reasons.  See also \class{tab}.

#class dialog_item "dialog_item(label)"
Class \class{dialog_item} is a super-class of all \product{} controllers. It
contains the code necessary to negotiate geometry with its neighbours
and enclosing \class{dialog} window and provides default fonts for the
label, etc. Class \class{graphical} defines similar methods to allow
integration of raw graphical objects into dialog windows easily, but
\class{graphical} uses the more expensive object-level attributes for
storing the necessary status.  Open the class-hierarchy below class
\class{dialog_item} to find all available \idx{controllers}.

#class dict "dict()"
A \class{dict} is an abbreviation of \idx{dictionary}. Dicts map
keywords to \class{dict_item} objects. Small dicts simply use a linear
list (\class{chain}) of items. Large dicts will automatically built a
\class{hash_table} for quick lookup on the first request that profits
from the availability of a table. A dict provides the storage for a
\class{list_browser}.  See also class \class{browser}.

#class dict_item "dict_item(key, label, object)"
Item in a \class{dict}. The {\em key} is used for lookup. {\em label} is
the text displayed by the \class{browser} (@default uses the {\em key}).
{\em Object} is an arbitrary object that can be associated to the dict.
If a dict presents a set of \product{} objects, it is common practice to extract
the key and or label from the object and store the object itself in the
`dict_item <->object' slot.

A \class{name} is translated to a dict_item using the name as {\em key},
default label and @nil object.  `dict_item <->style' can be used to
give an item special attributes (colour, font, etc.).

#class directory "directory(name)"
A \class{directory} represents an node (\idx{folder}) in the computer's
file-system. Directories are most commonly used to enumerate the files
and sub directories.  Directory objects can also be used to create or
delete directories from the file-system.

\begin{code}
?- get(directory(.), files, Files).
\end{code}

#class display "display(address)"
A \class{display} represents what X11 calls a \idx{screen}, a desktop on
which windows can be displayed with a mouse and keyboard attached to it.
\product{} support multiple display instances under X11 and only the predefined
default display @display under Win32.  The display implements a number of
global operations: getting the screen <-size, showing modal message
boxes using ->inform and ->confirm, etc.
\begin{code}
?- get(@display. size, size(W, H)).
W = 1024, H = 786
\end{code}

#class display_manager "display_manager()"
The object @display_manager is the only instance of this class.
It represents the collection of available \class{display} objects and
provides access to the system-wide event-dispatching services.  It is
the root of the consist-of hierarchy of \class{visual} objects as
displayed by the \tool{Visual Hierarchy} tool.

#class edit_text_gesture "edit_text_gesture(button, modifier)"
Used internally to handle selection inside a \class{text} object. See
also the library \pllib{pce_editable_text}.

#class editor "editor(text_buffer, width, height, margin_width)"
An \class{editor} is a general-purpose text editor. It is a graphical.
Class \class{view} provides a window-based version of the editor. \product{}'s
editors have commands and key-bindings that are based on
\idx{GNU-Emacs}. Editors are fully programmable. The associated
\class{key_binding} object parses key-strokes into commands that are
defined as methods on the editor.

An editor is a compound object and a subclass of \class{device}. The
other components are a \class{text_image} to form the actual display, a
\class{text_buffer} to provide the storage for the text, elementary
operations on the text and \idx{undo}, a \class{text_cursor} to indicate
the location of the caret, and optionally a \class{text_margin} to
visualise the presence of \idx{annotations}.

A single \class{text_buffer} can be associated with multiple
\class{editor} objects, providing \idx{shared editing}.

Editors can handle sensitive regions, different fonts, colours and
attributes using \class{fragment} objects. All text windows in \product{}'s
demo programs (PceEmacs, cards from the online help, application help,
etc.) either use class view or class editor to display the text. 

#class elevation "elevation(name, height, colour, relief, shadow)"
An \class{elevation} object describes an elevated region on the screen.
Elevations come in two flavours: as a shadow for monochrome displays
and using light and dark edges on colour displays.  The elevation object
itself just contains the colour definitions.  The actual painting is
left to the graphical object the elevation is attached to.

Most controllers handle elevations.  The only general purpose graphical
supporting an elevation is \class{figure}.

#class ellipse "ellipse(width, height)"
Elliptical shape.  Class \class{ellipse} defines similar attributes as
\class{box}: pen, texture, fill_pattern and shadow. See also
\class{circle}.

#class error "error(id, format)"
An \class{error} object represents a runtime message. Whenever an error
is trapped or a message needs to be displayed, the system will invoke
`object ->error: id, context ...' to the object that trapped the error.
If this method is not redefined, the system will report the error using
the `object ->report' mechanism described in \secref{report}. Errors can
be prevented from being reported using pce_catch_error/2. The
\tool{Error Browser} of the online manual shows all defined errors.

The development system will report errors that are considered
`programming errors' (undefined methods, type violations, invalid object
references, etc.) to the terminal and start the tracer. See also
\secref{debugging}.

#class event "event(receiver, name, position)"
An \class{event} represents an action from the application user:
pressing a key, moving the mouse, pressing a mouse-button, or entering
or leaving an area with the mouse.  The main loop of \product{} will read
window-system events from the computing environment (X11 or Win32).
If the event concerns a repaint or similar system event, it will be
handled appropriately.  If it can be expressed as an \product{} event, an
\class{event} object will be created and send to the window for which
the event was reported by the system using the method `event ->post'.

Graphical objects and windows can redefine their event handling using
two mechanisms: by redefining the ->event method or by associating
a \class{recogniser} object using `graphical ->recogniser'.

Normally, \product{} will read and dispatch events when `there is nothing else
to do'. For processing events during computation, see `graphical
->synchronise' and `display ->dispatch'.

#class event_node "event_node(value, parent)"
An \class{event_node} is a node in the event `is_a' hierarchy.  See the
demo program \demo{Events}.  Event-types are normally tested using
`event ->is_a'.

\begin{code}
event(Dev, Ev:event) :->
	"Forward all keyboard events to the text"::
	(   send(Ev, is_a, keyboard)
	->  get(Dev, member, text, Text),
	    send(Ev, post, Text)
	;   send(Dev, send_super, event, Ev)
	).
\end{code}

#class event_tree "event_tree(root)"
Event `is_a' hierarchy.  The only instance is @event_tree.

#class figure "figure()"
A \class{figure} is a refinement of a \class{device}. It is a compound
graphical, but in addition can define a background, surrounding box with
margin, possibly rounded corners and \class{elevation} and a
\idx{clipping} region. Finally, figures may be used not only to display
all member graphicals, but also to show `one of' the member graphicals
only. See `figure ->status'. An example of the usage of figures are the
`object cards' of the \tool{Inspector} tool.

#class file "file(name)"
An \product{} \class{file} object represents a file on the computers
file-system.  It can be used to specify a file, query a file for
various attributes, read a file, etc.  See also \class{directory}.

\begin{code}
?- get(file('summary.doc', size, Size).
Size = 30762
\end{code}

#class font "font(family, style, points)"
A \class{font} is a reusable object that describes the typeface of text.
\Secref{font} documents the specification of physical and logical fonts.
\begin{code}
...,
send(Text, font, bold),
...
\end{code}

#class format "format(direction, width, columns)"
A \class{format} describes the \idx{layout of graphicals} on a
\class{device}. It can specify `\idx{tabular}' and `\idx{paragraph}'
style layout. A format itself just specifies the parameters, `device
->format' actually realises the format.

#class fragment "fragment(text_buffer, start, length, style)"
A \class{fragment} defines a region of text in a \class{text_buffer}
using a start-position and a length.  Fragments are automatically
updated if the contents of the text_buffer changes.  A fragment can
be assigned a logical `category', called `style'.  The \class{editor}
visualising the text_buffer maps the style-names of fragments into
\class{style} objects using `editor ->style'.  

\begin{code}
...,
send(Editor, style, title, style(font := huge)),
new(_, fragment(Editor, Start, Len, title)),
...
\end{code}

#class frame "frame(label, kind, display)"
A \class{frame} is a collection of \class{tile}{\em d} windows.  Frames
handle the layout, resizing, etc. of its member windows. Any \product{} window
is enclosed in a frame, though it is often not necessary to specify a
frame explicitly.  Applications are often implemented as subclasses
of \class{frame}.  \Secref{framelayout} describes the layout of windows
inside a frame.

\begin{code}
...,
new(F, frame('My application')),
send(F, append, new(B, browser)),
send(new(P, picture), right, B),
...
send(F, open).
\end{code}

#class function "function()"
A \class{function} is a \class{code} object that yields a value when
executed.  See \secref{function}.

#class gesture "gesture(button, modifier)"
Class \class{gesture} is the super-class for the \class{recogniser}
classes that deal with the sequence mouse-button-down \ldots dragging
\ldots mouse-button-up. This super-class validates the various
conditions, handles the cursor and focus and activates the ->initiate,
->drag and ->terminate methods that are redefined in its subclasses.
This class is often sub-classed.

#class get_method "get_method(name, return_type, types, message, summary, source)"
Specification of get-behaviour that is associated with a class using
`class ->get_method' or with an individual object using `object
->get_method'. Normally specified through the preprocessor layer
defined in \chapref{udc}.

#class graphical "graphical(x, y, width, height)"
The most generic graphical object.  This class defines generic geometry
management, display, update, event-handling, etc.  This class can be
sub-classed to defined specialised graphics.  See \secref{ugraphics}.

#class grbox "grbox(graphical, alignment, rubber)"
Embed a graphical in a \class{parbox}. Using \const{left} or
\const{right} alignment, \class{grbox} can also be used to have text
floating around graphical illustrations.  See \secref{docrender}.

#class handle "handle(x_position, y_position, kind, name)"
A \class{handle} defines a typed and named position on a graphical used
by connections to connect to.  The positions are formulas expressed in
the with and height of the graphical.  The following definitions are
encountered regularly:

\begin{code}
:- pce_global(@north_handle,
	      new(handle(w/2, 0, link, north))).
:- pce_global(@south_handle,
	      new(handle(w/2, h, link, south))).
:- pce_global(@east_handle,
	      new(handle(0, h/2, link, east))).
:- pce_global(@west_handle,
	      new(handle(w, h/2, link, west))).
\end{code}

#class handler "handler(event, message, region)"
A \class{handler} is the most primitive \class{recogniser}, mapping an
event-type to a message.  Since the introduction of the more specialised
\class{gesture} and \class{key_binding} as well as the possibility to
refine the `graphical ->event' method, it is now rarely used.

\begin{code}
...,
send(Graphical, recogniser,
     handler(area_enter,
	     message(Graphical, report,
		     'Hi, I''m %s',
		     Graphical?name))),
...
\end{code}

#class handler_group "handler_group(recogniser ...)"
A \class{handler_group} is a compound \class{recogniser} object.  When
asked to handle an event, it will try each of its members until one
accepts the event, after which it will return success to its caller.
The following defines a combined move- an resize-gesture.  Note the
order: resize gestures only activate close by the edges of the
graphical, while move gestures do not have such a limitation.

\begin{code}
:- pce_global(@move_resize_gesture,
      new(handler_group(new(resize_gesture),
			new(move_gesture)))).
\end{code}

#class hash_table "hash_table(buckets)"
A \class{hash_table} is a fast association table between pairs of
objects.  For example, @classes is a hash_table mapping class-names
into class objects.  Names are often used as {\em keys}, but the
implementation poses no limit on the type of the key.

\begin{code}
?- new(@ht, hash_table),
   send(@ht, append, gnu, image('gnu.img')).

?- get(@ht, member, gnu, Image).
\end{code}

#class hbox "hbox(width, ascent, descent, rubber)"
Superclass of \class{tbox} and \class{grbox} dealing with
document-rendering.  Instances of \class{hbox} itself can be used to
define `rubber'.  See \secref{docrender} for details.

#class host "host(system)"
Class \class{host} represents the \idx{host-language}, Prolog for this
manual. It predefines a single instance called @prolog. Sending messages
to @prolog calls predicates.  See also \secref{pceprolog}.

\begin{code}
?- send(@prolog, write, hello).
hello
\end{code}

#class host_data "host_data(handle)"
Support class for passing data of the host-language natively around in
\product{}. The Prolog interface defines the subclass
\class{prolog_term} and the interface-type \type{prolog}.  Details are
discussed in the interface definition in \secref{prologdata}.

#class hyper "hyper(from, to, forward_name, backward_name)"
A \class{hyper} is a \idx{binary relation} between two objects.  The
relation can be created, destroyed and inspected.  It is automatically
destroyed if either of the two connected objects is destroyed.  The
destruction can be trapped.  Messages may be forwarded easily to all
related objects.  See also \secref{hyper}.

#class identity "identity(from, to)"
An \class{identity} is a \class{relation} that maintains the identify
between an attribute on one object and an attribute on another object.
Given a slider and a box, the following ensures the selection of the
slider is the same as the width of the box, regardless of which of the
two is changed.  See also \class{constraint}.

\begin{code}
new(_, constraint(Slider, Box,
		  identity(selection, width)))
\end{code}

#class if "if(condition, then, else)"
Code object implementing a \idx{branch}.  All three arguments are
statements.  Both `then' and `else' are optional, and when omitted,
simply succeed.  Class \class{if} is most commonly used in combination
with the iteration methods such as `chain ->for_all':

\begin{code}
...,
send(Device?graphicals, for_all,
     if(message(@arg1, instance_of, device),
	...)),
...
\end{code}

#class image "image(name)"
An \class{image} is a two-dimensional array of pixels.  Images come in
two flavours: monochrome, where each pixel represents a boolean and
colour, where each pixel represents a colour.  \product{} can save and load
both monochrome and colour images.  Images are displayed on a graphical
device using a \class{bitmap}. They are also used to specify
\class{cursor} objects and the icon associated with a `frame'.
See \secref{images}.

#class int_item "int_item(name, default, message, low, high)"
Subclass of \class{text_item} for entering integer values.  Has stepper
buttons for incrementing and decrementing the value.

#class joint "joint(arrows)"
Class \class{joint} is a super-class of the various line-types with
a start- end end-point.  It provides the code dealing with attached
\class{arrow}{\em -heads} at either end.  As well as common code to
reason about the start and end.  See also \class{line}, \class{path},
\class{arc} and \class{connection}.

#class key_binding "key_binding(name)"
A \class{key_binding} object parses events into messages or methods on
the object for which it is handling events.  Key-bindings are used by
the classes \class{text}, \class{text_item}, \class{editor} and
\class{list_browser}. They can be used to defined
\idx{keyboard-accelerators}, though `menu_item <->accelerator' is
generally more suitable for this purpose.

#class label "label(name, selection, font)"
A \class{label} is a controller used to display read-only text or
\class{image}. Labels can handle ->report messages. See \secref{report}.
The code below is the typical way to associate a label that will catch
report messages for all windows of the \class{frame} in which the
\class{dialog} is enclosed.

\begin{code}
...,
send(Dialog, append, label(reporter)),
...
\end{code}

#class label_box "label_box(name, message)"
Subclass of \class{dialog_group} for the definition of compound
controllers with a properly aligned label at their left-hand side.

#class layout_manager "layout_manager()"
#class layout_interface "layout_interface(graphical)"

A \class{layout_manager} may be attached to a graphical \class{device}
(including a \class{window}) to manage the layout of graphicals
displayed on the device, as well as painting the background of the
device.  See \class{table} for a typical example.

#class lbox "lbox(width)"
Class of the document-rendering system to render a list environment,
a sequence of labels and text.  See \secref{docrender} for details.

#class line "line(start_x, start_y, end_x, end_y, arrows)"
A \class{line} is a straight line-segment with optional arrows,
thickness and texture. Class \class{path} implements a `multi-line'.

#class link "link(from, to, line)"
A \class{link} is a reusable specification for a \class{connection}.
Links are used for defining connections and \class{connect_gesture}
objects.  A connection knows about the link used to instantiate it.
The example defines the \classs{handle}, \class{link} and
\class{connect_gesture} and shapes that allows the user to create
links with an error from `out' ports to `in' ports.

\begin{code}
:- pce_global(@in_handle,
	      new(handle(0, h/2, in, in))).
:- pce_global(@out_handle,
	      new(handle(w, h/2, out, out))).
:- pce_global(@inout_link,
	      new(link(out, in,
		       line(arrows := second)))).
:- pce_global(@link_in_out_gesture,
	      new(connect_gesture(left, '',
				  @inout_link))).

make_shape(S) :-
	new(S, box(50,50)),
	send_list(S, handle,
		  [@in_handle, @out_handle]),
	send(S, recogniser, @link_in_out_gesture).
\end{code}

#class list_browser "list_browser(dict, width, height)"
A \class{list_browser} is a graphical version of a \class{browser}, the
visualisation of a list of items (\class{dict_item}) stored in a
\class{dict}. The graphical version is sometimes displayed with other
controllers on a \class{dialog} window. The example created a
\class{list_browser} holding all current Prolog source files.
Double-clicking a file will start \tool{PceEmacs} on the file. Selecting
a file and pressing {\sf Consult} will (re)consult the file.

\begin{code}
show_source_files :-
	new(D, dialog('Prolog Source Files')),
	send(D, append, new(B, list_browser)),
	forall(source_file(X), send(B, append, X)),
	send(B, open_message,
	     message(@prolog, emacs, @arg1?key)),
	send(D, append,
	     button(consult,
		    message(@prolog, consult,
			    B?selection?key))),
	send(D, open).
\end{code}

#class menu "menu(label, kind, message)"
Class \class{menu} realises various different styles of menus and is the
super-class for \class{popup}. Basically, a menu presents multiple
values, allows the user to choose one or more items (`menu
->multiple_selection') and defines a `look'.  The `menu ->kind' set the
various attributes to often-used combinations. The other `look-and-feel'
attributes may be used to fine-tune the result afterwards.

Menu-items can have a textual or \class{image} label.  Labels can be
coloured and specify a different \class{font}.

\begin{code}
...,
new(M, menu(gender, choice)),
send_list(M, append, [male, female]),
send(M, layout, horizontal),
...,
\end{code}

#class menu_bar "menu_bar(label)"
A menu-bar is a row of pull-down menus. Many applications define a single
menu-bar at the top of the frame presenting the various commands in the
application.

\begin{code}
:- pce_begin_class(my_application, frame).

initialise(F) :->
	send(F, send_super, initialise,
	     'My Application'),
	send(F, append, new(MBD, dialog)),
	new(V, view),
	send(new(B, browser, left, V)),
	send(B, below, MBD),
	send(MBD, append, new(MB, menu_bar)),
	send(MB, append, new(F, popup(file))),
	send(MB, append, new(E, popup(edit))),
	send_list(F, append,
		  [ menu_item(load,
			      message(F, load)),
		    ...
\end{code}

#class menu_item "menu_item(value, message, label, end_group, condition, accelerator)"
Item of a \class{menu} or \class{popup}.   For \class{popup} menus, the 
items are normally created explicitly as each item often defines a
unique command. For \classs{menu}, it is common practice to simply
append the alternatives as \class{menu_item} will translate a
\class{name} into a menu_item with this <-value, <-message @default and
a <-label created by `capitalising' the value.

#class message "message(receiver, selection, argument ...)"
A \class{message} is a dormant `send-operation'.  When executed using
->execute or ->forward, a message is sent to the {\em receiver}. Message
are the most popular \class{code} objects.  See \secref{exeobjects} and
many examples in this chapter.

#class method "method(name, types, message, summary, source)"
Class \class{method} is the super-class of \class{send_method} and
\class{get_method}.  Instances of this class itself are useless.

#class modifier "modifier(shift, control, meta)"
A \class{modifier} is a reusable object that defines a condition on the
status of the three `modifier keys' \idx{shift}, \idx{control} and
\idx{meta}/\idx{alt}.  Modifiers are used by class \class{gesture} and
its sub-classes.  They are normally specified through their conversion
method, which translates a \class{name} consisting of the letters
\const{s}, \const{c} and \const{m} into a modifier that requires the
shift, control and/or meta-key to be down an the other modifier keys
to be up.  The example specifies a `\idx{shift-click}' gesture.

\begin{code}
...,
click_gesture(left, 's', single,
	      message(...)),
...
\end{code}

#class move_gesture "move_gesture(button, modifier)"
If a \class{move_gesture} is attached to a \class{graphical}, the
graphical can be moved by dragging it using the specified mouse-button.
See also \class{move_outline_gesture}.

\begin{code}
...,
send(Box, gesture, new(move_gesture)),
...
\end{code}

#class move_outline_gesture "move_outline_gesture(button, modifier)"
Similar to a \class{move_gesture}, but while the gesture is active,
it is not the graphical itself that is moved, but a dotted box
indicating the outline of the graphical.  If the button is released,
the graphical is moved to the location of the outline.  Should be used
for complicated objects with many constraints or connections as a direct
move_gesture would be too slow.

#class name "name(value)"
A \class{name} is a unique textual constant, similar to an \idx{atom}
in Prolog.  Whenever an atom is handed to \product{}, the interface will
automatically create a \class{name} for it.  There is no limit to the
number of characters that can be stored in a name, but some Prolog
implementations may limit the number of characters in an atom.  On
these platforms, it is implementation-dependent what will happen to
long names that are handed to the Prolog interface.

#class node "node(image)"
A {\em node} is a node in a \class{tree} of \class{graphical} objects.
\begin{code}
...,
new(T, tree(new(Root, node(text(shapes))))),
send(Root, son, node(circle(50))),
send(Root, son, node(box(50, 50))),
...
\end{code}

#class not "not(statement)"
Code object that inverses the success/failure of its argument statement.
Often used for code objects that represent conditions.

\begin{code}
primitives(Device, Primitives) :-
	get(Device?graphicals, find_all,
	    not(message(@arg1, instance_of, device)),
	    Primitives).
\end{code}

#class number "number(value)"
A \class{number} is the object version of an integer (\idx{int}). If may
be as a storage bin.  To compute the widest graphical of a device:

\begin{code}
widest_graphical(Device, Width) :-
	new(N, number(0)),
	send(Device, for_all,
	     message(N, maximum, @arg1?width)),
	get(N, value, Width),
	send(N, done).
\end{code}

#class object "object()"
Class \class{object} is the root of \product{}'s class-inheritance hierarchy.
It defines methods for general object-management, comparison, hypers,
attributes, etc. It is possible to create instances of class
\class{object}, but generally not very useful.

#class operator "operator(name, priority, kind)"
Part of \product{}'s object parser.  Not (yet) available to the application
programmer.

#class or "or(statement ...)"
Disjunctive \class{code} object.  An or starts executing its argument
statements left-to-right and terminates successfully as soon as one
succeeds.  The empty \class{or} fails immediately.

#class parbox "parbox(width, alignment)"
Class to render text with mixed fonts and colours together with
graphics.  Class \class{parbox} is the heart of the document-rendering
primitives described in \secref{docrender}.

#class parser "parser(tokeniser)"
Part of \product{}'s object parser.  Not (yet) available to the application
programmer.

#class path "path(kind, radius_or_interval)"
A \class{path} is a \idx{multi-segment line}.  It comes in two flavours:
{\tt poly} as a number of straight connected line-segments and
{\tt smooth} as an \idx{interpolated} line through a number of
`control-points'. Its line attributes can be defined and the interior
can be filled. Paths are used both to define new graphicals, for example
a \idx{triangle}, or to defines \idx{curves}.

\begin{code}
draw_sine :-
	send(new(Pict, picture), open),
	send(Pict, display, new(P, path)),
	(   between(0, 360, X),
	        Y is sin((X * 6.283185)/360) * 100,
	        send(P, append, point(X, Y)),
	    fail
	;   true
	).
\end{code}

#class pce "pce(version)"
Class \class{pce} defines a single instance called @pce.  Actions that
cannot sensibly be related to a particular object are often defined
on class \class{pce}.

\begin{code}
?- get(@pce, user, User).
User = jan
\end{code}

#class pen "pen(thickness, texture, colour)"
Reserved for future usage.

#class picture "picture(label)"
A \class{picture} is a \class{window} with scrollbars, normally used for
application graphics. If a graphical window without scrollbars is
required, \class{window} should be considered.

#class pixmap "pixmap(source, foreground, background)"
A \class{pixmap} is a subclass of \class{image} that is reserved for
colour images. All functionality of this class is in class
\class{image}.  The main reason for its existence is that some graphical
operations {\em require} a colour image and the introduction of a class
for it is the only way to allow this to be specified using \product{}'s type
system.  The ->initialise method is specialised for handling colour
images.

#class point "point(x, y)"
Position in a two-dimensional plane.  Together with \class{size} and
\class{area} used to communicate with graphicals about geometry.

\begin{code}
...
get(Box, center, Point),
get(Point, mirror, Mirrored),
send(Box, center, Mirrored),
...
\end{code}

#class popup "popup(name, message)"
A \class{popup} menu is	a menu that is shown after pressing a button on
the object the menu is attached to.  Popups are used in two different
contexts, as \idx{pulldown} menus attached to a \class{menu_bar} and
as popup-menus associated with windows or individual graphical objects.

Popups are ->append{}ed to menu_bars.  Various classes define the method
->popup to associate popup menus.  Finally, class \class{popup_gesture}
provides a gesture that operates popup menus.

A popup consists of \classs{menu_item}, each of which normally defines
a message to be executed if the corresponding item is activated.
Pull-right sub-menus are realised by appending a popup to a popup.

\begin{code}
...,
new(P, popup(options)),
send(P, append,
     new(L, popup(layout, message(Tree, layout, @arg1)))),
send_list(L, append, [horizontal, vertical, list]),
send(P, append,
     menu_item(quit, message(Tree, destroy))),
...
\end{code}

#class popup_gesture "popup_gesture(popup, button, modifier)"
A \class{popup_gesture} parses events and activates a \class{popup}
menu.  Popup gestures are explicitly addressed by the application
programmer to define compound gestures involving a popup:

\begin{code}
:- pce_global(@graph_node_gesture,
	      make_graph_node_gesture).

make_graph_node_gesture(G) :-
	new(P, popup),
	send_list(P, append, [...]),
	new(G, handler_group(connect_gesture(...),
			     move_gesture(middle),
			     popup_gesture(P))).
\end{code}

#class process "process(name)"
A \class{process} encapsulates a stream- or terminal program to get its
input from a graphical program and redirect its output to the same
graphical program.  Various of the \product{} tools and demo programs exploit
processes: The {\tt M-x shell}, {\tt M-x grep} and other shell commands
of \tool{PceEmacs}, the \demo{ispell} program and the \demo{chess}
front-end.  See also \class{socket}.

#class progn "progn(statement, ..., function|any)"
Code object with semantics like the LISP progn function. A \class{progn}
executes its statements.  If all statements are successfully executed
and the last argument is a \class{function}, execute the function and
return the result of it or, if the last argument is not a function,
simply return it.  Used infrequently in the \productpl{} context.

#class program_object "program_object()"
The super-class of almost the entire `meta-word' of XPCE: classes,
behaviour, attributes, types, etc.  Class \class{program_object} defines
the \product{} tracer.  See tracepce/1 and breakpce/1.

#class quote_function "quote_function(function)"
Most of \product{} is defined to evaluate function objects at the appropriate
time without the user having to worry about this. Sometimes however,
type-checking or execution of a statement will enforce the execution of
a function where this is not desired. In this case class
\class{quote_function} can help. As a direct sub-class of
\class{object}, it will generally be passed unchanged, but
type-conversion will translate extract the function itself if
appropriate, while delegation allows the quote_function to be treated as
a function.

In the example, {\em ChainOfChains} is a chain holding chains as its
elements.  The task is to sort each of the member chains, using the
\class{function} \mbox{\tt ?(@arg1, compare, @arg2)} for sorting.
If not enclosed in a \class{quote_function}, the message will try
to evaluate the function.  Now it passes the quote_function unchanged.
The `chain ->sort' method requires a \class{code} argument and therefore
the function will be extracted from the quote_function.

\begin{code}
...,
send(ChainOfChains, for_all,
     message(@arg1, sort,
         quote_function(?(@arg1, compare, @arg2)))),
...
\end{code}

#class real "real(value)"
A \class{real} is \product{}'s notion of a floating-point number.  Reals are
represented using a C single-precision `\idx{float}'.  Reals define
the same operation as class \class{number}, its integer equivalent.

#class recogniser "recogniser()"
Class \class{recogniser} is the super-class of all event-parsing
classes.  The sub-tree \class{gesture} handles mouse-button related
events, \class{key_binding} handles typing and \class{handler} may
be used for all events.  The main purpose of this class itself is
to provide a type for all its sub-classes.

#class regex "regex(pattern)"
A \class{regex} is \product{}'s encapsulation of the (GNU) \idx{Regular
Expression} library.  Regular expression form a powerful mechanism
for the analysis of text.  Class \class{regex} can be used to search
both \class{char_array} (\class{name} and  \class{string}) text and
text from a \class{text_buffer} as used by \class{editor}.  It is
possible to access the `registers' of the regular expression.

\begin{code}
?- new(S, string('Hello World')),
   new(R, regex('Hello\s +\(\w+\)')),
   send(R, match, S),
   get(R, register_value, S, 1, name, W).

W = 'World'
\end{code}

#class region "region(x, y, width, height)"
A \class{region} defines a sub-region of a graphical.  They are used
to restrict \class{handler} objects to a sub-area of a graphical.
Backward compatibility only.

#class relation "relation()"
Class \class{relation} is the super-class of \class{identity} and
\class{spatial}. Relations form the reusable part of
\classs{constraint}.  Class \class{relation} may be sub-classed to
define new relation-types.

#class resize_gesture "resize_gesture(button, modifier)"
A \class{resize_gesture} handles mouse-drag events to resize a graphical
object on the corners or edges.  See also \class{move_gesture} and
\class{resize_outline_gesture}.

\begin{code}
...,
send(Box, recogniser, new(resize_gesture)),
...
\end{code}

#class resize_outline_gesture "resize_outline_gesture(button, modifier)"
Outline version of the \class{resize_gesture}, often used to resize
objects that are expensive to resize, such as \class{editor} or
\class{list_browser}.

#class resize_table_slice_gesture "resize_table_slice_gesture(mode, button, modifier"
Gesture that can be used together with class \class{table} to allow the
user dragging the boundaries between columns and rows in a table.  See
also \secref{tabular}.

#class resource "resource(name, class)"

A \class{resource} is data associated with the application.  It is most
commonly used to get access to image-data.  Example:

\begin{code}
resource(splash, image, image('splash.gif')).

show_splash_screen :-
	new(W, window),
	send(W, kind, popup),		% don't show border
	new(I, image(resource(splash))),
	get(I, size, size(W, H)),
	send(W, size, size(W, H)),
	send(W, display, bitmap(I)),
	send(W, open_centered),
	send(timer(2), delay),
	send(W, destroy).
	
\end{code}

#class rubber "rubber(level, stretch, shrink, linebreak)"
Defines how elastic objects in the document-rendering system such as
\class{hbox} and its subclasses are.  Used by \class{parbox} to realise
layout.  See \secref{docrender} for a full description of the rendering
primitives.

#class scroll_bar "scroll_bar(object, orientation, message)"
A \class{scroll_bar} is used to indicate and control the visible part
of a large object viewed through a window.  Though possible, scroll_bars
are rarely used outside the context of the predefined scrollbars
associated with \class{list_browser}, \class{editor} and \class{window}.

\begin{code}
...,
send(Window, scrollbars, vertical),
...
\end{code}

#class send_method "send_method(name, types, message, summary, source)"
A \class{send_method} maps the name of a method {\em selector} onto an
implementation and defines various attributes of the method, such as
the required arguments, the source-location, etc.  Send-methods are
normally specified through user-defined classes preprocessor as
described in \chapref{udc}.

#class sheet "sheet(attribute ...)"
A \class{sheet} is a dynamic set of attribute/value pairs. The
introduction of object-level attributes implemented by `object
<->attribute' and user-defined classes have made sheets obsolete.

#class size "size(width, height)"
Combination of <-width and <-height used to communicate with graphical
objects about dimension.  See also \class{point} and \class{area}.

#class slider "slider(label, low, high, selection, message)"
Controller for a numeric value inside a range that does not require
exact values.  Specifying volume or speed are good examples of the
use of sliders.  They can also be used to realise a \idx{percent-done}
gauge.

\begin{code}
...,
new(Done, slider(done, 0, 100, 0)),
send(Done, show_label, @off),
send(Done, show_value, @off),
...
send(Done, selection, N),
send(Done, synchronise),
...
\end{code}

#class socket "socket(address)"
Communication end-point for a \idx{TCP/IP} or Unix-domain interprocess
communication stream.  \product{} supports both `server' and `client' sockets.
On the Win32 platform, only TCP/IP sockets are provided and only
Windows-NT supports server sockets. The \pllib{pce_server}
provides a good starting point for defining server sockets.  The
support executable {\tt \idx{xpce-client}} may be used to communicate
with \product{} server sockets.  See also PceEmacs server mode as defined
in \pllib{'emacs/server'}.

#class source_location "source_location(file_name, line_no)"
Specifies the location in a source file.  Used by \class{method} objects
to register the location they are defined.

#class source_sink "source_sink()"
Abstract super-class of \class{file}, \class{resource} and
\class{text_buffer} for type-checking purposes.  All \class{source_sink}
objects may be used for storing and retrieving image-data.  Notably
a \class{resource} can be used for creating images (see
\secref{resources} and \class{text_buffer} can be used to communicate
images over network connections (see \secref{httpd}).

#class spatial "spatial(x_from, y_from, x_to, y_to, w_to, h_to)"
A \class{spatial} defines a geometry \class{relation} between two
objects.  The first two equations express the {\em reference} point
of the 1st graphical in terms of its x, y, w and h.  The second
pair does the same for the second graphical, while the remaining
two equations relate the mutual widths and heights.  The example
defines the second graphical to be 10 pixels wider and higher than
the first, to share the same lower edge and be centered horizontally.

\begin{code}
new(_, constraint(Gr1, Gr2,
		  spatial(xref=x+w/2, yref=y+h,
			  xref=x+w/w, yref=y+h,
			  w2=w+2, h2=h+2)))
\end{code}

#class stream "stream()"
Class \class{stream} is the super-class of \class{socket} and
\class{process}, defining the stream-communication.  It handles
both synchronous and asynchronous input from the socket or
process.  It is not possible to created instances of this class.

#class string "string(value)"
A \class{string} represents a string of characters that may be modified.
This class defines a large number of methods to analyse the text that
are inherited from \class{char_array} and a large number of methods to
manipulate the text.  Class \class{regex} can analyse and modify string
objects. There is no limit to the number of characters in a string.
Storage is (re)allocated dynamically and always is `just enough' to hold
the text.  For large texts that need many manipulations, consider the
usage of \class{text_buffer} that implement more efficient manipulation.

Strings are commonly used to hold descriptions, text entered by the
user, etc.

#class style "style(icon, font)"
A \class{style} defines attributes for a text \class{fragment} as
handled by a \class{editor}/class{text_buffer} or a \class{dict_item} as
handled by a \class{list_browser}/\class{dict}. It defines the font,
fore- and background colours as well as underlining, etc. The example
defines a browser that displays files using normal and directories
using bold font.

\begin{code}
make_browser(B) :-
	new(B, browser),
	send(B, style, file, style(font := normal)),
	send(B, style, directory, style(font := bold)),
	send(B, open).

append_file(B, Name) :-
	send(B, append,
	     dict_item(Name, style := file)).
append_dir(B, Name) :-
	send(B, append,
	     dict_item(Name, style := directory)).
\end{code}

#class syntax_table "syntax_table(name)"
Syntax tables are used by class \class{text_buffer} to describe the
syntax of the text.  They describe the various syntactical categories
of characters (word-characters, digit-characters), the syntax for
quoted text, for comments as well as a definition for the end of a
sentence and paragraph.  Syntax tables are introduced to support
the implementation of \idx{modes} in PceEmacs.  See also the
emacs_begin_mode/5 directive as defined in \pllib{emacs_extend}.

#class tab "tab(name)"
A \class{tab} is a subclass of \class{dialog_group}, rendering as
a collection of \classs{dialog_item} with a `tag' associated.  Tabs
are normally displayed on a \class{tab_stack}, which in turn is
displayed on a \class{dialog}.  Skeleton:

\begin{code}
	new(D, dialog(settings)),
	send(D, append, new(TS, tab_stack)),
	send(TS, append, new(G, tab(global))),
	send(TS, append, new(U, tab(user))),
	...,
	<fill G and U>
	...,
	send(D, append, button(ok)),
	send(D, append, button(cancel)).
\end{code}

#class tab_stack "tab_stack(tab, ...)"
Defines a stack of tagged sub-dialogs (\class{tab} objects) that can
be displayed on a \class{dialog}.  See \class{tab} for an example.

#class table "table()"
A \class{table} defines a two-dimensional tabular layout of graphical
objects on a graphical \class{device}.  The functionality of \product{}
tables is modelled after HTML-3.  Example:

\begin{code}
simple_table :-
	new(P, picture),
	send(P, layout_manager, new(T, table)),
	send(T, border, 1),
	send(T, frame, box),
	send(T, append, text('row1/col1')),
	send(T, append, text('row1/col2')),
	send(T, next_row),
	send(T, append,
	     new(C, table_cell(text(spanned, font := bold)))),
	send(C, col_span, 2),
	send(C, halign, center),
	send(P, open).
\end{code}

#class table_cell "table_cell(graphical)"

Provides the \class{layout_interface} to a \class{table}.  Table cells
are automatically created if a graphical is appended to a \class{table}.
Explicit creation can be used to manipulate spanning, background and
other parameters of the cell.

#class table_column "table_column()"
#class table_row "table_row()"
#class table_slice "table_slice()"

These classes are used for storing row- and column information in
\class{table} objects.  They are normally created implicitly by the
table.  References to these objects can be used to change attributes
or delete rows or columns from the table.  Example:

\begin{code}
	...,
	get(Table, column, 2, @on, Column),
	send(Column, halign, center),
	...
\end{code}

#class tbox "tbox(text, style)"
Add text using a defined \class{style} to a \class{parbox}.  Part of the
document-rendering infra-structure.  See \secref{docrender}.

#class relation_table "table(names, keys)"
A \class{relation_table} defines a multi-column table data object that
can have one or more indexed {\em key} fields. They are (infrequently)
used for storing complex relational data as \product{} objects.

#class text "text(string, format, font)"
Graphical representing a string in a specified font.  Class text
defines various multi-line and wrapping/scrolling options.  It also
implements methods for editing.  Class \class{editable_text} as
defined in \pllib{pce_editable_text} exploits these methods to arrive
at a flexible editable text object.

#class text_buffer "text_buffer()"
A \class{text_buffer} provides the storage for an \class{editor}.
Multiple editors may be attached to the same \class{text_buffer},
realising shared editing on the same text. A text_buffer has an
associated \class{syntax_table} that describes the character categories
and other properties of the text contained. It can have \class{fragment}
objects associated that describe the properties of regions in the text.

See class \class{editor} for an overview of the other objects involved
in editing text.

#class text_cursor "text_cursor(style)"
Cursor as displayed by an \class{editor}.  Not intended for public
usage.  The example hides the caret from an editor.

\begin{code}
...,
send(Editor?text_cursor, displayed, @off),
...
\end{code}

#class text_image "text_image(text, width, height)"
A \class{text_image} object is used by the classes \class{editor} and
\class{list_browser} to actually display the text. It defines
the \idx{tab-stops} and \idx{line-wrapping} properties.  It also
provides methods to translate coordinates into character indices and
vise-versa.  The user sometimes associates \class{recogniser} objects
with the \class{text_image} to redefine event-processing.

#class text_item "text_item(label, selection, message)"
A \class{text_item} is a controller for entering one-line textual
values.  Text items (\idx{text-entry-field}) can have an associated
\class{type} and/or {\em value-set}.  If a value-set is present or
can be extracted from the type using `type <-value_set', the
item will perform \idx{completion}, which is by default bound to
the space-bar.  If a type is specified, the typed value will be
converted to the type and an error will be raised if this fails.
The following text-item is suitable for entering integers:

\begin{code}
...,
new(T, text_item(height, 0)),
send(T, type, int),
send(T, length, 8),
...
\end{code}

#class text_margin "text_margin(editor, width, height)"
A \class{text_margin} can be associated with an \class{editor} using
`editor ->margin_width' $>$ 0. If the \class{text_buffer} defines
fragments, and the \class{style} objects define `style <-icon', the
margin will show an icon near the start of the fragment.  After the
introduction of multiple fonts, attributes and colour this mechanism
has become obsolete.

#class tile "tile(object)"
Tiles are used to realise the `tile-layout' of windows in a
\class{frame}.  \Secref{framelayout} explains this in detail.  Tiles
can also be used to realise tabular layout of other re-sizable graphical
objects.

#class tile_adjuster "tile_adjuster(tile)"
Small window displayed on top of a \class{frame} at the right/bottom
of a user-adjustable window. Dragging this window allows the user the
adjust the subwindow layout.

#class timer "timer(interval, message)"
Timers are used to initiate messages at regular intervals, schedule
a single message in the future or delay execution for a specified
time.  The example realises a \idx{blinking} graphical.  Note that
prior to destruction of the graphical, the timer must be destroyed
to avoid it sending messages to a non-existing object.

\begin{code}
...,
new(T, timer(0.5, message(Gr, inverted,
			  Gr?inverted?negate))),
...
\end{code}

#class tokeniser "tokeniser(source, syntax)"
A \class{tokeniser} returns tokens from the input source according to
the syntax specified. It is part of the \product{} object parser and its
specification is not (yet) public.

#class tree "tree(root)"
Trees realise hierarchical layout for \class{graphical} objects. Class
\class{tree} itself is a subclass of \class{figure}. The hierarchy is
built from \class{node} objects, each of which encapsulates a graphical.
Trees trap changes to the geometry of the displayed graphicals and will
automatically update the layout. For an example, see \class{node}.

#class tuple "tuple(first, second)"
Anonymous tuple of two objects. Commonly used by get-methods that have
to return two values.

#class type "type(name, kind, context, supers)"
A \class{type} defines, implicitly or explicitly, a set of object that
satisfy the type, as well as optional conversion rules to translate
certain other object to an object that satisfies the type. The basic set
consists of a type for each class, defining the set of all instances of
the class or any of its sub-classes, a few `primitive' types (int, char
and event_id are examples). Disjunctive types can be created. See also
\secref{atype} and \secref{moretypes}.

\begin{code}
?- get(type(int), check, '42', X). X = 42
\end{code}

#class var "var(value)"
A \class{var} object is a \class{function} that yields the stored value
when evaluated. Vars in \product{} have global existence (like any object),
but local, dynamically scoped, binding. Scopes are started/ended with
the execution of (user-defined) methods, `code ->forward' and the
execution of a \class{block}.

The system predefines a number of \class{var} objects providing context
for messages, methods, etc: @arg1, ... @arg10 for argument forwarding,
@event for the current event, @receiver for the receiver of an event
or message and @class for the class under construction are the most
popular ones. Class \class{block} and \class{and} give examples of using
these objects.

#class variable "variable(name, type, access)"
A \class{variable} is a class' instance-variable. They are, like
\class{send_method} and \class{get_method}, normally defined through
the user-defined classes preprocessor described in \chapref{udc}.

#class vector "vector(any ...)"
Vector of arbitrary objects.  Vectors can be dynamically expanded by
adding objects at arbitrary indices.  Vectors are used at various places
of \product{}'s programming world: specifying the types of methods, the
instance variables of a class, to pack the arguments for
variable-argument methods, etc.  They share a lot of behaviour with
\class{chain} can sometimes be an attractive alternative.

#class view "view(label)"
A \class{view} is a \class{window} displaying an \class{editor}.  View
itself implements a reasonable powerful set of built-in commands
conforming the GNU-Emacs key-bindings.  See also \tool{PceEmacs} and
show_key_bindings/1.

#class visual "visual()"
Visual is the super-class of anything in \product{} that can `visualise'
things.  The class itself defines no storage.  Each subclass must
implement the `visual <-contains' and `visual <-contained_in' methods
that define the visual consists-of hierarchy as shown by the
\tool{Visual Hierarchy}.  Class visual itself plays a role in the
->report mechanism as described in \secref{report} and defines
`visual ->destroy' to ensure destruction of a sub-tree of the
visual consists-of hierarchy.

#class when "when(condition, then, else)"
Class \class{when} realises a function version of \class{if}. It
evaluates the {\em condition} and then returns the return-value of
either of the two functions. It is commonly used to define conditional
class-variable values.

\begin{code}
editor.selection_style: \
	when(@colour_display, \
	     style(background := yellow), \
	     style(highlight := @on))
\end{code}

#class while "while(condition, body)"
Code statement executing {\em body} as long as {\em condition} executes
successfully.  Not used frequently.  Most iteration in \product{} uses the
->for_all, ->for_some, <-find and <-find_all methods defines on most
collection classes.

#class window "window(label, size, display)"
The most generic \product{} window class.  A \class{window} is a sub-class of
\class{device} and thus capable of displaying graphical objects.
One or more windows are normally combined in a \class{frame} as
described in \secref{framelayout}.  The four main specialisations of
window are \class{dialog} for windows holding controllers, \class{view}
for windows holding text, \class{browser} for windows displaying a list
of items and finally, \class{picture} for displaying graphics.

Class \class{window} can be used as a graphics window if no scrollbars
are needed.

#class window_decorator "window_decorator(window, scrollbars, label)"
A \class{window_decorator} is a window that displays another window and
its `decorations': scrollbars and label.  A \class{picture} for example
is actually a window displayed on a window-decorator displaying the
scrollbars.  Almost never used directly by the application programmer.
\end{description}