ViewVC logotype

Contents of /mcclim/Doc/Guided-Tour/guided-tour.tex

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.6 - (hide annotations)
Sun Dec 3 19:59:29 2006 UTC (7 years, 4 months ago) by thenriksen
Branch: MAIN
CVS Tags: mcclim-0-9-4, McCLIM-0-9-5, McCLIM-0-9-4, McCLIM-0-9-6, HEAD
Changes since 1.5: +4 -3 lines
File MIME type: application/x-tex
Added mention of Gtkairo.
1 cfruhwirth 1.1 \documentclass[twocolumn,a4paper]{article}
2     \usepackage[dvips]{graphicx}
3     \usepackage{color} % Need the color package
4     \usepackage{listings}
5 cfruhwirth 1.2 \usepackage{url}
6 cfruhwirth 1.1 %\usepackage{epsfig}
7     \title{\Huge A Guided Tour of CLIM, \\ Common Lisp Interface Manager}
8     \author{
9     2006 Update \\
10     Clemens Fruhwirth \texttt{<clemens@endorphin.org>} \\ The McCLIM Project
11     \bigskip \\
12     \begin{tabular}{ll}
13     \multicolumn{2}{c}{Original article\footnote{Published in Lisp Pointers 1991}} \\
14     Ramana Rao \texttt{<rao@xerox.com>} & Xerox Palo Alto Research Center \\
15     William M. York \texttt{<york@ila.com>} & International Lisp Associates, Inc. \\
16     Dennis Doughty \texttt{<doughty@ila.com>} & International Lisp Associates, Inc.
17     \end{tabular}
18     }
20     \def\VRfont{\sffamily}
22     \lstset{%
23     basicstyle=\small\sffamily,
24     keywordstyle=\small\sffamily,
25     stringstyle=\rmfamily,
26     commentstyle=\rmfamily\itshape,
27     frame=lines,
28     language=Lisp }
30     \lstdefinestyle{framestyle}
31     {frame=lines}
32     \lstdefinestyle{inlinestyle}
33     {frame=none}
36     \makeatletter
37     \newcommand {\concept} [1] {{\sl #1}\index{#1}}
38     \newcommand {\term} [1] {{\sl #1}}
39     \newcommand {\code}[1]{{\sffamily #1}}
40 cfruhwirth 1.2 \newcommand {\CLIM}{\textsc{clim}}
41     \newcommand {\CLOS}{\textsc{clos}}
42     \newcommand {\mcclim}{\textsc{McCLIM}}
43 cfruhwirth 1.1 \let\class\code
44     \let\method\code
45     \let\constant\code
46     \let\variable\code
47     \let\macro\code
48     \let\keyword\code
49     \makeatother
51     \begin{document}
52     \maketitle
53     \begin{abstract}
54     \noindent The Common Lisp Interface Manager (\CLIM{}) provides a
55     layered set of facilities for building user interfaces. These
56     facilities include a portable layers for basic windowing, input,
57     output services, and mechanisms for constructing window types and user
58     interface components; stream-oriented input and output facilities
59     extended with presentations and context sensitive
60 cfruhwirth 1.2 input;\footnote{Similar to the work pioneered in the Genera UI system}
61 cfruhwirth 1.1 and a gadget-oriented toolkit similar to those found in the X world
62     extended with support for look and feel adaptiveness. In this article,
63     we present an overview of \CLIM{}'s broad range of functionality and
64     present a series of examples that illustrates \CLIM{}'s power. The
65     article originally appeared in Lisp Pointers in 1991 and was updated
66     in 2006 by Clemens Fruhwirth.\footnote{The CLIM 2 specification
67     changed significant parts of \CLIM{} rendering legacy code
68 cfruhwirth 1.2 unusable. Clemens Fruhwirth has rewritten all examples and the
69     corresponding text sections for the \CLIM{} 2 specification. In
70     addition, he has restructured the whole article, adding sections
71 cfruhwirth 1.1 to provide additional insights into \CLIM{} concepts.} All examples
72 cfruhwirth 1.2 in this article have been run with \mcclim{}\cite{mcclim}, a free
73     \CLIM{} implementation, as of January 2006.
74 cfruhwirth 1.1 \end{abstract}
76     \section*{Introduction}
77     Common Lisp is a language standard that has provided a broad range of
78     functionality, and that has, to a large degree, successfully enabled
79 cfruhwirth 1.2 the writing of truly portable Lisp programs. The emergence of \CLOS{} and
80     the cleanup efforts of ANSI X3J13 have further enhanced the utility
81 cfruhwirth 1.1 and portability of Common Lisp. However, one major stumbling block
82     remains in the path of those endeavoring to write large portable
83     applications. The Common Lisp community has not yet provided a
84     standard interface for implementing user interfaces beyond the most
85     basic operations based on stream reading and printing.\footnote{Notice
86 cfruhwirth 1.2 that this sentence was written in 1991; it is still
87 cfruhwirth 1.1 true 15 years later.}
89     The Common Lisp Interface Manager addresses this problem by specifying
90     an interface to a broad range of services necessary or useful for
91     developing graphical user interfaces. These services include low level
92 rgoldman 1.3 facilities such as geometry, graphics, event-oriented input, and
93     windowing; intermediate level facilities such as support for Common Lisp
94 cfruhwirth 1.1 stream operations, output recording, and advanced output formatting;
95 rgoldman 1.3 and high level facilities such as context sensitive input, an adaptive
96 cfruhwirth 1.1 toolkit, and an application building framework.
98 cfruhwirth 1.2 \CLIM{} implementations will eventually support a large number of window environments
99 cfruhwirth 1.1 including X Windows, Mac OS X and Microsoft Windows. \CLIM{} is
100     designed to exploit the functionality provided by the host environment
101     to the degree that it makes sense. For example, \CLIM{} top level
102     windows are typically mapped onto host windows, and input and output
103     operations are ultimately performed by host window system
104 rgoldman 1.3 code. \CLIM{} supports the incorporation of
105 cfruhwirth 1.1 toolkits written in other languages. A uniform interface provided by
106 cfruhwirth 1.2 \CLIM{} allows Lisp application programmers to deal only with Lisp
107 rgoldman 1.3 objects and functions regardless of the operating platform.
108 cfruhwirth 1.1
109 cfruhwirth 1.2 An important goal that has guided the design of \CLIM{} was to
110 cfruhwirth 1.1 layer the specification into a number of distinct
111     facilities. Furthermore, the specification does not distinguish the
112     use of a facility by higher level \CLIM{} facilities from its use by
113     \CLIM{} users. For example, the geometry substrate, which includes
114     transformations and regions, is designed for efficient use by the
115 cfruhwirth 1.2 graphics and windowing substrates as well as by \CLIM{} programmers. This
116     means that, in general, a \CLIM{} programmer can reimplement higher level
117 cfruhwirth 1.1 \CLIM{} facilities using the interfaces provided by lower level
118     facilities.
120     This modular, layered design has a number of benefits. The \CLIM{}
121     architecture balances the goal of ease of use on one hand, and the
122     goal of versatility on the other. High level facilities allow
123     programmers to build portable user interfaces quickly, whereas lower
124     level facilities provide a useful platform for building toolkits or
125     frameworks that better support the specific needs or requirements of a
126     particular application.
128     For example, \CLIM{}'s application framework and adaptive toolkit
129 cfruhwirth 1.2 allow programmers to develop applications that automatically adopt the look
130 rgoldman 1.3 and feel of the host's environment. We often call this
131 cfruhwirth 1.1 ``adaptiveness,'' ``look and feel independence,'' or occasionally more
132 rgoldman 1.3 picturesquely, ``chameleon look and feel''. However, many users may
133     need or want to define a particular look and feel that is constant
134 cfruhwirth 1.2 across all host environments (we call this ``portable look and
135     feel''). Such users can circumvent the look and feel adaptiveness
136 cfruhwirth 1.1 provided by \CLIM{}, while still using most of the application
137     framework facility and other high level \CLIM{} facilities like
138     context sensitive input. Furthermore, using the lower level facilities
139     of \CLIM{}, they can develop portable toolkit libraries that define
140     and implement their own particular look and feel. For instance, the
141 cfruhwirth 1.2 \CLIM{} programmer can implement new gadget types on top of the drawing
142     primitives and treat them equally to the built-in gadget types.
143 cfruhwirth 1.1
144     We will use the term \concept{CLIM implementor} for the party
145     implementing low-level and high-level parts according to the \CLIM{}
146     specification, \concept{CLIM programmer} for the party that will use
147     the facilities provided by the implementor, and \concept{CLIM user}
148     for the party that will use the programs provided by the programmer.
150     The next section presents an overview of the functionality provided by
151     \CLIM{} facilities.
153     \section{Overview of Functionality}
155     Figure \ref{clim-facilities} shows the various aspects of a host
156     environment in which \CLIM{} lives as well as the various elements
157     provided by \CLIM{}. Below we briefly describe a number of \CLIM{}'s
158     areas of functionality. Later sections will illustrate many of these
159     components.
161     \paragraph*{Geometry} \CLIM{} provides points, rectangles, and
162     transformations; and functions for manipulating these object types.
164     \begin{figure*}
165     \begin{center}
166     \input{techno-dep.pstex_t}
167     \end{center}
168     \caption{An Overview of \CLIM{} facilities}\label{clim-facilities}
169     \end{figure*}
171 rgoldman 1.3 \paragraph*{Graphics substrate} \CLIM{} provides a portable interface
172 cfruhwirth 1.1 to a broad set of graphics functions for drawing complex geometric
173     shapes.
175     \paragraph*{Windowing substrate} \CLIM{} provides a portable layer for
176     implementing sheets (windows and other window-like objects).
178     \paragraph*{Extended Streams} \CLIM{} integrates the Common Lisp
179     Stream I/O functionality with the \CLIM{} graphics, windowing, and
180 rgoldman 1.3 panes facilities.
181     % I believe that this was what was intended [2006/03/14:rpg]
182     In addition to ordinary text, the programmer can send a
183 cfruhwirth 1.1 button, a picture or any other arbitrary widget to a \CLIM{} output
184     stream and \CLIM{} will display the widget in the sheet associated
185     with the output stream.
187     \paragraph*{Output Recording} \CLIM{} provides output recording for
188     capturing all output done to an extended stream and automatically
189     repainting it when necessary.
191     \paragraph*{Formatted Output} \CLIM{} provides a set of high-level
192     macros that enable programs to produce neatly formatted tabular and
193     graphical displays easily.\footnote{This also includes Graph
194 rgoldman 1.3 Formatting. Graph formatting is only partly implemented in McCLIM
195     at this date (March 2006).}
196 cfruhwirth 1.1
197     \paragraph*{Presentations} \CLIM{} provides the ability to associate
198     semantics with output, such that Lisp objects may be retrieved later
199 cfruhwirth 1.2 via user gestures (e.g.{} mouse clicks) on their displayed
200 cfruhwirth 1.1 representation. This context sensitive input is modularly layered on
201     top of the output recording facility and is integrated with the Common
202 rgoldman 1.3 Lisp type system.
203     % I understand this, but I suspect it's not going to be obvious to the
204     % ordinary reader why type coercion provides the basis for a user
205     % interface... [2006/03/14:rpg]
206     A mechanism for type coercion is also included,
207 cfruhwirth 1.1 providing the basis for powerful user interfaces.
209     \paragraph*{Panes} \CLIM{} provides \concept{panes} that are analogous
210     to the gadgets or widgets of toolkits like the X toolkit, GTK or Mac
211     OS X's toolkit.
213     Supported pane types include layout panes for arranging other panes,
214     gadget panes for presenting users with feedback information or
215     mechanisms for invoking application behavior, and application panes
216     for displaying and allowing users to interact with application data.
218     \paragraph*{Look and Feel Adaptiveness} \CLIM{} supports look and feel
219     independence by specifying a set of abstract gadget pane
220     protocols. These protocols define a gadget in terms of its function
221     and not in terms of the details of its appearance or
222 rgoldman 1.3 operation. Applications that use these gadget types and related
223 cfruhwirth 1.1 facilities will automatically adapt to use whatever toolkit is
224 rgoldman 1.3 available on and appropriate for the host environment. In addition,
225 cfruhwirth 1.1 portable Lisp-based implementations of the abstract gadget pane
226 thenriksen 1.6 protocols are provided.\footnote{\mcclim{} does not support look and
227     feel adaptiveness at the moment except for the experimental beagle
228     backend for Mac OS X's Cocoa platform, or the Gtkairo backend using
229     GTK. Hence, \mcclim{} mostly uses this portable Lisp-based
230 cfruhwirth 1.1 implementation.}
232     \paragraph*{Application Building} \CLIM{} provides a set of tools for
233     defining application frames. These tools allow the programmer to
234     specify all aspects of an application's user interface, including pane
235     layout, interaction style, look and feel, and command menus and/or
236     menu bars.
238     \paragraph*{Commands} \CLIM{} supports the separation of command
239     execution and command invocation. A \CLIM{} user can invoke commands
240     either via typing it into an interactor, clicking on a menu entry or
241     implicitly invoking a presentation-translator by clicking on a
242     presentation. Commands can also be invoked explicitly by the
243     programmer.
245 rgoldman 1.3 % added ``Redisplay'' below so that the paragraph header harmonizes
246     % with the jargon used in the paragraph.
247     \paragraph*{Dialogs and Incremental Update/Redisplay} Incremental Redisplay goes
248 cfruhwirth 1.1 a bit further than Output Recording. With Incremental Redisplay, an
249     output record can not only reproduce content that was written to a
250     stream, the \CLIM{} programmer can also attach the code that generated
251     the content to the content itself. Whenever necessary, the application
252     programmer can ask an output stream to update itself. \CLIM{} will
253 cfruhwirth 1.2 query all drawn elements for obsolescence, and if necessary, rerun the
254     code to produce fresh output.
255 cfruhwirth 1.1
256     \noindent\hrulefill
258 cfruhwirth 1.2 \noindent This is a large number of facilities to explore. The most
259     systematic way -- progressing from the lowest-level to the highest
260     -- would also be the lengthiest. Therefore, we start
261 cfruhwirth 1.1 with showing several facilities in action with the most fundamental
262     example in the realm of programming: Hello World.
264     \section{Our first application}
266 rgoldman 1.3 We will start with a few lines of code for the trivial Hello World example
267 cfruhwirth 1.1 to give the reader a test case to verify his \CLIM{} setup. It also
268     serves as a point of reference from where the reader can start his
269 rgoldman 1.3 explorations of more challenging \CLIM{} facilities. We do not try to
270 cfruhwirth 1.1 elaborate the \CLIM{} concepts in detail here, but simply use them
271     with a brief discussion. The confused reader may hope for a more
272     in-depth explanation in the following section. Please regard
273     \concept{pane}, \concept{application frame}, \concept{sheet},
274     \concept{sheet hierarchy}, \concept{graft} and \concept{top-level
275     loop} as terms we will discuss later.
277 rgoldman 1.3 We provide extensive \CLIM{} specification references in
278 cfruhwirth 1.1 footnotes. The motivation for this is to show that all the relevant
279     information can be found in the \CLIM{} 2
280     specification\cite{clim-spec}. Before a good \CLIM{} programmer can
281     master any \CLIM{} concept, he has to get used to the style of writing
282 rgoldman 1.3 of the specification, as this is the most relevant work for
283     \CLIM{}. The best we can do in this short paper is provide pointers and
284 cfruhwirth 1.1 references and hope that the interested reader starts to explore the
285     surrounding text sections on his own.
287 cfruhwirth 1.2 After loading a \CLIM{} implementation, the package
288     \keyword{:clim-user} is available to absorb user code. This package is
289 rgoldman 1.3 a good start for experimentation and first steps. When proper
290 cfruhwirth 1.2 packaging is required, simply include the packages \keyword{:clim} and
291 rgoldman 1.3 \keyword{:clim-lisp} in your new package's \keyword{:use} list.
292 cfruhwirth 1.2
293 cfruhwirth 1.1 The central element of \CLIM{} application programming is the
294     \concept{application-frame}. An application frame is defined via
295     \code{define-application-frame}.\footnote{See Section 28.2 ``Defining
296 rgoldman 1.3 and Creating Application Frames'' in \cite{clim-spec}.} Here is
297     the application frame definition for Hello World:
298 cfruhwirth 1.1 \lstset{style=inlinestyle}
299     \lstinputlisting{hello-world-def-app}
301     \begin{figure*}
302     \lstset{style=framestyle}
303     \lstinputlisting{hello-world-handle-repaint}
304     \caption{\method{handle-repaint} for \class{hello-world-pane}}\label{hello-world-repaint}
305     \end{figure*}
306 rgoldman 1.3 \code{define-application-frame}'s basic syntax is similar to \code{defclass} because
307 cfruhwirth 1.1 \code{define-application-frame} also generates classes. In this case,
308     it creates a frame class \class{hello-world} that has no superclass
309 rgoldman 1.3 except \class{frame} (which is added automatically).
310 cfruhwirth 1.1
311     With \code{:pane}, we define a \concept{top-level-pane} that becomes
312 rgoldman 1.3 the content of a fresh window that belongs to an application
313     frame. Although the usual case is for an application frame to
314     correspond to a top level window, sometimes an application frame is swallowed by another
315     application and only space in another existing window is
316 cfruhwirth 1.1 reserved. For instance, a web site management tool might swallow a
317 rgoldman 1.3 text editor, so that the user has the option to edit web sites without
318 cfruhwirth 1.1 switching to another application.
320     % \footnote{The graft is the root of a sheet hierarchy and on most
321     % windowing system, all children of a graft are mapped to windows.}
322     % With elaborating on details, this means that the content of the
323     % top-level-pane becomes the content of the application
324     % window.\footnote{This is not 100\% correct. A frame might decorate
325     % the top-level-pane with a menu-bar or other refinements. The pane
326     % adopted by the graft is then a composite pane containing a
327     % menu-bar and the original top-level-pane.}
329     The list given after the \keyword{:pane} option is a form which is
330     evaluated when an instance of the \class{hello-world} class is
331     created. We use \method{make-pane} to construct a pane as the
332     top-level-pane for frame instances. \method{make-pane} is a
333     constructor for panes.\footnote{See Section 29.2 ``Basic Pane
334 rgoldman 1.3 Construction'' in \cite{clim-spec}.} We can treat it as an analog to
335 cfruhwirth 1.1 \code{make-instance} especially made for pane classes. Let us have a
336     look at the definition of \class{hello-world-pane}.
338     \lstset{style=inlinestyle} \lstinputlisting{hello-world-defclass}
340     The one and only superclass of \class{hello-world-pane} is
341 rgoldman 1.3 \class{clim-stream-pane}.\footnote{See Section 29.4 ``CLIM Stream
342     Panes'' in \cite{clim-spec}.} As there are no additional slots, an
343     experienced \CLOS{} programmer might guess that we will use
344 cfruhwirth 1.2 \class{hello-world-pane} solely for method specialization. Before doing so,
345     let us have a look what we have actually
346 rgoldman 1.3 inherited from \class{clim-stream-pane}:\footnote{Internal classes
347     removed from listing.}
348 cfruhwirth 1.1
349     \lstset{style=inlinestyle}
350     \begin{lstlisting}
351     CLIM-USER> (describe (find-class
352     'clim-stream-pane))
360     BASIC-PANE
361     \end{lstlisting}
363 rgoldman 1.3 % would it be appropriate to define the phrase ``protocol class''
364     % here? I'm not sufficiently confident in my CLIM fu to provide a
365     % definition myself. [2006/03/14:rpg]
367 cfruhwirth 1.1 \class{basic-pane} is the foundation of all pane classes. It provides
368     reasonable defaults for all protocol methods and inherits from the
369     protocol class \class{pane}. In turn, \class{pane} inherits from
370     \class{basic-sheet}. Hence, all panes we construct via
371     \class{basic-pane} automatically adhere to the sheet protocol.
373     % The standard extended-input provides \class{clim-stream-pane} with a
374     % concept called \concept{command-inversion}. This concept allows the
375     % treatment of events as if they were coming from a stream with
376     % blocking reads.
378     % The permanent-sheet-output-mixin class delivers all methods for the
379     % \concept{output protocol} \footnote{See Section 8.3 ``Output
380     % Protocol'' in \cite{clim-spec}}. This protocol used for delivering
381     % output to the user's screen. The special feature of this mixin is
382     % that the output medium is always present, it's permanent. That
383     % means, there is always a screen on which graphic operations can be
384     % carried out. In contrast, there are also output classes, that does
385     % not guarentee an output medium, but more on that later.
387     Our \class{hello-world-pane} needs some methods to be useful. With
388     \method{handle-repaint} in \figurename~\ref{hello-world-repaint}, we
389     participate in the \concept{repaint protocol}.\footnote{See Section
390     8.4 ``Repaint Protocol'' in \cite{clim-spec}} This method has two
391     tasks: paint the pane with the pane's background and draw the greeting
392     of \code{*application-frame*} in the center of the pane. The
393     \code{hello-world} frame instance is automatically available in the
394     context of \method{handle-repaint} via the dynamically scoped variable
395     \code{*application-frame*} and so it is possible to use the accessor
396     \code{greeting} to obtain the instance's slot content.
398     Two functions are needed to see this code in action:
399     \code{make-application-frame} and \code{run-frame-top-level}. The
400     former is a constructor for instances of frame classes, the latter for
401     running the \concept{top-level loop} of the application frame. The
402     top-level loop is used for command reading, execution and displaying
403     results. But all we need to know for the moment is that it makes the
404     frame visible before entering the loop.
405     \lstset{style=inlinestyle}
406     \begin{lstlisting}
407     (run-frame-top-level
408     (make-application-frame 'hello-world))
409     \end{lstlisting}
410     This completes the Hello World example. In the next section, we catch
411     up to the details we skipped in this example.
413     \section{Basic Facilities}
415     \subsection{Geometry}
417 rgoldman 1.3 % The footnote describing ``protocol'' below seems to give a critical
418     % insight into the style and functioning of CLIM. It should certainly
419     % be promoted out of footnote and into body text. I'm inclined to
420     % think it should be promoted to the introduction. The notion of
421     % Protocol is alluded to there, but not clearly described.
422     % [2006/03/14:rpg]
424 cfruhwirth 1.1 To \CLIM{}, geometry means \concept{regions}. A region is either bound
425     or unbound and has a dimensionality of either zero, one or two. That
426     corresponds to a point, a path or an area respectively. Regions can be
427 cfruhwirth 1.2 compared (region predicate protocol\footnote{\CLIM{} relies heavily on
428     \CLOS{}. In \CLOS{}, the term \concept{protocol} means a set of generic
429 cfruhwirth 1.1 functions that together form a coherent interface. A protocol
430 cfruhwirth 1.2 specification not only includes the syntactic details of the
431 cfruhwirth 1.1 function names and the number of function arguments, but also the
432 cfruhwirth 1.2 functions' purpose and the semantics of the return values (and/or side
433 cfruhwirth 1.1 effects) must be given in a textual specification.}) and composed
434     (region composition protocol).
436     Every bounded region has a \concept{bounding rectangle}. It is the
437     smallest rectangle that contains every point in the region. The
438     bounding rectangle of every bounded region can be accessed via the
439     \concept{bounding rectangle protocol}.
441     \CLIM{} supports \concept{affine transformations} of regions. Such
442     transformations can move, stretch and rotate a region. A
443     transformation is affine when every straight line remains straight
444     after transformation. Transformations can be composed arbitrarily. The
445     programmer can attach transformations to mediums and panes. In layout
446 rgoldman 1.3 panes, \CLIM{} uses transformations to map the coordinates of child
447     panes to the coordinate system of their parents.
449     % This was attached to the previous paragraph, but doesn't seem to
450     % have anything to do with its topic. I'm inclined to think that this
451     % could use some further expansions (have we adequately explained what
452     % a drawing setting is?) [2006/03/14:rpg]
453     All drawing settings can be changed either permanently, or temporarily
454     in the context of the \macro{with-drawing-options} macro.
455 cfruhwirth 1.1
457     \subsection{The Windowing Substrate}
459     \CLIM{} does not directly talk to the window system. Instead, \CLIM{}
460 cfruhwirth 1.2 is layered on top of a windowing substrate.\footnote{formerly known as Silica.}
461 cfruhwirth 1.1 This substrate is a middleware between \CLIM{} on one side and the
462     host window system on the other. This middleware layer provides a
463     portable windowing model that insulates higher levels of \CLIM{} and
464     \CLIM{} programmers from the details of the host window system. From
465     the perspective of a \CLIM{} programmer, talking to the window system
466     is equal to talking to this abstraction layer. The implementation
467 cfruhwirth 1.2 details are hidden in \concept{backends}, like in \mcclim{} the CLX
468 cfruhwirth 1.1 backend, which hides X11 details, or the beagle backend, which hides
469     details for Mac OS X's toolkit. These backends will use the services
470     of a host window system to provide efficient windowing, input and
471     output facilities. Thanks to this middleware, \CLIM{} is portable
472     across different host windowing systems.
474     This framework allows uniform treatment of the following GUI building
475     blocks:
476     \begin{itemize}
477     \item Windows like those in X, Mac OS X and Microsoft Windows.
478 cfruhwirth 1.2 \item Gadgets typical of toolkit layers, such as Gtk+, QT or Mac OS X's
479 cfruhwirth 1.1 toolkit. The backend provides a frame manager which takes care of
480     mapping the abstract gadget types found in \CLIM{} to appropriate
481     gadget with a native look and feel.
482     \item Structured graphics like output records and an application's
483     presentation objects
484     \end{itemize}
486     The central abstraction specified by \CLIM{} is the \concept{sheet}. A
487     sheet is a surface that can be painted on and to which input gestures
488     can be directed, and that lives in a hierarchy of other such objects.
489     To get used to the notation of sheets, you can think of them as
490     swallowable windows.
492     The fundamental notion in \CLIM{} is the nesting of sheets within
493     another sheet called a windowing relationship. In a windowing
494     relationship, a parent sheet provides space to or groups a number of
495     other children sheets. The \concept{sheet protocols} specify
496     functionality for constructing, using, and managing hierarchies of
497     sheets.
499     Sheets have the following properties:
500     \begin{description}
501     \item[parent/children:] a sheet is part of a windowing hierarchy and
502     maintains links to its parent and its children.
503     \item[coordinate system:] a sheet has its own coordinate system that
504     might have a different scaling or orientation than its parent.
505     \item[transformation:] via a sheet transformation these differing
506     sheet coordinate systems are mapped into coordinate system of their
507     parents.
508     \item[clipping region:] defines an area within a sheet's coordinate
509     system that indicates the area of interest.
510     \end{description}
512     \paragraph*{Window hierarchies} Sheets participate in a number of
513     protocols. The windowing protocols describes the relationship between
514     sheets. Every sheet has a parent, a sheet might have one or more
515     children. A sheet can be adopted by a parent sheet and disowned later.
516     A sheet is grafted when it is connected to a \concept{graft} either
517     directly or through it's ancestors. A graft is a special kind of sheet
518 cfruhwirth 1.2 that stands in for a host window, typically a root window (i.e.{} screen
519 cfruhwirth 1.1 level). A sheet is attached to a particular host window system by
520     making it a child of an associated graft. A host window will be
521     allocated for that sheet; the sheet will then appear to be a child of
522     the window associated with the graft.
524     Sheet hierarchies are displayed and manipulated on particular host
525     window systems by establishing a connection to that window system and
526     attaching them to an appropriate place in that window system's window
527     hierarchy. Ports and grafts provide the functionality for managing
528     this process. A port is a connection to a display service that is
529     responsible for managing host window system resources and for
530     processing input events received from the host window system.
532     \paragraph*{Window input} The input architecture of the windowing
533     substrate allows sheets to receive any window event from the host
534     windowing system. The event class hierarchy descends from the class
535     \code{event} to \code{device-event} (including all keyboard and mouse
536     actions), \code{window-event} (window-size-changed and window-repaint
537     events), \code{window-manager-events} (window-deleted) to artificial
538     \code{timer-events}. See 8.2 ``Standard Device Events'' in
539     \cite{clim-spec}.
541     The function pair \code{dispatch-event} and \code{handle-event} is the
542     center of all event handling. \code{dispatch-event} is intended to be
543     called when an event is to be dispatched to a client either
544     immediately or queued for later processing in an event queue. On the
545     other side, \code{handle-event} is intended for further
546     specialization, so the application developer can implement special
547     policies for selected events. For instance, when a sheet notices
548     through a \code{window-configuration-event} that the sheet's size
549 rgoldman 1.3 has changed, it might redo its layout for its children.
550 cfruhwirth 1.1
551     % There are two mixins that specialize on the
552     % \code{window-repaint-event} class as event argument to
553     % dispatch-event. The mixins are named standard-repaint-mixin and
554     % immediate-repainting-mixin. The first queues the repaint events when
555     % they arive via dispatch-event and redirect calls to handle-event
556     % with repaint events to the method handle-repaint. The latter mixin
557     % also redirects handle-event to handle-repaint for repaint events,
558     % but in contrast to the former it also immediately calls
559     % handle-repaint for any events ariving via dispatch-event. See Figure
560     % \ref{fig1}.
562     % \paragraph*{The repaint protocol} By demonstrating the use of
563     % handle-event with the repaint mixins, we have actually shown smaller
564     % protocol at work: the \concept{repaint protocol}. It's usually
565     % triggered by events generated from the host window system via the
566     % handle-event mechanism, but the \CLIM{} programmer can also trigger
567     % a repaint manually via the \code{repaint-sheet} function. The
568     % programmer should specialize on handle-repaint for his own classes.
569     % We have done that in the Hello World example.
571     \paragraph*{Window output}
573     All drawing operation happen on a \concept{medium}. This object
574     captures the state of the drawing like foreground, background, line
575     style, and the transformation which is applied to the coordinates
576     before drawing. Every medium is associated with a sheet. In turn, a
577     sheet must be associated with a medium whenever drawing operation
578     should be executed. Many \CLIM{} sheets are associated with a medium
579     permanently. \code{sheet-medium} obtains the medium associated with a
580     sheet.
581     % \footnote{Notice that the \CLIM{} specification \cite{clim-spec}
582     % specifies draw-text, draw-line, draw-rectangle, etc. as functions
583 cfruhwirth 1.2 % that operate on mediums. \mcclim{} names these functions
584 cfruhwirth 1.1 % medium-draw-text, medium-draw-line, medium-draw-rectangle, and so
585 cfruhwirth 1.2 % on. The functions that are available in \mcclim{} without the
586 cfruhwirth 1.1 % ``medium-'' prefix operate on sheets. These are trampoline
587     % functions that call the appropriate medium-prefixed function on
588 cfruhwirth 1.2 % the sheet's medium. According to the \mcclim{} authors, this is done
589 cfruhwirth 1.1 % for optimization.}
591 rgoldman 1.3 % in the topic sentence here, should it read ``of sheets'' or ``of
592     % mediums'' (media?). I'm not sure, but if ``sheets'' is meant, we
593     % should probably have some transition wording here to explain how we
594     % got from discussing mediums above to discussing sheets here.
595     % [2006/03/14:rpg]
597 cfruhwirth 1.1 The graphic output capabilities of sheets range from simple line style
598     and text style customization over rendering various geometrical
599     shapes, a color model capable of doing alpha blending, composable
600     affine transformations to pattern, stencil and tiling filling, and
601     pixmaps usage. The features of the \concept{output protocol} are
602     specified briefly in Section 8.3 ``Output Protocol''and more precisely
603     in Chapters 10-14 of \cite{clim-spec}.
605 rgoldman 1.3 \CLIM{} lives in an idealized world in terms of graphics operations. A
606 cfruhwirth 1.1 \CLIM{} programmer can use an infinitely long and wide drawing pane
607 rgoldman 1.3 with arbitrarily precise resolution and continuously variable
608 cfruhwirth 1.2 opacity. As rendering devices with these properties are rare,
609     we need to render the idealized graphic description to a device
610 cfruhwirth 1.1 with finite size and a fixed drawing precision. The rendering rules
611     are specified in Section 12.4 ``Rendering Conventions for Geometric
612     Shapes''of \cite{clim-spec}.
614     \section{Building Applications}
616     In this section, we explain a number of the necessary ingredients for
617     building applications in \CLIM{}. We will illustrate frames, panes,
618     and simple commands with two examples: a color editor and a simple
619     line and text drawing program.
621     \subsection{Application Frames}
623     Frames are the central abstraction defined by the \CLIM{} interface
624     for presenting an application's user interface. Many of the high level
625     features and facilities for application building provided by \CLIM{}
626     can be conveniently accessed through the frame facility.
628     Frames are typically displayed as top level windows on a desktop.
629     \concept{Frame managers} provide the machinery for realizing frames on
630     particular host window systems. A frame manager acts as an mediator
631     between the frame and what is typically called a desktop manager, or
632     in X terminology, a window manager. The \concept{frame manager} is
633     responsible for attaching the pane hierarchy of a frame to an
634     appropriate place in a sheet hierarchy (and therefore to a host window
635     system window hierarchy) when the frame is adopted.
637     To build a user interface, an application programmer defines one or
638 rgoldman 1.3 more frame classes. These frame classes define a number of frame
639 cfruhwirth 1.1 properties including application specific state and a hierarchy of
640 cfruhwirth 1.2 panes (i.e.{} user interface gadgets and regions, for interacting with
641 cfruhwirth 1.1 the users). Frame classes also provide hooks for customizing
642     application behavior during various portions of the frame protocol.
643     For example, an \keyword{:after} method on generic functions in the
644     frame protocol can allow applications to manage application resources
645     when the frame is made visible on some display server.
647     \CLIM{} is able to show dialog windows, but the code that brings them
648     up is usually quite different from the code that is used to generate
649     the content of application frames. This is unusual for a windowing
650     toolkit as most of them unify the generation of dialog content and
651 rgoldman 1.3 content of other window types.
652 cfruhwirth 1.1
653     \CLIM{} generates a dialog with the appropriate input gadget as
654     consequence of a series of input requests. Thanks to the stream
655     facility, the programmer can actually request input synchronously with
656     a blocking read request. He does not have to take care of
657     asynchronously handling confirmation or cancel button clicks. For
658     instance, the programmer requests a string from the user and the user
659     is presented with a prompt, an editable text field, and two buttons
660 rgoldman 1.3 for confirmation and canceling.
661     The string requesting function returns only after the user hits the
662     confirmation button. The
663 cfruhwirth 1.1 programmer can directly use the function's return value which is the
664 rgoldman 1.3 string provided by the user.
665     % Is the following rewrite correct? Seems like in the actual code an
666     % abort-gesture is signaled, but it is handled by invoking an abort,
667     % if no abort-gesture handler is found. [2006/03/14:rpg]
668     % OLD:
669     % Clicking the cancel button is dealt with by throwing to an
670     % \code{abort} tag.
671     Clicking the cancel button is dealt with by signaling an abort-gesture
672     condition.
673 cfruhwirth 1.1
674 cfruhwirth 1.2 From the caller's perspective, an attempt to separate application
675 cfruhwirth 1.1 frames and dialogs could be: a dialog window itself is side-effect
676     free with respect to the application state and therefore the whole
677     sense of calling a dialog creation routine must arise from the values
678     it returns. For example, the code that modifies the state of the text
679     editor in a text-replace operation does not rest with the callback
680     code of the Ok button in the dialog. This task rests with the code
681     that is executed after the dialog returns its values, namely the code
682     of the Search/Replace command.
684     % \footnote{This isn't a sharp distinction. We can also reinterprete
685     % an application frame as something resulting from a command in
686     % progress at a higher level. For instance, assume the application
687     % frame to be the intermediate dialog resulting from the click on
688     % your text editor icon of the desktop's launch menu/button, or to
689     % be the result from typing the application name in your shell. A
690     % more nifty example would be a text editor that allows embedded
691     % graphics which can be edited in-place by graphics editor. The text
692     % editor's application frame would then use another the graphic
693     % editor's application frame intermediately returning the modified
694     % graphic object.}
696     An intermediate dialog is something that is brought up to collect
697     additional information for (or before) an operation. When the user
698     selects the ``Search'' command, he is queried for a search string in
699     an additional dialog window; probably offering other search options
700 cfruhwirth 1.2 like case-insensitive search or backwards search. This is done in a
701 cfruhwirth 1.1 synchronous manner, blocking until the requested input is made
702     available by the user.
704     % The notation of sheets already capture the idea of windows.
705     % Remember, sheets are drawable entities that can receive user input.
706     % In fact, the entire screen area is also represented as sheet. The
707     % sheet representing the whole screen real-estate is named
708     % \concept{graft} in \CLIM{}\footnote{In X terminology, a graft would
709     % be called root window.}. To create a new window, we have to order
710     % a graft to adopt a new sheet as its children. The new sheet is
711     % inserted into the sheet hierarchy below the graft (the sheet is said
712     % to be \concept{grafted}). But actually, we rarely do it that way.
714     % \CLIM{} provides a higher level abstraction of windows and what
715     % their purpose are. In \CLIM{}, we either have application frames or
716     % intermediate dialogs.
718     An application frame is an interface that provides the user with a
719     variety of commands to choose as his next step. For instance, the user
720     may choose from commands like Open, Save, Search, or Quit. The frame
721 cfruhwirth 1.2 is a long-living GUI object compared to dialogs, and there is no linear
722 cfruhwirth 1.1 execution path as there is in after a dialog as the user is free to
723 cfruhwirth 1.2 select any commands he likes as his next action.
724 cfruhwirth 1.1
725     Hence, the synchronous programming pattern for dialogs is more
726     convenient because after dialog confirmations there is a predetermined
727     path of execution, while an application frame has to be prepared to
728     handle an arbitrary sequence of commands.
730     % In contrast to dialogs, application frames tend to life longer than
731     % dialogs. Hence, application frames are usually required to maintain
732     % some state of some form. This is also the reason why
733     % \method{define-application-frame} was implemented on top of
734     % \macro{defclass}. A dialog does not need to maintain state as they
735     % are disposed too quickly.\footnote{They do have a state but this
736     % state is not important to the programmer as it mostly consist of
737     % state of the input gadgets, like the content of a text input
738     % field. The amount of information contained in there is usually
739     % neglectible, so we do not speak of state management here.}
741     % \paragraph*{Frame Managers} One important function provided by a
742     % frame manager is to adapt a frame to the look and feel of the host
743     % window manager. Before the top-level loop of a frame is entered, the
744     % frame is adopted by a frame manager provided by a \CLIM{} backend.
747     \subsection{Panes}
749     An application frame constructs its pane tree by specifying a
750     top-level pane in \macro{define-application-frame}. This pane is
751     usually a layout pane that contains more gadget and/or layout panes as
752     its children. With the help of layout panes, a pane hierarchy can be
753 cfruhwirth 1.2 constructed. The top-level pane (and the whole hierarchy when it is a
754 cfruhwirth 1.1 layout pane) is created when the application frame is adopted by a
755     frame manager and made visible to the user. The programmer can compose
756     an interface consisting of pre-defined gadget panes, layout panes, or
757     application-specific panes. \CLIM{} panes are rectangular sheets that
758     are analogous to the gadgets or widgets of other toolkits.
760     Panes and sheets as defined by the windowing substrate have in common
761     that they are associated with a region on screen, a parent, and
762     optional children. They differ in their usage of the input and output
763 rgoldman 1.3 capabilities. A sheet is passive and intended to be used by other,
764     active components,
765     while a pane already contains this active part.
766     For this reason,
767     panes are implemented as subclasses of \class{basic-sheet}
768 cfruhwirth 1.1 augmenting the class with an active part. For instance, a button-pane
769     actively draws its own button representation on its allotted screen
770     area and a click on the correct button area triggers a callback for
771 cfruhwirth 1.2 the button. A composite pane lays out its child elements and
772     requests them to draw themselves onto specific screen regions.
773 cfruhwirth 1.1
774     \CLIM{} comes with a set of predefined gadget panes. They consist of
775     push-button, toggle-button, slider, radio-box, text-field, text-editor
776     panes ready for use by the \CLIM{} application programmer. These
777     gadgets might be remapped to native system gadgets by the frame
778     manager, so a native look and feel is possible.\footnote{Only possible
779 cfruhwirth 1.2 in \mcclim{} with the experimental beagle backend for Mac OS X.}
780 cfruhwirth 1.1
781     Each gadget pane class is associated with a set of generic functions
782 cfruhwirth 1.2 that act as callbacks do in traditional toolkits. For example, a pushbutton
783 cfruhwirth 1.1 has an ``activate'' callback method which is invoked when its button
784     is pressed. For this particular callback, a method named
785 cfruhwirth 1.2 \method{activate-callback} is invoked by default, and a \CLIM{}
786     programmer can provide a specialized method to implement
787     application-specific behavior for a subclassed button-pane. But except
788 cfruhwirth 1.1 in the case where the programmer needs a lot of buttons with related
789     behavior, creating a subclass for changing a single specific callback
790     is not economical. Hence upon gadget creation, the programmer can
791 rgoldman 1.3 specify an alternative callback method for any callback available. For
792     example, by
793 cfruhwirth 1.1 providing the \keyword{:activate-callback} initarg, the programmer can
794     change the callback to any regular or generic function. By convention,
795 rgoldman 1.3 any callback can be changed by providing an initarg keyword equal to
796 cfruhwirth 1.1 the callback's name. See Chapter 30 in \cite{clim-spec} for a listing
797     and description of available callbacks.
799     \CLIM{} also provides composite and layout panes. These pane types are
800 rgoldman 1.3 used for aggregating several child panes into a bigger single pane
801 cfruhwirth 1.1 that has a layout according to the requested directives. For example,
802     \CLIM{} provides two pane classes, \class{hbox-pane} and
803     \class{vbox-pane}, that lay out their children in horizontal rows or
804     vertical columns respectively. The parent/child relations are managed
805     via the sheet's windowing protocol. If the user interface does not
806     change in ways unpredictable in advance (as in a user interface
807     builder for instance), the program does not have to do hierarchy
808     management via the windowing protocol. He is provided with a set of
809     convenience macros that allows elegant interfaces composed simply by
810     wrapping the respective pane construction code into the convenience
811 rgoldman 1.3 macros. % could we name the convenience macros here? [2006/03/14:rpg]
812 cfruhwirth 1.1
813     Application pane classes can be used for subclassing. They can be used
814     to present application specific data -- for instance by specializing
815 rgoldman 1.3 \method{handle-repaint} -- and to manage user interactions -- for
816 cfruhwirth 1.1 instance by specializing \method{handle-event}.
818     \subsection{Commands}
820     Most applications have a set of operations that can be invoked by the
821     user. In \CLIM{}, the command facility is used to define these
822     operations. Commands support the goal of separating an application's
823     user interface from its underlying functionality. In particular,
824     commands separate the notion of an operation from the details of how
825     the operation is invoked by the user.
827     Application programmers define a command for each operation that they
828     choose to export as an explicit user entry point. A command is defined
829     to have a name and a set of zero or more operands, or arguments. These
830     commands can then be invoked using a variety of interaction
831 rgoldman 1.3 techniques. For example, commands can be invoked from menus, keyboard
832 cfruhwirth 1.1 accelerators, direct typein, mouse clicks on application data, or
833     gadgets.
835     The commands are processed in a REPL-like loop. Every application
836     frame has its own running top-level loop specified via
837     \keyword{:top-level} in \method{define-application-frame}. For a
838     \CLIM{} application, it is rarely necessary to change the default top
839     level loop.
841     The top-level loop becomes visible when an interactor-pane is added to
842     the user interface. Here the \CLIM{} user gains direct access to the
843     command loop. The loop steps are similar to read-eval-print:
845     \begin{enumerate}
846     \item Read a command.
847     \item Execute the command.
848     \item Run the \concept{display function} for each pane in the frame
849     associated with the top-level loop as necessary.
850     \end{enumerate}
852     Whenever a command is invoked other than by typing, an appropriate
853     command-invoking text appears after the command prompt
854     nonetheless. Here, the user can directly see how his commands are
855     synthesized from other invocation methods like pointer clicks or menu
856     item selections.
858     \section{Simple applications}
860     \subsection{Color Editor} In this next example, we define a frame for
861     color selection by manipulating their red, green, and blue components
862     separately. This example illustrates the use of gadget panes provided
863     by \CLIM{}. In the code in Figure \ref{fig-color-editor}, we define an
864     application frame using \method{define-application-frame}. As said
865 cfruhwirth 1.2 before, the syntax of this macro is similar to that of \class{defclass}. It
866 cfruhwirth 1.1 defines a new frame class which automatically inherits from the class
867     \class{frame} which provides most of the functionality for handling
868     frames.
870     One requirement must be fulfilled by all frame definitions: code to
871     generate a pane hierarchy must be supplied. The \keyword{:pane} option
872 cfruhwirth 1.2 is the simplest way to supply this code. The \class{hello-world} frame
873 cfruhwirth 1.1 constructs a hierarchy with only one application pane via
874     \method{make-pane}. The pane hierarchy of color editor is more
875     interesting.
877     Every pane can request space via its initarg. A request for space
878     allocation is specified as a preferred size (\keyword{:height},
879     \keyword{:width}), a maximum size (\keyword{:max-height},
880     \keyword{:max-width}), and a minimum size (\keyword{:min-width},
881     \keyword{:max-width}). The special constant \constant{+fill+} can be
882     used to indicate the tolerance for any width or height.
884     The color editor frame uses three application slots for storing the
885     current RGB values as well as two panes for showing the currently
886     selected colors. The variable \variable{*application-frame*} is
887     dynamically scoped and is defined in any event handler as well as for
888     all code that is evaluated in the context of the \keyword{:pane(s)}
889     frame option.
891     \begin{figure*} \lstset{style=framestyle}
892     \lstinputlisting[firstline=7]{color-editor.lisp}
893     \caption{Color Editor}\label{fig-color-editor}
894     \end{figure*}
896     The code provided in the \keyword{:pane} option in Figure
897     \ref{fig-color-editor} uses all three kinds of panes provided by
898     \CLIM{}. It uses two application-panes to display colors, two layout
899     panes (\class{vbox-pane} and \class{hbox-pane}) and three gadget panes
900     (\class{slider-pane}).
902     In contrast to \class{hello-world}, we do not need a specialized pane
903     class here. We can use an application-pane for displaying chosen
904     colors. An application pane supports graphics operations and invokes
905     generic functions on the pane when input events are received. For the
906     color editor, we only need its ability to refresh its background
907     color.
909     The \macro{vertically} and \macro{horizontally} convenience macros
910     provide an interface to the \class{hbox-pane} and \class{vbox-pane}
911     classes. Most \CLIM{} layout panes provide similar convenience
912     macros. The vertical box pane arranges its children in a stack from
913     top to bottom in the order they are listed at creation in the
914     vertically form. This pane type also supports inter-element space and
915     ``pieces of glue'' at arbitrary points in the children sequence. In
916     the color editor frame, the \constant{+fill+} ``glue'' is used to
917     absorb all extra space when too much vertical space is allocated to
918     the vertical box. \CLIM{} also provides a horizontal box which does
919     the same thing except in the horizontal direction.
921     In the \macro{horizontally} macro in
922     \figurename~\ref{fig-color-editor}, we do not supply forms to be
923     evaluated directly. Instead, \method{horizontally} processes a form
924     wrapped up in a list. The first list element is a rational number
925     which denotes the amount of space the pane generated by the following
926     form is allowed to occupy in the resulting horizontal layout. In our
927     code in \figurename~\ref{fig-color-editor}, \class{hbox-pane}
928     generated from the \macro{horizontally} macro has a space requirement
929     on its own. The whole composite pane is forced to have a size 200
930     pixels high.
932     Now we are ready to turn to the gadget panes. The color editor uses
933     three sliders one for each component of RGB.
934     \method{make-color-slider} creates all three sliders that differ by
935     \variable{id}, \variable{initval} and \variable{label}. The first two
936     variables are handed to \method{make-pane} to construct the slider
937     panes. The remaining initargs for \method{make-pane} are shared across
938     all three entities. To decorate each slider-pane with a proper label,
939     each of them is wrapped up in a \class{label-pane} via the
940     \macro{labelling} convenience macro.
942     The slider gadget protocol defines two callback functions:
943     \method{drag-callback} is repeatedly invoked while the slider is being
944     dragged by the user, and \method{value-change-callback} is invoked
945     when the slider is released in a new location. Notice that this
946     specification is sufficiently abstract to allow a variety of different
947     look and feels for a slider. For example, no guarantee is made as to
948     whether the mouse button is held down during dragging, or whether the
949     mouse button is pressed once to start and again to stop dragging.
951 cfruhwirth 1.2 We use the gadget ID to distinguish between the red, green and blue
952 cfruhwirth 1.1 slider in the callback code. We could use three different callback
953     functions here, but such callbacks would have much more similarities
954     than differences, thus we do not do that here. Instead, we distinguish
955     the gadget by their \variable{id}.
957     The \method{drag-callback} method resets the background of
958     \variable{drag-feedback-pane} and delegates its redrawing to
959     \method{redisplay-frame-pane}, while \method{value-change-callback}
960     does the same for the frame's current color pane. These methods use
961     the \variable{id} argument of the gadget to determine which color
962     component was changed.
964     The color editor frame uses the \keyword{:menu-bar} option to indicate
965     that a menu-bar should be added to the application frame. Frame
966     commands defined with \code{:menu t} are accessible from the
967     menu-bar. In this example, we define only one command named
968     \code{com-quit} which is presented as ``Quit'' to the
969     user. \code{com-quit} is defined via
970     \macro{define-color-editor-command}. This macro is generated
971     automatically along \macro{define-application-frame} from the
972     application frame's name. \code{com-quit} simply closes the
973     application frame causing the termination of the frame's
974     top-level-loop. In the next example, commands will be explored in
975     greater detail.
977     \begin{figure*}[t] \lstset{style=framestyle}
978     \lstinputlisting{draw-frame-def-app}
979     \caption{define-application-frame for
980     \class{draw-frame}}\label{fig-draw-defapp}\label{fig-draw-handlerepaint}
981     \end{figure*}
983     We can invoke the color-editor with the regular
984 thenriksen 1.5 \method{run-frame-top-level}/\method{make-application-frame}
985 cfruhwirth 1.1 combination.
986     \lstset{style=inlinestyle}
987     \begin{lstlisting}
988 thenriksen 1.5 (run-frame-top-level
989     (make-application-frame 'color-editor))
990 cfruhwirth 1.1 \end{lstlisting}
993     \subsection{A simple drawing application}
995 rgoldman 1.4 We move on to a simple application that draws
996 cfruhwirth 1.1 lines and inserts text interactively. Our simple drawing program
997     defines commands for various drawing operations and binds specific
998     input events to these commands.
1000     The application frame is defined in
1001     \figurename~\ref{fig-draw-defapp}. A different approach is used to
1002 cfruhwirth 1.2 generate the pane hierarchy: instead of mixing the layout and pane
1003     information, we use the \keyword{:panes} keyword to list all panes
1004 cfruhwirth 1.1 that should be available in frame layouts. The \keyword{:layouts}
1005     keyword combines them into several layouts. It is possible to define
1006     multiple layouts with this option. We define two simple layouts,
1007     \code{default-layout} and \code{alternative}.
1009 rgoldman 1.4 % I was confused by the discussion of layouts here. Looking at Figure
1010     % 4, I do not see an alternative layout, and the default-default in
1011     % the listing looks odd to me. Is this the remainder of a discussion
1012     % that was deleted or an extension yet to be written? [2006/03/19:rpg]
1014 cfruhwirth 1.1 \begin{figure*}[t]
1015     \lstset{style=framestyle}
1016     \lstinputlisting{draw-frame-commands}
1017     \caption{Commands for \class{draw-frame}}\label{fig-draw-commands}
1018     \end{figure*}
1020     \begin{figure*}
1021     \lstset{style=framestyle}
1022     \lstinputlisting{draw-frame-interfacing}
1023     \caption{User Interfaces}\label{fig-draw-interfacing}
1024     \end{figure*}
1026     There are two options to \macro{define-application-frame} that we have
1027     not seen before, \keyword{:command-definer} and \keyword{:top-level}
1028     (both with there defaults). \keyword{:command-definer} is used to
1029     specify a name for a command-defining macro for this frame
1030     class. Passing \constant{t} to this option (its default) generates a
1031     command definer named
1032     \macro{define-\texttt{<}frame-name\texttt{>}-command}. We can use the
1033 cfruhwirth 1.2 command-defining macro as a convenience macro for
1034     \method{define-command} which is used to define frame commands, and
1035     will see it in action before long. \keyword{:top-level} specifies a
1036 cfruhwirth 1.1 special form that is used as top level command loop. The top level is
1037     responsible for dequeuing and executing commands that have been
1038     invoked by the user. This loop is to a application frame what the REPL
1039     is to a terminal.
1041     This is the first example that does not use \class{clim-stream-pane}
1042 cfruhwirth 1.2 (or one of its subclasses) as a pane class.\footnote{When using \mcclim{},
1043 cfruhwirth 1.1 we have to do this as there are bugs in the behavior of
1044     \class{clim-stream-pane} that have not been fixed yet.} Instead, we
1045     compose our own drawing pane using
1046     \class{standard-extended-input-stream}, \class{basic-pane} and
1047     \class{permanent-medium-sheet-output-mixin}. The first class is used
1048     to provide the application programmer with stream properties for the
1049     draw-pane that are required for the convenience macro
1050     \macro{tracking-pointer}. \class{basic-pane} is responsible for
1051     handling all requests belonging to the sheet and pane protocols in a
1052     standard manner. The last class is a mixin to tag the pane as
1053     permanently visible on screen during its instances' lifetime. Most
1054 cfruhwirth 1.2 static user interfaces use this mixin. Note that \mcclim{} is sensitive
1055     to the order of the superclasses.\footnote{All stream classes like
1056 cfruhwirth 1.1 \class{standard-extended-input-stream} must be listed before
1057 rgoldman 1.4 \class{basic-pane}. Otherwise, no stream handling facilities
1058     will be available.}
1060     % The above footnote refers to what looks like a very big potential
1061     % ``gotcha'' for the beginning McCLIM programmer. Suggestion: promote
1062     % this out of the footnote into body text as a main body paragraph
1063     % here. That paragraph should explain (1) why is it that putting
1064     % basic-pane before standard-extended-input-stream will cause stream
1065     % handling facilities to be crushed and (2) what exactly are the
1066     % implications of not having stream handling facilities. The phrase
1067     % ``stream handling'' hasn't been defined, and it's not obvious what
1068     % these facilities are. [2006/03/19:rpg]
1069 cfruhwirth 1.1
1070     For \class{draw-pane}, the \method{handle-repaint} method shown in
1071 cfruhwirth 1.2 \figurename~\ref{fig-draw-handlerepaint} is straightforward. It
1072 cfruhwirth 1.1 delegates background filling to the next less specific method and then
1073     iterates through the lines and strings painting them. Here, we
1074     implicitly defined the format of the \code{lines} slot and the
1075     \code{strings} slot of the application frame class. The elements of
1076     the list stored in \code{lines} are pairs of points, namely the start
1077     and end point for a line. In \code{strings}, we store the text's
1078 cfruhwirth 1.2 position as the \code{car} of a cons and the text as its \code{cdr}.
1079 cfruhwirth 1.1
1080     % \class{draw-frame} uses two options in
1081     % \macro{define-application-frame} that we have not encountered
1082     % before. The \keyword{:command-definer} option is used to specify a
1083     % name for a command-defining macro for this frame class. Passing
1084     % \constant{t} to this option, as in the example, indicates that a
1085     % name of the form
1086     % \macro{define-\texttt{<}frame-name\texttt{>}-command} should be
1087     % used. The command-defining macro can then be used to define commands
1088     % that are specialized to the defined frame class.
1091     Figure \ref{fig-draw-commands} shows the command definitions. We have
1092     commands for adding a text string, for adding a line and resetting the
1093     draw pane. After every command, we update the drawing pane via the
1094     auxiliary method \method{update-draw-pane}.\footnote{An experienced
1095     \CLIM{} programmer would define a display-function for
1096 cfruhwirth 1.2 \class{draw-pane}. This function is run after a command is
1097     executed, and causes the display pane to be updated with any changes. We
1098     will save this technique for later examples.}
1099 cfruhwirth 1.1
1100     At this point, we can actually use the application; although not very
1101     conveniently. The interactor pane can be used to invoke one of three
1102     commands, either by typing the complete command including all its
1103     parameters or by typing only the command name, then a dialog queries
1104 rgoldman 1.4 the user for the missing command argument(s). Clicking on the menu bar
1105     entries is another way to invoke commands. When commands are invoked
1106     through the menu bar, the user will be queried for the missing
1107     argument(s) in the same way as if a command had been typed into the
1108     interactor pane.
1109     % also possible. Also in this case, the user is queried for
1110     % the missing arguments.
1111 cfruhwirth 1.1
1112     But drawing by typing coordinates is not convenient. Therefore, we
1113     attach these commands to other user interactions. Figure
1114 rgoldman 1.4 \ref{fig-draw-interfacing} defines input methods (methods for
1115     \code{handle-event}) for pointer button
1116     presses as well as key presses on the draw pane.
1117     Each handler invokes a tracking function (\code{track-line-drawing} and
1118     \code{track-text-drawing}) that uses \macro{tracking-pointer} to
1119 cfruhwirth 1.1 bypass the regular input distribution channels and to dispatch events
1120     to user defined handlers.
1121 rgoldman 1.4 % old text: [2006/03/19:rpg]
1122     % Both handlers invoke
1123     % the respective tracking function that uses \macro{tracking-pointer} to
1124     % bypass the regular input distribution channels and to dispatch events
1125     % to user defined handlers.
1127     For \class{pointer-button-press-event}, which is used to draw lines,
1128     the input loop manages a
1129     ``rubber-banding'' line. %
1130     % what is pointer-motion here? Is it an event? And it's not really
1131     % the event that's invoked, to be absolutely clear. The event is
1132     % signaled, and the tracking-pointer macro provides a handler for that
1133     % event. So it is the code associated with :pointer-motion that is
1134     % invoked... I wasn't confident enough in my understanding of the
1135     % precise organization of the (Mc)CLIM architecture to venture a
1136     % rewrite, but there should be a clarification here. [2006/03/19:rpg]
1137     The \keyword{:pointer-motion} is invoked
1138 cfruhwirth 1.1 whenever the mouse pointer is moved by the user. The code attached to
1139 rgoldman 1.4 \keyword{:pointer-motion} clears the previously-drawn line and draws a new
1140 cfruhwirth 1.1 line with the new pointer position. It can easily undraw the old line
1141     by the using the special ink \constant{+flipping-ink+}. When the user
1142     confirms the line by releasing the pointer button, a command to the
1143     application is synthesized via \method{execute-frame-command}
1144     supplying all required parameters.
1146 rgoldman 1.4 We provide a similar input facility for text input. Whenever
1147 cfruhwirth 1.1 the user hits a key in the draw-pane, the respective
1148     \method{handle-event} calls \method{track-text-drawing} which attaches
1149 rgoldman 1.4 the character entered to the mouse pointer. As with the
1150     rubber-banding line, the user can move the displayed string around while
1151 cfruhwirth 1.1 he is free to append additional string characters by additional key
1152     presses. He can confirm the text position with a mouse click causing a
1153 rgoldman 1.4 command to be dispatched to the application frame that will add the text to
1154 cfruhwirth 1.1 the application frame permanently.
1156     As each of these methods invoke \code{execute-frame-command} passing
1157 rgoldman 1.4 in a special command invocation form, this naturally leads to a
1158     separation between the code that specifies how a command is invoked (menu-bar click, click on
1159 cfruhwirth 1.1 draw-pane or typing in the interactor pane) and the code for command
1160     execution (code bodies of \method{define-command}).
1162     % \section{Shaping concepts}
1163     %
1164     % \subsection{The Extended Input Stream vs. The Event-Based Input Protocol of Sheets}
1165     %
1166     % \hrulefill
1167     %
1168     % Usually, UI toolkits are event driven from design as most windowing
1169     % systems use an event-driven design on their own. \CLIM{} supports a
1170     % different style of programming. The difference command-inversion
1171     % makes becomes mostly visible from the coding style of input
1172     % processing (performing output is rarely an asynchronus operation).
1173     %
1174     % The \CLIM{} programmer can treat the input as if they are coming
1175     % from an stream. The extendend-input-stream even provides blocking
1176     % read methods. The regular stream classes focus on character based
1177     % interaction such as \method{stream-read-char} or
1178     % \method{stream-read-line}, while the extended stream input class
1179     % provides reading of mouse clicks and keyboard presses of the pane
1180     % stream.
1181     %
1182     % Later, when we talk about presentation-type, we will present a way
1183     % to request objects with a special semantic from the user. For
1184     % instance, we require the user to provide a file pathname, or
1185     % clicking on a weekday item in a calendar. But more of
1186     % command-inversion and presentations later.
1187     %
1188     % \hrulefill
1189     %
1190     % Even when you are familar with event-based GUI programming, this
1191     % section is likely to be new to you. As said earlier, a \CLIM{}
1192     % programmer can persue a different programming style with the
1193     % extended input stream facilities. Any event-handler or command code
1194     % can query an input stream for information.
1195     %
1196     % \method{handle-event} from accept-demo shows an event handler for
1197     % pointer release events. The handler calls two stream reading
1198     % function \method{stream-read-line} and \method{stream-read-accept}.
1199     % Notice that both functions are blocking. The argument to
1200     % \method{stream-read-accept} signals that the predefined presentation
1201     % type 'pathname' is requested.
1202     %
1203     % \lstinputlisting{accept-demo-handle-event} For the second pathname
1204     % prompt, the user can either type a character-based representation of
1205     % the pathname into the query window or he can select a pathname that
1206     % is already present on screen with the pointer. accept-demo doesn't
1207     % show any pathnames, so that is only a theoretical option, but we
1208     % will see more about this option later in the presentation type demo.
1209     %
1210     % The evaluation of both format forms is block by the evaluation of
1211     % one of its argument, the stream-reading functions. Only after
1212     % further interaction with the user, the accept call returns. In many
1213     % other GUI toolkits, such a programming style is not possible as
1214     % event handlers would not be allowed to block and therefore stall the
1215     % event-handling thread.
1216     %
1218     \section{High Level Facilities}
1220     In this section, we explain a number of higher level facilities
1221     provided by \CLIM{}, including output recording, formatted output,
1222     presentations, context sensitive input, and command
1223     processors.\footnote{Many of these facilities are derived from work
1224     done at Symbolics on the Dynamic Windows (DW) project for
1225     Genera\cite{prog-ref-manual}. See \cite{presentation-manager} for
1226     more detailed information on the motivations and design details
1227     behind DW. Many of the original contributers to DW have participated
1228     in the redesign of these facilities for \CLIM{}.} We illustrate
1229     these facilities in two examples: a directory lister and a simple
1230     schedule browser.
1232     \paragraph*{Output Recording} Many of the higher level facilities in
1233     \CLIM{} are based on the concept of output recording. The \CLIM{}
1234     output recording facility is simply a mechanism wherein a window
1235     remembers all of the output that has been performed on it. This output
1236     history (stored basically as a display list) can be used by \CLIM{}
1237     for several purposes. For example, the output history can be used to
1238     automatically support window contents refreshing (or ``damage
1239     repaint'' events). The application programmer has considerable
1240     control over the output history. Output recording can be enabled or
1241     suspended, and the history itself can be cleared or rearranged.
1243     Output records can be nested, thereby forming their own hierarchy. The
1244     leaves of this tree are typically records that represent a piece of
1245     output, say the result of a call to \method{draw-rectangle} or
1246     \method{write-string}. The intermediate nodes typically provide
1247     additional semantics to the tree, such as marking a subtree of nodes
1248     as resultant output of one particular phase of an application, for
1249     instance row and column formatting information. Chapter 16 in
1250     \cite{clim-spec} has all the details.
1252     \paragraph*{Output Formatting} \CLIM{} provides a convenient table and
1253     graph formatting facility, which is built on top of the output
1254     recording facility. The key to these formatting tools (as opposed to,
1255 cfruhwirth 1.2 say, \code{format}'s \code{~T} directive) is that they dynamically compute the
1256 cfruhwirth 1.1 formatting parameters based on the actual size of the
1257     application-generated output.
1259     The application programmer uses these tools by wrapping any piece of
1260     output-producing code with advisory macros that help the system
1261     determine the structure of the output.
1263     For example, start with a simple output function that shows some
1264     information about the packages in the Lisp environment:
1265     \lstset{style=inlinestyle}
1266     \begin{lstlisting}
1267     (defun show-package-info (stream)
1268     (dolist (package (list-all-packages))
1269     (write-string (package-name package)
1270     stream)
1271     (write-string " " stream)
1272     (format stream "~D"
1273     (count-package-symbols
1274     package))
1275     (terpri stream)))
1276     \end{lstlisting}
1277     Any attempt to fix this function to produce tabular output by building
1278     in a certain fixed spacing between the package name and symbol count
1279     will either get caught by an unexpectedly long package name, or will
1280 cfruhwirth 1.2 have to reserve way too much space for the typical case. In \CLIM{}, we
1281 cfruhwirth 1.1 can use the code in Figure \ref{fig-formatting} to produce a neatly
1282     formatted table for any set of package names.
1283     \begin{figure*}
1284     \lstset{style=framestyle}
1285     \begin{lstlisting}
1286     (defun show-packages (stream)
1287     (formatting-table (stream)
1288     (dolist (package (list-all-packages))
1289     (formatting-row (stream)
1290     ;; The first column contains the package name
1291     (formatting-cell (stream)
1292     (write-string (package-name package) stream))
1294     ;; The second color contains the symbol count, aligned with the right
1295     ;; edge of the column
1296     (formatting-cell (stream :align-x ':right)
1297     (format stream "~D" (count-package-symbols-package)))))))
1298     \end{lstlisting}
1299     \caption{An output function that uses table formatting.}\label{fig-formatting}
1300     \end{figure*}
1302     % \paragraph*{Updating output} FIXME think of a GOOD example for
1303     % updating output.
1305     \paragraph*{Presentations} The next step up from preserving the mere
1306     physical appearance of output done to a window is to preserve its
1307     semantics. For example, when an application displays a Lisp pathname
1308     on the screen via \code{(format t "\~{}A" path)}, the string
1309     ``/clim/demo/cad-demo.lisp'' may appear. To the user this string has
1310     obvious semantic meaning; it is a pathname. However, to Lisp and the
1311     underlying system it is just a text string. Fortunately, in many cases
1312     the semantics can be recovered from the string. Thus the power of the
1313     various textual cut-and-paste mechanisms supported by contemporary
1314     computer systems. However, it is possible to improve upon the utility
1315 cfruhwirth 1.2 of this lowest common denominator facility (i.e.{} squeezing everything
1316 cfruhwirth 1.1 through its printed representation) by remembering the semantics of
1317     the output as well as its appearance. This is the idea behind
1318     presentations.
1320     A presentation is a special kind of output record that maintains the
1321     link between screen output and the Lisp data structure that it
1322     represents. A presentation remembers three things: the displayed
1323     output by capturing a subtree of output records, the Lisp object
1324     associated with the output, and the presentation type of the output.
1325     By maintaining this back pointer to the underlying Lisp data
1326     structure, the presentation facility allows output to be reused at a
1327     higher semantic level.
1329     An application can produce semantically tagged output by calling the
1330     \CLIM{} function \method{present}. For example, to display the
1331     pathname referred to above as a presentation, the application would
1332     execute:
1333     \begin{lstlisting}
1334     (present path 'pathname)
1335     \end{lstlisting}
1336     \method{present} captures the resulting output and the pathname object
1337     in a presentation of type \code{'pathname}.
1339     \paragraph*{Presentation Types} \CLIM{} defines a set of presentation
1340     types, which are arranged in a super-type/subtype lattice like the CL
1341     types. In fact, the presentation type hierarchy is an extension of the
1342     CL type hierarchy. The reason that this extended type system is needed
1343 cfruhwirth 1.2 is that the CL type system is insufficient from the UI perspective. For
1344 cfruhwirth 1.1 example, the integer 72 might represent a heart rate in one
1345     application and a Fahrenheit temperature in another, but it will
1346 cfruhwirth 1.2 always be just an integer to Lisp.
1347 cfruhwirth 1.1
1348     The application programmer can define the UI entities of the
1349     application by defining presentation types, thus extending the
1350     presentation type library. By defining a presentation type, the
1351     programmer can centralize all of the UI aspects of the new type in one
1352     place, including output appearance and input syntax. As an example,
1353     \CLIM{} defines a pathname presentation type that defines how a
1354     pathname is displayed and how one is input. The pathname input side
1355 cfruhwirth 1.2 provides pathname completion and display of possibilities. By
1356 cfruhwirth 1.1 defining this behavior in one place and using it in all applications
1357     that need to display or read pathnames, \CLIM{} helps build consistent
1358     user interfaces.
1360     Note that in the pathname output example given above \method{present}
1361     invokes the standard pathname displayer defined by the presentation
1362     type. However, since the presentation facility is simply based on the
1363     output recording facility, presentation semantics can be given to any
1364     output. The following example shows how the pathname object could be
1365     associated with some graphics that were displayed on the screen.
1367     \begin{lstlisting}
1368     (with-output-as-presentation
1369 cfruhwirth 1.2 (:object path
1370     :type 'pathname
1371     :stream s)
1372 cfruhwirth 1.1 (draw-rectangle* s 0 0 30 30))
1373     \end{lstlisting}
1375     \paragraph*{Context-Dependent Input} Once output is
1376     semantically-tagged, it can be reused as semantically-meaningful
1377     input. To achieve this, the application does not only have to tag its
1378     output but it also has to provide additional semantic information when
1379     doing input operations. For instance, whenever a pathname is required,
1380     the program has to use a special method in contrast to reading a
1381     string of characters.
1383     The counterpart to \method{present} is \method{accept}. It is used to
1384     establish an \concept{input context}. The input context is a
1385     presentation type that is appropriate for the current input point. For
1386     example, if the application requires the user to input a pathname, it
1387     can trigger an appropriate prompt, input parser and input context
1388     with:
1389     \begin{lstlisting}
1390     (accept 'pathname :stream s)
1391     \end{lstlisting}
1392     Typically, this invokes the input reader (or parser) that was defined
1393     for the pathname type and establishes an input context that indicates
1394     that it is waiting for a pathname.
1396     Once the input context is established, \CLIM{} automatically makes any
1397     appropriate existing output available to the user via mouse gestures.
1398     After calling \method{accept} as shown above, the user can move the
1399     mouse over any presentation that is of type pathname (or is a subtype
1400     of pathname), click on it, and the pathname object underlying the
1401     presentation is returned as the value of the call to \code{accept}.
1403     \paragraph*{Command Processors} \CLIM{} promotes the separation of
1404     command execution code and command invocation code. The command
1405     facility aids this task. Every application frame can define
1406     application commands that are accessible via various input methods.
1407     The most common are clicking on the command's entry in the menu bar or
1408     a context menu, typing the command in the interactor pane, or the
1409     application dispatches a command to itself (maybe triggered by other
1410     ways of user input or network interactions, etc.). The latter case is
1411     seen in \code{track-line-drawing} and \code{track-text-drawing} of the
1412     \class{draw-frame} example. These methods generate ``Add Line'' and
1413     ``Add String'' commands as the result of event-handling on the
1414     draw-pane.
1416     A command has a name specified as string and a set arguments specified
1417     as presentation types. Looking back at the command ``Add String'' of
1418     draw-frame, we see that this command takes a string and two integer as
1419     arguments. This type information is useful for partial command
1420     parsing. Assume the user clicks on a menu entry or types only the
1421     command name in the interactor. \CLIM{} notices that there are
1422     arguments missing in the command and requests the missing ones in a
1423     dialog via calls to \code{accept}. Mentioned early, \code{accept}
1424     establishes an input context and so the user is able to fill the
1425     missing argument with clicks on appropriate visible output objects.
1426     Also keyboard users will find semantically-tagged input methods
1427     convenient as implementations of presentation types can provide the
1428     user with a completion facility.
1430     In addition, the command processor is extensible by application
1431     programmers. For example, the command processor can be extended to
1432     support a ``noun then verb'' interaction style, where the user can
1433     first click on a displayed presentation and then invoke a command that
1434     is defined to take an argument of the selected presentation type.
1436     \subsection{A Directory Browser}
1437     \begin{figure*}
1438     \lstset{style=framestyle}
1439     \lstinputlisting{file-browser-all}
1440     \caption{File Browser}\label{fig-file-browser}
1441     \end{figure*}
1443 cfruhwirth 1.2 The \class{dirlist-frame} application is a very simple file
1444 cfruhwirth 1.1 system browser using presentation types. It defines two panes, an
1445     output pane to display directory contents and an input pane to handle
1446     user typein. For the output pane, the application defines a display
1447     function. \code{dirlist-display-files} works in conjunction with the
1448 cfruhwirth 1.2 top level command loop. By default, the command loop calls all
1449 cfruhwirth 1.1 display functions after a command was processed to make all changes in
1450     the application's data structures visible that the command execution
1451     might have caused. When all display functions have updated their
1452     panes, the command loop displays a prompt in the
1453 cfruhwirth 1.2 interactor\footnote{Omitted when there is no interactor pane.}
1454 cfruhwirth 1.1 and waits for the next command.
1456     The \method{dirlist-display-files} display function iterates over the
1457     contents of the current directory displaying the files one by one.
1458     Each output line is produced by a call to \method{present}.
1459     \method{present} creates the association between the text lines on the
1460     screen and the Lisp pathname objects.
1462     \class{draw-frame} has a single command ``Edit directory''. The
1463     command's body interprets the pathname that it receives as a
1464     directory, obtaining a list of the files contained therein. The
1465     command simply updates the application variable
1466     \variable{active-files} with the new list.
1468     The \CLIM{} presentation substrate supports a general concept of
1469     presentation type translation. This translation mechanism can be used
1470     to map objects of one type into a different presentation type, if
1471     appropriate. For example, it might be possible to satisfy an input
1472     request for a pathname by selecting a computer user's login ID and
1473     returning the pathname of the user's home directory. This would be
1474     accomplished by defining a translator from a user-id presentation type
1475     to the pathname type. The translator would consult the system's user
1476     database to retrieve the home directory information to achieve its
1477     conversion task.
1479     The command loop of an application frame is regularly requesting
1480     commands for processing and it uses \method{accept} for its request.
1481     Hence, an input context for reading an object with the presentation
1482     type \class{command} is established and all objects that can be used
1483     as commands will become clickable on screen. Here, we can define a
1484     presentation-to-command translator that translates a pathname into the
1485     edit directory command.
1487     The presentation-to-command translator in
1488     \figurename~\ref{fig-file-browser} is very simple. It has the name
1489     \class{pathname-to-edit-command} and converts the presentation type
1490     \code{pathname} to the command \code{com-edit-directory} for the
1491     command table of \class{file-browser}. The gesture option specifies
1492     that it works with the select gesture, while the string supplied to
1493     \keyword{:documentation} is used in the context menu.
1495     This command translator has little work to do. The body of the
1496     translator has to return a list of arguments that are handed to the
1497     command \code{com-edit-directory}. But we do not need to any
1498     conversion of the supplied object, as it is already a pathname. Thus,
1499 cfruhwirth 1.2 the object is wrapped in a list and returned to the caller
1500     which will apply \code{com-edit-directory} to the list.
1501 cfruhwirth 1.1
1502     A simple trick is used to dispatch an initial command to the
1503     application frame. An after-method is provided for
1504     \method{adopt-frame} which runs after the frame manager has adopted
1505     the frame for displaying. This is different for an after-method on
1506     \method{initialize-instance} as an after-method on
1507     \method{adopt-frame} runs later, when the application frame instance
1508     has already a command queue associated with it.
1510     Since this application was defined with an interactor pane for user
1511     input, the user can invoke the sole command by typing its name, ``Edit
1512     Directory.'' Here, \CLIM{} supports for automatic command completion
1513     becomes visible. Only the first letter has to be typed followed by the
1514     complete action (usually Tab) and the command completion facility will
1515     complete the input to ``Edit Directory''. At this point, the \CLIM{}
1516     command loop will begin reading the arguments for that command, and
1517     will automatically enter a pathname input context. Thus, the user can
1518     fill in the required argument either by typing a pathname, or by
1519     clicking on one of the pathnames visible in the display pane.
1521     \subsection{Schedule Example}
1523     In this example, we build a simple appointment browser. Since the user
1524     of this application will frequently be dealing with the days of the
1525     week, we start by defining a new presentation type weekday. This
1526     simple presentation type, shown in Figure \ref{fig-scheduler1},
1527     represents a day of the week as a number from 0 to 6. Each day number
1528     is associated with an abbreviated day name, ``Mon,'' ``Tue,'' etc.
1530     \begin{figure*}
1531     \lstset{style=framestyle}
1532     \lstinputlisting{scheduler-part1}
1533     \caption{Scheduler: application frame, presentation type and commands}\label{fig-scheduler1}
1534     \end{figure*}
1535     \begin{figure*}
1536     \lstset{style=framestyle}
1537     \lstinputlisting{scheduler-part2}
1538     \caption{Scheduler: display functions}\label{fig-scheduler2}
1539     \end{figure*}
1541     The weekday presentation type defines two basic pieces of behavior:
1542     how a weekday is displayed, and how it is read as input. The macro
1543     \macro{define-presentation-method} is intended for specializing
1544     methods on presentation types. Via this macro, we define a printer
1545     and a parser function for the type \code{weekday}. As is the case with
1546     most presentation types, the printer and parser are duals. That is,
1547     the printer, when given an object to print, produces output that the
1548 cfruhwirth 1.2 parser can interpret to arrive back at the original object.
1549     \code{accept} does not need a parser in every case, and for simplicity
1550     the programmer might choose not to provide a parser at all.
1551 cfruhwirth 1.1
1552     We took the easy way out with our parser. \CLIM{} provides a
1553     completion facility and instead of reading the day name of the stream
1554     and parsing it into an integer, we provided an exhaustive set of input
1555     to object mappings. The \macro{completing-from-suggestions} macro
1556     collects all suggestions made by the parser via
1557 cfruhwirth 1.2 \code{suggest}. \code{suggest} takes an input and object as
1558 cfruhwirth 1.1 suggestion. In our case, day name taken from \variable{*days*} is the
1559     input and the number of the week \variable{i} is the object. \CLIM{}
1560     will match the input given by the user with the suggestions and in
1561     case of a match will return the corresponding object to the caller.
1563     We define an application frame for the appointment browser in Figure
1564     \ref{fig-scheduler1}. The frame defines state variables to hold the
1565     list of appointments and the current day. This information is kept in
1566     slots on the frame, so that multiple copies of the application can be
1567     run, each with its own appointment list. The application represents
1568     the appointment data as an alist containing an entry for each day of
1569     the week, with each entry containing a list of the appointments for
1570     the day. Test data is provided as a default initform.
1572     Just as in the previous example, the appointment application defines
1573     two panes, an interactor and an output display pane. The appointment
1574     application defines two commands. The ``Show Summary'' command resets
1575     the display back to the weekly summary mode by setting the
1576     \variable{current-day} slot to \constant{nil}. The ``Select Day''
1577     command sets \variable{current-day} to the value of an argument that
1578     is specified to be a weekday. This presentation type specification
1579     allows the command processor to make all presented weekday active when
1580     it is filling in this argument, as well as, provide completion
1581     assistance to the user.
1583     The command ``Select Day'' has the following argument specification:
1584     \begin{lstlisting}
1585     ((day 'weekday :gesture :select))
1586     \end{lstlisting}
1587     It takes an argument \code{day} of type \class{weekday}. Up until now,
1588     our command arguments have looked similarly to specialized lambda
1589     lists, but next to the type information the arguments of commands are
1590     also allowed to have various keyword-value pairs for selection further
1591     options. In this case, we supplied the value \code{:select} for the
1592     option \keyword{:gesture}. The macro \macro{define-command} parses
1593     this keyword-value pair and generate a presentation translator. More
1594     precisely, a presentation-to-command translator is defined that is
1595     equal in functionality to the one we have seen in the file-browser
1596     example. Whenever a presentation of the type \code{pathname} is
1597 cfruhwirth 1.2 selected (e.g.{} with pointer clicks) in a \class{command} input
1598 cfruhwirth 1.1 context, it is translated into a command invocation of ``Select
1599     Weekday''.
1601     Finally, we turn to the display the appointment information. The
1602     display function, \method{display-appointments}, shown in Figure
1603     \ref{fig-scheduler2}, is somewhat more complex than our earlier
1604     example. It can display two different sets of information: a weekly
1605     summary showing the days of the week and the number of appointments
1606     for each day, or a detailed description of one day's appointments.
1608     \method{display-appointments} decides which set of information to
1609     display by examining the application state variable
1610     \variable{current-day}. The table formatting facility is used to
1611     present the weekly summary information neatly organized. The daily
1612     appointment list, by contrast, is displayed using
1613     \method{write-string}. Note, however, that whenever a day of the week
1614     is displayed, it is done with a call to \code{present} using the
1615     weekday presentation type. This allows the printed weekdays to be
1616     selected either as a command or as a weekday argument. This example
1617     illustrates how an application with interesting UI behavior can be
1618     constructed from a high-level specification of its functionality.
1620     % \section{The benefits of the extended output stream}
1621     %
1622     % At the first glance, the extended output stream facilities does not
1623     % look more exciting than the output capabilities of sheets. In fact,
1624     % the output streams use the output facility of sheets to do their
1625     % job, thus the variaty of graphic operations is less or equal to that
1626     % of the lower facility. But an output stream helps to organize output
1627     % can do many things, we are not able to achieve that easy with the
1628     % low-level output tools.
1629     %
1630     % Output Recording, Table/Graph Formatting,and Incremental Redisplay
1631     % are tools that are built on top of the stream characteristic in the
1632     % extended output stream. We have already seen Table Formatting at
1633     % work in the scheduler example.
1634     %
1635     % \begin{figure*}
1636     % \hrulefill
1637     % \begin{lstlisting}
1638     % (let (a-string
1639     % sum-of-ints
1640     % (input-stream (frame-standard-input *application-frame*)))
1641     % (accepting-values (input-stream :own-window t)
1642     % (setq a-string (accept 'string :prompt "1st string" :stream input-stream))
1643     % (terpri input-stream)
1644     % (setq sum-of-ints
1645     % (+ (prog1 (or (accept 'integer :prompt "1st integer" :stream input-stream) 0)
1646     % (terpri input-stream))
1647     % (prog1 (or (accept 'integer :prompt "2nd integer" :stream input-stream) 0)
1648     % (terpri input-stream))))))
1649     % \end{lstlisting}
1650     % \hrulefill
1651     % \caption{Hairy example of accepting-values demonstrating the use of the blocking \method{accept} method}\label{accepting-values-example}
1652     % \end{figure*}
1653     %
1654     % With the \macro{accepting-values} even more is possible.
1655     % \figurename~\ref{accepting-values-example} demonstrates that it is
1656     % possible to build up a whole dialog window simply by requesting a
1657     % series of input types. It does that via \method{accepting-values}
1658     % which brings up a seperate dialog window to request a string and two
1659     % integers from the user.
1660     %
1661     % The trick of \method{accepting-value} is dual-evaluation. Its body
1662     % is evaluated twice. First to collect all accept calls and build up a
1663     % dialog. The second evaluation happens after the user has entered all
1664     % requested information and has hit the ``Ok'' button as confirmation.
1665     % In the second evaluation the entered values are returned from the
1666     % corresponding accept forms. Notice that we have to wrap
1667     % \method{accept} in an or statement for \method{+}, because when the
1668     % body is evaluated for the first time all \method{accept} forms
1669     % return \constant{nil} causing an exception if handed to
1670     % +.\footnote{In pratice, we would sum up the integers after
1671     % accepting-values, because this is much more easy to read later.}
1672     % Please do not try to mimic the code shown in
1673     % \figurename~\ref{accepting-values-example}. Nonetheless it is shown
1674     % to give the reader an insight how this sudden violation of
1675     % evaluation sequence is implemented.
1676     %
1677     % We should emphasize that only the body of accepting-values is
1678     % evaluated twice. The \method{let} statement in
1679     % \figurename~\ref{accepting-values-example} does not return before
1680     % \method{accepting-values} does. This is not a form of continuation.
1681     % \method{accepting-values} effectively blocks the event thread just
1682     % as a single \method{accept} would (\method{accepting-values} can
1683     % therefore be seen as something that aggregates several accept
1684     % statements). Despite this blocking, \CLIM{} manages to continue
1685     % event handling.
1687     \section{Conclusion}
1689 cfruhwirth 1.2 The series of examples presented in this article illustrates the broad
1690 cfruhwirth 1.1 range of functionality provided by \CLIM{}. The later examples,
1691     especially, demonstrate that complex user interfaces can be built
1692 cfruhwirth 1.2 economically and in a modular fashion using \CLIM{}. Many of the higher level
1693 cfruhwirth 1.1 facilities make it possible to separate the issues involved in
1694     designing an application's user interface from the functionality of
1695     the application.
1697 cfruhwirth 1.2 On the other hand, these higher level facilities are not
1698     appropriate for all programmers. \CLIM{}'s lower level facilities and clean
1699     modularization of the higher level facilities provide these programmers with
1700 cfruhwirth 1.1 portable platform and a framework for implementing their own user
1701 cfruhwirth 1.2 interface toolkits and frameworks. In addition, \CLIM{}'s use of \CLOS{}
1702 cfruhwirth 1.1 to define explicit, documented protocols provides application
1703     programmers with the opportunity to customize \CLIM{} and support
1704     interfaces not anticipated by the \CLIM{} designers.
1706 cfruhwirth 1.2 A free \CLIM{} implementation is available as \mcclim{}, found at
1707     \url{http://common-lisp.net/project/mcclim/}. In addition to the
1708     caveats in this document, note that \mcclim{} only works with an X
1709     windows backend as of January 2006. An experimental port called
1710     beagle to the native toolkit of Mac OS X is in progress.
1711 cfruhwirth 1.1
1712     \section*{Acknowledgments}
1714     \paragraph*{Original article} \CLIM{} represents the cooperative
1715     effort of individuals at several companies. These individuals include
1716     Jim Veitch, John Irwin, and Chris Richardson of Franz; Richard Lamson,
1717     David Linden, and Mark Son-Bell of ILA; Paul Wieneke and Zack Smith of
1718     Lucid; Scott McKay, John Aspinall, Dave Moon and Charlie Hornig of
1719     Symbolics; and Gregor Kizcales and John Seely Brown of Xerox PARC.
1720     Mark Son-Bell and Jon L. White have help us improve this paper.
1722     \paragraph*{2006 update} Clemens Fruhwirth thanks the developers for
1723 cfruhwirth 1.2 \mcclim{} for producing a free \CLIM{} implementation, and especially
1724 cfruhwirth 1.1 Robert Strandh for answering so many questions in conjunction with
1725 cfruhwirth 1.2 \mcclim{}.
1726 cfruhwirth 1.1
1727     \bibliographystyle{alpha}
1728     \bibliography{guided-tour}
1730     \end{document}

  ViewVC Help
Powered by ViewVC 1.1.5