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]