/[mcclim]/mcclim/Doc/Guided-Tour/guided-tour.tex
ViewVC logotype

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

Parent Directory Parent Directory | Revision Log Revision Log


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

  ViewVC Help
Powered by ViewVC 1.1.5