A Guided Tour of CLIM,Common Lisp Interface Manager

2006 UpdateClemens Fruhwirth <clemens@endorphin.org>

The McCLIM Project

Original article∗

Ramana Rao <rao@xerox.com> Xerox Palo Alto Research CenterWilliam M. York <york@ila.com> International Lisp Associates, Inc.Dennis Doughty <doughty@ila.com> International Lisp Associates, Inc.

October 14, 2019

Abstract

The Common Lisp Interface Manager (clim) pro-vides a layered set of facilities for building user in-terfaces. These facilities include a portable lay-ers for basic windowing, input, output services,and mechanisms for constructing window types anduser interface components; stream-oriented inputand output facilities extended with presentationsand context sensitive input;1 and a gadget-orientedtoolkit similar to those found in the X world ex-tended with support for look and feel adaptiveness.In this article, we present an overview of clim’sbroad range of functionality and present a series ofexamples that illustrates clim’s power. The arti-cle originally appeared in Lisp Pointers in 1991 andwas updated in 2006 by Clemens Fruhwirth.2 Allexamples in this article have been run with Mc-CLIM[McC], a free clim implementation, as ofJanuary 2006.

∗Published in Lisp Pointers 19911Similar to the work pioneered in the Genera UI system2The CLIM 2 specification changed significant parts of

clim rendering legacy code unusable. Clemens Fruhwirthhas rewritten all examples and the corresponding text sec-tions for the clim 2 specification. In addition, he has restruc-tured the whole article, adding sections to provide additionalinsights into clim concepts.

Introduction

Common Lisp is a language standard that has pro-vided a broad range of functionality, and that has,to a large degree, successfully enabled the writingof truly portable Lisp programs. The emergenceof clos and the cleanup efforts of ANSI X3J13have further enhanced the utility and portabilityof Common Lisp. However, one major stumblingblock remains in the path of those endeavoring towrite large portable applications. The CommonLisp community has not yet provided a standardinterface for implementing user interfaces beyondthe most basic operations based on stream readingand printing.3

The Common Lisp Interface Manager addressesthis problem by specifying an interface to a broadrange of services necessary or useful for develop-ing graphical user interfaces. These services in-clude low level facilities such as geometry, graphics,event-oriented input, and windowing; intermediatelevel facilities such as support for Common Lispstream operations, output recording, and advancedoutput formatting; and high level facilities such ascontext sensitive input, an adaptive toolkit, and anapplication building framework.

3Notice that this sentence was written in 1991; it is stilltrue 15 years later.

1

clim implementations will eventually support alarge number of window environments includingX Windows, Mac OS X and Microsoft Windows.clim is designed to exploit the functionality pro-vided by the host environment to the degree that itmakes sense. For example, clim top level windowsare typically mapped onto host windows, and inputand output operations are ultimately performed byhost window system code. clim supports the in-corporation of toolkits written in other languages.A uniform interface provided by clim allows Lispapplication programmers to deal only with Lisp ob-jects and functions regardless of the operating plat-form.

An important goal that has guided the design ofclim was to layer the specification into a numberof distinct facilities. Furthermore, the specificationdoes not distinguish the use of a facility by higherlevel clim facilities from its use by clim users. Forexample, the geometry substrate, which includestransformations and regions, is designed for effi-cient use by the graphics and windowing substratesas well as by clim programmers. This means that,in general, a clim programmer can reimplementhigher level clim facilities using the interfaces pro-vided by lower level facilities.

This modular, layered design has a number ofbenefits. The clim architecture balances the goalof ease of use on one hand, and the goal of versa-tility on the other. High level facilities allow pro-grammers to build portable user interfaces quickly,whereas lower level facilities provide a useful plat-form for building toolkits or frameworks that bettersupport the specific needs or requirements of a par-ticular application.

For example, clim’s application framework andadaptive toolkit allow programmers to develop ap-plications that automatically adopt the look andfeel of the host’s environment. We often call this“adaptiveness,” “look and feel independence,” oroccasionally more picturesquely, “chameleon lookand feel”. However, many users may need or wantto define a particular look and feel that is constantacross all host environments (we call this “portablelook and feel”). Such users can circumvent thelook and feel adaptiveness provided by clim, whilestill using most of the application framework facil-ity and other high level clim facilities like contextsensitive input. Furthermore, using the lower levelfacilities of clim, they can develop portable toolkit

libraries that define and implement their own par-ticular look and feel. For instance, the clim pro-grammer can implement new gadget types on topof the drawing primitives and treat them equally tothe built-in gadget types.

We will use the term CLIM implementor for theparty implementing low-level and high-level partsaccording to the clim specification, CLIM pro-grammer for the party that will use the facilitiesprovided by the implementor, and CLIM user forthe party that will use the programs provided bythe programmer.

The next section presents an overview of thefunctionality provided by clim facilities.

1 Overview of Functionality

Figure 1 shows the various aspects of a host envi-ronment in which clim lives as well as the variouselements provided by clim. Below we briefly de-scribe a number of clim’s areas of functionality.Later sections will illustrate many of these compo-nents.

Geometry clim provides points, rectangles, andtransformations; and functions for manipulatingthese object types.

Graphics substrate clim provides a portableinterface to a broad set of graphics functions fordrawing complex geometric shapes.

Windowing substrate clim provides aportable layer for implementing sheets (windowsand other window-like objects).

Extended Streams clim integrates the Com-mon Lisp Stream I/O functionality with the climgraphics, windowing, and panes facilities. In addi-tion to ordinary text, the programmer can send abutton, a picture or any other arbitrary widget to aclim output stream and clim will display the wid-get in the sheet associated with the output stream.

Output Recording clim provides outputrecording for capturing all output done to anextended stream and automatically repainting itwhen necessary.

2

Application

Common Lisp

Dialog Facilities PresentationsCommands

Output Recording

Host Look & Feel

Frames

Panes

Layout Panes

Sheet DefinitionGraphics

GeometryPorts

Application PanesGadget Panes

Incremental RedisplayFormated Output

Standard SheetsExtended Streams

Figure 1: An Overview of clim facilities

Formatted Output clim provides a set of high-level macros that enable programs to produceneatly formatted tabular and graphical displayseasily.4

Presentations clim provides the ability to asso-ciate semantics with output, such that Lisp objectsmay be retrieved later via user gestures (e.g. mouseclicks) on their displayed representation. This con-text sensitive input is modularly layered on top ofthe output recording facility and is integrated withthe Common Lisp type system. A mechanism fortype coercion is also included, providing the basisfor powerful user interfaces.

Panes clim provides panes that are analogous tothe gadgets or widgets of toolkits like the X toolkit,GTK or Mac OS X’s toolkit.

Supported pane types include layout panes forarranging other panes, gadget panes for present-ing users with feedback information or mechanismsfor invoking application behavior, and application

4This also includes Graph Formatting. Graph formattingis only partly implemented in McCLIM at this date (March2006).

panes for displaying and allowing users to interactwith application data.

Look and Feel Adaptiveness clim supportslook and feel independence by specifying a set ofabstract gadget pane protocols. These protocolsdefine a gadget in terms of its function and notin terms of the details of its appearance or oper-ation. Applications that use these gadget typesand related facilities will automatically adapt touse whatever toolkit is available on and appropri-ate for the host environment. In addition, portableLisp-based implementations of the abstract gadgetpane protocols are provided.5

Application Building clim provides a set oftools for defining application frames. These toolsallow the programmer to specify all aspects ofan application’s user interface, including pane lay-out, interaction style, look and feel, and commandmenus and/or menu bars.

5McCLIM does not support look and feel adaptivenessat the moment. Hence, McCLIM mostly uses this portableLisp-based implementation.

3

Commands clim supports the separation ofcommand execution and command invocation. Aclim user can invoke commands either via typingit into an interactor, clicking on a menu entry or im-plicitly invoking a presentation-translator by click-ing on a presentation. Commands can also be in-voked explicitly by the programmer.

Dialogs and Incremental Update/RedisplayIncremental Redisplay goes a bit further than Out-put Recording. With Incremental Redisplay, anoutput record can not only reproduce content thatwas written to a stream, the clim programmer canalso attach the code that generated the content tothe content itself. Whenever necessary, the appli-cation programmer can ask an output stream toupdate itself. clim will query all drawn elementsfor obsolescence, and if necessary, rerun the codeto produce fresh output.

This is a large number of facilities to explore. Themost systematic way – progressing from the lowest-level to the highest – would also be the lengthiest.Therefore, we start with showing several facilitiesin action with the most fundamental example inthe realm of programming: Hello World.

2 Our first application

We will start with a few lines of code for the trivialHello World example to give the reader a test caseto verify his clim setup. It also serves as a pointof reference from where the reader can start his ex-plorations of more challenging clim facilities. Wedo not try to elaborate the clim concepts in de-tail here, but simply use them with a brief discus-sion. The confused reader may hope for a more in-depth explanation in the following section. Pleaseregard pane, application frame, sheet, sheet hierar-chy, graft and top-level loop as terms we will dis-cuss later.

