# Diff of /mcclim/Doc/Guided-Tour/guided-tour.tex

revision 1.1 by cfruhwirth, Mon Jan 30 16:14:01 2006 UTC revision 1.2 by cfruhwirth, Thu Feb 9 13:20:38 2006 UTC
# Line 2  Line 2
2  \usepackage[dvips]{graphicx}  \usepackage[dvips]{graphicx}
3  \usepackage{color}              % Need the color package  \usepackage{color}              % Need the color package
4  \usepackage{listings}  \usepackage{listings}
5    \usepackage{url}
6  %\usepackage{epsfig}  %\usepackage{epsfig}
7  \title{\Huge A Guided Tour of CLIM, \\ Common Lisp Interface Manager}  \title{\Huge A Guided Tour of CLIM, \\ Common Lisp Interface Manager}
8  \author{  \author{
# Line 36  Dennis Doughty \texttt{<doughty@ila.com> Line 37  Dennis Doughty \texttt{<doughty@ila.com>
41    \newcommand {\CLOS}{\textsc{clos}}
42    \newcommand {\mcclim}{\textsc{McCLIM}}
43  \let\class\code  \let\class\code
44  \let\method\code  \let\method\code
45  \let\constant\code  \let\constant\code
# Line 54  facilities include a portable layers for Line 57  facilities include a portable layers for
57  output services, and mechanisms for constructing window types and user  output services, and mechanisms for constructing window types and user
58  interface components; stream-oriented input and output facilities  interface components; stream-oriented input and output facilities
59  extended with presentations and context sensitive  extended with presentations and context sensitive
60  input\footnote{Similar to the work pioneered in the Genera UI system};  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  and a gadget-oriented toolkit similar to those found in the X world
63  we present an overview of \CLIM{}'s broad range of functionality and  we present an overview of \CLIM{}'s broad range of functionality and
# Line 62  present a series of examples that illust Line 65  present a series of examples that illust
65  article originally appeared in Lisp Pointers in 1991 and was updated  article originally appeared in Lisp Pointers in 1991 and was updated
66  in 2006 by Clemens Fruhwirth.\footnote{The CLIM 2 specification  in 2006 by Clemens Fruhwirth.\footnote{The CLIM 2 specification
67    changed significant parts of \CLIM{} rendering legacy code    changed significant parts of \CLIM{} rendering legacy code
68    unusable. Clemens Fruhwirth has rewritten all examples and the    unusable. Clemens Fruhwirth has rewritten all examples and the
69    corresponding text section for the \CLIM{} 2 specification. In    corresponding text sections for the \CLIM{} 2 specification. In
71    to provide additional insights into \CLIM{} concepts.} All examples    to provide additional insights into \CLIM{} concepts.} All examples
73  \CLIM{} implementation.  \CLIM{} implementation, as of January 2006.
74  \end{abstract}  \end{abstract}
75
76  \section*{Introduction}  \section*{Introduction}
77  Common Lisp is a language standard that has provided a broad range of  Common Lisp is a language standard that has provided a broad range of
78  functionality, and that has, to a large degree, successfully enabled  functionality, and that has, to a large degree, successfully enabled
79  the writing of truly portable Lisp programs. The emergence of CLOS and  the writing of truly portable Lisp programs. The emergence of \CLOS{} and
80  the cleanup efforts of Ansi X3J13 have further enhanced the utility  the cleanup efforts of ANSI X3J13 have further enhanced the utility
81  and portability of Common Lisp. However, one major stumbling block  and portability of Common Lisp. However, one major stumbling block
82  remains in the path of those endeavoring to write large portable  remains in the path of those endeavoring to write large portable
83  applications. The Common Lisp community has not yet provided a  applications. The Common Lisp community has not yet provided a
84  standard interface for implementing user interfaces beyond the most  standard interface for implementing user interfaces beyond the most
85  basic operations based on stream reading and printing.\footnote{Notice  basic operations based on stream reading and printing.\footnote{Notice
86    that this sentence was written in 1991. Unfortunately, it is still    that this sentence was written in 1991; it is still
87    true 15 years later.}    true 15 years later.}
88
89  The Common Lisp Interface Manager addresses this problem by specifying  The Common Lisp Interface Manager addresses this problem by specifying
# Line 92  stream operations, output recording, and Line 95  stream operations, output recording, and
95  and high level facilities like context sensitive input, an adaptive  and high level facilities like context sensitive input, an adaptive
96  toolkit, and an application building framework.  toolkit, and an application building framework.
97
98  \CLIM{} will eventually support a large number of window environments  \CLIM{} implementations will eventually support a large number of window environments
99  including X Windows, Mac OS X and Microsoft Windows. \CLIM{} is  including X Windows, Mac OS X and Microsoft Windows. \CLIM{} is
100  designed to exploit the functionality provided by the host environment  designed to exploit the functionality provided by the host environment
101  to the degree that it makes sense. For example, \CLIM{} top level  to the degree that it makes sense. For example, \CLIM{} top level
# Line 100  windows are typically mapped onto host w Line 103  windows are typically mapped onto host w
103  operations are ultimately performed by host window system  operations are ultimately performed by host window system
104  code. Another example is that \CLIM{} supports the incorporation of  code. Another example is that \CLIM{} supports the incorporation of
105  toolkits written in other languages. A uniform interface provided by  toolkits written in other languages. A uniform interface provided by
106  \CLIM{} allows Lisp applications programmers to deal only with Lisp  \CLIM{} allows Lisp application programmers to deal only with Lisp
107  objects and functions regardless of their operating platform.  objects and functions regardless of their operating platform.
108
109  An important goal that has guided the design of \CLIM{} has been to  An important goal that has guided the design of \CLIM{} was to
110  layer the specification into a number of distinct  layer the specification into a number of distinct
111  facilities. Furthermore, the specification does not distinguish the  facilities. Furthermore, the specification does not distinguish the
112  use of a facility by higher level \CLIM{} facilities from its use by  use of a facility by higher level \CLIM{} facilities from its use by
113  \CLIM{} users. For example, the geometry substrate, which includes  \CLIM{} users. For example, the geometry substrate, which includes
114  transformations and regions, is designed for efficient use by the  transformations and regions, is designed for efficient use by the
115  graphics and windowing substrates as well as by \CLIM{} users. This  graphics and windowing substrates as well as by \CLIM{} programmers. This
116  means that, in general, a \CLIM{} user can reimplement higher level  means that, in general, a \CLIM{} programmer can reimplement higher level
117  \CLIM{} facilities using the interfaces provided by lower level  \CLIM{} facilities using the interfaces provided by lower level
118  facilities.  facilities.
119
# Line 123  frameworks that better support the speci Line 126  frameworks that better support the speci
126  particular application.  particular application.
127
128  For example, \CLIM{}'s application framework and adaptive toolkit  For example, \CLIM{}'s application framework and adaptive toolkit
129  allow users to develop applications that automatically adopt the look  allow programmers to develop applications that automatically adopt the look
130  and feel of the host's environment. (We often call this  and feel of the host's environment. (We often call this
131  adaptiveness,'' look and feel independence,'' or occasionally more  adaptiveness,'' look and feel independence,'' or occasionally more
132  picturesquely, chameleon look and feel''.) However, many users may  picturesquely, chameleon look and feel''.) However, many users may
133  need or want to define a particular look and feel that stays constant  need or want to define a particular look and feel that stays constant
134  across all host environments (we call this "portable look and  across all host environments (we call this portable look and
135  feel"). Such users can circumvent the look and feel adaptiveness  feel''). Such users can circumvent the look and feel adaptiveness
136  provided by \CLIM{}, while still using most of the application  provided by \CLIM{}, while still using most of the application
137  framework facility and other high level \CLIM{} facilities like  framework facility and other high level \CLIM{} facilities like
138  context sensitive input. Furthermore, using the lower level facilities  context sensitive input. Furthermore, using the lower level facilities
139  of \CLIM{}, they can develop portable toolkit libraries that define  of \CLIM{}, they can develop portable toolkit libraries that define
140  and implement their own particular look and feel. For instance, the  and implement their own particular look and feel. For instance, the
141  \CLIM{} user can implement new gadget types on top of the drawing  \CLIM{} programmer can implement new gadget types on top of the drawing
142  primitives and treat them equally to the build-in gadget types.  primitives and treat them equally to the built-in gadget types.
143
144  We will use the term \concept{CLIM implementor} for the party  We will use the term \concept{CLIM implementor} for the party
145  implementing low-level and high-level parts according to the \CLIM{}  implementing low-level and high-level parts according to the \CLIM{}
# Line 186  repainting it when necessary. Line 189  repainting it when necessary.
189  \paragraph*{Formatted Output} \CLIM{} provides a set of high-level  \paragraph*{Formatted Output} \CLIM{} provides a set of high-level
190  macros that enable programs to produce neatly formatted tabular and  macros that enable programs to produce neatly formatted tabular and
191  graphical displays easily.\footnote{This also includes Graph  graphical displays easily.\footnote{This also includes Graph
192    Formatting}    Formatting.}
193
194  \paragraph*{Presentations} \CLIM{} provides the ability to associate  \paragraph*{Presentations} \CLIM{} provides the ability to associate
195  semantics with output, such that Lisp objects may be retrieved later  semantics with output, such that Lisp objects may be retrieved later
196  via user gestures (e.g. mouse clicks) on their displayed  via user gestures (e.g.{} mouse clicks) on their displayed
197  representation. This context sensitive input is modularly layered on  representation. This context sensitive input is modularly layered on
198  top of the output recording facility and is integrated with the Common  top of the output recording facility and is integrated with the Common
199  Lisp type system. A mechanism for type coercion is also included,  Lisp type system. A mechanism for type coercion is also included,
# Line 213  operation. Application that use these ga Line 216  operation. Application that use these ga
216  facilities will automatically adapt to use whatever toolkit is  facilities will automatically adapt to use whatever toolkit is
217  available and appropriate for the host environment. In addition,  available and appropriate for the host environment. In addition,
218  portable Lisp-based implementations of the abstract gadget pane  portable Lisp-based implementations of the abstract gadget pane
219  protocols are provided.\footnote{McCLIM does not support look and feel  protocols are provided.\footnote{\mcclim{} does not support look and feel
220    adaptiveness at the moment except for the experimental port for Mac    adaptiveness at the moment except for the experimental beagle backend for Mac
221    OS X. Hence, McCLIM mostly uses this portable Lisp-based    OS X's Cocoa platform. Hence, \mcclim{} mostly uses this portable Lisp-based
222    implementation.}    implementation.}
223
224  \paragraph*{Application Building} \CLIM{} provides a set of tools for  \paragraph*{Application Building} \CLIM{} provides a set of tools for
# Line 237  output record can not only reproduce con Line 240  output record can not only reproduce con
240  stream, the \CLIM{} programmer can also attach the code that generated  stream, the \CLIM{} programmer can also attach the code that generated
241  the content to the content itself. Whenever necessary, the application  the content to the content itself. Whenever necessary, the application
242  programmer can ask an output stream to update itself. \CLIM{} will  programmer can ask an output stream to update itself. \CLIM{} will
243  query all code generators and in case, replace obsolete content.  query all drawn elements for obsolescence, and if necessary, rerun the
244    code to produce fresh output.
245
246  \noindent\hrulefill  \noindent\hrulefill
247
248  \noindent These are a lot of facilities to explore. The most  \noindent This is a large number of facilities to explore. The most
249  systematically way -- exploring from the most low-level to the most  systematic way -- progressing from the lowest-level to the highest
250  high-level -- would also be the most longsome. Therefore, we start  -- would also be the lengthiest. Therefore, we start
251  with showing several facilities in action with the most fundamental  with showing several facilities in action with the most fundamental
252  example in the realm of programming: Hello World.  example in the realm of programming: Hello World.
253
# Line 270  of the specification first as this is th Line 274  of the specification first as this is th
274  references and hope that the interested reader starts to explore the  references and hope that the interested reader starts to explore the
275  surrounding text sections on his own.  surrounding text sections on his own.
276
278    \keyword{:clim-user} is available to absorb user code. This package is
279    a good start for experimentations and first steps. When proper
280    packaging is required, simply include the packages \keyword{:clim} and
281    \keyword{:clim-lisp} in your \keyword{:use} list.
282
283  The central element of \CLIM{} application programming is the  The central element of \CLIM{} application programming is the
284  \concept{application-frame}. An application frame is defined via  \concept{application-frame}. An application frame is defined via
285  \code{define-application-frame}.\footnote{See Section 28.2 Defining  \code{define-application-frame}.\footnote{See Section 28.2 Defining
# Line 318  look at the definition of \class{hello-w Line 328  look at the definition of \class{hello-w
328
329  The one and only superclass of \class{hello-world-pane} is  The one and only superclass of \class{hello-world-pane} is
330  \class{clim-stream-pane}\footnote{See Section 29.4 CLIM Stream  \class{clim-stream-pane}\footnote{See Section 29.4 CLIM Stream
331    Panes'' in \cite{clim-spec}.}. As there are no additional slot, an    Panes'' in \cite{clim-spec}.}. As there are no additional slots, an
332  experience CLOS user might have correctly guessed that we will use  experienced \CLOS{} user might guess that we will use
333  \class{hello-world-pane} solely for method specialization.  \class{hello-world-pane} solely for method specialization.  Before doing so,
334    let us have a look what we have actually
But before we do that, let us have a look what we have actually
335  inherited from \class{clim-stream-pane}\footnote{Internal classes  inherited from \class{clim-stream-pane}\footnote{Internal classes
336    removed from Listing}:    removed from listing.}:
337
\pagebreak % formathack
338  \lstset{style=inlinestyle}  \lstset{style=inlinestyle}
339  \begin{lstlisting}  \begin{lstlisting}
340  CLIM-USER> (describe (find-class  CLIM-USER> (describe (find-class
# Line 394  up to the details we skipped in this exa Line 402  up to the details we skipped in this exa
402  To \CLIM{}, geometry means \concept{regions}. A region is either bound  To \CLIM{}, geometry means \concept{regions}. A region is either bound
403  or unbound and has a dimensionality of either zero, one or two. That  or unbound and has a dimensionality of either zero, one or two. That
404  corresponds to a point, a path or an area respectively. Regions can be  corresponds to a point, a path or an area respectively. Regions can be
405  compared (region predicate protocol\footnote{\CLIM{} relays heavily on  compared (region predicate protocol\footnote{\CLIM{} relies heavily on
406    CLOS. In CLOS, the term \concept{protocol} means a set of generic    \CLOS{}. In \CLOS{}, the term \concept{protocol} means a set of generic
407    functions that together form a coherent interface. A protocol    functions that together form a coherent interface. A protocol
408    specification does not only include the syntactic details of the    specification not only includes the syntactic details of the
409    function names and the number of function arguments, but also the    function names and the number of function arguments, but also the
410    functions purpose and the semantic of the return values (and/or side    functions' purpose and the semantics of the return values (and/or side
411    effects) must be given in a textual specification.}) and composed    effects) must be given in a textual specification.}) and composed
412  (region composition protocol).  (region composition protocol).
413
# Line 422  can be changed permanently, or in the co Line 430  can be changed permanently, or in the co
430  \subsection{The Windowing Substrate}  \subsection{The Windowing Substrate}
431
432  \CLIM{} does not directly talk to the window system. Instead, \CLIM{}  \CLIM{} does not directly talk to the window system. Instead, \CLIM{}
433  is layered on top of a windowing substrate\footnote{former Silica}.  is layered on top of a windowing substrate.\footnote{formerly known as Silica.}
434  This substrate is a middleware between \CLIM{} on one side and the  This substrate is a middleware between \CLIM{} on one side and the
435  host window system on the other.  This middleware layer provides a  host window system on the other.  This middleware layer provides a
436  portable windowing model that insulates higher levels of \CLIM{} and  portable windowing model that insulates higher levels of \CLIM{} and
437  \CLIM{} programmers from the details of the host window system. From  \CLIM{} programmers from the details of the host window system. From
438  the perspective of a \CLIM{} programmer, talking to the window system  the perspective of a \CLIM{} programmer, talking to the window system
439  is equal to talking to this abstraction layer. The implementation  is equal to talking to this abstraction layer. The implementation
440  details are hidden in \concept{backends}, like in McCLIM the CLX  details are hidden in \concept{backends}, like in \mcclim{} the CLX
441  backend, which hides X11 details, or the beagle backend, which hides  backend, which hides X11 details, or the beagle backend, which hides
442  details for Mac OS X's toolkit. These backends will use the services  details for Mac OS X's toolkit. These backends will use the services
443  of a host window system to provide efficient windowing, input and  of a host window system to provide efficient windowing, input and
# Line 440  This framework allows uniform treatment Line 448  This framework allows uniform treatment
448  blocks:  blocks:
449  \begin{itemize}  \begin{itemize}
450  \item Windows like those in X, Mac OS X and Microsoft Windows.  \item Windows like those in X, Mac OS X and Microsoft Windows.
451  \item Gadgets typical of toolkit layers, such as GTK, QT or Mac OS X's  \item Gadgets typical of toolkit layers, such as Gtk+, QT or Mac OS X's
452    toolkit. The backend provides a frame manager which takes care of    toolkit. The backend provides a frame manager which takes care of
453    mapping the abstract gadget types found in \CLIM{} to appropriate    mapping the abstract gadget types found in \CLIM{} to appropriate
454    gadget with a native look and feel.    gadget with a native look and feel.
# Line 480  sheets. Every sheet has a parent, a shee Line 488  sheets. Every sheet has a parent, a shee
488  children. A sheet can be adopted by a parent sheet and disowned later.  children. A sheet can be adopted by a parent sheet and disowned later.
489  A sheet is grafted when it is connected to a \concept{graft} either  A sheet is grafted when it is connected to a \concept{graft} either
490  directly or through it's ancestors. A graft is a special kind of sheet  directly or through it's ancestors. A graft is a special kind of sheet
491  that stands in for a host window, typically a root window (i.e. screen  that stands in for a host window, typically a root window (i.e.{} screen
492  level). A sheet is attached to a particular host window system by  level). A sheet is attached to a particular host window system by
493  making it a child of an associated graft. A host window will be  making it a child of an associated graft. A host window will be
494  allocated for that sheet; the sheet will then appear to be a child of  allocated for that sheet; the sheet will then appear to be a child of
# Line 545  permanently. \code{sheet-medium} obtains Line 553  permanently. \code{sheet-medium} obtains
553  sheet.  sheet.
554  % \footnote{Notice that the \CLIM{} specification \cite{clim-spec}  % \footnote{Notice that the \CLIM{} specification \cite{clim-spec}
555  %   specifies draw-text, draw-line, draw-rectangle, etc. as functions  %   specifies draw-text, draw-line, draw-rectangle, etc. as functions
556  %   that operate on mediums. McCLIM names these functions  %   that operate on mediums. \mcclim{} names these functions
557  %   medium-draw-text, medium-draw-line, medium-draw-rectangle, and so  %   medium-draw-text, medium-draw-line, medium-draw-rectangle, and so
558  %   on. The functions that are available in McCLIM without the  %   on. The functions that are available in \mcclim{} without the
559  %   medium-'' prefix operate on sheets. These are trampoline  %   medium-'' prefix operate on sheets. These are trampoline
560  %   functions that call the appropriate medium-prefixed function on  %   functions that call the appropriate medium-prefixed function on
561  %   the sheet's medium. According to the McCLIM authors, this is done  %   the sheet's medium. According to the \mcclim{} authors, this is done
562  %   for optimization.}  %   for optimization.}
563
564  The graphic output capabilities of sheets range from simple line style  The graphic output capabilities of sheets range from simple line style
# Line 563  in Chapters 10-14 of \cite{clim-spec}. Line 571  in Chapters 10-14 of \cite{clim-spec}.
571
572  \CLIM{} lives in idealized world in terms of graphics operations. A  \CLIM{} lives in idealized world in terms of graphics operations. A
573  \CLIM{} programmer can use an infinitely long and wide drawing pane  \CLIM{} programmer can use an infinitely long and wide drawing pane
574  with an arbitrary precise resolution and continuously variable amount  with an arbitrarily precise resolution and continuously variable
575  of opacity. As rendering devices with these properties are rare these  opacity. As rendering devices with these properties are rare,
576  days, we need to render the idealized graphic description to a device  we need to render the idealized graphic description to a device
577  with finite size and a fixed drawing precision. The rendering rules  with finite size and a fixed drawing precision. The rendering rules
578  are specified in Section 12.4 Rendering Conventions for Geometric  are specified in Section 12.4 Rendering Conventions for Geometric
579  Shapes''of \cite{clim-spec}.  Shapes''of \cite{clim-spec}.
# Line 596  system window hierarchy) when the frame Line 604  system window hierarchy) when the frame
604  To build a user interface, an application programmer defines one or  To build a user interface, an application programmer defines one or
605  more frames classes. These frame classes define a number of frame  more frames classes. These frame classes define a number of frame
606  properties including application specific state and a hierarchy of  properties including application specific state and a hierarchy of
607  panes (i.e. user interface gadgets and regions for interacting with  panes (i.e.{} user interface gadgets and regions, for interacting with
608  the users). Frame classes also provide hooks for customizing  the users). Frame classes also provide hooks for customizing
609  application behavior during various portions of the frame protocol.  application behavior during various portions of the frame protocol.
610  For example, an \keyword{:after} method on generic functions in the  For example, an \keyword{:after} method on generic functions in the
# Line 616  a blocking read request. He does not hav Line 624  a blocking read request. He does not hav
624  asynchronously handling confirmation or cancel button clicks.  For  asynchronously handling confirmation or cancel button clicks.  For
625  instance, the programmer requests a string from the user and the user  instance, the programmer requests a string from the user and the user
626  is presented with a prompt, an editable text field, and two buttons  is presented with a prompt, an editable text field, and two buttons
627  for confirmation and canceling. Only after the user hit the  for confirmation and canceling. Only after the user hits the
628  confirmation button, the string requesting function returns and the  confirmation button, the string requesting function returns; the
629  programmer can directly use the function's return value which is the  programmer can directly use the function's return value which is the
630  user provided string. A cancel button click is handled via throwing an  string provided by the user. Clicking the cancel button is dealt with by throwing to an
631  abort tag.  \code{abort} tag.
632
633  From the callers perspective, an attempt to separate application  From the caller's perspective, an attempt to separate application
634  frames and dialogs could be: a dialog window itself is side-effect  frames and dialogs could be: a dialog window itself is side-effect
635  free with respect to the application state and therefore the whole  free with respect to the application state and therefore the whole
636  sense of calling a dialog creation routine must arise from the values  sense of calling a dialog creation routine must arise from the values
# Line 648  An intermediate dialog is something that Line 656  An intermediate dialog is something that
656  additional information for (or before) an operation. When the user  additional information for (or before) an operation. When the user
657  selects the Search'' command, he is queried for a search string in  selects the Search'' command, he is queried for a search string in
658  an additional dialog window; probably offering other search options  an additional dialog window; probably offering other search options
659  like case insensitive search or backwards search. This is done in a  like case-insensitive search or backwards search. This is done in a
660  synchronous manner, blocking until the requested input is made  synchronous manner, blocking until the requested input is made
661  available by the user.  available by the user.
662
# Line 669  available by the user. Line 677  available by the user.
677  An application frame is an interface that provides the user with a  An application frame is an interface that provides the user with a
678  variety of commands to choose as his next step. For instance, the user  variety of commands to choose as his next step. For instance, the user
679  may choose from commands like Open, Save, Search, or Quit. The frame  may choose from commands like Open, Save, Search, or Quit. The frame
680  is a long-living GUI object compared to dialogs and there is no linear  is a long-living GUI object compared to dialogs, and there is no linear
681  execution path as there is in after a dialog as the user is free to  execution path as there is in after a dialog as the user is free to
682  select any commands he likes as next step.  select any commands he likes as his next action.
683
684  Hence, the synchronous programming pattern for dialogs is more  Hence, the synchronous programming pattern for dialogs is more
685  convenient because after dialog confirmations there is a predetermined  convenient because after dialog confirmations there is a predetermined
# Line 701  An application frame constructs its pane Line 709  An application frame constructs its pane
709  top-level pane in \macro{define-application-frame}. This pane is  top-level pane in \macro{define-application-frame}. This pane is
710  usually a layout pane that contains more gadget and/or layout panes as  usually a layout pane that contains more gadget and/or layout panes as
711  its children. With the help of layout panes, a pane hierarchy can be  its children. With the help of layout panes, a pane hierarchy can be
712  constructed. The top-level pane (and the whole hierarchy when its a  constructed. The top-level pane (and the whole hierarchy when it is a
713  layout pane) is created when the application frame is adopted by a  layout pane) is created when the application frame is adopted by a
714  frame manager and made visible to the user. The programmer can compose  frame manager and made visible to the user. The programmer can compose
715  an interface consisting of pre-defined gadget panes, layout panes, or  an interface consisting of pre-defined gadget panes, layout panes, or
# Line 717  leads that panes are implemented as subc Line 725  leads that panes are implemented as subc
725  augmenting the class with an active part. For instance, a button-pane  augmenting the class with an active part. For instance, a button-pane
726  actively draws its own button representation on its allotted screen  actively draws its own button representation on its allotted screen
727  area and a click on the correct button area triggers a callback for  area and a click on the correct button area triggers a callback for
728  the button. A composite pane lays out its children elements and  the button. A composite pane lays out its child elements and
729  request them to draw themselves onto specific screen regions.  requests them to draw themselves onto specific screen regions.
730
731  \CLIM{} comes with a set of predefined gadget panes. They consist of  \CLIM{} comes with a set of predefined gadget panes. They consist of
732  push-button, toggle-button, slider, radio-box, text-field, text-editor  push-button, toggle-button, slider, radio-box, text-field, text-editor
733  panes ready for use by the \CLIM{} application programmer. These  panes ready for use by the \CLIM{} application programmer. These
734  gadgets might be remapped to native system gadgets by the frame  gadgets might be remapped to native system gadgets by the frame
735  manager, so a native look and feel is possible.\footnote{Only possible  manager, so a native look and feel is possible.\footnote{Only possible
736    in McCLIM with the experimental beagle backend for Mac OS X.}    in \mcclim{} with the experimental beagle backend for Mac OS X.}
737
738  Each gadget pane class is associated with a set of generic functions  Each gadget pane class is associated with a set of generic functions
739  that as callbacks in traditional toolkits. For example, a pushbutton  that act as callbacks do in traditional toolkits. For example, a pushbutton
740  has an activate'' callback method which is invoked when its button  has an activate'' callback method which is invoked when its button
741  is pressed. For this particular callback, a method named  is pressed. For this particular callback, a method named
742  \method{activate-callback} is invoked per default and a \CLIM{}  \method{activate-callback} is invoked by default, and a \CLIM{}
743  programmer can provide a specialized method to implementation  programmer can provide a specialized method to implement
744  application specific behavior for a subclassed button-pane. But except  application-specific behavior for a subclassed button-pane. But except
745  in the case where the programmer needs a lot of buttons with related  in the case where the programmer needs a lot of buttons with related
746  behavior, creating a subclass for changing a single specific callback  behavior, creating a subclass for changing a single specific callback
747  is not economical. Hence upon gadget creation, the programmer can  is not economical. Hence upon gadget creation, the programmer can
748  specify an alternative callback method for all callback available. By  specify an alternative callback method for all callbacks available. By
749  providing the \keyword{:activate-callback} initarg, the programmer can  providing the \keyword{:activate-callback} initarg, the programmer can
750  change the callback to any regular or generic function. By convention,  change the callback to any regular or generic function. By convention,
751  all callbacks can be changed by providing an initarg keyword equal to  all callbacks can be changed by providing an initarg keyword equal to
# Line 810  color selection by manipulating their re Line 818  color selection by manipulating their re
818  separately. This example illustrates the use of gadget panes provided  separately. This example illustrates the use of gadget panes provided
819  by \CLIM{}. In the code in Figure \ref{fig-color-editor}, we define an  by \CLIM{}. In the code in Figure \ref{fig-color-editor}, we define an
820  application frame using \method{define-application-frame}. As said  application frame using \method{define-application-frame}. As said
821  before, the syntax of this macro is similar to \class{defclass}. It  before, the syntax of this macro is similar to that of \class{defclass}. It
822  defines a new frame class which automatically inherits from the class  defines a new frame class which automatically inherits from the class
823  \class{frame} which provides most of the functionality for handling  \class{frame} which provides most of the functionality for handling
824  frames.  frames.
825
826  One requirement must be fulfilled by all frame definitions: code to  One requirement must be fulfilled by all frame definitions: code to
827  generate a pane hierarchy must be supplied. The \keyword{:pane} option  generate a pane hierarchy must be supplied. The \keyword{:pane} option
828  is the simplest way to supply this code. \class{hello frame}  is the simplest way to supply this code.  The \class{hello-world} frame
829  constructs a hierarchy with only one application pane via  constructs a hierarchy with only one application pane via
830  \method{make-pane}. The pane hierarchy of color editor is more  \method{make-pane}. The pane hierarchy of color editor is more
831  interesting.  interesting.
# Line 896  look and feels for a slider. For example Line 904  look and feels for a slider. For example
904  whether the mouse button is held down during dragging, or whether the  whether the mouse button is held down during dragging, or whether the
905  mouse button is pressed once to start and again to stop dragging.  mouse button is pressed once to start and again to stop dragging.
906
907  We use the gadget id to distinguish between the red, green and blue  We use the gadget ID to distinguish between the red, green and blue
908  slider in the callback code. We could use three different callback  slider in the callback code. We could use three different callback
909  functions here, but such callbacks would have much more similarities  functions here, but such callbacks would have much more similarities
910  than differences, thus we do not do that here. Instead, we distinguish  than differences, thus we do not do that here. Instead, we distinguish
# Line 940  combination. Line 948  combination.
948
949  \subsection{A simple drawing application}  \subsection{A simple drawing application}
950
951  Next in our show case, we have a simple drawing application that draws  We move on to a simple drawing application that draws
952  lines and inserts text interactively. Our simple drawing program  lines and inserts text interactively. Our simple drawing program
953  defines commands for various drawing operations and binds specific  defines commands for various drawing operations and binds specific
954  input events to these commands.  input events to these commands.
955
956  The application frame is defined in  The application frame is defined in
957  \figurename~\ref{fig-draw-defapp}. A different approach is used to  \figurename~\ref{fig-draw-defapp}. A different approach is used to
958  generate the pane hierarchy. Instead of mixing the layout and pane  generate the pane hierarchy: instead of mixing the layout and pane
959  information, we used the \keyword{:panes} keyword to list all panes  information, we use the \keyword{:panes} keyword to list all panes
960  that should be available in frame layouts. The \keyword{:layouts}  that should be available in frame layouts. The \keyword{:layouts}
961  keyword combines them into several layouts. It is possible to define  keyword combines them into several layouts. It is possible to define
962  multiple layouts with this option. We define two simple layouts,  multiple layouts with this option. We define two simple layouts,
# Line 973  specify a name for a command-defining ma Line 981  specify a name for a command-defining ma
981  class. Passing \constant{t} to this option (its default) generates a  class. Passing \constant{t} to this option (its default) generates a
982  command definer named  command definer named
983  \macro{define-\texttt{<}frame-name\texttt{>}-command}. We can use the  \macro{define-\texttt{<}frame-name\texttt{>}-command}. We can use the
984  command-defining macro as convenience macro for  command-defining macro as a convenience macro for
985  \method{define-command} which is used to define frame commands. We  \method{define-command} which is used to define frame commands, and
986  will see them in action before long. \keyword{:top-level} specifies a  will see it in action before long. \keyword{:top-level} specifies a
987  special form that is used as top level command loop. The top level is  special form that is used as top level command loop. The top level is
988  responsible for dequeuing and executing commands that have been  responsible for dequeuing and executing commands that have been
989  invoked by the user. This loop is to a application frame what the REPL  invoked by the user. This loop is to a application frame what the REPL
990  is to a terminal.  is to a terminal.
991
992  This is the first example that does not use \class{clim-stream-pane}  This is the first example that does not use \class{clim-stream-pane}
993  (or one of its descendant) as pane class.\footnote{When using McCLIM,  (or one of its subclasses) as a pane class.\footnote{When using \mcclim{},
994  we have to do this as there are bugs in the behavior of  we have to do this as there are bugs in the behavior of
995  \class{clim-stream-pane} that have not been fixed yet.} Instead, we  \class{clim-stream-pane} that have not been fixed yet.} Instead, we
996  compose our own drawing pane using  compose our own drawing pane using
# Line 994  draw-pane that are required for the conv Line 1002  draw-pane that are required for the conv
1002  handling all requests belonging to the sheet and pane protocols in a  handling all requests belonging to the sheet and pane protocols in a
1003  standard manner. The last class is a mixin to tag the pane as  standard manner. The last class is a mixin to tag the pane as
1004  permanently visible on screen during its instances' lifetime. Most  permanently visible on screen during its instances' lifetime. Most
1005  static user interfaces use this mixin. Notice that McCLIM is sensible  static user interfaces use this mixin. Note that \mcclim{} is sensitive
1006  to the order of the superclasses.\footnote{All stream class like  to the order of the superclasses.\footnote{All stream classes like
1007  \class{standard-extended-input-stream} must be listed before  \class{standard-extended-input-stream} must be listed before
1008  \class{basic-pane}. Otherwise, there is no stream handling facilities  \class{basic-pane}. Otherwise, there are no stream handling facilities
1009  available.}  available.}
1010
1011  For \class{draw-pane}, the \method{handle-repaint} method shown in  For \class{draw-pane}, the \method{handle-repaint} method shown in
1012  \figurename~\ref{fig-draw-handlerepaint} is straight forward. It  \figurename~\ref{fig-draw-handlerepaint} is straightforward. It
1013  delegates background filling to the next less specific method and then  delegates background filling to the next less specific method and then
1014  iterates through the lines and strings painting them. Here, we  iterates through the lines and strings painting them. Here, we
1015  implicitly defined the format of the \code{lines} slot and the  implicitly defined the format of the \code{lines} slot and the
1016  \code{strings} slot of the application frame class. The elements of  \code{strings} slot of the application frame class. The elements of
1017  the list stored in \code{lines} are pairs of points, namely the start  the list stored in \code{lines} are pairs of points, namely the start
1018  and end point for a line. In \code{strings}, we store the text's  and end point for a line. In \code{strings}, we store the text's
1019  position as the first element of a cons and the text as its cdr.  position as the \code{car} of a cons and the text as its \code{cdr}.
1020
1021  % \class{draw-frame} uses two options in  % \class{draw-frame} uses two options in
1022  % \macro{define-application-frame} that we have not encountered  % \macro{define-application-frame} that we have not encountered
# Line 1026  commands for adding a text string, for a Line 1034  commands for adding a text string, for a
1034  draw pane. After every command, we update the drawing pane via the  draw pane. After every command, we update the drawing pane via the
1035  auxiliary method \method{update-draw-pane}.\footnote{An experienced  auxiliary method \method{update-draw-pane}.\footnote{An experienced
1036  \CLIM{} programmer would define a display-function for  \CLIM{} programmer would define a display-function for
1037  \class{draw-pane}. These function is run whenever a command was  \class{draw-pane}. This function is run after a command is
1038  executed causing the display pane to be updated with any changes. But  executed, and causes the display pane to be updated with any changes. We
1039  we will save this technique for later examples.}  will save this technique for later examples.}
1040
1041  At this point, we can actually use the application; although not very  At this point, we can actually use the application; although not very
1042  conveniently. The interactor pane can be used to invoke one of three  conveniently. The interactor pane can be used to invoke one of three
# Line 1128  execution (code bodies of \method{define Line 1136  execution (code bodies of \method{define
1137  %  %
1138
You may notice that there are issue with redrawing with this example
in McCLIM. Unfortunately, this has not been fixed before the release

1139  \section{High Level Facilities}  \section{High Level Facilities}
1140
1141  In this section, we explain a number of higher level facilities  In this section, we explain a number of higher level facilities
# Line 1170  instance row and column formatting infor Line 1173  instance row and column formatting infor
1173  \paragraph*{Output Formatting} \CLIM{} provides a convenient table and  \paragraph*{Output Formatting} \CLIM{} provides a convenient table and
1174  graph formatting facility, which is built on top of the output  graph formatting facility, which is built on top of the output
1175  recording facility. The key to these formatting tools (as opposed to,  recording facility. The key to these formatting tools (as opposed to,
1176  say, \code{format}'s X directive) is that they dynamically compute the  say, \code{format}'s \code{~T} directive) is that they dynamically compute the
1177  formatting parameters based on the actual size of the  formatting parameters based on the actual size of the
1178  application-generated output.  application-generated output.
1179
# Line 1195  information about the packages in the Li Line 1198  information about the packages in the Li
1198  Any attempt to fix this function to produce tabular output by building  Any attempt to fix this function to produce tabular output by building
1199  in a certain fixed spacing between the package name and symbol count  in a certain fixed spacing between the package name and symbol count
1200  will either get caught by an unexpectedly long package name, or will  will either get caught by an unexpectedly long package name, or will
1201  have to reserve way to much space for the typical case. In \CLIM{}, we  have to reserve way too much space for the typical case. In \CLIM{}, we
1202  can use the code in Figure \ref{fig-formatting} to produce a neatly  can use the code in Figure \ref{fig-formatting} to produce a neatly
1203  formatted table for any set of package names.  formatted table for any set of package names.
1204  \begin{figure*}  \begin{figure*}
# Line 1230  underlying system it is just a text stri Line 1233  underlying system it is just a text stri
1233  the semantics can be recovered from the string. Thus the power of the  the semantics can be recovered from the string. Thus the power of the
1234  various textual cut-and-paste mechanisms supported by contemporary  various textual cut-and-paste mechanisms supported by contemporary
1235  computer systems. However, it is possible to improve upon the utility  computer systems. However, it is possible to improve upon the utility
1236  of this lowest common denominator facility (i.e. squeezing everything  of this lowest common denominator facility (i.e.{} squeezing everything
1237  through its printed representation) by remembering the semantics of  through its printed representation) by remembering the semantics of
1238  the output as well as its appearance. This is the idea behind  the output as well as its appearance. This is the idea behind
1239  presentations.  presentations.
# Line 1258  in a presentation of type \code{'pathnam Line 1261  in a presentation of type \code{'pathnam
1261  types, which are arranged in a super-type/subtype lattice like the CL  types, which are arranged in a super-type/subtype lattice like the CL
1262  types. In fact, the presentation type hierarchy is an extension of the  types. In fact, the presentation type hierarchy is an extension of the
1263  CL type hierarchy. The reason that this extended type system is needed  CL type hierarchy. The reason that this extended type system is needed
1264  is that the CL type system is overloaded from the UI perspective. For  is that the CL type system is insufficient from the UI perspective. For
1265  example, the integer 72 might represent a heart rate in one  example, the integer 72 might represent a heart rate in one
1266  application and a Fahrenheit temperature in another, but it will  application and a Fahrenheit temperature in another, but it will
1267  always just be an integer to Lisp.  always be just an integer to Lisp.
1268
1269  The application programmer can define the UI entities of the  The application programmer can define the UI entities of the
1270  application by defining presentation types, thus extending the  application by defining presentation types, thus extending the
# Line 1270  programmer can centralize all of the UI Line 1273  programmer can centralize all of the UI
1273  place, including output appearance and input syntax. As an example,  place, including output appearance and input syntax. As an example,
1274  \CLIM{} defines a pathname presentation type that defines how a  \CLIM{} defines a pathname presentation type that defines how a
1275  pathname is displayed and how one is input. The pathname input side  pathname is displayed and how one is input. The pathname input side
1276  provides pathname completion and possibilities-display features. By  provides pathname completion and display of possibilities. By
1277  defining this behavior in one place and using it in all applications  defining this behavior in one place and using it in all applications
1278  that need to display or read pathnames, \CLIM{} helps build consistent  that need to display or read pathnames, \CLIM{} helps build consistent
1279  user interfaces.  user interfaces.
# Line 1284  associated with some graphics that were Line 1287  associated with some graphics that were
1287
1288  \begin{lstlisting}  \begin{lstlisting}
1289  (with-output-as-presentation  (with-output-as-presentation
1290         (:object path      (:object path
1291          :type 'pathname       :type 'pathname
1292          :stream s)       :stream s)
1293    (draw-rectangle* s 0 0 30 30))    (draw-rectangle* s 0 0 30 30))
1294  \end{lstlisting}  \end{lstlisting}
1295
# Line 1358  is defined to take an argument of the se Line 1361  is defined to take an argument of the se
1361  \caption{File Browser}\label{fig-file-browser}  \caption{File Browser}\label{fig-file-browser}
1362  \end{figure*}  \end{figure*}
1363
1364  The \class{dirlist-frame} application is a very simple-minded file  The \class{dirlist-frame} application is a very simple file
1365  system browser using presentation types.  It defines two panes, an  system browser using presentation types.  It defines two panes, an
1366  output pane to display directory contents and an input pane to handle  output pane to display directory contents and an input pane to handle
1367  user typein.  For the output pane, the application defines a display  user typein.  For the output pane, the application defines a display
1368  function. \code{dirlist-display-files} works in conjunction with the  function. \code{dirlist-display-files} works in conjunction with the
1369  top level command loop. Per default, the command loop calls all  top level command loop. By default, the command loop calls all
1370  display functions after a command was processed to make all changes in  display functions after a command was processed to make all changes in
1371  the application's data structures visible that the command execution  the application's data structures visible that the command execution
1372  might have caused. When all display functions have updated their  might have caused. When all display functions have updated their
1373  panes, the command loop displays a prompt in the  panes, the command loop displays a prompt in the
1374  interactor\footnote{Might be omitted when there is no interactor pane}  interactor\footnote{Omitted when there is no interactor pane.}
1375  and waits for the next command.  and waits for the next command.
1376
1377  The \method{dirlist-display-files} display function iterates over the  The \method{dirlist-display-files} display function iterates over the
# Line 1414  This command translator has little work Line 1417  This command translator has little work
1417  translator has to return a list of arguments that are handed to the  translator has to return a list of arguments that are handed to the
1418  command \code{com-edit-directory}. But we do not need to any  command \code{com-edit-directory}. But we do not need to any
1419  conversion of the supplied object, as it is already a pathname. Thus,  conversion of the supplied object, as it is already a pathname. Thus,
1420  the received object is wrapped in a list and handed back to the caller  the object is wrapped in a list and returned to the caller
1421  which will call \code{com-edit-directory} with the supplied objects.  which will apply \code{com-edit-directory} to the list.
1422
1423  A simple trick is used to dispatch an initial command to the  A simple trick is used to dispatch an initial command to the
1424  application frame. An after-method is provided for  application frame. An after-method is provided for
# Line 1463  methods on presentation types.  Via this Line 1466  methods on presentation types.  Via this
1466  and a parser function for the type \code{weekday}. As is the case with  and a parser function for the type \code{weekday}. As is the case with
1467  most presentation types, the printer and parser are duals. That is,  most presentation types, the printer and parser are duals. That is,
1468  the printer, when given an object to print, produces output that the  the printer, when given an object to print, produces output that the
1469  parser can interpret to arrive back at the original object. Not in  parser can interpret to arrive back at the original object.
1470  every case the parser in \code{accept} is needed to return an object  \code{accept} does not need a parser in every case, and for simplicity
1471  of the requested type, and for simplicity the programmer might choose  the programmer might choose not to provide a parser at all.
not to provide a parser at all.
1472
1473  We took the easy way out with our parser. \CLIM{} provides a  We took the easy way out with our parser. \CLIM{} provides a
1474  completion facility and instead of reading the day name of the stream  completion facility and instead of reading the day name of the stream
1475  and parsing it into an integer, we provided an exhaustive set of input  and parsing it into an integer, we provided an exhaustive set of input
1476  to object mappings. The \macro{completing-from-suggestions} macro  to object mappings. The \macro{completing-from-suggestions} macro
1477  collects all suggestions made by the parser via  collects all suggestions made by the parser via
1478  \code{suggest}. \code{suggest} is takes an input and object as  \code{suggest}. \code{suggest} takes an input and object as
1479  suggestion. In our case, day name taken from \variable{*days*} is the  suggestion. In our case, day name taken from \variable{*days*} is the
1480  input and the number of the week \variable{i} is the object. \CLIM{}  input and the number of the week \variable{i} is the object. \CLIM{}
1481  will match the input given by the user with the suggestions and in  will match the input given by the user with the suggestions and in
# Line 1513  this keyword-value pair and generate a p Line 1515  this keyword-value pair and generate a p
1515  precisely, a presentation-to-command translator is defined that is  precisely, a presentation-to-command translator is defined that is
1516  equal in functionality to the one we have seen in the file-browser  equal in functionality to the one we have seen in the file-browser
1517  example. Whenever a presentation of the type \code{pathname} is  example. Whenever a presentation of the type \code{pathname} is
1518  selected (e.g. with pointer clicks) in a \class{command} input  selected (e.g.{} with pointer clicks) in a \class{command} input
1519  context, it is translated into a command invocation of Select  context, it is translated into a command invocation of Select
1520  Weekday''.  Weekday''.
1521
# Line 1605  constructed from a high-level specificat Line 1607  constructed from a high-level specificat
1607
1608  \section{Conclusion}  \section{Conclusion}
1609
1611  range of functionality provided by \CLIM{}. The later examples,  range of functionality provided by \CLIM{}. The later examples,
1612  especially, demonstrate that complex user interfaces can be built  especially, demonstrate that complex user interfaces can be built
1613  economically and modularly using \CLIM{}. Many of the higher level  economically and in a modular fashion using \CLIM{}. Many of the higher level
1614  facilities make it possible to separate the issues involved in  facilities make it possible to separate the issues involved in
1615  designing an application's user interface from the functionality of  designing an application's user interface from the functionality of
1616  the application.  the application.
1617
1618  On the other hand, many of these higher level facilities may not be  On the other hand, these higher level facilities are not
1619  appropriate for all users. \CLIM{}'s lower level facilities and clean  appropriate for all programmers. \CLIM{}'s lower level facilities and clean
1620  modularization of the higher level facilities provide these users with  modularization of the higher level facilities provide these programmers with
1621  portable platform and a framework for implementing their own user  portable platform and a framework for implementing their own user
1622  interface toolkits and frameworks. In addition, \CLIM{}'s use of CLOS  interface toolkits and frameworks. In addition, \CLIM{}'s use of \CLOS{}
1623  to define explicit, documented protocols provides application  to define explicit, documented protocols provides application
1624  programmers with the opportunity to customize \CLIM{} and support  programmers with the opportunity to customize \CLIM{} and support
1625  interfaces not anticipated by the \CLIM{} designers.  interfaces not anticipated by the \CLIM{} designers.
1626
1627  A free \CLIM{} implementation is available as McCLIM. McCLIM only  A free \CLIM{} implementation is available as \mcclim{}, found at
1628  works on X windows at the moment. An experimental port to Mac OS X  \url{http://common-lisp.net/project/mcclim/}. In addition to the
1629  called Beagle is in progress. It can be found on  caveats in this document, note that \mcclim{} only works with an X
1630  http://common-lisp.net/project/mcclim/.  windows backend as of January 2006.  An experimental port called
1631    beagle to the native toolkit of Mac OS X is in progress.
1632
1633  \section*{Acknowledgments}  \section*{Acknowledgments}
1634
# Line 1638  Symbolics; and Gregor Kizcales and John Line 1641  Symbolics; and Gregor Kizcales and John
1641  Mark Son-Bell and Jon L. White have help us improve this paper.  Mark Son-Bell and Jon L. White have help us improve this paper.
1642
1643  \paragraph*{2006 update} Clemens Fruhwirth thanks the developers for  \paragraph*{2006 update} Clemens Fruhwirth thanks the developers for
1644  McCLIM for producing a free \CLIM{} implementation, and especially  \mcclim{} for producing a free \CLIM{} implementation, and especially
1645  Robert Strandh for answering so many questions in conjunction with  Robert Strandh for answering so many questions in conjunction with
1646  McCLIM.  \mcclim{}.
1647
1648  \bibliographystyle{alpha}  \bibliographystyle{alpha}
1649  \bibliography{guided-tour}  \bibliography{guided-tour}

Legend:
 Removed from v.1.1 changed lines Added in v.1.2