Update of /project/mcclim/cvsroot/mcclim/Doc/Guided-Tour
In directory common-lisp:/tmp/cvs-serv19537
Modified Files:
draw-frame.lisp guided-tour.tex
Log Message:
* Incorporate suggestions from Christophe Rhodes & Luis Oliveira.
* Parenthesis error in draw-frame.
--- /project/mcclim/cvsroot/mcclim/Doc/Guided-Tour/draw-frame.lisp 2006/01/30 16:14:01 1.1
+++ /project/mcclim/cvsroot/mcclim/Doc/Guided-Tour/draw-frame.lisp 2006/02/09 13:20:38 1.2
@@ -11,7 +11,7 @@
(interactor :interactor))
(:layouts (default-default (vertically ()
draw-pane
- interactor))
+ interactor)))
(:menu-bar t)
(:command-definer t)
(:top-level (default-frame-top-level)))
--- /project/mcclim/cvsroot/mcclim/Doc/Guided-Tour/guided-tour.tex 2006/01/30 16:14:01 1.1
+++ /project/mcclim/cvsroot/mcclim/Doc/Guided-Tour/guided-tour.tex 2006/02/09 13:20:38 1.2
@@ -2,6 +2,7 @@
\usepackage[dvips]{graphicx}
\usepackage{color} % Need the color package
\usepackage{listings}
+\usepackage{url}
%\usepackage{epsfig}
\title{\Huge A Guided Tour of CLIM, \\ Common Lisp Interface Manager}
\author{
@@ -36,7 +37,9 @@
\newcommand {\concept} [1] {{\sl #1}\index{#1}}
\newcommand {\term} [1] {{\sl #1}}
\newcommand {\code}[1]{{\sffamily #1}}
-\newcommand {\CLIM}{{\small CLIM}}
+\newcommand {\CLIM}{\textsc{clim}}
+\newcommand {\CLOS}{\textsc{clos}}
+\newcommand {\mcclim}{\textsc{McCLIM}}
\let\class\code
\let\method\code
\let\constant\code
@@ -54,7 +57,7 @@
output services, and mechanisms for constructing window types and user
interface components; stream-oriented input and output facilities
extended with presentations and context sensitive
-input\footnote{Similar to the work pioneered in the Genera UI system};
+input;\footnote{Similar to the work pioneered in the Genera UI system}
and a gadget-oriented toolkit similar to those found in the X world
extended with support for look and feel adaptiveness. In this article,
we present an overview of \CLIM{}'s broad range of functionality and
@@ -62,25 +65,25 @@
article originally appeared in Lisp Pointers in 1991 and was updated
in 2006 by Clemens Fruhwirth.\footnote{The CLIM 2 specification
changed significant parts of \CLIM{} rendering legacy code
- unusable. Clemens Fruhwirth has rewritten all examples and the
- corresponding text section for the \CLIM{} 2 specification. In
- addition, he restructured the whole article and added text sections
+ unusable. Clemens Fruhwirth has rewritten all examples and the
+ corresponding text sections for the \CLIM{} 2 specification. In
+ addition, he has restructured the whole article, adding sections
to provide additional insights into \CLIM{} concepts.} All examples
-in this article have been developed with McCLIM{}\cite{mcclim}, a free
-\CLIM{} implementation.
+in this article have been run with \mcclim{}\cite{mcclim}, a free
+\CLIM{} implementation, as of January 2006.
\end{abstract}
\section*{Introduction}
Common Lisp is a language standard that has provided a broad range of
functionality, and that has, to a large degree, successfully enabled
-the writing of truly portable Lisp programs. The emergence of CLOS and
-the cleanup efforts of Ansi X3J13 have further enhanced the utility
+the writing of truly portable Lisp programs. The emergence of \CLOS{} and
+the cleanup efforts of ANSI X3J13 have further enhanced the utility
and portability of Common Lisp. However, one major stumbling block
remains in the path of those endeavoring to write large portable
applications. The Common Lisp community has not yet provided a
standard interface for implementing user interfaces beyond the most
basic operations based on stream reading and printing.\footnote{Notice
- that this sentence was written in 1991. Unfortunately, it is still
+ that this sentence was written in 1991; it is still
true 15 years later.}
The Common Lisp Interface Manager addresses this problem by specifying
@@ -92,7 +95,7 @@
and high level facilities like context sensitive input, an adaptive
toolkit, and an application building framework.
-\CLIM{} will eventually support a large number of window environments
+\CLIM{} implementations will eventually support a large number of window environments
including X Windows, Mac OS X and Microsoft Windows. \CLIM{} is
designed to exploit the functionality provided by the host environment
to the degree that it makes sense. For example, \CLIM{} top level
@@ -100,17 +103,17 @@
operations are ultimately performed by host window system
code. Another example is that \CLIM{} supports the incorporation of
toolkits written in other languages. A uniform interface provided by
-\CLIM{} allows Lisp applications programmers to deal only with Lisp
+\CLIM{} allows Lisp application programmers to deal only with Lisp
objects and functions regardless of their operating platform.
-An important goal that has guided the design of \CLIM{} has been to
+An important goal that has guided the design of \CLIM{} was to
layer the specification into a number of distinct
facilities. Furthermore, the specification does not distinguish the
use of a facility by higher level \CLIM{} facilities from its use by
\CLIM{} users. For example, the geometry substrate, which includes
transformations and regions, is designed for efficient use by the
-graphics and windowing substrates as well as by \CLIM{} users. This
-means that, in general, a \CLIM{} user can reimplement higher level
+graphics and windowing substrates as well as by \CLIM{} programmers. This
+means that, in general, a \CLIM{} programmer can reimplement higher level
\CLIM{} facilities using the interfaces provided by lower level
facilities.
@@ -123,20 +126,20 @@
particular application.
For example, \CLIM{}'s application framework and adaptive toolkit
-allow users to develop applications that automatically adopt the look
+allow programmers to develop applications that automatically adopt the look
and feel of the host's environment. (We often call this
``adaptiveness,'' ``look and feel independence,'' or occasionally more
picturesquely, ``chameleon look and feel''.) However, many users may
need or want to define a particular look and feel that stays constant
-across all host environments (we call this "portable look and
-feel"). Such users can circumvent the look and feel adaptiveness
+across all host environments (we call this ``portable look and
+feel''). Such users can circumvent the look and feel adaptiveness
provided by \CLIM{}, while still using most of the application
framework facility and other high level \CLIM{} facilities like
context sensitive input. Furthermore, using the lower level facilities
of \CLIM{}, they can develop portable toolkit libraries that define
and implement their own particular look and feel. For instance, the
-\CLIM{} user can implement new gadget types on top of the drawing
-primitives and treat them equally to the build-in gadget types.
+\CLIM{} programmer can implement new gadget types on top of the drawing
+primitives and treat them equally to the built-in gadget types.
We will use the term \concept{CLIM implementor} for the party
implementing low-level and high-level parts according to the \CLIM{}
@@ -186,11 +189,11 @@
\paragraph*{Formatted Output} \CLIM{} provides a set of high-level
macros that enable programs to produce neatly formatted tabular and
graphical displays easily.\footnote{This also includes Graph
- Formatting}
+ Formatting.}
\paragraph*{Presentations} \CLIM{} provides the ability to associate
semantics with output, such that Lisp objects may be retrieved later
-via user gestures (e.g. mouse clicks) on their displayed
+via user gestures (e.g.{} mouse clicks) on their displayed
representation. This context sensitive input is modularly layered on
top of the output recording facility and is integrated with the Common
Lisp type system. A mechanism for type coercion is also included,
@@ -213,9 +216,9 @@
facilities will automatically adapt to use whatever toolkit is
available and appropriate for the host environment. In addition,
portable Lisp-based implementations of the abstract gadget pane
-protocols are provided.\footnote{McCLIM does not support look and feel
- adaptiveness at the moment except for the experimental port for Mac
- OS X. Hence, McCLIM mostly uses this portable Lisp-based
+protocols are provided.\footnote{\mcclim{} does not support look and feel
+ adaptiveness at the moment except for the experimental beagle backend for Mac
+ OS X's Cocoa platform. Hence, \mcclim{} mostly uses this portable Lisp-based
implementation.}
\paragraph*{Application Building} \CLIM{} provides a set of tools for
@@ -237,13 +240,14 @@
stream, the \CLIM{} programmer can also attach the code that generated
the content to the content itself. Whenever necessary, the application
programmer can ask an output stream to update itself. \CLIM{} will
-query all code generators and in case, replace obsolete content.
+query all drawn elements for obsolescence, and if necessary, rerun the
+code to produce fresh output.
\noindent\hrulefill
-\noindent These are a lot of facilities to explore. The most
-systematically way -- exploring from the most low-level to the most
-high-level -- would also be the most longsome. Therefore, we start
+\noindent This is a large number of facilities to explore. The most
+systematic way -- progressing from the lowest-level to the highest
+-- would also be the lengthiest. Therefore, we start
with showing several facilities in action with the most fundamental
example in the realm of programming: Hello World.
@@ -270,6 +274,12 @@
references and hope that the interested reader starts to explore the
surrounding text sections on his own.
+After loading a \CLIM{} implementation, the package
+\keyword{:clim-user} is available to absorb user code. This package is
+a good start for experimentations and first steps. When proper
+packaging is required, simply include the packages \keyword{:clim} and
+\keyword{:clim-lisp} in your \keyword{:use} list.
+
The central element of \CLIM{} application programming is the
\concept{application-frame}. An application frame is defined via
\code{define-application-frame}.\footnote{See Section 28.2 ``Defining
@@ -318,15 +328,13 @@
The one and only superclass of \class{hello-world-pane} is
\class{clim-stream-pane}\footnote{See Section 29.4 ``CLIM Stream
- Panes'' in \cite{clim-spec}.}. As there are no additional slot, an
-experience CLOS user might have correctly guessed that we will use
-\class{hello-world-pane} solely for method specialization.
-
-But before we do that, let us have a look what we have actually
+ Panes'' in \cite{clim-spec}.}. As there are no additional slots, an
+experienced \CLOS{} user might guess that we will use
+\class{hello-world-pane} solely for method specialization. Before doing so,
+let us have a look what we have actually
inherited from \class{clim-stream-pane}\footnote{Internal classes
- removed from Listing}:
+ removed from listing.}:
-\pagebreak % formathack
\lstset{style=inlinestyle}
\begin{lstlisting}
CLIM-USER> (describe (find-class
@@ -394,12 +402,12 @@
To \CLIM{}, geometry means \concept{regions}. A region is either bound
or unbound and has a dimensionality of either zero, one or two. That
corresponds to a point, a path or an area respectively. Regions can be
-compared (region predicate protocol\footnote{\CLIM{} relays heavily on
- CLOS. In CLOS, the term \concept{protocol} means a set of generic
+compared (region predicate protocol\footnote{\CLIM{} relies heavily on
+ \CLOS{}. In \CLOS{}, the term \concept{protocol} means a set of generic
functions that together form a coherent interface. A protocol
- specification does not only include the syntactic details of the
+ specification not only includes the syntactic details of the
function names and the number of function arguments, but also the
- functions purpose and the semantic of the return values (and/or side
+ functions' purpose and the semantics of the return values (and/or side
effects) must be given in a textual specification.}) and composed
(region composition protocol).
@@ -422,14 +430,14 @@
\subsection{The Windowing Substrate}
\CLIM{} does not directly talk to the window system. Instead, \CLIM{}
-is layered on top of a windowing substrate\footnote{former Silica}.
+is layered on top of a windowing substrate.\footnote{formerly known as Silica.}
This substrate is a middleware between \CLIM{} on one side and the
host window system on the other. This middleware layer provides a
portable windowing model that insulates higher levels of \CLIM{} and
\CLIM{} programmers from the details of the host window system. From
the perspective of a \CLIM{} programmer, talking to the window system
is equal to talking to this abstraction layer. The implementation
-details are hidden in \concept{backends}, like in McCLIM the CLX
+details are hidden in \concept{backends}, like in \mcclim{} the CLX
backend, which hides X11 details, or the beagle backend, which hides
details for Mac OS X's toolkit. These backends will use the services
of a host window system to provide efficient windowing, input and
@@ -440,7 +448,7 @@
blocks:
\begin{itemize}
\item Windows like those in X, Mac OS X and Microsoft Windows.
-\item Gadgets typical of toolkit layers, such as GTK, QT or Mac OS X's
+\item Gadgets typical of toolkit layers, such as Gtk+, QT or Mac OS X's
toolkit. The backend provides a frame manager which takes care of
mapping the abstract gadget types found in \CLIM{} to appropriate
gadget with a native look and feel.
@@ -480,7 +488,7 @@
children. A sheet can be adopted by a parent sheet and disowned later.
A sheet is grafted when it is connected to a \concept{graft} either
directly or through it's ancestors. A graft is a special kind of sheet
-that stands in for a host window, typically a root window (i.e. screen
+that stands in for a host window, typically a root window (i.e.{} screen
level). A sheet is attached to a particular host window system by
making it a child of an associated graft. A host window will be
allocated for that sheet; the sheet will then appear to be a child of
@@ -545,12 +553,12 @@
sheet.
% \footnote{Notice that the \CLIM{} specification \cite{clim-spec}
% specifies draw-text, draw-line, draw-rectangle, etc. as functions
-% that operate on mediums. McCLIM names these functions
+% that operate on mediums. \mcclim{} names these functions
% medium-draw-text, medium-draw-line, medium-draw-rectangle, and so
-% on. The functions that are available in McCLIM without the
+% on. The functions that are available in \mcclim{} without the
% ``medium-'' prefix operate on sheets. These are trampoline
% functions that call the appropriate medium-prefixed function on
-% the sheet's medium. According to the McCLIM authors, this is done
+% the sheet's medium. According to the \mcclim{} authors, this is done
% for optimization.}
The graphic output capabilities of sheets range from simple line style
@@ -563,9 +571,9 @@
\CLIM{} lives in idealized world in terms of graphics operations. A
\CLIM{} programmer can use an infinitely long and wide drawing pane
-with an arbitrary precise resolution and continuously variable amount
-of opacity. As rendering devices with these properties are rare these
-days, we need to render the idealized graphic description to a device
+with an arbitrarily precise resolution and continuously variable
+opacity. As rendering devices with these properties are rare,
+we need to render the idealized graphic description to a device
with finite size and a fixed drawing precision. The rendering rules
are specified in Section 12.4 ``Rendering Conventions for Geometric
Shapes''of \cite{clim-spec}.
@@ -596,7 +604,7 @@
To build a user interface, an application programmer defines one or
more frames classes. These frame classes define a number of frame
properties including application specific state and a hierarchy of
-panes (i.e. user interface gadgets and regions for interacting with
+panes (i.e.{} user interface gadgets and regions, for interacting with
the users). Frame classes also provide hooks for customizing
application behavior during various portions of the frame protocol.
For example, an \keyword{:after} method on generic functions in the
@@ -616,13 +624,13 @@
asynchronously handling confirmation or cancel button clicks. For
instance, the programmer requests a string from the user and the user
is presented with a prompt, an editable text field, and two buttons
-for confirmation and canceling. Only after the user hit the
-confirmation button, the string requesting function returns and the
+for confirmation and canceling. Only after the user hits the
+confirmation button, the string requesting function returns; the
programmer can directly use the function's return value which is the
-user provided string. A cancel button click is handled via throwing an
-abort tag.
+string provided by the user. Clicking the cancel button is dealt with by throwing to an
+\code{abort} tag.
-From the callers perspective, an attempt to separate application
+From the caller's perspective, an attempt to separate application
frames and dialogs could be: a dialog window itself is side-effect
free with respect to the application state and therefore the whole
sense of calling a dialog creation routine must arise from the values
@@ -648,7 +656,7 @@
additional information for (or before) an operation. When the user
selects the ``Search'' command, he is queried for a search string in
an additional dialog window; probably offering other search options
-like case insensitive search or backwards search. This is done in a
+like case-insensitive search or backwards search. This is done in a
synchronous manner, blocking until the requested input is made
available by the user.
@@ -669,9 +677,9 @@
An application frame is an interface that provides the user with a
variety of commands to choose as his next step. For instance, the user
may choose from commands like Open, Save, Search, or Quit. The frame
-is a long-living GUI object compared to dialogs and there is no linear
+is a long-living GUI object compared to dialogs, and there is no linear
execution path as there is in after a dialog as the user is free to
-select any commands he likes as next step.
+select any commands he likes as his next action.
Hence, the synchronous programming pattern for dialogs is more
convenient because after dialog confirmations there is a predetermined
@@ -701,7 +709,7 @@
top-level pane in \macro{define-application-frame}. This pane is
usually a layout pane that contains more gadget and/or layout panes as
its children. With the help of layout panes, a pane hierarchy can be
-constructed. The top-level pane (and the whole hierarchy when its a
+constructed. The top-level pane (and the whole hierarchy when it is a
layout pane) is created when the application frame is adopted by a
frame manager and made visible to the user. The programmer can compose
an interface consisting of pre-defined gadget panes, layout panes, or
@@ -717,27 +725,27 @@
augmenting the class with an active part. For instance, a button-pane
actively draws its own button representation on its allotted screen
area and a click on the correct button area triggers a callback for
-the button. A composite pane lays out its children elements and
-request them to draw themselves onto specific screen regions.
+the button. A composite pane lays out its child elements and
+requests them to draw themselves onto specific screen regions.
\CLIM{} comes with a set of predefined gadget panes. They consist of
push-button, toggle-button, slider, radio-box, text-field, text-editor
panes ready for use by the \CLIM{} application programmer. These
gadgets might be remapped to native system gadgets by the frame
manager, so a native look and feel is possible.\footnote{Only possible
- in McCLIM with the experimental beagle backend for Mac OS X.}
+ in \mcclim{} with the experimental beagle backend for Mac OS X.}
Each gadget pane class is associated with a set of generic functions
-that as callbacks in traditional toolkits. For example, a pushbutton
+that act as callbacks do in traditional toolkits. For example, a pushbutton
has an ``activate'' callback method which is invoked when its button
is pressed. For this particular callback, a method named
-\method{activate-callback} is invoked per default and a \CLIM{}
-programmer can provide a specialized method to implementation
-application specific behavior for a subclassed button-pane. But except
+\method{activate-callback} is invoked by default, and a \CLIM{}
+programmer can provide a specialized method to implement
+application-specific behavior for a subclassed button-pane. But except
in the case where the programmer needs a lot of buttons with related
behavior, creating a subclass for changing a single specific callback
is not economical. Hence upon gadget creation, the programmer can
-specify an alternative callback method for all callback available. By
+specify an alternative callback method for all callbacks available. By
providing the \keyword{:activate-callback} initarg, the programmer can
change the callback to any regular or generic function. By convention,
all callbacks can be changed by providing an initarg keyword equal to
@@ -810,14 +818,14 @@
separately. This example illustrates the use of gadget panes provided
by \CLIM{}. In the code in Figure \ref{fig-color-editor}, we define an
application frame using \method{define-application-frame}. As said
-before, the syntax of this macro is similar to \class{defclass}. It
+before, the syntax of this macro is similar to that of \class{defclass}. It
defines a new frame class which automatically inherits from the class
\class{frame} which provides most of the functionality for handling
frames.
One requirement must be fulfilled by all frame definitions: code to
generate a pane hierarchy must be supplied. The \keyword{:pane} option
-is the simplest way to supply this code. \class{hello frame}
+is the simplest way to supply this code. The \class{hello-world} frame
constructs a hierarchy with only one application pane via
\method{make-pane}. The pane hierarchy of color editor is more
interesting.
@@ -896,7 +904,7 @@
whether the mouse button is held down during dragging, or whether the
mouse button is pressed once to start and again to stop dragging.
-We use the gadget id to distinguish between the red, green and blue
+We use the gadget ID to distinguish between the red, green and blue
slider in the callback code. We could use three different callback
[270 lines skipped]