We provide extensive clim specification refer-ences in footnotes. The motivation for this is toshow that all the relevant information can be foundin the clim 2 specification[MY05]. Before a goodclim programmer can master any clim concept,he has to get used to the style of writing of thespecification, as this is the most relevant work forclim. The best we can do in this short paper is

provide pointers and references and hope that theinterested reader starts to explore the surroundingtext sections on his own.

After loading a clim implementation, the pack-age :clim-user is available to absorb user code. Thispackage is a good start for experimentation andfirst steps. When proper packaging is required, sim-ply include the packages :clim and :clim-lisp in yournew package’s :use list.

The central element of clim application pro-gramming is the application-frame. An applicationframe is defined via define-application-frame.6 Hereis the application frame definition for Hello World:

( d e f i n e−app l i c a t i o n− f r ame he l l o−wor l d ( )( ( g r e e t i n g : i n i t f o rm ”He l lo World”

: a c c e s s o r g r e e t i n g ) )( : pane (make−pane ’ he l lo−wor ld−pane ) ) )

define-application-frame’s basic syntax is similarto defclass because define-application-frame also gen-erates classes. In this case, it creates a frameclass hello-world that has no superclass except frame(which is added automatically).

With :pane, we define a top-level-pane that be-comes the content of a fresh window that belongsto an application frame. Although the usual caseis for an application frame to correspond to a toplevel window, sometimes an application frame isswallowed by another application and only space inanother existing window is reserved. For instance,a web site management tool might swallow a texteditor, so that the user has the option to edit websites without switching to another application.

The list given after the :pane option is a formwhich is evaluated when an instance of the hello-world class is created. We use make-pane to con-struct a pane as the top-level-pane for frame in-stances. make-pane is a constructor for panes.7 Wecan treat it as an analog to make-instance especiallymade for pane classes. Let us have a look at thedefinition of hello-world-pane.

( d e f c l a s s he l lo−wor ld−pane( cl im−stream−pane ) ( ) )

The one and only superclass of hello-world-pane isclim-stream-pane.8 As there are no additional slots,

6See Section 28.2 “Defining and Creating ApplicationFrames” in [MY05].

7See Section 29.2 “Basic Pane Construction” in [MY05].8See Section 29.4 “CLIM Stream Panes” in [MY05].

4

; ; ; Behavior de f ined by the Handle Repaint Pro toco l( defmethod hand l e− r epa i n t ( ( pane he l lo−wor ld−pane ) r e g i o n )

( l e t ( (w ( bound ing− rec tang le−width pane ) )( h ( bound ing− r e c tang l e−he igh t pane ) ) )

; ; Blank the pane out( d raw− r ec tang l e ∗ pane 0 0 w h

: f i l l e d t: i n k ( pane−background pane ) )

; ; Draw g r e e t i n g in cen te r o f pane( draw−text∗ pane

( g r e e t i n g ∗ app l i c a t i o n− f r ame ∗)( f l o o r w 2) ( f l o o r h 2): a l i gn−x : c e n t e r: a l i gn−y : c e n t e r ) ) )

Figure 2: handle-repaint for hello-world-pane

an experienced clos programmer might guess thatwe will use hello-world-pane solely for method spe-cialization. Before doing so, let us have a look whatwe have actually inherited from clim-stream-pane:9

CLIM−USER> ( d e s c r i b e ( f i n d− c l a s s’ cl im−stream−pane ) )

DIRECT−SUPERCLASSES :PERMANENT−MEDIUM−SHEET−OUTPUT−MIXINSTANDARD−REPAINTING−MIXINSTANDARD−EXTENDED−INPUT−STREAMSTANDARD−EXTENDED−OUTPUT−STREAMSTANDARD−OUTPUT−RECORDING−STREAMSHEET−MULTIPLE−CHILD−MIXINBASIC−PANE

basic-pane is the foundation of all pane classes. Itprovides reasonable defaults for all protocol meth-ods and inherits from the protocol class pane. Inturn, pane inherits from basic-sheet. Hence, allpanes we construct via basic-pane automatically ad-here to the sheet protocol.

Our hello-world-pane needs some methods to beuseful. With handle-repaint in Figure 2, we partic-ipate in the repaint protocol.10 This method hastwo tasks: paint the pane with the pane’s back-ground and draw the greeting of *application-frame*in the center of the pane. The hello-world frame in-stance is automatically available in the context ofhandle-repaint via the dynamically scoped variable*application-frame* and so it is possible to use theaccessor greeting to obtain the instance’s slot con-

9Internal classes removed from listing.10See Section 8.4 “Repaint Protocol” in [MY05]

tent.Two functions are needed to see this code in

action: make-application-frame and run-frame-top-level. The former is a constructor for instances offrame classes, the latter for running the top-levelloop of the application frame. The top-level loopis used for command reading, execution and dis-playing results. But all we need to know for themoment is that it makes the frame visible beforeentering the loop.

( run− f rame−top− l eve l( make−appl icat ion− f rame ’ he l l o−wor l d ) )

This completes the Hello World example. In thenext section, we catch up to the details we skippedin this example.

3 Basic Facilities

3.1 Geometry

To clim, geometry means regions. A region is ei-ther bound or unbound and has a dimensionalityof either zero, one or two. That corresponds toa point, a path or an area respectively. Regionscan be compared (region predicate protocol11) and

11clim relies heavily on clos. In clos, the term protocolmeans a set of generic functions that together form a coher-ent interface. A protocol specification not only includes thesyntactic details of the function names and the number offunction arguments, but also the functions’ purpose and thesemantics of the return values (and/or side effects) must begiven in a textual specification.

5

composed (region composition protocol).

Every bounded region has a bounding rectangle.It is the smallest rectangle that contains every pointin the region. The bounding rectangle of everybounded region can be accessed via the boundingrectangle protocol.

clim supports affine transformations of regions.Such transformations can move, stretch and rotatea region. A transformation is affine when everystraight line remains straight after transformation.Transformations can be composed arbitrarily. Theprogrammer can attach transformations to medi-ums and panes. In layout panes, clim uses trans-formations to map the coordinates of child panesto the coordinate system of their parents.

All drawing settings can be changed either per-manently, or temporarily in the context of the with-drawing-options macro.

3.2 The Windowing Substrate

clim does not directly talk to the window system.Instead, clim is layered on top of a windowingsubstrate.12 This substrate is a middleware be-tween clim on one side and the host window sys-tem on the other. This middleware layer providesa portable windowing model that insulates higherlevels of clim and clim programmers from the de-tails of the host window system. From the perspec-tive of a clim programmer, talking to the windowsystem is equal to talking to this abstraction layer.The implementation details are hidden in backends,like in McCLIM the CLX backend, which hidesX11 details. These backends will use the servicesof a host window system to provide efficient win-dowing, input and output facilities. Thanks to thismiddleware, clim is portable across different hostwindowing systems.

This framework allows uniform treatment of thefollowing GUI building blocks:

• Windows like those in X, Mac OS X and Mi-crosoft Windows.

• Gadgets typical of toolkit layers, such asGtk+, QT or Mac OS X’s toolkit. The back-end provides a frame manager which takes careof mapping the abstract gadget types found in

12formerly known as Silica.

clim to appropriate gadget with a native lookand feel.

• Structured graphics like output records and anapplication’s presentation objects

The central abstraction specified by clim is thesheet. A sheet is a surface that can be painted onand to which input gestures can be directed, andthat lives in a hierarchy of other such objects. Toget used to the notation of sheets, you can think ofthem as swallowable windows.

The fundamental notion in clim is the nestingof sheets within another sheet called a windowingrelationship. In a windowing relationship, a par-ent sheet provides space to or groups a number ofother children sheets. The sheet protocols specifyfunctionality for constructing, using, and managinghierarchies of sheets.

Sheets have the following properties:

parent/children: a sheet is part of a windowinghierarchy and maintains links to its parent andits children.

coordinate system: a sheet has its own coordi-nate system that might have a different scalingor orientation than its parent.

transformation: via a sheet transformation thesediffering sheet coordinate systems are mappedinto coordinate system of their parents.

clipping region: defines an area within a sheet’scoordinate system that indicates the area ofinterest.

Window hierarchies Sheets participate in anumber of protocols. The windowing protocolsdescribes the relationship between sheets. Everysheet has a parent, a sheet might have one or morechildren. A sheet can be adopted by a parent sheetand disowned later. A sheet is grafted when it isconnected to a graft either directly or through it’sancestors. A graft is a special kind of sheet thatstands in for a host window, typically a root win-dow (i.e. screen level). A sheet is attached to aparticular host window system by making it a childof an associated graft. A host window will be allo-cated for that sheet; the sheet will then appear tobe a child of the window associated with the graft.

6

Sheet hierarchies are displayed and manipulatedon particular host window systems by establishinga connection to that window system and attachingthem to an appropriate place in that window sys-tem’s window hierarchy. Ports and grafts providethe functionality for managing this process. A portis a connection to a display service that is respon-sible for managing host window system resourcesand for processing input events received from thehost window system.

Window input The input architecture of thewindowing substrate allows sheets to receive anywindow event from the host windowing sys-tem. The event class hierarchy descends fromthe class event to device-event (including all key-board and mouse actions), window-event (window-size-changed and window-repaint events), window-manager-events (window-deleted) to artificial timer-events. See 8.2 “Standard Device Events” in[MY05].

