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

revision 1.2 by cfruhwirth, Thu Feb 9 13:20:38 2006 UTC revision 1.3 by rgoldman, Thu Mar 16 15:50:20 2006 UTC
# Line 89  basic operations based on stream reading Line 89  basic operations based on stream reading
89  The Common Lisp Interface Manager addresses this problem by specifying  The Common Lisp Interface Manager addresses this problem by specifying
90  an interface to a broad range of services necessary or useful for  an interface to a broad range of services necessary or useful for
91  developing graphical user interfaces. These services include low level  developing graphical user interfaces. These services include low level
92  facilities like geometry, graphics, event-oriented input, and  facilities such as geometry, graphics, event-oriented input, and
93  windowing; intermediate level facilities like support for Common Lisp  windowing; intermediate level facilities such as support for Common Lisp
94  stream operations, output recording, and advanced output formatting;  stream operations, output recording, and advanced output formatting;
95  and high level facilities like context sensitive input, an adaptive  and high level facilities such as context sensitive input, an adaptive
96  toolkit, and an application building framework.  toolkit, and an application building framework.
97
98  \CLIM{} implementations will eventually support a large number of window environments  \CLIM{} implementations will eventually support a large number of window environments
# Line 101  designed to exploit the functionality pr Line 101  designed to exploit the functionality pr
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
102  windows are typically mapped onto host windows, and input and output  windows are typically mapped onto host windows, and input and output
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. \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 application 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 the operating platform.
108
109  An important goal that has guided the design of \CLIM{} was 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
# Line 127  particular application. Line 127  particular application.
127
128  For example, \CLIM{}'s application framework and adaptive toolkit  For example, \CLIM{}'s application framework and adaptive toolkit
129  allow programmers 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 is 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
# Line 168  transformations; and functions for manip Line 168  transformations; and functions for manip
168  \caption{An Overview of \CLIM{} facilities}\label{clim-facilities}  \caption{An Overview of \CLIM{} facilities}\label{clim-facilities}
169  \end{figure*}  \end{figure*}
170
171  \paragraph*{Graphic substrate} \CLIM{} provides a portable interface  \paragraph*{Graphics substrate} \CLIM{} provides a portable interface
172  to a broad set of graphics functions for drawing complex geometric  to a broad set of graphics functions for drawing complex geometric
173  shapes.  shapes.
174
# Line 177  implementing sheets (windows and other w Line 177  implementing sheets (windows and other w
177
178  \paragraph*{Extended Streams} \CLIM{} integrates the Common Lisp  \paragraph*{Extended Streams} \CLIM{} integrates the Common Lisp
179  Stream I/O functionality with the \CLIM{} graphics, windowing, and  Stream I/O functionality with the \CLIM{} graphics, windowing, and
180  panes facilities. Next to ordinary text, the programmer can send a  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  button, a picture or any other arbitrary widget to a \CLIM{} output
184  stream and \CLIM{} will display the widget in the sheet associated  stream and \CLIM{} will display the widget in the sheet associated
185  with the output stream.  with the output stream.
# Line 189  repainting it when necessary. Line 191  repainting it when necessary.
191  \paragraph*{Formatted Output} \CLIM{} provides a set of high-level  \paragraph*{Formatted Output} \CLIM{} provides a set of high-level
192  macros that enable programs to produce neatly formatted tabular and  macros that enable programs to produce neatly formatted tabular and
193  graphical displays easily.\footnote{This also includes Graph  graphical displays easily.\footnote{This also includes Graph
194    Formatting.}    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  \paragraph*{Presentations} \CLIM{} provides the ability to associate
198  semantics with output, such that Lisp objects may be retrieved later  semantics with output, such that Lisp objects may be retrieved later
199  via user gestures (e.g.{} mouse clicks) on their displayed  via user gestures (e.g.{} mouse clicks) on their displayed
200  representation. This context sensitive input is modularly layered on  representation. This context sensitive input is modularly layered on
201  top of the output recording facility and is integrated with the Common  top of the output recording facility and is integrated with the Common
202  Lisp type system. A mechanism for type coercion is also included,  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.  providing the basis for powerful user interfaces.
208
209  \paragraph*{Panes} \CLIM{} provides \concept{panes} that are analogous  \paragraph*{Panes} \CLIM{} provides \concept{panes} that are analogous
# Line 212  for displaying and allowing users to int Line 219  for displaying and allowing users to int
219  independence by specifying a set of abstract gadget pane  independence by specifying a set of abstract gadget pane
220  protocols. These protocols define a gadget in terms of its function  protocols. These protocols define a gadget in terms of its function
221  and not in terms of the details of its appearance or  and not in terms of the details of its appearance or
222  operation. Application that use these gadget types and related  operation. Applications that use these gadget types and related
223  facilities will automatically adapt to use whatever toolkit is  facilities will automatically adapt to use whatever toolkit is
224  available and appropriate for the host environment. In addition,  available on and appropriate for the host environment. In addition,
225  portable Lisp-based implementations of the abstract gadget pane  portable Lisp-based implementations of the abstract gadget pane
226  protocols are provided.\footnote{\mcclim{} does not support look and feel  protocols are provided.\footnote{\mcclim{} does not support look and feel
227    adaptiveness at the moment except for the experimental beagle backend for Mac    adaptiveness at the moment except for the experimental beagle backend for Mac
# Line 234  implicitly invoking a presentation-trans Line 241  implicitly invoking a presentation-trans
241  presentation. Commands can also be invoked explicitly by the  presentation. Commands can also be invoked explicitly by the
242  programmer.  programmer.
243
244  \paragraph*{Dialogs and Incremental Update} Incremental Redisplay goes  % 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  a bit further than Output Recording. With Incremental Redisplay, an
248  output record can not only reproduce content that was written to a  output record can not only reproduce content that was written to a
249  stream, the \CLIM{} programmer can also attach the code that generated  stream, the \CLIM{} programmer can also attach the code that generated
# Line 253  example in the realm of programming: Hel Line 262  example in the realm of programming: Hel
262
263  \section{Our first application}  \section{Our first application}
264
265  We will spend a few lines of code for the trivial Hello World example  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  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  serves as a point of reference from where the reader can start his
268  explorations for more challenging \CLIM{} facilities. We do not try to  explorations of more challenging \CLIM{} facilities. We do not try to
269  elaborate the \CLIM{} concepts in detail here, but simply use them  elaborate the \CLIM{} concepts in detail here, but simply use them
270  with a brief discussion. The confused reader may hope for a more  with a brief discussion. The confused reader may hope for a more
271  in-depth explanation in the following section. Please regard  in-depth explanation in the following section. Please regard
# Line 264  in-depth explanation in the following se Line 273  in-depth explanation in the following se
273  \concept{sheet hierarchy}, \concept{graft} and \concept{top-level  \concept{sheet hierarchy}, \concept{graft} and \concept{top-level
274    loop} as terms we will discuss later.    loop} as terms we will discuss later.
275
276  Also, we conduct excessive \CLIM{} specification referencing in  We provide extensive \CLIM{} specification references in
277  footnotes. The motivation for this is to show that all the relevant  footnotes. The motivation for this is to show that all the relevant
278  information can be found in the \CLIM{} 2  information can be found in the \CLIM{} 2
279  specification\cite{clim-spec}. Before a good \CLIM{} programmer can  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  master any \CLIM{} concept, he has to get used to the style of writing
281  of the specification first as this is the most relevant work for  of the specification, as this is the most relevant work for
282  \CLIM{}. The best we can do in this context is to provide pointers and  \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  references and hope that the interested reader starts to explore the
284  surrounding text sections on his own.  surrounding text sections on his own.
285
286  After loading a \CLIM{} implementation, the package  After loading a \CLIM{} implementation, the package
287  \keyword{:clim-user} is available to absorb user code. This package is  \keyword{:clim-user} is available to absorb user code. This package is
288  a good start for experimentations and first steps. When proper  a good start for experimentation and first steps. When proper
289  packaging is required, simply include the packages \keyword{:clim} and  packaging is required, simply include the packages \keyword{:clim} and
290  \keyword{:clim-lisp} in your \keyword{:use} list.  \keyword{:clim-lisp} in your new package's \keyword{:use} list.
291
292  The central element of \CLIM{} application programming is the  The central element of \CLIM{} application programming is the
293  \concept{application-frame}. An application frame is defined via  \concept{application-frame}. An application frame is defined via
294  \code{define-application-frame}.\footnote{See Section 28.2 Defining  \code{define-application-frame}.\footnote{See Section 28.2 Defining
295    and Creating Application Frames'' in \cite{clim-spec}.} Here comes    and Creating Application Frames'' in \cite{clim-spec}.} Here is
296  the application frame for Hello World:  the application frame definition for Hello World:
297  \lstset{style=inlinestyle}  \lstset{style=inlinestyle}
298  \lstinputlisting{hello-world-def-app}  \lstinputlisting{hello-world-def-app}
299
# Line 293  the application frame for Hello World: Line 302  the application frame for Hello World:
302  \lstinputlisting{hello-world-handle-repaint}  \lstinputlisting{hello-world-handle-repaint}
303  \caption{\method{handle-repaint} for \class{hello-world-pane}}\label{hello-world-repaint}  \caption{\method{handle-repaint} for \class{hello-world-pane}}\label{hello-world-repaint}
304  \end{figure*}  \end{figure*}
305  Its basic syntax is similar to \code{defclass} because  \code{define-application-frame}'s basic syntax is similar to \code{defclass} because
306  \code{define-application-frame} also generates classes. In this case,  \code{define-application-frame} also generates classes. In this case,
307  it creates a frame class \class{hello-world} that has no superclass  it creates a frame class \class{hello-world} that has no superclass
308  except \class{frame} which is added automatically.  except \class{frame} (which is added automatically).
309
310  With \code{:pane}, we define a \concept{top-level-pane} that becomes  With \code{:pane}, we define a \concept{top-level-pane} that becomes
311  the content of the fresh window that belongs to an application  the content of a fresh window that belongs to an application
312  frame. But sometimes, an application frame is swallowed by another  frame.  Although the usual case is for an application frame to
313  application and only space in an other existing window is  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  reserved. For instance, a web site management tool might swallow a
316  text editor, so the user has the option to edit web sites without  text editor, so that the user has the option to edit web sites without
317  switching to another application.  switching to another application.
318
319  % \footnote{The graft is the root of a sheet hierarchy and on most  % \footnote{The graft is the root of a sheet hierarchy and on most
# Line 320  evaluated when an instance of the \class Line 330  evaluated when an instance of the \class
330  created. We use \method{make-pane} to construct a pane as the  created. We use \method{make-pane} to construct a pane as the
331  top-level-pane for frame instances. \method{make-pane} is a  top-level-pane for frame instances. \method{make-pane} is a
332  constructor for panes.\footnote{See Section 29.2 Basic Pane  constructor for panes.\footnote{See Section 29.2 Basic Pane
333    Construction'' in \cite{clim-spec}.} We can treat it as    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  \code{make-instance} especially made for pane classes.  Let us have a
335  look at the definition of \class{hello-world-pane}.  look at the definition of \class{hello-world-pane}.
336
337  \lstset{style=inlinestyle} \lstinputlisting{hello-world-defclass}  \lstset{style=inlinestyle} \lstinputlisting{hello-world-defclass}
338
339  The one and only superclass of \class{hello-world-pane} is  The one and only superclass of \class{hello-world-pane} is
340  \class{clim-stream-pane}\footnote{See Section 29.4 CLIM Stream  \class{clim-stream-pane}.\footnote{See Section 29.4 CLIM Stream
341    Panes'' in \cite{clim-spec}.}. As there are no additional slots, an    Panes'' in \cite{clim-spec}.} As there are no additional slots, an
342  experienced \CLOS{} user might guess that we will use  experienced \CLOS{} programmer might guess that we will use
343  \class{hello-world-pane} solely for method specialization.  Before doing so,  \class{hello-world-pane} solely for method specialization.  Before doing so,
344  let us have a look what we have actually  let us have a look what we have actually
345  inherited from \class{clim-stream-pane}\footnote{Internal classes  inherited from \class{clim-stream-pane}:\footnote{Internal classes
346    removed from listing.}:    removed from listing.}
347
348  \lstset{style=inlinestyle}  \lstset{style=inlinestyle}
349  \begin{lstlisting}  \begin{lstlisting}
# Line 349  SHEET-MULTIPLE-CHILD-MIXIN Line 359  SHEET-MULTIPLE-CHILD-MIXIN
359  BASIC-PANE  BASIC-PANE
360  \end{lstlisting}  \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  \class{basic-pane} is the foundation of all pane classes. It provides
367  reasonable defaults for all protocol methods and inherits from the  reasonable defaults for all protocol methods and inherits from the
368  protocol class \class{pane}. In turn, \class{pane} inherits from  protocol class \class{pane}. In turn, \class{pane} inherits from
# Line 399  up to the details we skipped in this exa Line 413  up to the details we skipped in this exa
413
414  \subsection{Geometry}  \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  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  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  corresponds to a point, a path or an area respectively. Regions can be
# Line 421  transformations can move, stretch and ro Line 442  transformations can move, stretch and ro
442  transformation is affine when every straight line remains straight  transformation is affine when every straight line remains straight
443  after transformation. Transformations can be composed arbitrarily. The  after transformation. Transformations can be composed arbitrarily. The
444  programmer can attach transformations to mediums and panes. In layout  programmer can attach transformations to mediums and panes. In layout
445  panes, \CLIM{} uses transformation to map the coordinates of children  panes, \CLIM{} uses transformations to map the coordinates of child
446  panes to the coordinate system of its parents. All drawing settings  panes to the coordinate system of their parents.
447  can be changed permanently, or in the context of a
448  \macro{with-drawing-options} macro temporarily.  % 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}  \subsection{The Windowing Substrate}
# Line 519  other side, \code{handle-event} is inten Line 545  other side, \code{handle-event} is inten
545  specialization, so the application developer can implement special  specialization, so the application developer can implement special
546  policies for selected events. For instance, when a sheet notices  policies for selected events. For instance, when a sheet notices
547  through a \code{window-configuration-event} that the sheet's size  through a \code{window-configuration-event} that the sheet's size
548  changed, it might redo its layout for its children panes.  has changed, it might redo its layout for its children.
549
550  % There are two mixins that specialize on the  % There are two mixins that specialize on the
551  % \code{window-repaint-event} class as event argument to  % \code{window-repaint-event} class as event argument to
# Line 561  sheet. Line 587  sheet.
587  %   the sheet's medium. According to the \mcclim{} authors, this is done  %   the sheet's medium. According to the \mcclim{} authors, this is done
588  %   for optimization.}  %   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  The graphic output capabilities of sheets range from simple line style
597  and text style customization over rendering various geometrical  and text style customization over rendering various geometrical
598  shapes, a color model capable of doing alpha blending, composable  shapes, a color model capable of doing alpha blending, composable
# Line 569  pixmaps usage. The features of the \conc Line 601  pixmaps usage. The features of the \conc
601  specified briefly in Section 8.3 Output Protocol''and more precisely  specified briefly in Section 8.3 Output Protocol''and more precisely
602  in Chapters 10-14 of \cite{clim-spec}.  in Chapters 10-14 of \cite{clim-spec}.
603
604  \CLIM{} lives in idealized world in terms of graphics operations. A  \CLIM{} lives in an idealized world in terms of graphics operations. A
605  \CLIM{} programmer can use an infinitely long and wide drawing pane  \CLIM{} programmer can use an infinitely long and wide drawing pane
606  with an arbitrarily precise resolution and continuously variable  with arbitrarily precise resolution and continuously variable
607  opacity. As rendering devices with these properties are rare,  opacity. As rendering devices with these properties are rare,
608  we need to render the idealized graphic description to a device  we need to render the idealized graphic description to a device
609  with finite size and a fixed drawing precision. The rendering rules  with finite size and a fixed drawing precision. The rendering rules
# Line 602  appropriate place in a sheet hierarchy ( Line 634  appropriate place in a sheet hierarchy (
634  system window hierarchy) when the frame is adopted.  system window hierarchy) when the frame is adopted.
635
636  To build a user interface, an application programmer defines one or  To build a user interface, an application programmer defines one or
637  more frames classes. These frame classes define a number of frame  more frame classes. These frame classes define a number of frame
638  properties including application specific state and a hierarchy of  properties including application specific state and a hierarchy of
639  panes (i.e.{} user interface gadgets and regions, for interacting with  panes (i.e.{} user interface gadgets and regions, for interacting with
640  the users). Frame classes also provide hooks for customizing  the users). Frame classes also provide hooks for customizing
# Line 615  when the frame is made visible on some d Line 647  when the frame is made visible on some d
647  up is usually quite different from the code that is used to generate  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  the content of application frames. This is unusual for a windowing
649  toolkit as most of them unify the generation of dialog content and  toolkit as most of them unify the generation of dialog content and
650  content of other windows types.  content of other window types.
651
652  \CLIM{} generates a dialog with the appropriate input gadget as  \CLIM{} generates a dialog with the appropriate input gadget as
653  consequence of a series of input requests. Thanks to the stream  consequence of a series of input requests. Thanks to the stream
# Line 624  a blocking read request. He does not hav Line 656  a blocking read request. He does not hav
656  asynchronously handling confirmation or cancel button clicks.  For  asynchronously handling confirmation or cancel button clicks.  For
657  instance, the programmer requests a string from the user and the user  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  is presented with a prompt, an editable text field, and two buttons
659  for confirmation and canceling. Only after the user hits the  for confirmation and canceling.
660  confirmation button, the string requesting function returns; the  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  programmer can directly use the function's return value which is the
663  string provided by the user. Clicking the cancel button is dealt with by throwing to an  string provided by the user.
664  \code{abort} tag.  % 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  From the caller's perspective, an attempt to separate application
674  frames and dialogs could be: a dialog window itself is side-effect  frames and dialogs could be: a dialog window itself is side-effect
# Line 719  are analogous to the gadgets or widgets Line 759  are analogous to the gadgets or widgets
759  Panes and sheets as defined by the windowing substrate have in common  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  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  optional children. They differ in their usage of the input and output
762  capabilities. A sheet is passive and intended for others to be used,  capabilities. A sheet is passive and intended to be used by other,
763  while a pane already contains this active part. This relationship  active components,
764  leads that panes are implemented as subclasses of \class{basic-sheet}  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  augmenting the class with an active part. For instance, a button-pane
768  actively draws its own button representation on its allotted screen  actively draws its own button representation on its allotted screen
769  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
# Line 745  application-specific behavior for a subc Line 787  application-specific behavior for a subc
787  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
788  behavior, creating a subclass for changing a single specific callback  behavior, creating a subclass for changing a single specific callback
789  is not economical. Hence upon gadget creation, the programmer can  is not economical. Hence upon gadget creation, the programmer can
790  specify an alternative callback method for all callbacks available. By  specify an alternative callback method for any callback available. For
791    example, by
792  providing the \keyword{:activate-callback} initarg, the programmer can  providing the \keyword{:activate-callback} initarg, the programmer can
793  change the callback to any regular or generic function. By convention,  change the callback to any regular or generic function. By convention,
794  all callbacks can be changed by providing an initarg keyword equal to  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  the callback's name. See Chapter 30 in \cite{clim-spec} for a listing
796  and description of available callbacks.  and description of available callbacks.
797
798  \CLIM{} also provides composite and layout panes. These pane types are  \CLIM{} also provides composite and layout panes. These pane types are
799  used for aggregating several children panes into a bigger single pane  used for aggregating several child panes into a bigger single pane
800  that has a layout according to the requested directives.  For example,  that has a layout according to the requested directives.  For example,
801  \CLIM{} provides two pane classes, \class{hbox-pane} and  \CLIM{} provides two pane classes, \class{hbox-pane} and
802  \class{vbox-pane}, that lay out their children in horizontal rows or  \class{vbox-pane}, that lay out their children in horizontal rows or
# Line 764  builder for instance), the program does Line 807  builder for instance), the program does
807  management via the windowing protocol. He is provided with a set of  management via the windowing protocol. He is provided with a set of
808  convenience macros that allows elegant interfaces composed simply by  convenience macros that allows elegant interfaces composed simply by
809  wrapping the respective pane construction code into the convenience  wrapping the respective pane construction code into the convenience
810  macros.  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  Application pane classes can be used for subclassing. They can be used
813  to present application specific data -- for instance by specializing  to present application specific data -- for instance by specializing
814  \method{handle-repaint} -- and manage user interactions -- for  \method{handle-repaint} -- and to manage user interactions -- for
815  instance by specializing \method{handle-event}.  instance by specializing \method{handle-event}.
816
817  \subsection{Commands}  \subsection{Commands}
# Line 784  Application programmers define a command Line 827  Application programmers define a command
827  choose to export as an explicit user entry point. A command is defined  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  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  commands can then be invoked using a variety of interaction
830  techniques. For example, commands can be invoked from menu, keyboard  techniques. For example, commands can be invoked from menus, keyboard
831  accelerators, direct typein, mouse clicks on application data, or  accelerators, direct typein, mouse clicks on application data, or