\chapter{Introduction}

\product{} is an object-oriented library for building Graphical User
Interfaces (GUI's) for symbolic or strongly typed languages. It provides
high level GUI specification primitives and dynamic modification of the
program to allow for rapid development of interfaces. It integrates a
graphical tool for the specification of interfaces, in addition to
powerful and uniform mechanisms to facilitate automatic generation of
GUI's.

\product{} is not a programming language in the traditional sense. Language
constructs and objects of the system do not have a direct textual
representation. The interface to the `hosting' language defines what
\product{} looks like from the programmers point of view. As a consequence,
the programmer will first of all experience \product{} as a {\em library}.

\product{} however, does provide all semantic elements that can be found in
many object-oriented programming languages: classes, objects, methods,
instance-variables, inheritance, statements, conditions, iteration, etc.

All the above primitives are represented by first-class {\em objects}
that may be created, modified, inspected and destroyed. This allows the
programmer to extend the \product{} object-oriented system with new methods
and classes from the host-language. In addition, procedures can be
expressed as objects and then given to \product{} for execution.

The interface between \product{} and its hosting language is small, which
makes \product{} especially a good GUI candidate for special-purpose
languages.

\begin{xpceonly}
The main target language for \product{} is {\em Prolog} and this document
concentrates on \productpl{} rather then \product{}/Lisp or \product{}/C++.
\end{xpceonly}
\productpl{} comes with a graphical programming environment that allows
for quick browsing of the source-code, provides debugging tools and
allows for the graphical construction of {\em dialog boxes} (graphical
windows with {\em controllers}). \product{}'s built-in editor is
modelled after the standard (GNU-)Emacs editor and can be programmed in
\productpl{}.



\section{Organisation of the \plainproduct{} documentation}

This document describes the basics of \product{} and its relation to Prolog.
Besides the written version, this document is also available as an HTML
document from the URL below.  The second URL may be used to download
the entire WWW tree for installation on a local host.
\begin{quote}\small
\url{http://www.swi.psy.uva.nl/projects/xpce/UserGuide/} \\
\url{ftp://ftp.swi.psy.uva.nl/xpce/HTML/UserGuide.tgz}
\end{quote}

\noindent
This document provides the background material needed to understand
the other documentation:

\begin{itemize}
    \tick{The \product{} Reference Manual} \ifpw{}{\cite{XPCE:reference}}
The reference manual is available by means of the Prolog predicate
\ifpw{user_help/0}{manpce/0}. The reference manual provides detailed
descriptions of all classes, methods, etc.\ which may be accessed from
various viewpoints. See also \chapref{online}.
    \tick{PceDraw: An example of using \product{}} \ifpw{}{\cite{XPCE:draw}}
This document contains the annotated sources of the drawing tool PceDraw.
It illustrates the (graphical) functionality of \product{} and is useful as
a source of examples.
    \tick{{\productpl{}} Course Notes} \ifpw{}{\cite{XPCE:course}}
Course-notes, examples and exercises for programming \productpl{}.  The
course-notes have a large overlap in contents with this user guide, but
the material is more concise.  If you are familiar with object-oriented
systems, Prolog and graphical user interfaces the course-notes might
be a quick alternative to this user guide.
\end{itemize}


\section{Other sources of information}		\label{sec:faq}

\index{home,web}\index{WWW,addresses}%
Various other information can be found on or through the \product{}
WEB-home:

\begin{quote}\small
\ifpw{\url{http://www.swi.psy.uva.nl/projects/xpce/ProWindows.html}}{%
      \url{http://www.swi.psy.uva.nl/projects/xpce/}}
\end{quote}

\noindent
Utility programs, recent examples, documentation, etc.\ can be found
in the primary \product{} anonymous ftp archive:

\begin{quote}\small
\url{ftp://ftp.swi.psy.uva.nl/xpce/}
\end{quote}

\index{bug,reporting}%
\noindent
There is a mailing list for exchanging information and problems between
programmers as well as for us to announce new releases and developments.
The address is \email{xpce@swi.psy.uva.nl}. Please send mail to
\email{xpce-request@swi.psy.uva.nl} to subscribe or unsubscribe to this
list.  This E-mail address can also be used to communicate with the
authors.  The address \email{xpce-bugs@swi.psy.uva.nl} should be used
for reporting bugs.


\begin{xpceonly}
\section{Language interfaces}

The interface between \product{} and the application (host) language is
very small. This feature makes it easy to connect \product{} to a new
language. \product{} fits best with dynamically typed or strongly
statically typed languages with type-conversion facilities that can be
programmed. \product{} itself is dynamically typed. Cooperating with
languages with the named properties avoid the need for explicitly
programmed type-conversion. For a dynamically typed host-language such
as Prolog or Lisp, the interface determines the type of the
host-language construct passed and translates it into the corresponding
\product{} object. For \idx{C++}, the rules for translating C data
structures to \product{} objects can be handled by the programmable
type-casting mechanism of C++.


%\section{ProWindows-3}				\label{sec:prowindows}
%
%\index{ProWindows-3}\index{AIIL}%
%\product{} is distributed as a commercially supported system for Quintus
%Prolog under the name ProWindows-3.  ProWindows-3 is identical to
%\product{}, linking the power of the best Prolog implementation with an
%advanced and portable GUI toolkit.  ProWindows-3 is distributed and
%supported by AIIL.  For further information, please contact:
%
%\begin{quote}
%Simon Heywood \\
%AI International Ltd \\
%Castle Chambers, High Street, \\
%Berkhamsted, Hertfordshire, \\
%HP4 2DF, United Kingdom \\[5pt]
%\setlength{\tabcolsep}{0pt}
%\begin{tabular}{ll}
%Tel:    & ~+44 1442 860214/873873 \\
%Fax:    & ~+44 1442 860200 \\
%E-mail: & ~\email{sales@aiil.co.uk} \\
%WWW:	& ~\url{http://www.aiil.co.uk/prolog/frames_home.htm}
%\end{tabular}
%\end{quote}
\end{xpceonly}


\section{Portability}

The \product{} virtual machine and built-in class library is written in
standard ANSI-C and is portable to any machine offering a flat,
sufficiently large, memory model (32 or 64 bits). \product{}'s graphical
classes (including windows, etc.) interface to \product{} {\em Virtual
Windows System} (VWS). Currently there are VWS implementations for X11
and the Microsoft Win32 API. \ifpw{}{Please contact the authors if you
are interested in other implementations.}


\subsection{Unix/X-windows}

\ifpw{\product{} runs on all Unix platforms supported by \quintus{}.}{
\index{X-windows}\index{OpenWindows}\index{Motif}
\product{} runs on most Unix/X11 platforms.  Tested platforms include SunOs,
Solaris, AIX, HPUX, IRIX, OSF/1 and Linux.  Platform configuration is
realised using GNU autoconf with an extensive test-suite.}


\subsection{Win32 (Windows 95 and NT)}

\index{Windows 95}\index{Windows NT}
The same binary version of \product{} runs on both Windows~95 and NT.
Its functionality is very close to the Unix/X11 version, making
applications source-code compatible between the two platforms. \ifpw{
Quintus \fileext{qof} files are identical on Unix and Windows platforms,
reducing the effort of porting an application to relinking the
\fileext{qof} files on the target platform}{}.

A detailed description of the differences between the Unix/X11 version
and the Windows version as well as additions to the Windows version to
access Windows-specific resources is in \appref{mswin}.
  

\section{Look-and-feel}

\index{look-and-feel}\index{Motif}\index{OpenWindows}\index{MS-Windows}%
\product{} is not implemented on top of a standard UI library such as
Motif, OpenWindows, or Win32. Instead, it is built on top of its own VWS
defining primitives to create and manipulate windows, draw primitives
such as lines, circles, text and handle user-events.

As a consequence, \product{} programs are fully compatible over the available
platforms, except that some (almost exclusively obscure) features may
have a different or have no effect on some implementations.

The implementation of all of \product{} on top of its primitive
graphicals guarantees there are no platform-specific limitations in the
manipulation and semantics of certain controllers. \product{} defines
the look-and-feel for each of the controllers. As a consequence,
\product{} controllers may not behave exactly the same as controllers of
other applications in the same windowing environment. 

All good things come at a price-tag and portability based on a virtual
environment is no exception to this rule. \product{} builds high-level
controllers (called dialog-items in its jargon) on top of the virtual
machine and therefore bypasses the graphical libraries of the hosting
system.  The same technique is used by many other portable GUI toolkits,
among which Java.

The visual feedback (look) and to some extend the reactions to user
actions (feel) of the \product{} controllers is determined by
\product{}'s {\em defaults} file, located in
\metafile{<pcehome>/Defaults}. See \secref{classvar}.

\begin{xpceonly}
\section{A brief history of (X)PCE}

The ``PCE Project'' was started in 1985 by Anjo Anjewierden.  His aim
was to develop a high-level UI environment for (C-)Prolog.  The
requirements for this environment came from the ``Thermodynamics Coach''
project in which Paul Kamsteeg used PCE/Prolog to implement the UI for
a courseware system for thermodynamics.  This system included a
`scratch-pad' that allowed the student to create structured drawings
of component configurations. The application had to be able to analyse
the drawing made by the student.

PCE has been redesigned and largely re-implemented on a SUN workstation
using Quintus Prolog and later SWI-Prolog \cite{SWI-Prolog:manual} in
the Esprit project P1098 (KADS).  This project used PCE to implement a
knowledge engineering workbench called Shelley
\cite{Anjewierden:90b}.  During this period PCE/Prolog has been used by
various research groups to implement graphical interfaces for
applications implemented in Prolog.  Most of these interfaces stressed
the use of \idx{direct-manipulation} graphical interfaces. Feedback
from these projects has made PCE generally useful and mature.

During the versions 4.0 to 4.5, \product{} was moved from SunView to
X-windows and since 4.7 compatibility to the Win32 platform is
maintained. In addition, the virtual machine has been made available to
the application programmer, allowing for the definition of new
\product{} classes. These versions have been used mainly for small
internal case-studies to validate the new approach. Larger-scale
external usage started from version 4.6 and introduced the vital
requirement to reduce incompatible changes to the absolute minimum.

In version 5, the XPCE/Prolog interface was revisited, improving
performance and making it possible to pass native Prolog data to XPCE
classes defined in Prolog as well as associate native Prolog data with
XPCE objects. Various new graphical primitives, among which HTML-4 like
tables and graphical primitives for rendering markup containing a
mixture of graphics and text.

As of XPCE 5.1, the license terms have been changed from a proprietary
license schema to the open source GPL-2 licence.

As of XPCE 6.0, the licence terms have been changed from GPL to the
more permissive LGPL for the XPCE kernel (compiled C-part) and GPL
with an exception allowing for generating non-free applications with
XPCE for the Prolog libraries.  Please visit the SWI-Prolog home page
at \url{http://www.swi-prolog.org} for details.
\end{xpceonly}

\begin{pwonly}
\section{A brief history of \product{}}

The basic design underlying \product{} was developed for an internal
project at the University of Amsterdam by Anjo Anjewierden. It was
further developed in `Esprit' project P1098 (KADS-I) for the realisation
of a workbench for knowledge engineering (Shelley).  PCE 2.0, as the
system was called then was commercialised by Quintus as ProWindows 1.

Development of PCE continued in the academic environment, producing
XPCE-3, and later XPCE-4. In this process, the system was ported from
SunView to X11 and Win32. Controllers and basic graphicals were unified,
the class-system was made available to the user and user-defined classes
were introduced. Performance, robustness and programming environment
were improved drastically.

XPCE-4 was brought to the attention of James Little (AIIL) by Paul
Holmes-Higgin from Surrey University.  AIIL decided to commercialise
XPCE-4 using the name `ProWindows-3', and introduce it as the portable
Quintus GUI environment.
\end{pwonly}


\section{About this manual}

qThis userguide introduces the basics of \productpl{} and its
development environment. \Chapref{starting}, ``Getting Started''
explains the interface. \Chapref{online}, ``Using the online manual''
introduces the online documentation tools. These are introduced early,
as many of the examples in this manual introduce classes and methods
without explaining them. The online manual tool can be used to find the
definitions of these constructs quickly. The \chapref{graphics} and
\chapref{controller}, ``Dialog (controller) windows'' and ``Simple
Graphics'' introduce the various controller and graphical primitives.

With the material of the above described chapters, the user is
sufficiently informed to create simple GUI's from predefined \product{}
objects.  The remaining chapters provide the background information
and techniques that allow for the design of larger graphical systems.

\Chapref{pceprolog}, ``The relation between \product{} and Prolog'' is a
brief intermezzo, explaining the relation between \product{} and Prolog
data in more detail. \Chapref{udc}, ``Defining classes'' explain the
definition of new \product{} classes from Prolog and thus brings
object-oriented programming to the user. \Chapref{techniques},
``Programming techniques'' is an assorted collection of hints on how
\product{} can be used to solve real-world problems elegantly.
\Chapref{libraries}, ``Commonly used libraries'' documents some of
the commonly used \productpl{} libraries.

\Chapref{debugging}, ``Development and debugging tools'' introduces
the \product{} debugger.  The current debugger is powerful, but not very
intuitive and requires a nice-looking front-end.

Of the appendices, \appref{summary} is probably the most
useful, providing a short description of each class and its relation
to other classes.  Many of the classes are accompanied with a
small example.


\begin{xpceonly}
\section{Acknowledgements}

The development of \product{} was  started by Anjo Anjewierden.  The package
was  then called PCE.  He designed  and implemented  version  1 and 2.
Version 3 is the result of a joint effort by Anjo Anjewierden and Jan
Wielemaker.

XPCE-4, offering support for X-windows and user-defined classes, has
been implemented by Jan Wielemaker. The implementation of user-defined
classes was initiated when Jan Wielemaker was guest at SERC (Software
Engineering Research Centre). Gert Florijn has contributed in the
initial discussions on user-defined classes. Frans Heeman has been the
first user.

The interface to SICStus Prolog has been implemented in cooperation with
Stefan Andersson and Mats Carlsson from SICS.

The interface to Quintus Prolog was initiated by Paul-Holmes Higgins.  The
project was realised by James Little, Mike Vines and Simon Heywood
from AIIL.

Luca Passani has bothered us with many questions, but was so kind to
organise this material and make it available to other \product{} programmers
in the form of a FAQ.

Gertjan van Heijst has commented on \product{} as well as earlier drafts of
this documents.

(X)PCE is used by many people. They have often been puzzled by bugs,
incompatibilities with older versions, etc. We would like to thank them
for their patience and remarks.
\end{xpceonly}