The function pair dispatch-event and handle-eventis the center of all event handling. dispatch-event is intended to be called when an event isto be dispatched to a client either immediatelyor queued for later processing in an event queue.On the other side, handle-event is intended forfurther specialization, so the application devel-oper can implement special policies for selectedevents. For instance, when a sheet notices througha window-configuration-event that the sheet’s sizehas changed, it might redo its layout for its chil-dren.

Window output All drawing operation happenon a medium. This object captures the state ofthe drawing like foreground, background, line style,and the transformation which is applied to the co-ordinates before drawing. Every medium is associ-ated with a sheet. In turn, a sheet must be asso-ciated with a medium whenever drawing operationshould be executed. Many clim sheets are asso-ciated with a medium permanently. sheet-mediumobtains the medium associated with a sheet.

The graphic output capabilities of sheets rangefrom simple line style and text style customizationover rendering various geometrical shapes, a colormodel capable of doing alpha blending, compos-able affine transformations to pattern, stencil and

tiling filling, and pixmaps usage. The features ofthe output protocol are specified briefly in Section8.3 “Output Protocol”and more precisely in Chap-ters 10-14 of [MY05].

clim lives in an idealized world in terms of graph-ics operations. A clim programmer can use an in-finitely long and wide drawing pane with arbitrarilyprecise resolution and continuously variable opac-ity. As rendering devices with these properties arerare, we need to render the idealized graphic de-scription to a device with finite size and a fixeddrawing precision. The rendering rules are spec-ified in Section 12.4 “Rendering Conventions forGeometric Shapes”of [MY05].

4 Building Applications

In this section, we explain a number of the neces-sary ingredients for building applications in clim.We will illustrate frames, panes, and simple com-mands with two examples: a color editor and asimple line and text drawing program.

4.1 Application Frames

Frames are the central abstraction defined by theclim interface for presenting an application’s userinterface. Many of the high level features and facil-ities for application building provided by clim canbe conveniently accessed through the frame facility.

Frames are typically displayed as top level win-dows on a desktop. Frame managers provide themachinery for realizing frames on particular hostwindow systems. A frame manager acts as an medi-ator between the frame and what is typically calleda desktop manager, or in X terminology, a windowmanager. The frame manager is responsible for at-taching the pane hierarchy of a frame to an appro-priate place in a sheet hierarchy (and therefore toa host window system window hierarchy) when theframe is adopted.

To build a user interface, an application pro-grammer defines one or more frame classes. Theseframe classes define a number of frame propertiesincluding application specific state and a hierarchyof panes (i.e. user interface gadgets and regions,for interacting with the users). Frame classes alsoprovide hooks for customizing application behaviorduring various portions of the frame protocol. For

7

example, an :after method on generic functions inthe frame protocol can allow applications to man-age application resources when the frame is madevisible on some display server.clim is able to show dialog windows, but the

code that brings them up is usually quite differentfrom the code that is used to generate the content ofapplication frames. This is unusual for a window-ing toolkit as most of them unify the generation ofdialog content and content of other window types.clim generates a dialog with the appropriate in-

put gadget as consequence of a series of input re-quests. Thanks to the stream facility, the program-mer can actually request input synchronously witha blocking read request. He does not have to takecare of asynchronously handling confirmation orcancel button clicks. For instance, the programmerrequests a string from the user and the user is pre-sented with a prompt, an editable text field, andtwo buttons for confirmation and canceling. Thestring requesting function returns only after theuser hits the confirmation button. The programmercan directly use the function’s return value which isthe string provided by the user. Clicking the cancelbutton is dealt with by signaling an abort-gesturecondition.

From the caller’s perspective, an attempt to sep-arate application frames and dialogs could be: a di-alog window itself is side-effect free with respect tothe application state and therefore the whole senseof calling a dialog creation routine must arise fromthe values it returns. For example, the code thatmodifies the state of the text editor in a text-replaceoperation does not rest with the callback code ofthe Ok button in the dialog. This task rests withthe code that is executed after the dialog returnsits values, namely the code of the Search/Replacecommand.

An intermediate dialog is something that isbrought up to collect additional information for (orbefore) an operation. When the user selects the“Search” command, he is queried for a search stringin an additional dialog window; probably offeringother search options like case-insensitive search orbackwards search. This is done in a synchronousmanner, blocking until the requested input is madeavailable by the user.

An application frame is an interface that providesthe user with a variety of commands to choose ashis next step. For instance, the user may choose

from commands like Open, Save, Search, or Quit.The frame is a long-living GUI object compared todialogs, and there is no linear execution path asthere is in after a dialog as the user is free to selectany commands he likes as his next action.

Hence, the synchronous programming pattern fordialogs is more convenient because after dialog con-firmations there is a predetermined path of execu-tion, while an application frame has to be preparedto handle an arbitrary sequence of commands.

4.2 Panes

An application frame constructs its pane tree byspecifying a top-level pane in define-application-frame. This pane is usually a layout pane thatcontains more gadget and/or layout panes as itschildren. With the help of layout panes, a panehierarchy can be constructed. The top-level pane(and the whole hierarchy when it is a layout pane)is created when the application frame is adoptedby a frame manager and made visible to the user.The programmer can compose an interface consist-ing of pre-defined gadget panes, layout panes, orapplication-specific panes. clim panes are rectan-gular sheets that are analogous to the gadgets orwidgets of other toolkits.

Panes and sheets as defined by the windowingsubstrate have in common that they are associatedwith a region on screen, a parent, and optionalchildren. They differ in their usage of the inputand output capabilities. A sheet is passive andintended to be used by other, active components,while a pane already contains this active part. Forthis reason, panes are implemented as subclassesof basic-sheet augmenting the class with an activepart. For instance, a button-pane actively drawsits own button representation on its allotted screenarea and a click on the correct button area triggersa callback for the button. A composite pane laysout its child elements and requests them to drawthemselves onto specific screen regions.

clim comes with a set of predefined gadgetpanes. They consist of push-button, toggle-button,slider, radio-box, text-field, text-editor panes readyfor use by the clim application programmer. Thesegadgets might be remapped to native system gad-gets by the frame manager, so a native look andfeel is possible.

Each gadget pane class is associated with a set of

8

generic functions that act as callbacks do in tradi-tional toolkits. For example, a pushbutton has an“activate” callback method which is invoked whenits button is pressed. For this particular callback,a method named activate-callback is invoked by de-fault, and a clim programmer can provide a spe-cialized method to implement application-specificbehavior for a subclassed button-pane. But ex-cept in the case where the programmer needs alot of buttons with related behavior, creating asubclass for changing a single specific callback isnot economical. Hence upon gadget creation, theprogrammer can specify an alternative callbackmethod for any callback available. For example,by providing the :activate-callback initarg, the pro-grammer can change the callback to any regular orgeneric function. By convention, any callback canbe changed by providing an initarg keyword equalto the callback’s name. See Chapter 30 in [MY05]for a listing and description of available callbacks.clim also provides composite and layout panes.

These pane types are used for aggregating severalchild panes into a bigger single pane that has a lay-out according to the requested directives. For ex-ample, clim provides two pane classes, hbox-paneand vbox-pane, that lay out their children in hor-izontal rows or vertical columns respectively. Theparent/child relations are managed via the sheet’swindowing protocol. If the user interface does notchange in ways unpredictable in advance (as in auser interface builder for instance), the programdoes not have to do hierarchy management via thewindowing protocol. He is provided with a set ofconvenience macros that allows elegant interfacescomposed simply by wrapping the respective paneconstruction code into the convenience macros.

Application pane classes can be used for sub-classing. They can be used to present applicationspecific data – for instance by specializing handle-repaint – and to manage user interactions – for in-stance by specializing handle-event.

4.3 Commands

Most applications have a set of operations that canbe invoked by the user. In clim, the command fa-cility is used to define these operations. Commandssupport the goal of separating an application’s userinterface from its underlying functionality. In par-ticular, commands separate the notion of an opera-

tion from the details of how the operation is invokedby the user.

Application programmers define a command foreach operation that they choose to export as an ex-plicit user entry point. A command is defined tohave a name and a set of zero or more operands, orarguments. These commands can then be invokedusing a variety of interaction techniques. For ex-ample, commands can be invoked from menus, key-board accelerators, direct typein, mouse clicks onapplication data, or gadgets.

The commands are processed in a REPL-likeloop. Every application frame has its own run-ning top-level loop specified via :top-level in define-application-frame. For a clim application, it israrely necessary to change the default top levelloop.

The top-level loop becomes visible when aninteractor-pane is added to the user interface. Herethe clim user gains direct access to the commandloop. The loop steps are similar to read-eval-print:

1. Read a command.

2. Execute the command.

3. Run the display function for each pane in theframe associated with the top-level loop as nec-essary.

Whenever a command is invoked other thanby typing, an appropriate command-invoking textappears after the command prompt nonetheless.Here, the user can directly see how his commandsare synthesized from other invocation methods likepointer clicks or menu item selections.

5 Simple applications

5.1 Color Editor

In this next example, we define a frame for color se-lection by manipulating their red, green, and bluecomponents separately. This example illustratesthe use of gadget panes provided by clim. In thecode in Figure 3, we define an application frameusing define-application-frame. As said before, thesyntax of this macro is similar to that of defclass.It defines a new frame class which automaticallyinherits from the class frame which provides mostof the functionality for handling frames.

9

One requirement must be fulfilled by all framedefinitions: code to generate a pane hierarchy mustbe supplied. The :pane option is the simplest wayto supply this code. The hello-world frame con-structs a hierarchy with only one application panevia make-pane. The pane hierarchy of color editoris more interesting.

Every pane can request space via its initarg. Arequest for space allocation is specified as a pre-ferred size (:height, :width), a maximum size (:max-height, :max-width), and a minimum size (:min-width, :max-width). The special constant +fill+ canbe used to indicate the tolerance for any width orheight.

The color editor frame uses three applicationslots for storing the current RGB values as wellas two panes for showing the currently selected col-ors. The variable *application-frame* is dynami-cally scoped and is defined in any event handler aswell as for all code that is evaluated in the contextof the :pane(s) frame option.

The code provided in the :pane option in Figure3 uses all three kinds of panes provided by clim.It uses two application-panes to display colors, twolayout panes (vbox-pane and hbox-pane) and threegadget panes (slider-pane).

In contrast to hello-world, we do not need a spe-cialized pane class here. We can use an application-pane for displaying chosen colors. An applica-tion pane supports graphics operations and invokesgeneric functions on the pane when input eventsare received. For the color editor, we only need itsability to refresh its background color.

The vertically and horizontally conveniencemacros provide an interface to the hbox-pane andvbox-pane classes. Most clim layout panes pro-vide similar convenience macros. The vertical boxpane arranges its children in a stack from top tobottom in the order they are listed at creation inthe vertically form. This pane type also supportsinter-element space and “pieces of glue” at arbi-trary points in the children sequence. In the coloreditor frame, the +fill+ “glue” is used to absorball extra space when too much vertical space is al-located to the vertical box. clim also provides ahorizontal box which does the same thing except inthe horizontal direction.

In the horizontally macro in Figure 3, we do notsupply forms to be evaluated directly. Instead, hor-izontally processes a form wrapped up in a list. The

first list element is a rational number which denotesthe amount of space the pane generated by the fol-lowing form is allowed to occupy in the resultinghorizontal layout. In our code in Figure 3, hbox-pane generated from the horizontally macro has aspace requirement on its own. The whole compos-ite pane is forced to have a size 200 pixels high.

Now we are ready to turn to the gadget panes.The color editor uses three sliders one for each com-ponent of RGB. make-color-slider creates all threesliders that differ by id, initval and label. The firsttwo variables are handed to make-pane to constructthe slider panes. The remaining initargs for make-pane are shared across all three entities. To deco-rate each slider-pane with a proper label, each ofthem is wrapped up in a label-pane via the labellingconvenience macro.

The slider gadget protocol defines two callbackfunctions: drag-callback is repeatedly invoked whilethe slider is being dragged by the user, and value-change-callback is invoked when the slider is re-leased in a new location. Notice that this speci-fication is sufficiently abstract to allow a variety ofdifferent look and feels for a slider. For example,no guarantee is made as to whether the mouse but-ton is held down during dragging, or whether themouse button is pressed once to start and again tostop dragging.

We use the gadget ID to distinguish between thered, green and blue slider in the callback code. Wecould use three different callback functions here,but such callbacks would have much more similar-ities than differences, thus we do not do that here.Instead, we distinguish the gadget by their id.

The drag-callback method resets the backgroundof drag-feedback-pane and delegates its redrawingto redisplay-frame-pane, while value-change-callbackdoes the same for the frame’s current color pane.These methods use the id argument of the gadgetto determine which color component was changed.

The color editor frame uses the :menu-bar op-tion to indicate that a menu-bar should be addedto the application frame. Frame commands de-fined with :menu t are accessible from the menu-bar. In this example, we define only one commandnamed com-quit which is presented as “Quit” tothe user. com-quit is defined via define-color-editor-command. This macro is generated automaticallyalong define-application-frame from the applicationframe’s name. com-quit simply closes the applica-

10

( l a b e l l i n g ( : l a b e l l a b e l )(make−pane : s l i d e r : i d i d : o r i e n t a t i o n : h o r i z o n t a l : v a l u e i n i t v a l

: max−value 1 : min−value 0: show−value−p t : dec ima l−p l ace s 2: d r ag−ca l l back #’ co l o r− s l i d e r−d r agg ed: va lue−changed−ca l lback #’ co l o r− s l i d e r−va lue−changed ) ) )

( d e f i n e−app l i c a t i o n− f r ame c o l o r− e d i t o r ( )( cur rent−co lo r−panedrag− feedback−pane( red : i n i t f o rm 0 . 0 )( g reen : i n i t f o rm 1 . 0 )( b l u e : i n i t f o rm 0 . 0 ) )

( : pane ( w i t h− s l o t s ( drag− feedback−pane cur rent−co lo r−pane red g reen b l u e )∗ app l i c a t i o n− f r ame ∗

( v e r t i c a l l y ( )( s e t f cu r rent−co lo r−pane

(make−pane ’ app l i c a t i on−pane: min−height 100 : max−height 100: background ( make−rgb−color r ed g reen b l u e ) ) )

( h o r i z o n t a l l y ( : min−height 100 : max−height 100)(1/2 ( make−co lo r− s l i de r ’ r ed red ”Red” ) )(1/4 ( make−co lo r− s l i de r ’ g r een g reen ”Green” ) )(1/4 ( make−co lo r− s l i de r ’ b l u e b l u e ”Blue” ) ) )

( s e t f drag− feedback−pane(make−pane ’ app l i c a t i on−pane

: min−height 100 : max−height 100: background ( make−rgb−color r ed g reen b l u e ) ) ) ) ) )

( : menu−bar t ) )

( de fun co l o r− s l i d e r−d r agg ed ( s l i d e r v a l u e )( w i t h− s l o t s ( drag− feedback−pane red g reen b l u e ) ∗ app l i c a t i o n− f r ame ∗

( l e t ( ( c o l o r ( e ca s e ( gadget− id s l i d e r )( r ed ( make−rgb−color v a l u e g reen b l u e ) )( g reen ( make−rgb−color r ed v a l u e b l u e ) )( b l u e ( make−rgb−color r ed g reen v a l u e ) ) ) ) )

( s e t f ( pane−background drag− feedback−pane ) c o l o r( medium−background drag− feedback−pane ) c o l o r ) )

( red i sp lay− f rame−pane ∗ app l i c a t i o n− f r ame ∗ drag− feedback−pane ) ) )

( de fun co l o r− s l i d e r−va lue−changed ( s l i d e r new−value )( w i t h− s l o t s ( cur rent−co lo r−pane red g reen b l u e ) ∗ app l i c a t i o n− f r ame ∗

; ; The gadget− id symbols match the s l o t names in co lo r−ed i t o r( s e t f ( s l o t− v a l u e ∗ app l i c a t i o n− f r ame ∗ ( gadget− id s l i d e r ) ) new−value )( l e t ( ( c o l o r ( make−rgb−color r ed g reen b l u e ) ) )

( s e t f ( pane−background cur rent−co lo r−pane ) c o l o r(medium−background cur rent−co lo r−pane ) c o l o r ) )

( red i sp lay− f rame−pane ∗ app l i c a t i o n− f r ame ∗ cur rent−co lo r−pane ) ) )

( def ine−color−editor−command ( com−quit : name ”Quit” : menu t ) ( )( f rame−ex i t ∗ app l i c a t i o n− f r ame ∗ ) )

Figure 3: Color Editor

11

tion frame causing the termination of the frame’stop-level-loop. In the next example, commands willbe explored in greater detail.

We can invoke the color-editor with the regu-lar run-frame-top-level/make-application-frame com-bination.

( run− f rame−top− l eve l( make−appl icat ion− f rame ’ c o l o r− e d i t o r ) )

5.2 A simple drawing application

We move on to a simple application that draws linesand inserts text interactively. Our simple drawingprogram defines commands for various drawing op-erations and binds specific input events to thesecommands.

The application frame is defined in Figure 4. Adifferent approach is used to generate the pane hier-archy: instead of mixing the layout and pane infor-mation, we use the :panes keyword to list all panesthat should be available in frame layouts. The :lay-outs keyword combines them into several layouts. Itis possible to define multiple layouts with this op-tion. We define two simple layouts, default-layoutand alternative.

There are two options to define-application-framethat we have not seen before, :command-definer and:top-level (both with there defaults). :command-definer is used to specify a name for a command-defining macro for this frame class. Passing tto this option (its default) generates a commanddefiner named define-<frame-name>-command. Wecan use the command-defining macro as a conve-nience macro for define-command which is used todefine frame commands, and will see it in actionbefore long. :top-level specifies a special form thatis used as top level command loop. The top level isresponsible for dequeuing and executing commandsthat have been invoked by the user. This loop is toa application frame what the REPL is to a termi-nal.

This is the first example that does not useclim-stream-pane (or one of its subclasses) asa pane class.13 Instead, we compose ourown drawing pane using standard-extended-input-stream, basic-pane and permanent-medium-sheet-

13When using McCLIM, we have to do this as there arebugs in the behavior of clim-stream-pane that have not beenfixed yet.

output-mixin. The first class is used to provide theapplication programmer with stream properties forthe draw-pane that are required for the conveniencemacro tracking-pointer. basic-pane is responsible forhandling all requests belonging to the sheet andpane protocols in a standard manner. The last classis a mixin to tag the pane as permanently visibleon screen during its instances’ lifetime. Most staticuser interfaces use this mixin. Note that McCLIMis sensitive to the order of the superclasses.14

For draw-pane, the handle-repaint method shownin Figure 4 is straightforward. It delegates back-ground filling to the next less specific method andthen iterates through the lines and strings paint-ing them. Here, we implicitly defined the format ofthe lines slot and the strings slot of the applicationframe class. The elements of the list stored in linesare pairs of points, namely the start and end pointfor a line. In strings, we store the text’s position asthe car of a cons and the text as its cdr.

Figure 5 shows the command definitions. Wehave commands for adding a text string, for addinga line and resetting the draw pane. After everycommand, we update the drawing pane via the aux-iliary method update-draw-pane.15

At this point, we can actually use the applica-tion; although not very conveniently. The interac-tor pane can be used to invoke one of three com-mands, either by typing the complete command in-cluding all its parameters or by typing only thecommand name, then a dialog queries the user forthe missing command argument(s). Clicking on themenu bar entries is another way to invoke com-mands. When commands are invoked through themenu bar, the user will be queried for the missingargument(s) in the same way as if a command hadbeen typed into the interactor pane.

But drawing by typing coordinates is not con-venient. Therefore, we attach these commandsto other user interactions. Figure 6 defines in-put methods (methods for handle-event) for pointerbutton presses as well as key presses on the drawpane. Each handler invokes a tracking function

14All stream classes like standard-extended-input-streammust be listed before basic-pane. Otherwise, no stream han-dling facilities will be available.

15An experienced clim programmer would define adisplay-function for draw-pane. This function is run aftera command is executed, and causes the display pane to beupdated with any changes. We will save this technique forlater examples.

12

( d e f i n e−app l i c a t i o n− f r ame draw−frame ( )( ( l i n e s : a c c e s s o r l i n e s : i n i t f o rm n i l ) ; l i n e s o f drawing( s t r i n g s : a c c e s s o r s t r i n g s : i n i t f o rm n i l ) ) ; t e x t s o f drawing

( : panes ( draw−pane (make−pane ’ draw−pane ) )( i n t e r a c t o r : i n t e r a c t o r ) )

( : l a y o u t s ( d e f a u l t− d e f a u l t ( v e r t i c a l l y ( )( : f i l l draw−pane )(1/4 i n t e r a c t o r ) ) ) )

( : menu−bar t )( : command−definer t )( : t o p− l e v e l ( de fau l t− f r ame− top− l e ve l ) ) )

( d e f c l a s s draw−pane( standard−extended− input−st ream ; must have precedence over basic−panebas ic−panec l ime : a lways− repa int−background−mix inpermanent−medium−sheet−output−mixin )

( ) )

( defmethod hand l e− r epa i n t ( ( pane draw−pane ) r e g i o n )( w i th−app l i c a t i on− f r ame ( frame )

( cal l−next−method ) ; Paints the background( d o l i s t ( l i n e ( l i n e s f rame ) )

( draw− l i ne pane ( ca r l i n e ) ( cd r l i n e ) ) )( d o l i s t ( p a i r ( s t r i n g s f rame ) )

( draw−text pane ( cd r p a i r ) ( ca r p a i r ) ) ) ) )

Figure 4: define-application-frame for draw-frame

(track-line-drawing and track-text-drawing) that usestracking-pointer to bypass the regular input distri-bution channels and to dispatch events to user de-fined handlers.

For pointer-button-press-event, which is used todraw lines, the input loop manages a “rubber-banding” line. The :pointer-motion is invokedwhenever the mouse pointer is moved by the user.The code attached to :pointer-motion clears thepreviously-drawn line and draws a new line withthe new pointer position. It can easily undraw theold line by the using the special ink +flipping-ink+.When the user confirms the line by releasing thepointer button, a command to the application issynthesized via execute-frame-command supplyingall required parameters.

We provide a similar input facility for text input.Whenever the user hits a key in the draw-pane,the respective handle-event calls track-text-drawingwhich attaches the character entered to the mousepointer. As with the rubber-banding line, the user

can move the displayed string around while he isfree to append additional string characters by ad-ditional key presses. He can confirm the text posi-tion with a mouse click causing a command to bedispatched to the application frame that will addthe text to the application frame permanently.

As each of these methods invoke execute-frame-command passing in a special command invocationform, this naturally leads to a separation betweenthe code that specifies how a command is invoked(menu-bar click, click on draw-pane or typing inthe interactor pane) and the code for command ex-ecution (code bodies of define-command).

6 High Level Facilities

In this section, we explain a number of higherlevel facilities provided by clim, including outputrecording, formatted output, presentations, context

13

( define−draw−frame−command ( com−draw−add−string : menu t : name ”Add St r ing ” )( ( s t r i n g ’ s t r i n g ) ( x ’ i n t e g e r ) ( y ’ i n t e g e r ) )

( push ( cons ( make−point x y ) s t r i n g )( s t r i n g s ∗ app l i c a t i o n− f r ame ∗ ) )

( update−draw−pane ) )

( define−draw−frame−command ( com−draw−add−line : menu t : name ”Add Line ” )( ( x1 ’ i n t e g e r ) ( y1 ’ i n t e g e r ) ( x2 ’ i n t e g e r ) ( y2 ’ i n t e g e r ) )

( w i t h− s l o t s ( l i n e s ) ∗ app l i c a t i o n− f r ame ∗( push ( cons ( make−point x1 y1 ) ( make−point x2 y2 ) )

l i n e s ) )( update−draw−pane ) )

( define−draw−frame−command ( com−draw−clear : menu t : name ”Clear ” ) ( )( w i t h− s l o t s ( l i n e s s t r i n g s ) ∗ app l i c a t i o n− f r ame ∗

( s e t f l i n e s n i l s t r i n g s n i l ) )( update−draw−pane ) )

; ; Aux i lary Method( de fun update−draw−pane ( )

( r e pa i n t− s h e e t ( find−pane−named ∗ app l i c a t i o n− f r ame ∗ ’ draw−pane ) +eve rywhe re +))

Figure 5: Commands for draw-frame

sensitive input, and command processors.16 We il-lustrate these facilities in two examples: a directorylister and a simple schedule browser.

Output Recording Many of the higher level fa-cilities in clim are based on the concept of out-put recording. The clim output recording facilityis simply a mechanism wherein a window remem-bers all of the output that has been performed onit. This output history (stored basically as a dis-play list) can be used by clim for several purposes.For example, the output history can be used toautomatically support window contents refreshing(or “damage repaint” events). The application pro-grammer has considerable control over the outputhistory. Output recording can be enabled or sus-pended, and the history itself can be cleared or re-arranged.

Output records can be nested, thereby formingtheir own hierarchy. The leaves of this tree are

16Many of these facilities are derived from work doneat Symbolics on the Dynamic Windows (DW) project forGenera[Sym]. See [MYM89] for more detailed informationon the motivations and design details behind DW. Manyof the original contributers to DW have participated in theredesign of these facilities for clim.

typically records that represent a piece of output,say the result of a call to draw-rectangle or write-string. The intermediate nodes typically provideadditional semantics to the tree, such as markinga subtree of nodes as resultant output of one par-ticular phase of an application, for instance rowand column formatting information. Chapter 16 in[MY05] has all the details.

Output Formatting clim provides a conve-nient table and graph formatting facility, which isbuilt on top of the output recording facility. Thekey to these formatting tools (as opposed to, say,format’s T directive) is that they dynamically com-pute the formatting parameters based on the actualsize of the application-generated output.

The application programmer uses these tools bywrapping any piece of output-producing code withadvisory macros that help the system determine thestructure of the output.

For example, start with a simple output functionthat shows some information about the packages inthe Lisp environment:

( de fun show−package− info ( s t ream )( d o l i s t ( package ( l i s t− a l l−p a c k a g e s ) )

( w r i t e− s t r i n g ( package−name package )

14

( defmethod hand le−event ( ( pane draw−pane ) ( even t po in te r−but ton−pres s−event ) ); ; S t a r t l i n e t r a c k i n g when l e f t po in t e r bu t ton i s pres sed(when ( e q l ( po in te r−event−but ton even t ) +po i n t e r− l e f t−bu t t on+)

( t rack− l i n e−draw ing pane( po inte r−event−x even t )( po inte r−event−y even t ) ) ) )

( defmethod hand le−event ( ( pane draw−pane ) ( even t key−press−event ) )(when ( keyboard−event−characte r even t )

( mu l t i p l e−va lue−b ind ( x y ) ( s t r e am−po i n t e r−po s i t i on pane ); ; S t a r t wi th empty s t r i n g , as a key r e l e a s e event w i l l be r e c e i v ed anyway( t rack− text−drawing pane ”” x y ) ) )

( update−draw−pane ) )

( de fun t rack− l i n e−draw ing ( pane s t a r t x s t a r t y )( l e t ( ( l a s t x s t a r t x )

( l a s t y s t a r t y )endx endy )

( b l o ck n i l( wi th−drawing−opt ions ( pane : i n k +f l i p p i n g− i n k+)

( draw− l i ne ∗ pane s t a r t x s t a r t y l a s t x l a s t y )( t r a c k i n g−po i n t e r ( pane )

( : po inte r−mot ion (&key x y )( draw− l i ne ∗ pane s t a r t x s t a r t y l a s t x l a s t y ) ; d e l e t e o l d( draw− l i ne ∗ pane s t a r t x s t a r t y x y ) ; draw new( s e t f l a s t x x l a s t y y ) )

( : po i n t e r−bu t t on− r e l e a s e (&key even t x y )(when ( e q l ( po in te r−event−but ton even t ) +po i n t e r− l e f t−bu t t on+)

( draw− l i ne ∗ pane s t a r t x s t a r t y l a s t x l a s t y ) ; d e l e t e o l d( s e t f endx x endy y )( r e t u r n ) ) ) ) ) )

( execute−frame−command∗ app l i c a t i o n− f r ame ∗ ‘ ( com−draw−add−line , s t a r t x , s t a r t y , endx , endy ) ) ) )

( de fun t rack− text−drawing ( pane c u r r e n t− s t r i n g cur rent−x cur rent−y )( t r a c k i n g−po i n t e r ( pane )

( : po inte r−mot ion (&key x y ); ; We can ’ t use f l i p p i n g ink f o r t e x t , hence redraw .( hand l e− r epa i n t pane +eve rywhe r e+)( s e t q cur rent−x x cur rent−y y )( draw−text∗ pane c u r r e n t− s t r i n g x y ) )

( : keyboard (&key g e s t u r e )(when ( and ( typep g e s t u r e ’ key− r e l ea se−event )

( keyboard−event−characte r g e s t u r e ) )( s e t f c u r r e n t− s t r i n g

( conca t ena t e ’ s t r i n gc u r r e n t− s t r i n g( s t r i n g ( keyboard−event−characte r g e s t u r e ) ) ) )

( hand l e− r epa i n t pane +eve rywhe r e+)( draw−text∗ pane c u r r e n t− s t r i n g cur rent−x cur rent−y ) ) )

( : po i n t e r−bu t t on− r e l e a s e (&key even t x y )(when ( e q l ( po in te r−event−but ton even t ) +po i n t e r− l e f t−bu t t on+)

( execute−frame−command ∗ app l i c a t i o n− f r ame ∗‘ ( com−draw−add−string , c u r r e n t− s t r i n g , x , y ) )

( return− f rom track− text−drawing n i l ) ) ) ) )

Figure 6: User Interfaces15

s t ream )( w r i t e− s t r i n g ” ” s t ream )( format st ream ”˜D”

( count−package−symbolspackage ) )

( t e r p r i s t ream ) ) )

Any attempt to fix this function to produce tab-ular output by building in a certain fixed spacingbetween the package name and symbol count willeither get caught by an unexpectedly long packagename, or will have to reserve way too much spacefor the typical case. In clim, we can use the codein Figure 7 to produce a neatly formatted table forany set of package names.

Presentations The next step up from preserv-ing the mere physical appearance of output done toa window is to preserve its semantics. For exam-ple, when an application displays a Lisp pathnameon the screen via (format t ”˜A” path), the string“/clim/demo/cad-demo.lisp” may appear. To theuser this string has obvious semantic meaning; itis a pathname. However, to Lisp and the underly-ing system it is just a text string. Fortunately, inmany cases the semantics can be recovered fromthe string. Thus the power of the various tex-tual cut-and-paste mechanisms supported by con-temporary computer systems. However, it is possi-ble to improve upon the utility of this lowest com-mon denominator facility (i.e. squeezing everythingthrough its printed representation) by rememberingthe semantics of the output as well as its appear-ance. This is the idea behind presentations.

A presentation is a special kind of output recordthat maintains the link between screen output andthe Lisp data structure that it represents. A pre-sentation remembers three things: the displayedoutput by capturing a subtree of output records,the Lisp object associated with the output, andthe presentation type of the output. By maintain-ing this back pointer to the underlying Lisp datastructure, the presentation facility allows output tobe reused at a higher semantic level.

An application can produce semantically taggedoutput by calling the clim function present. Forexample, to display the pathname referred to aboveas a presentation, the application would execute:

( p r e s e n t path ’ pathname )

present captures the resulting output and the path-name object in a presentation of type ’pathname.

Presentation Types clim defines a set of pre-sentation types, which are arranged in a super-type/subtype lattice like the CL types. In fact, thepresentation type hierarchy is an extension of theCL type hierarchy. The reason that this extendedtype system is needed is that the CL type systemis insufficient from the UI perspective. For exam-ple, the integer 72 might represent a heart rate inone application and a Fahrenheit temperature inanother, but it will always be just an integer toLisp.

The application programmer can define the UIentities of the application by defining presentationtypes, thus extending the presentation type library.By defining a presentation type, the programmercan centralize all of the UI aspects of the new typein one place, including output appearance and in-put syntax. As an example, clim defines a path-name presentation type that defines how a path-name is displayed and how one is input. The path-name input side provides pathname completion anddisplay of possibilities. By defining this behavior inone place and using it in all applications that needto display or read pathnames, clim helps build con-sistent user interfaces.

Note that in the pathname output example givenabove present invokes the standard pathname dis-player defined by the presentation type. However,since the presentation facility is simply based onthe output recording facility, presentation seman-tics can be given to any output. The following ex-ample shows how the pathname object could beassociated with some graphics that were displayedon the screen.

( w i th−output−as−presentat ion( : o b j e c t path: type ’ pathname: s t ream s )

( d raw− r ec tang l e ∗ s 0 0 30 30))

Context-Dependent Input Once outputis semantically-tagged, it can be reused assemantically-meaningful input. To achieve this,the application does not only have to tag its out-put but it also has to provide additional semanticinformation when doing input operations. For

16

( de fun show−packages ( st ream )( f o rma t t i n g− t ab l e ( s t ream )

( d o l i s t ( package ( l i s t− a l l−p a c k a g e s ) )( formatt ing− row ( st ream )

; ; The f i r s t column conta ins the package name( f o rma t t i n g− c e l l ( s t ream )

( w r i t e− s t r i n g ( package−name package ) st ream ) )

; ; The second co l o r conta ins the symbol count , a l i gn ed wi th the r i g h t; ; edge o f the column( f o rma t t i n g− c e l l ( s t ream : a l i gn−x ’ : r i g h t )

( fo rmat st ream ”˜D” ( count−package−symbols−package ) ) ) ) ) ) )

Figure 7: An output function that uses table formatting.

instance, whenever a pathname is required, theprogram has to use a special method in contrastto reading a string of characters.

The counterpart to present is accept. It is usedto establish an input context. The input context isa presentation type that is appropriate for the cur-rent input point. For example, if the applicationrequires the user to input a pathname, it can trig-ger an appropriate prompt, input parser and inputcontext with:

( accep t ’ pathname : s t ream s )

Typically, this invokes the input reader (or parser)that was defined for the pathname type and es-tablishes an input context that indicates that it iswaiting for a pathname.

Once the input context is established, clim au-tomatically makes any appropriate existing outputavailable to the user via mouse gestures. After call-ing accept as shown above, the user can move themouse over any presentation that is of type path-name (or is a subtype of pathname), click on it, andthe pathname object underlying the presentation isreturned as the value of the call to accept.

Command Processors clim promotes the sep-aration of command execution code and commandinvocation code. The command facility aids thistask. Every application frame can define applica-tion commands that are accessible via various in-put methods. The most common are clicking onthe command’s entry in the menu bar or a con-text menu, typing the command in the interactorpane, or the application dispatches a command to

itself (maybe triggered by other ways of user inputor network interactions, etc.). The latter case isseen in track-line-drawing and track-text-drawing ofthe draw-frame example. These methods generate“Add Line” and “Add String” commands as theresult of event-handling on the draw-pane.

A command has a name specified as string anda set arguments specified as presentation types.Looking back at the command “Add String” ofdraw-frame, we see that this command takes astring and two integer as arguments. This typeinformation is useful for partial command parsing.Assume the user clicks on a menu entry or typesonly the command name in the interactor. clim no-tices that there are arguments missing in the com-mand and requests the missing ones in a dialog viacalls to accept. Mentioned early, accept establishesan input context and so the user is able to fill themissing argument with clicks on appropriate visi-ble output objects. Also keyboard users will findsemantically-tagged input methods convenient asimplementations of presentation types can providethe user with a completion facility.

In addition, the command processor is extensi-ble by application programmers. For example, thecommand processor can be extended to support a“noun then verb” interaction style, where the usercan first click on a displayed presentation and theninvoke a command that is defined to take an argu-ment of the selected presentation type.

17

( d e f i n e−app l i c a t i o n− f r ame f i l e−b r ow s e r ( )( ( a c t i v e− f i l e s : i n i t f o rm n i l : a c c e s s o r a c t i v e− f i l e s ) )( : panes( f i l e−b r ow s e r : a p p l i c a t i o n

: d i s p l a y− f u n c t i o n ’ ( d i r l i s t− d i s p l a y− f i l e s ); ; Ca l l the d i sp l ay− f unc t i on whenever the command; ; loop makes a ‘ ‘ f u l l− c y c l e ’ ’: d i s p l a y− t ime : command−loop )

( i n t e r a c t o r : i n t e r a c t o r ) )( : l a y o u t s ( d e f a u l t ( v e r t i c a l l y ( )

( : f i l l f i l e−b r ow s e r )(1/4 i n t e r a c t o r ) ) ) )

( : menu−bar n i l ) )

( d e f i n e−p r e s en t a t i o n− t yp e dir−pathname ( ): i n h e r i t− f r om ’ pathname )

( defmethod d i r l i s t− d i s p l a y− f i l e s ( ( f rame f i l e−b r ow s e r ) pane ); ; Clear o ld d i s p l a y ed e n t r i e s( c l ea r−output− r e co rd ( s t r eam−output−h i s to ry pane ) )

( d o l i s t ( f i l e ( a c t i v e− f i l e s f rame ) ); ; Ins t ead o f wr i t e− s t r ing , we use pre sen t so t ha t the l i n k to; ; o b j e c t f i l e and the semantic in format ion t ha t f i l e i s; ; pathname i s r e t a ined .( p r e s e n t f i l e

( i f ( c l− f ad : d i rectory−pathname−p f i l e ) ’ dir−pathname ’ pathname ): s t ream pane )

( t e r p r i pane ) ) )

( def ine− f i le−browser−command ( com−ed i t−d i r ec to ry : name ”Edit Di rec to ry ” )( ( d i r ’ dir−pathname ) ); ; t he f o l l ow i n g was a prev ious at tempt to dea l wi th the o d d i t i e s o f; ; CL pathnames . Unfor tunate ly , i t does not work prope r l y wi th a l l; ; l i s p implementat ions . Because o f t h e s e odd i t i e s , we r e a l l y need; ; a l a y e r l i k e c l− fad to keep t h i n g s s t r a i g h t . [2007/01/05: rpg ]

; ; ; ( l e t ( ( d i r (make−pathname : d i r e c t o r y ( pathname−directory d i r ); ; ; : name : w i l d : type : w i l d : v e r s i on : w i l d; ; ; : d e f a u l t s d i r ) ) )

( s e t f ( a c t i v e− f i l e s ∗ app l i c a t i o n− f r ame ∗)( c l− f ad : l i s t− d i r e c t o r y d i r ) ) )

( de f ine−presentat ion− to−command− t rans la to r pathname−to−edit−command( dir−pathname ; source presen ta t ion− t ypecom−ed i t−d i r ec to ry ; target−commandf i l e−b r ow s e r ; command−table: g e s t u r e : s e l e c t ; use t h i s t r a n s l a t o r f o r po in t e r c l i c k s: documentat ion ”Edit t h i s path” ) ; used in con t ex t menu

( o b j e c t ) ; argument L i s t( l i s t o b j e c t ) ) ; arguments f o r target−command

( def ine− f i le−browser−command ( com−quit : name t ) ( )( f rame−ex i t ∗ app l i c a t i o n− f r ame ∗ ) )

( defmethod adopt−frame : a f t e r ( frame−manager ( f rame f i l e−b r ow s e r ) )( d e c l a r e ( i g n o r e frame−manager ) )( execute−frame−command frame

‘ ( com−ed i t−d i r ec to ry , ( make−pathname : d i r e c t o r y ’ ( : a b s o l u t e ) ) ) ) )

Figure 8: File Browser

18

6.1 A Directory Browser

The dirlist-frame application is a very simple filesystem browser using presentation types. It definestwo panes, an output pane to display directory con-tents and an input pane to handle user typein. Forthe output pane, the application defines a displayfunction. dirlist-display-files works in conjunctionwith the top level command loop. By default, thecommand loop calls all display functions after acommand was processed to make all changes in theapplication’s data structures visible that the com-mand execution might have caused. When all dis-play functions have updated their panes, the com-mand loop displays a prompt in the interactor17

and waits for the next command.The dirlist-display-files display function iterates

over the contents of the current directory displayingthe files one by one. Each output line is producedby a call to present. present creates the associationbetween the text lines on the screen and the Lisppathname objects.

draw-frame has a single command “Edit direc-tory”. The command’s body interprets the path-name that it receives as a directory, obtaining alist of the files contained therein. The commandsimply updates the application variable active-fileswith the new list.

The clim presentation substrate supports a gen-eral concept of presentation type translation. Thistranslation mechanism can be used to map objectsof one type into a different presentation type, ifappropriate. For example, it might be possibleto satisfy an input request for a pathname by se-lecting a computer user’s login ID and returningthe pathname of the user’s home directory. Thiswould be accomplished by defining a translatorfrom a user-id presentation type to the pathnametype. The translator would consult the system’suser database to retrieve the home directory infor-mation to achieve its conversion task.

The command loop of an application frame isregularly requesting commands for processing andit uses accept for its request. Hence, an inputcontext for reading an object with the presenta-tion type command is established and all objectsthat can be used as commands will become click-able on screen. Here, we can define a presentation-to-command translator that translates a pathname

17Omitted when there is no interactor pane.

into the edit directory command.The presentation-to-command translator in Fig-

ure 8 is very simple. It has the name pathname-to-edit-command and converts the presentation typepathname to the command com-edit-directory forthe command table of file-browser. The gesture op-tion specifies that it works with the select gesture,while the string supplied to :documentation is usedin the context menu.

This command translator has little work to do.The body of the translator has to return a list ofarguments that are handed to the command com-edit-directory. But we do not need to any conversionof the supplied object, as it is already a pathname.Thus, the object is wrapped in a list and returnedto the caller which will apply com-edit-directory tothe list.

A simple trick is used to dispatch an initial com-mand to the application frame. An after-method isprovided for adopt-frame which runs after the framemanager has adopted the frame for displaying. Thisis different for an after-method on initialize-instanceas an after-method on adopt-frame runs later, whenthe application frame instance has already a com-mand queue associated with it.

Since this application was defined with an in-teractor pane for user input, the user can invokethe sole command by typing its name, “Edit Direc-tory.” Here, clim supports for automatic commandcompletion becomes visible. Only the first letterhas to be typed followed by the complete action(usually Tab) and the command completion facil-ity will complete the input to “Edit Directory”. Atthis point, the clim command loop will begin read-ing the arguments for that command, and will au-tomatically enter a pathname input context. Thus,the user can fill in the required argument either bytyping a pathname, or by clicking on one of thepathnames visible in the display pane.

6.2 Schedule Example

In this example, we build a simple appointmentbrowser. Since the user of this application will fre-quently be dealing with the days of the week, westart by defining a new presentation type weekday.This simple presentation type, shown in Figure 9,represents a day of the week as a number from 0 to6. Each day number is associated with an abbrevi-ated day name, “Mon,” “Tue,” etc.

19

( d e f v a r ∗ days ∗ #(”Sun” ”Mon” ”Tue” ”Wed” ”Thu” ”Fr i ” ”Sat” ) )

; ; A l i s t o f day number and appointment s t r i n g s( d e f v a r ∗ t e s t−data ∗

’ ( ( 0 ) (1 ”Dent i s t ” ) (2 ” S t a f f meeting” ) (3 ”Performance Evaluat ion ” ”Bowling” )(4 ” Inte rv i ew at ACME” ”The Simpsons” ) (5 ”TGIF” ) (6 ” S a i l i n g ” ) ) )

( d e f i n e−p r e s en t a t i o n− t yp e weekday ( ) )

( de f ine−pre senta t i on−method accep t( ( type weekday ) st ream ( v iew tex tua l−v i ew ) &key )

( v a l u e s ( comple t ing− f rom− sugges t i ons ( s t ream )( dot imes ( i 7)

( s ugge s t ( a r e f ∗ days ∗ i ) i ) ) ) ) )

( de f ine−pre senta t i on−method p r e s e n t( daynumber ( type weekday ) st ream ( v iew tex tua l−v i ew ) &key )

( w r i t e− s t r i n g ( a r e f ∗ days ∗ daynumber ) s t ream ) )

( d e f i n e−app l i c a t i o n− f r ame s c h e d u l e r ( )( ( appo in tments : i n i t a r g : appo in tments : i n i t f o rm ∗ t e s t−data ∗)( cur rent−day : i n i t f o rm n i l ) )

( : panes ( s c h e d u l e r−d i s p l a y : a p p l i c a t i o n: d i s p l a y− f u n c t i o n ’ ( d i sp l a y−appo in tment s ) )

( i n t e r a c t o r : i n t e r a c t o r ) )( : l a y o u t s ( d e f a u l t− l a y o u t

( v e r t i c a l l y ( )s c h e d u l e r−d i s p l a yi n t e r a c t o r ) )

( a l t e r n a t i v e− l a y o u t( h o r i z o n t a l l y ( )

i n t e r a c t o rs c h e d u l e r−d i s p l a y ) ) )

( : menu−bar t ) )

; ; ; Chooses which day to see in d e t a i l ,( def ine−scheduler−command ( com−select−day : name t : menu t )

( ( day ’ weekday : g e s t u r e : s e l e c t ) )( w i t h− s l o t s ( cur rent−day ) ∗ app l i c a t i o n− f r ame ∗

( s e t q cur rent−day day ) ) )

; ; ; Show week ly summary .( def ine−scheduler−command (com−show−summary : name t : menu t ) ( )

( w i t h− s l o t s ( cur rent−day ) ∗ app l i c a t i o n− f r ame ∗( s e t q cur rent−day n i l ) ) )

( def ine−scheduler−command ( com−toggle− layout : name t : menu t ) ( )( w i t h−acc e s so r s ( ( l a y o u t f rame−cur rent− l ayout ) ) ∗ app l i c a t i o n− f r ame ∗

( s e t f l a y o u t ( i f ( eq l a y o u t ’ d e f a u l t− l a y o u t )’ a l t e r n a t i v e− l a y o u t’ d e f a u l t− l a y o u t ) ) ) )

Figure 9: Scheduler: application frame, presentation type and commands

20

; ; ; Complex d i s p l a y func t ion , shows two comp l e t e l y d i f f e r e n t d i s p l a y s .( defmethod d i sp l a y−appo in tment s ( ( f rame s c h e d u l e r ) pane )

( c l ea r−output− r e co rd ( s t ream−output−h i s to ry pane ) )( w i t h− s l o t s ( cur rent−day appo intments ) f rame

( i f ( n u l l cur rent−day )( show−weekly−summary pane appo intments )( show−appointments pane

cur rent−day( r e s t ( a s s o c cur rent−day appo intments ) ) ) ) ) )

; ; ; Show a summary o f the week , wi th an appointment count f o r each; ; ; day . You can see the appointments f o r a s p e c i f i c day by c l i c k i n g on; ; ; the day name .( de fun show−weekly−summary ( pane appo intments )

( f o rma t t i n g− t ab l e ( pane ) ; Table headings( formatt ing− row ( pane )

( with−drawing−opt ions ( pane : t e x t− f a c e : bo ld )( f o rma t t i n g− c e l l ( pane )

( w r i t e− s t r i n g ”Day o f week” pane ) )( f o rma t t i n g− c e l l ( pane )

( w r i t e− s t r i n g ”number o f appointments ” pane ) ) ) )( d o l i s t ( day appo in tments )

( formatt ing− row ( pane )( f o rma t t i n g− c e l l ( pane )

( p r e s e n t ( f i r s t day ) ’ weekday : s t ream pane ) )( f o rma t t i n g− c e l l ( pane )

( fo rmat pane ”˜D appointment ˜ :P”( l e n g t h ( r e s t day ) ) ) ) ) ) ) )

; ; ; Show d e t a i l e d appointment l i s t f o r day( de fun show−appointments ( pane cur rent−day current−day−appo intments )

; ; Show a l l days at top so you can sw i t ch to another; ; day wi th one c l i c k .( dot imes ( day 7)

( wi th− text− face ( pane ( i f ( e q l day cur rent−day ) ’ : bo ld ’ : roman ) )( p r e s e n t day ’ weekday : s t ream pane ) )

( w r i t e− s t r i n g ” ” pane ) )( t e r p r i pane ) ( t e r p r i pane ); ; Show a l l the appointments , one per l i n e( w r i t e− s t r i n g ”Appointments f o r ” pane )( p r e s e n t cur rent−day ’ weekday : s t ream pane )( t e r p r i pane ) ( t e r p r i pane )( d o l i s t ( appo intment current−day−appo intments )

( w r i t e− s t r i n g appo intment pane )( t e r p r i pane ) ) )

Figure 10: Scheduler: display functions

21

The weekday presentation type defines two ba-sic pieces of behavior: how a weekday is dis-played, and how it is read as input. The macrodefine-presentation-method is intended for specializ-ing methods on presentation types. Via this macro,we define a printer and a parser function for thetype weekday. As is the case with most presenta-tion types, the printer and parser are duals. Thatis, the printer, when given an object to print, pro-duces output that the parser can interpret to arriveback at the original object. accept does not needa parser in every case, and for simplicity the pro-grammer might choose not to provide a parser atall.

We took the easy way out with our parser. climprovides a completion facility and instead of read-ing the day name of the stream and parsing itinto an integer, we provided an exhaustive set ofinput to object mappings. The completing-from-suggestions macro collects all suggestions made bythe parser via suggest. suggest takes an input andobject as suggestion. In our case, day name takenfrom *days* is the input and the number of theweek i is the object. clim will match the inputgiven by the user with the suggestions and in caseof a match will return the corresponding object tothe caller.

We define an application frame for the appoint-ment browser in Figure 9. The frame defines statevariables to hold the list of appointments and thecurrent day. This information is kept in slots onthe frame, so that multiple copies of the applica-tion can be run, each with its own appointmentlist. The application represents the appointmentdata as an alist containing an entry for each day ofthe week, with each entry containing a list of theappointments for the day. Test data is provided asa default initform.

Just as in the previous example, the appointmentapplication defines two panes, an interactor andan output display pane. The appointment applica-tion defines two commands. The “Show Summary”command resets the display back to the weeklysummary mode by setting the current-day slot tonil. The “Select Day” command sets current-day tothe value of an argument that is specified to be aweekday. This presentation type specification al-lows the command processor to make all presentedweekday active when it is filling in this argument, aswell as, provide completion assistance to the user.

The command “Select Day” has the following ar-gument specification:

( ( day ’ weekday : g e s t u r e : s e l e c t ) )

It takes an argument day of type weekday. Up untilnow, our command arguments have looked simi-larly to specialized lambda lists, but next to thetype information the arguments of commands arealso allowed to have various keyword-value pairsfor selection further options. In this case, we sup-plied the value :select for the option :gesture. Themacro define-command parses this keyword-valuepair and generate a presentation translator. Moreprecisely, a presentation-to-command translator isdefined that is equal in functionality to the one wehave seen in the file-browser example. Whenever apresentation of the type pathname is selected (e.g.with pointer clicks) in a command input context, itis translated into a command invocation of “SelectWeekday”.

Finally, we turn to the display the appoint-ment information. The display function, display-appointments, shown in Figure 10, is somewhatmore complex than our earlier example. It candisplay two different sets of information: a weeklysummary showing the days of the week and thenumber of appointments for each day, or a detaileddescription of one day’s appointments.

display-appointments decides which set of infor-mation to display by examining the applicationstate variable current-day. The table formatting fa-cility is used to present the weekly summary infor-mation neatly organized. The daily appointmentlist, by contrast, is displayed using write-string.Note, however, that whenever a day of the weekis displayed, it is done with a call to present us-ing the weekday presentation type. This allows theprinted weekdays to be selected either as a com-mand or as a weekday argument. This exampleillustrates how an application with interesting UIbehavior can be constructed from a high-level spec-ification of its functionality.

7 Conclusion

The series of examples presented in this article illus-trates the broad range of functionality provided byclim. The later examples, especially, demonstratethat complex user interfaces can be built econom-

22

ically and in a modular fashion using clim. Manyof the higher level facilities make it possible to sep-arate the issues involved in designing an applica-tion’s user interface from the functionality of theapplication.

On the other hand, these higher level facilitiesare not appropriate for all programmers. clim’slower level facilities and clean modularization ofthe higher level facilities provide these program-mers with portable platform and a framework forimplementing their own user interface toolkits andframeworks. In addition, clim’s use of clos todefine explicit, documented protocols provides ap-plication programmers with the opportunity to cus-tomize clim and support interfaces not anticipatedby the clim designers.

A free clim implementation is available asMcCLIM, found at http://common-lisp.net/

project/mcclim/. In addition to the caveats inthis document, note that McCLIM only workswith an X windows backend as of January 2006.

Acknowledgments

Original article clim represents the cooperativeeffort of individuals at several companies. These in-dividuals include Jim Veitch, John Irwin, and ChrisRichardson of Franz; Richard Lamson, David Lin-den, and Mark Son-Bell of ILA; Paul Wieneke andZack Smith of Lucid; Scott McKay, John Aspinall,Dave Moon and Charlie Hornig of Symbolics; andGregor Kizcales and John Seely Brown of XeroxPARC. Mark Son-Bell and Jon L. White have helpus improve this paper.

2006 update Clemens Fruhwirth thanks the de-velopers for McCLIM for producing a free climimplementation, and especially Robert Strandh foranswering so many questions in conjunction withMcCLIM.

References

[McC] McCLIM. A free CLIM implementation.

[MY05] Scott McKay and Wiliam York. Com-mon lisp interface manager specification,2005.

[MYM89] Scott McKay, William York, andMichael McMahon. A presentation man-ager based on application semantics. InProceedings of the ACM SIG-GRAPHSymposium on User Interface Softwareand Technology, pages 141–148. ACMPress, November 1989.

[Sym] Symbolics, Inc. Programmer’s ReferenceManual Vol 7: Programming the UserInterface.

23