McCLIM User’s Manual

1.1.1 Examples and demos

Demos are meant to be run after loading the clim-examples system from the frame created with (clim-demo:demodemo).

The easiest way to try this is to use the Quicklisp library manager. Assuming that Quicklisp has already been set up, trying out the demos is straightforward:

(ql:quickload :clim-examples)
(clim-demo:demodemo)

Alternatively, for the more courageous (which requires separately downloading dependencies and setting a local repository), asdf also works well starting from the McCLIM source code directory.

(asdf:load-system "clim-examples")
(clim-demo:demodemo)

The source code of all demos can be found in the Examples directory.

1.1.2 Applications

Additionally McCLIM has a few bundled applications:

Apps/Listener

CLIM-enabled Lisp listener. System name is clim-listener. See Listener for more information.

(asdf:load-system "clim-listener")
(clim-listener:run-listener)

Apps/Clouseau

CLIM-enabled Lisp inspector. System name is clouseau. See Inspector for more information.

(asdf:load-system "clouseau")
(clouseau:inspect clim:+indian-red+)

Apps/Debugger

Common Lisp debugger implemented in McCLIM. It uses the portable debugger interface for sldb (part of Slime project). System name is clim-debugger. See Debugger for more information.

(asdf:load-system "clim-debugger")
(clim-debugger:with-debugger
 (break "simple-break"))

Apps/Functional-Geometry

Peter Henderson idea, see http://www.ecs.soton.ac.uk/~ph/funcgeo.pdf and http://www.ecs.soton.ac.uk/~ph/papers/funcgeo2.pdf implemented in Lisp by Frank Buss. CLIM Listener interface by Rainer Joswig. System name is functional-geometry.

(asdf:load-system 'functional-geometry)
(functional-geometry:run-functional-geometry)
(clim-plot *fishes*) ; from a listener

1.2.1 A bit of terminology

CLIM was developed before the GUI toolkits widely used at the moment. Qt, GTK and others appeared much later than CLIM and the difference of terminology reflects this.

A CLIM application is made up of a hierarchy of an application frame, panes and gadgets (gadgets are special kinds of panes):

application frame

An application frame is what would usually be called an application.

panes

At a very high level, panes describe an application frame’s visual building blocks: a side bar, a menu bar, a table displaying a list of items, a text input are all panes. They can be used by application programmers to compose the top-level user interface of their applications, as well as auxiliary components such as menus and dialogs. In addition, panes can be more abstract such as layout panes such as hbox, vbox to arrange other panes horizontally or vertically, etc.

gadgets

gadgets correspond to what other toolkits call widgets and control. Frequently used CLIM gadgets are buttons, sliders, etc.

1.2.2 How CLIM applications produce output

Although it is easy to imagine panes in terms of their appearance on screen, they are much richer: they are actually the series of operations that produces that appearance. They are not only the end product visible on a screen, but they contain all the step-by-step information that led to that representation.

More precisely, CLIM panes record the series of operations that generates an output. This means that such a pane maintains a display list, consisting of a sequence of output records, ordered chronologically, from the first output record to be drawn to the last.

This display list is used to fill in damaged areas of the pane, for instance as a result of the pane being partially or totally covered by other panes, and then having some or all of its area again becoming visible. The output records of the display list that have some parts in common with the exposed area are partially or totally replayed (in chronological order) to redraw the contents of the area.

An application can have a pane establish this display list in several fundamentally different ways, each more sophisticated:

Simple application

Very simple applications have no internal data structure to keep track of application objects, and simply produce output to the pane from time to time as a result of running commands, occasionally perhaps erasing the pane and starting over. Such applications typically use text or graphics output as a result of running commands. CLIM maintains the display list for the pane, and adds to the end of it, each time also producing the pixels that result from drawing the new output record. If the pane uses scrolling (which it typically does), then CLIM must determine the extent of the pane so as to update the scroll bar after each new output.

Application with a static display function

More complicated applications use a display function. Before the display function is run, the existing display list is typically deleted, so that the purpose of the display function becomes to establish an entirely new display list. The display function might for instance produce some kind of form to be filled in, and application commands can use text or graphics operations to fill in the form. A game of tic-tac-toe could work this way, where the display function draws the board and commands draw shapes into the squares.

Application with a dynamic display function

Even more complicated applications might have some internal data structure that has a direct mapping to output, and commands simply modify this internal data structure. In this case, the display function is run after each time around the command loop, because a command can have modified the internal data structure in some arbitrary ways. Some such applications might simply want to delete the existing display list and produce a new one each time (to minimize flicker, double buffering could be used). This is a very simple way of structuring an application, and entirely acceptable in many cases. Consider, for instance, a board game where pieces can be moved (as opposed to just added). A very simple way of structuring such an application is to have an internal representation of the board, and to make the display function traverse this data structure and produce the complete output each time in the command loop.

Application with an incremental static display function

Some applications have very large internal data structures to be displayed, and it would cause a serious performance problem if the display list had to be computed from scratch each time around the command loop. To solve this problem, CLIM contains a feature called incremental redisplay. It allows many of the output records to be kept from one iteration of the command loop to the next. This can be done in two different ways. The simplest way is for the application to keep the simple structure which consists of traversing the entire data structure each time, but at various points indicate to CLIM that the output has not changed since last time, so as to avoid actually invoking the application code for computing it. This is accomplished by the use of updating-output. The advantage of updating-output is that the application logic remains straightforward, and it is up to CLIM to do the hard work of recycling output records. The disadvantage is that for some very demanding applications, this method might not be fast enough.

Programmer does it all

The other way is more complicated and requires the programmer to structure the application differently. Essentially, the application has to keep track of the output records in the display list, and inform CLIM about modifications to it. The main disadvantage of this method is that the programmer must now write the application to keep track of the output records itself, as opposed to leaving it to CLIM.

1.2.3 Panes and Gadgets

A CLIM application is made up of a hierarchy of panes and gadgets (gadgets are special kinds of panes). These elements correspond to what other toolkits call widgets. Frequently used CLIM gadgets are buttons, sliders, etc, and typical panes are the layout panes such as hbox, vbox, hrack, etc.

1.2.4 Defining Application Frames

Each CLIM application is defined by an application frame. An application frame is an instance of the class application-frame. As a CLIM user, you typically define a class that inherits from the class application-frame, and that contains additional slots needed by your application. It is considered good style to keep all your application-specific data in slots in the application frame (rather than, say, in global variables), and to define your application-specific application frame in its own package.

The usual way to define an application frame is to use the macro define-application-frame. This macro works much like defclass, but also allows you to specify the hierarchy of panes and gadgets to use.

1.2.5 A First Attempt

Let us define a very primitive CLIM application. For that, let us put the following code in a file:

(in-package :common-lisp-user)

(defpackage :my-first-app
  ;; Imports the appropriate CLIM library
  (:use :clim :clim-lisp)

  ;; The package will only export a function to run the app
  (:export run-my-first-app))

;; Good practice
(in-package :my-first-app)

;; Definition of the structure of a minimum app
(define-application-frame my-first-clim-app ()
  ()

  ;; This app only has 1 pane
  (:panes
   (my-interactor :interactor
                  :height 400
                  :width 600))

  ;; :layouts section describes how the pane is positioned inside
  ;; the application frame.
  ;; With 1 pane, no point getting complicated, Default is fine...
  (:layouts
    (my-default my-interactor)))

;; Now that the structure of the app is defined, need a function
;; to launch an instance of this app. (The user could run
;; several instances of the same app.)
(defun run-my-first-app ()
  (run-frame-top-level (make-application-frame 'my-first-clim-app)))

As we can see in this example, we have put our application in a separate package, here a package named MY-FIRST-APP. While not required, putting the application in its own package is good practice.

The package for the application uses two packages: CLIM and CLIM-LISP. The CLIM package is the one that contains all the symbols needed for using CLIM. The CLIM-LISP package replaces the COMMON-LISP package for CLIM applications. It is essentially the same as the COMMON-LISP package as far as the user is concerned.

In our example, we export the symbol that corresponds to the main function to start our application, here called run-my-first-app.

The most important part of the code in our example is the definition of the application-frame. In our example, we have defined an application frame called my-first-clim-app, which becomes a CLOS class that automatically inherits from some standard CLIM application frame class.

The second argument to define-application-frame is a list of additional superclasses from which you want your application frame to inherit. In our example, this list is empty, which means that our application frame only inherits from the standard CLIM application frame.

The third argument to define-application-frame is a list of CLOS slots to be added to any instance of this kind of application frame. These slots are typically used for holding all application-specific data. The current instance of the application frame will always be the value of the special variable *application-frame*, so that the values of these slots can be accessed. In our example, we do not initially have any further slots.

The rest of the definition of an application frame contains additional elements that CLIM will allow the user to define. In our example, we have two additional (mandatory) elements: :panes and :layouts.

The :panes element defines a collection of CLIM panes that each instance of your application may have. Each pane has a name, a type, and perhaps some options that are used to instantiate that particular type of pane. Here, we have a pane called my-interactor of type :interactor with a height of 400 units and a width of 600 units. In McCLIM, the units are initially physical units (number of pixels) of the native windowing system.

The :layouts element defines one or more ways of organizing the panes in a hierarchy. Each layout has a name and a description of a hierarchy. In our example, only one layout, named my-default, is defined. The layout called my-default is the one that is used by CLIM at startup. In our example, the corresponding hierarchy is trivial, since it contains only the one element my-interactor, which is the name of our only pane.

1.2.6 Executing the Application

In order to run a CLIM application, you must have a Lisp system that contains McCLIM. If you use CMUCL or SBCL, you either need a core file that already has McCLIM in it, or else, you have to load the McCLIM compiled files that make up the McCLIM distribution. The first solution is recommended so as to avoid having to load the McCLIM files each time you start your CLIM application.

To execute the application, load the file containing your code (possibly after compiling it) into your running Lisp system. Then start the application. Our example can be started by typing (my-first-app:run-my-first-app).

1.2.7 Adding Functionality

In a serious application, you would probably want some area where your application objects are to be displayed. In CLIM, such an area is called an application pane, and would be an instance (direct or indirect) of the CLIM class application-pane. In fact, instances of this class are in reality also streams which can be used in calls both to ordinary input and output functions such as format and read and to CLIM-specific functions such as draw-line.

Let’s consider an improved example, where the my- names have been replaced by shorter versions for brevity:

(in-package :common-lisp-user)

(defpackage :app
  (:use :clim :clim-lisp)
  (:export run-app))

(in-package :app)

(define-application-frame superapp ()
  ()
  (:pointer-documentation t)
  (:panes

   ;; Let's add an additional pane
   (app :application

        ;; :DISPLAY-TIME specifies when this pane should be displayed
        ;; in the command loop. Note that the refresh is
        ;; pane-specific, not application-wide.
        :display-time nil
        :height 400
        :width 600)

   (int :interactor
        :height 200
        :width 600))

  (:layouts

   ;; This time we explicitly specify that the 2 defined panes
   ;; should be stacked vertically.
   (default (vertically ()
              app int))))

;;
;; Let's also define commands that will act on the application.
;;

;; How to leave the application.
;; Note the '-superapp-' part of the command definition, coming from
;; the name of the application frame.
(define-superapp-command (com-quit :name t) ()
  (frame-exit *application-frame*))


;; This is an additional command that will be used in the next
;; example, so its content is not important. However, it is useful to
;; describe some aspects of the command loop. See below.
(define-superapp-command (com-parity :name t) ((number 'integer))
  (format t "~a is ~a~%" number
          (if (oddp number)
              "odd"
              "even")))


(defun run-app ()
  (run-frame-top-level (make-application-frame 'superapp)))

In this example we have such an application pane, the name of which is app. As you can see, we have defined it with an option :display-time nil. The default value for this option for an application pane is :command-loop, which means that the pane is cleared after each iteration in the command loop, and then redisplayed using a client-supplied display function. The default display function does nothing, and we have not supplied any, so if we had omitted the :display-time nil option, the parity command would have written to the pane. Then, at the end of the command loop, the pane would have been cleared, and nothing else would have been displayed. The net result is that we would have seen no visible output. With the option :display-time nil, the pane is never cleared, and output is accumulated every time we execute the parity command.

For this example, we also added a few commands. Such commands are defined by the use of a macro called define-name-command, where name is the name of the application, in our case superapp. This macro is automatically defined by define-application-frame.

In addition, we added a pane that automatically provides documentation for different actions on the pointer device. This was done by including (:pointer-documentation t) in the frame definition.

If you execute this example, you will find that you now have three different panes—the application pane, the interactor pane, and the pointer documentation pane. In the pointer documentation pane, you will see the text ‘R possibilities’ which indicates that if you click the right mouse button, you will automatically see a popup menu that lets you choose a command. In our case, you will have the default commands that are automatically proposed by McCLIM plus the commands that you defined yourself, in this case quit and parity.

Figure 1.1 shows what ought to be visible on the screen.

Figure 1.1: View of the improved example.

Notice that commands, in order to be available from the command line, must have an option of :name t. The reason is that some commands will be available only from menus or by some other mechanism.

You may notice that if the output of the application is hidden (say by the window of some other application) and then re-exposed, the output reappears normally, without any intervention necessary on the part of the programmer. This effect is accomplished by a CLIM mechanism called output recording. Essentially, every piece of output is not only displayed in the pane, but also captured in an output record associated with the pane. When a pane is re-exposed, its output records are consulted and if any of them overlap the re-exposed region, they are redisplayed. In fact, some others may be redisplayed as well, because CLIM guarantees that the effect will be the same as when the initial output was created. It does that by making sure that the order between (partially) overlapping output records is respected.

Not all panes support output recording, but application panes certainly do, so it is recommended that you use some subclass of application-pane to display application-specific objects, so that output recording is done automatically.

1.2.8 An application displaying a data structure

Many applications use a central data structure that is to be on display at all times, and that is modified by the commands of the application. CLIM allows for a very easy way to write such an application. The main idea is to store the data structure in slots of the application frame, and to use a display function that after each iteration of the command loop displays the entire data structure to the application pane.

Here is a variation of the previous application that shows this possibility:

(in-package :common-lisp-user)

(defpackage "APP"
  (:use :clim :clim-lisp)
  (:export "APP-MAIN"))

(in-package :app)

(define-application-frame superapp ()
  ;; New addition of a slot to the application frame, which defines a
  ;; application-specific slot. The slot is simply a number.
  ((current-number :initform nil
                    :accessor current-number))

  ;; We no longer specify :DISPLAY-TIME (see below), and we supply our
  ;; own :DISPLAY-FUNCTION. The rest of the application frame is
  ;; unchanged.
  (:pointer-documentation t)
  (:panes
    (app :application
         :height 400
         :width 600
         :display-function 'display-app)
    (int :interactor
         :height 200
         :width 600))
  (:layouts
    (default (vertically ()
              app int))))

;; The display function for the "app" pane. It simply prints the
;; number from the application frame slot, and whether it is odd or
;; even. Note that the print stream of `format' is PANE.
(defun display-app (frame pane)
  (let ((number (current-number frame)))
    (format pane "~a is ~a"
            number
            (cond ((null number) "not a number")
                  ((oddp number) "odd")
                  (t "even")))))

(define-superapp-command (com-quit :name t) ()
  (frame-exit *application-frame*))

(define-superapp-command (com-parity :name t) ((number 'integer))
  (setf (current-number *application-frame*) number))


(defun app-main ()
  (run-frame-top-level (make-application-frame 'superapp)))

Here, we have added a slot that is called current-number to the application frame. It is initialized to NIL and it has an accessor function that allow us to query and to modify the value.

Observe that in this example, we no longer have the option :display-time nil set in the application pane. By default, then, the :display-time is :command-loop, which means that the pane is erased after each iteration of the command loop. Also observe the option :display-function in the application pane definition, which takes the name of a function that will be called to display the pane after it has been cleared. In this case, the function is display-app, which we have defined immediately after the application frame.

Instead of immediately displaying information about its argument, the command com-parity instead modifies the new slot of the application frame. Think of this function as being more general, for instance a command to add a new object to a set of graphical objects in a figure drawing program, or as a command to add a new name to an address book. Notice how this function accesses the current application frame by means of the special variable *application-frame*.

A display function is called with the frame and the pane as arguments. It is good style to use the pane as the stream in calls to functions that will result in output. This makes it possible for the same function to be used by several different frames, should that be called for. In our simple example, the display function only displays the value of a single number (or NIL), but you could think of this as displaying all the objects that have been drawn in some figure drawing program or displaying all the entries in an address book.

1.4.1 What is a presentation type

The concept of presentation types is central to CLIM. Client code can choose to output graphical or textual representations of application objects either as just graphics or text, or to associate such output with an arbitrary Common Lisp object and a presentation type. The presentation type is not necessarily related to the idea Common Lisp might have of the underlying object.

When a CLIM command or some other client code requests an object (say as an argument) of a certain presentation type, the user of the application can satisfy the request by clicking on any visible output labeled with a compatible presentation type. The command then receives the underlying Common Lisp object as a response to the request.

CLIM presentation types are usually distinct from Common Lisp types. The reason is that the Common Lisp type system, although very powerful, is not quite powerful enough to represent the kind of relationships between types that are required by CLIM. However, every Common Lisp class (except the built-in classes) is automatically a presentation type.

A presentation type has a name, but can also have one or more parameters. Parameters of presentation types are typically used to restrict the type. For instance, the presentation type integer takes as parameters the low and the high values of an interval. Such parameters allow the application to restrict objects that become clickable in certain contexts, for instance if a date in the month of March is requested, only integers between 1 and 31 should be clickable.

1.4.2 A simple example

Consider the following example:

(in-package :common-lisp-user)

(defpackage :app
  (:use :clim :clim-lisp)
  (:export #:app-main))

(in-package :app)

(define-application-frame superapp ()
  ()
  (:pointer-documentation t)
  (:panes
    (app :application :display-time t :height 300 :width 600)
    (int :interactor :height 200 :width 600))
  (:layouts
    (default (vertically () app int))))

(defun app-main ()
  (run-frame-top-level (make-application-frame 'superapp)))

(define-superapp-command (com-quit :name t) ()
  (frame-exit *application-frame*))

(define-presentation-type name-of-month ()
  :inherit-from 'string)

(define-presentation-type day-of-month ()
  :inherit-from 'integer)

(define-superapp-command (com-out :name t) ()
  (with-output-as-presentation (t "The third month" 'name-of-month)
    (format t "March~%"))
  (with-output-as-presentation (t 15 'day-of-month)
    (format t "fifteen~%")))

(define-superapp-command (com-get-date :name t)
    ((name 'name-of-month) (date 'day-of-month))
  (format (frame-standard-input *application-frame*)
	  "the ~a of ~a~%" date name))

In this application, we have two main panes, an application pane and an interactor pane. The application pane is given the option :display-time t which means that it will not be erased before every iteration of the command loop.

We have also defined two presentation types: name-of-month and day-of-month. The out command uses with-output-as-presentation in order to associate some output, a presentation type, and an underlying object. In this case, it will show the string “March” which is considered to be of presentation type name-of-month with the underlying object being the character string "The third month". It will also show the string “fifteen” which is considered to be of presentation type day-of-month with the underlying object being the number 15. The argument t to with-output-as-presentation indicates that the stream to present on is *standard-output*.

Thus, if the out command has been executed, and then the user types ‘Get Date’ in the interactor pane, the get-date command will try to acquire its arguments, the first of presentation type name-of-month and the second of type day-of-month. At the first prompt, the user can click on the string ‘March’ but not on the string ‘fifteen’ in the application pane. At the second prompt it is the string ‘fifteen’ that is clickable, whereas ‘March’ is not.

The get-date command will acquire the underlying objects. What is finally displayed (in the interactor pane, which is the standard input of the frame), is ‘the 15 of The third month’.

1.7.1 Creating Menu bar

McCLIM makes creating menu bar quite easy.

(clim:define-application-frame foo ()
      ;; ...
      (:menu-bar t)
      ;; ...
      )

The only argument for :menu-bar can be:

T (default)

McCLIM will provide the menu bar. Later, when you start defining commands, you can provide a (:menu t) argument to command definition that will add this command to menu bar.

NIL

McCLIM won’t provide the menu bar.

command-table

If you provide a named command table as argument, that command table is used to provide the menu bar (See Using command tables).

To add a sub-menu to menu bar, you need to change the type of menu-item from :command to :menu (which requires another command-table as argument) which is described in the next section.

1.7.2 Modifying Menu bar

Menu bar can be changed anytime by changing command-table associated with the current frame.

(setf (frame-command-table *application-frame*)
      new-command-table)

Example above changes menu bar of *application-frame* by replacing current command-table (accessible with frame-command-table function) with new-command-table.

Modifying menu items of command table

Function: add-menu-item-to-command-table [clim] command-table string type value &rest args &key documentation after keystroke text-style errorp ¶

Adds menu item to the command table.

Function arguments:

command-table

Command table to which we want to add the menu item.

string

Name of the menu item as it will appear on the menu bar. Its character case is ignored e.g. you may give it ‘file’ or ‘FILE’ but it will appear as ‘File’.

type and value

type can be one of :command, :function, :menu and :divider. Value of value depends on type:

:command

value must be a command or a cons of command name and its arguments. If you omit the arguments McCLIM will prompt for them.

:function

value must be a function having indefinite extent that, when called, returns a command. The function must accept two arguments: the gesture (keyboard or mouse press event) and a numeric argument.

:menu

value must be another command table. This type is used to add sub-menus to the menu.

:divider

value is ignored and string is used as a divider string. Using ‘|’ as string will make it obvious to users that it is a divider.

documentation

You can provide the documentation (for non-obvious menu items) which will be displayed on pointer-documentation pane (if you have one).

after (default :end)

This determines where item will be inserted in the menu. The default is to add it to the end. Other values could be :start, :sort (add in alphabetical order) or string which is name of existing menu-item to add after it.

keystroke

If keystroke is supplied, it will be added to comand tables keystroke accelerator table. Value must be a keyboard gesture name e.g. (:s :control) for Control + s.

text-style

Either a text style spec or NIL. It is used to indicate that the command menu item should be drawn with the supplied text style in command menus.

error-p

If T and the item already exists in the menu, it signal a command-already-present error. If NIL, it will first remove the existing item and add the new item to the command-table.

To remove items from command table, the following function is used:

Function: remove-menu-item-from-command-table [clim] command-table string &key errorp ¶

Removes item from the command-table.

Where command-table is command-table-designator and string is the menu item’s name (it is case-insensitive). You can provide :error-p nil to suppress the error if item is not in the command-table.

Note that both of the above functions do not automatically update the menu bar. For that you need to replace the existing frame-command-table with the modified command table using setf. The typical way to do this is to use let to create a copy of frame-command-table, modify it and at the end call setf to replace the original.

2.1.1 Coordinate systems

CLIM uses a number of different coordinate systems and transformations to transform coordinates between them.

The coordinate system used for the arguments of drawing functions is called the user coordinate system, and coordinate values expressed in the user coordinate system are known as user coordinates.

Each sheet has its own coordinate system called the sheet coordinate system, and positions expressed in this coordinate system are said to be expressed in sheet coordinates. User coordinates are translated to sheet coordinates by means of the user transformation also called the medium transformation. This transformation is stored in the medium used for drawing. The medium transformation can be composed temporarily with a transformation given as an explicit argument to a drawing function. In that case, the user transformation is temporarily modified for the duration of the drawing.

Before drawing can occur, coordinates in the sheet coordinate system must be transformed to native coordinates, which are coordinates of the coordinate system of the native windowing system. The transformation responsible for computing native coordinates from sheet coordinates is called the native transformation. Notice that each sheet potentially has its own native coordinate system, so that the native transformation is specific for each sheet. Another way of putting it is that each sheet has a mirror, which is a window in the underlying windowing system. If the sheet has its own mirror, it is the direct mirror of the sheet. Otherwise its mirror is the direct mirror of one of its ancestors. In any case, the native transformation of the sheet determines how sheet coordinates are to be translated to the coordinates of that mirror, and the native coordinate system of the sheet is that of its mirror.

The composition of the user transformation and the native transformation is called the device transformation. It allows drawing functions to transform coordinates only once before obtaining native coordinates.

Sometimes, it is useful to express coordinates of a sheet in the coordinate of its parent. The transformation responsible for that is called the sheet transformation.

2.1.2 Arguments to drawing functions

Drawing functions are typically called with a sheet as an argument.

A sheet often, but not always, corresponds to a window in the underlying windowing system.

2.2.1 Computing the native transformation

2.2.2 Computing the native region

2.2.3 Moving and resizing sheets and regions

2.2.4 Scrolling

2.3.1 Windowing system drawing

A typical windowing system provides a hierarchy of rectangular areas called windows. When a drawing functions is called to draw an object (such as a line or a circle) in a window of such a hierarchy, the arguments to the drawing function will include at least the window and a number of coordinates relative to (usually) the upper left corner of the window.

To translate such a request to the actual altering of pixel values in the video memory, the windowing system must translate the coordinates given as argument to the drawing functions into coordinates relative to the upper left corner of the entire screen. This is done by a composition of translation transformations applied to the initial coordinates. These transformations correspond to the position of each window in the coordinate system of its parent.

Thus a window in such a system is really just some values indicating its height, its width, and its position in the coordinate system of its parent, and of course information about background and foreground colors and such.

2.3.2 CLIM drawing

CLIM generalizes the concept of a hierarchy of window in a windowing system in several different ways. A window in a windowing system generalizes to a sheet in CLIM. More precisely, a window in a windowing system generalizes to the sheet region of a sheet. A CLIM sheet is an abstract concept with an infinite drawing plane and the region of the sheet is the potentially visible part of that drawing plane.

CLIM sheet regions don’t have to be rectangular the way windows in most windowing systems have to be. Thus, the width and the height of a window in a windowing system generalizes to an arbitrary region in CLIM. A CLIM region is simply a set of mathematical points in a plane. CLIM allows this set to be described as a combination (union, intersection, difference) of elementary regions made up of rectangles, polygons and ellipses.

Even rectangular regions in CLIM are generalizations of the width+height concept of windows in most windowing systems. While the upper left corner of a window in a typical windowing system has coordinates (0,0), that is not necessarily the case of a CLIM region. CLIM uses that generalization to implement various ways of scrolling the contents of a sheet. To see that, imagine just a slight generalization of the width+height concept of a windowing system into a rectangular region with x+y+width+height. Don’t confuse the x and y here with the position of a window within its parent, they are different. Instead, imagine that the rectangular region is a hole into the (infinite) drawing plane defined by all possible coordinates that can be given to drawing functions. If graphical objects appear in the window with respect to the origin of some coordinate system, and the upper-left corner of the window has coordinates (x,y) in that coordinate system, then changing x and y will have the effect of scrolling.

CLIM sheets also generalize windows in that a window typically has pixels with integer-value coordinates. CLIM sheets, on the other hand, have infinte resolution. Drawing functions accept non-integer coordinate values which are only translated into integers just before the physical rendering on the screen.

The x and y positions of a window in the coordinate system of its parent window in a typical windowing system is a translation transformation that takes coordinates in a window and transform them into coordinates in the parent window. CLIM generalizes this concepts to arbitrary affine transformations (combinations of translations, rotations, and scalings). This generalization makes it possible for points in a sheet to be not only translated compared to the parent sheet, but also rotated and scaled (including negative scaling, giving mirror images). A typical use for scaling would be for a sheet to be a zoomed version of its parent, or for a sheet to have its y-coordinate go the opposite direction from that of its parent.

When the shapes of, and relationship between sheets are as simple as those of a typical windowing system, each sheet typically has an associated window in the underlying windowing system. In that case, drawing on a sheet translates in a relativly straightforward way into drawing on the corresponding window. CLIM sheets that have associated windows in the underlying windowing system are called mirrored sheets and the system-dependent window object is called the mirror. When shapes and relationships are more complicated, CLIM uses its own transformations to transform coordinates from a sheet to its parent and to its grandparent, etc., until a mirrored sheet is found. To the user of CLIM, the net effect is to have a windowing system with more general shapes of, and relationships between windows.

2.4.1 Creating panes

There is some confusion about the options that are allowed when a pane is created with make-pane. Some parts of the specification suggest that stream panes such as application panes and interactor panes can be created using make-pane and an option :scroll-bars. Since these application panes do not in themselves contain any scroll bars, using that option results in a pane hierarchy being created with the topmost pane being a pane of type scroller-pane.

As far as McCLIM is concerned, this option to make-pane is obsolete. ¹

This does not apply for using this option together with the equivalent keyword, i.e., :application or :interactor, in the :panes section of define-application-frame, because they are created by the function make-clim-stream-pane which does specify this argument.

Instead, we recommend following the examples of the specification, where scroll bars are added in the layouts section of define-application-frame.

When specification talks about panes in a fashion implying some order (i.e “first application-pane”) McCLIM assumes order of definition, not order of appearing in layout. Particularly that means, that if one pane is put before another in :panes option, then it precedes it. It is relevant to frame-standard-output (therefore binding of *standard-output*) and other similar functions.

2.4.2 Pane names

Every pane class accepts the initialization argument :name the value of which is typically a symbol in the package defined by the application. The generic function pane-name returns the value of this initialization argument. There is no standard way of changing the name of an existing pane. Using the function reinitialize-instance may not have the desired effect, since the application frame may create a dictionary mapping names to panes, and there is no way to invalidate the contents of such a potential dictionary.

The function find-pane-named searches the pane hierarchy of the application frame, consulting the names of each pane until a matching name is found. The CLIM specification does not say what happens if a name is given that does not correspond to any pane. McCLIM returns nil in that case. If pane names are not unique, it is unspecified which of several panes is returned by a call to this function.

If the advice of Creating panes is followed, then the name given in the :panes option of the macro define-application-frame will always be the name of the top-level pane returned by the body following the pane name.

If that advice is not followed, then the name given to a pane in the :panes option of the macro define-application-frame may or may not become the name of the pane that is constructed by the body that follows the name. Recall that the syntax of the expression that defines a pane in the :panes option is (name . body). Currently, McCLIM does the following:

• If the body creates a pane by using a keyword, or by using an explicitly mentioned call to make-pane, then the name is given to the pane of the type explicitly mentioned, even when the option :scroll-bars is given.
• If the body creates a pane by calling some arbitrary form other than a call to make-pane, then the name is given to the topmost pane returned by the evaluation of that form.

We reserve the right to modify this behavior in the future. Application code should respect the advice given in Creating panes.

2.4.3 Redisplaying panes

Recall that redisplay refers to the creation of the output history of a pane. There are two typical ways of creating this output history:

• The application maintains some data structure that needs to be reflected in the text and graphics of the pane. In this case, a pane of type application-pane is typically used, and the default value of the :display-time option is used, which means that some kind of application-supplied display function is executed at the end of each iteration of the command loop. In this situation, the output history is either recomputed from scratch in each iteration, or the programmer can use the incremental redisplay facility to reuse some of the existing output records in the history.
• The application does not keep any data structure, and instead generates output incrementally, either as a result of some user action, or of some data arriving from an external source. In this case, the :display-time option is either going to be t or nil. With both of these options, the output history is maintained intact after each iteration of the command loop. Instead, when user actions are issued, more output records are simply added to the existing output history.

For the second possibility, the pane is never redisplayed. Instead, the action of updating the pane contents is referred to as replaying the output history. The remainder of this section is entirely dedicated to the redisplay action.

It is occasionally necessary for the application to redisplay a pane explicitly, as opposed to letting the command loop handle it. For example, if the application data structure is updated in some way, but this update is not the result of a command, then after such an update, the redisplay function needs to be executed explicitly. Such an update could be the result of a timer event, or of communication with an external process.

Generic Function: redisplay-frame-pane [clim] frame pane &key force-p ¶

Calling this generic function causes an immediate redisplay of pane. When force-p is false and the incremental redisplay facility is in use for pane, then output records are reused as appropriate. Supplying a true value for force-p causes the entire output history to be recomputed from scratch.

Notice that this function does not check whether the pane has been marked to need redisplay, as indicated by a call to the generic function pane-needs-redisplay. It results in an unconditional redisplay of pane.

Generic Function: redisplay-frame-panes [clim] frame &key force-p ¶

Calling this generic function causes an immediate redisplay of all the panes of frame that are visible in the current layout. This function simply calls redisplay-frame-pane for each visible pane of frame.

Again, notice that no check is being made as to whether the visible panes have been marked as needing redisplay. This function calls redisplay-frame-pane unconditionally for each visible pane, and since redisplay-frame-pane redisplays the pane unconditionally, it follows that all visible panes are unconditionally redisplayed.

Also notice that the implication of this unconditional behavior on the part of redisplay-frame-panes means that this is not the function called by the standard command loop. The standard command loop only redisplays panes that have been marked as needing redisplay, though when the value of the :display-time option is :command-loop for some pane, then it is always marked as needing redisplay in each iteration of the command loop.

2.4.4 Layout protocol

There is a set of fundamental rules of CLIM dividing responsibility between a parent pane and a child pane, with respect to the size and position of the region of the child and the sheet transformation of the child. This set of rules is called the layout protocol.

The layout protocol is executed in two phases. The first phase is called the space compostion phase, and the second phase is called the space allocation phase.

• Space composition
• Space allocation
• Change-space Notification Protocol

     (setf (space-requirement-width ...)  (or explicit-width
           (space-requirement-width request)) ...
           (space-requirement-max-width ...)  (or explicit-max-width
           explicit-width (space-requirement-max-width request)) ...)

3.1.1 Packages

In addition to the packages mentioned in the specification, McCLIM defines the packages clim-extensions and clim-backend. Both are used by the clim-internals package to avoid conflicts.

clim-extensions (which has the nickname clime) exports all extensions provided by McCLIM. While each extension may define its own package for implementation purposes, application programmers should access symbols only via the clim-extensions package.

clim-backend (which has the nickname climb) exports symbols which are intended for use by backend writers. It uses the packages clim and clim-extensions.

3.1.2 Examples

Examples and demos which are distributed with McCLIM are loaded from a separate system named clim-examples. Each example should be put either directly in the package clim-demo or live in its own package the name of which should be start with clim-demo., for instance clim-demo.foobar-example.

3.3.1 Different types of backends

Backend provides platform specific API for low level drawing operations, getting events, managing window geometry properties and providing native look-and-feel to the application.

There are three types of backends:

Draw-only backend

This type doesn’t implement any kind of events and allows only drawing on it. A good example of it is the See PostScript backend which is part of CLIM II specification.

Basic backend

OpenGL, X, or HTML 5 canvas are resources which provide only drawing and event handling primitives. In this case we need to wrap their APIs for McCLIM to use. McCLIM will then use these drawing and windowing primitives to implement portable widgets.

Native backend

Native backend is based on already complete GUI library which provides a rich set of widgets (for example Cocoa or Win32 API). Additionally to the things needed to be implement in the first two cases, we can also map these native look and feel widgets in McCLIM.

The clim-null backend can be used as a template to start with a new backend. If the underlying library you write backend for manages window hierarchy, positioning and events, it is possible to base new pane types on mirrored-sheet-mixin class which provides native handles into native windowing system. Mirrored and “native lisp” sheets may be freely mixed in the pane hierarchy.

3.3.2 Backend protocol

NEW CLASS FOR BACKEND `FOO'
---------------------------
foo-frame-manager
foo-native-frame-manager (optional)
foo-graft
foo-port
foo-medium
foo-pointer

3.3.3 Event handling

EVENT HANDLING (in port.lisp)
-----------------------------
;;; Originally in CLIM-INTERNALS
synthesize-pointer-motion-event

3.3.4 Graft protocol

GRAFT (in grafts.lisp)
-----------------------------------
;;; Originally in CLIM
graft        ; root window/screen
graft-height ; screen height
graft-width  ; screen width

3.3.5 Medium drawing

MEDIUM DRAWING (in medium.lisp)
-------------------------------
;;; Originally in CLIM
medium-draw-ellipse*
medium-draw-line*
medium-draw-lines*
medium-draw-point*
medium-draw-points*
medium-draw-polygon*
medium-draw-rectangle*
medium-draw-rectangles*
medium-draw-text*

3.3.6 Medium operation

MEDIUM OPERATIONS (in medium.lisp)
----------------------------------
;;; Originally in CLIM
make-medium ; make medium for a given sheet
medium-beep
medium-buffering-output-p
medium-clear-area
medium-copy-area
medium-finish-output
medium-force-output
medium-line-style
medium-text-style

3.3.7 Port protocol

PORT (BRIDGE) TO GUI (A SERVER LIKE)
------------------------------------
;;; Originally in CLIM
destroy-port

;;; Originally in CLIM-INTERNALS
enable-mirror
disable-mirror
set-mirror-name
set-mirror-icon
set-mirror-geometry
port-force-output
set-sheet-pointer-cursor

3.3.8 Frame manager, panes and gadgets

FRAME MANAGER, PANES AND GADGETS
--------------------------------
;;; Originally in CLIM
;; in frame-manager.lisp
make-pane-1
note-space-requirements-changed
adopt-frame

;; in port.lisp or pane.lisp/gadget.lisp
allocate-space
destroy-mirror
handle-repaint
realize-mirror

3.3.9 Pointer protocol (events?)

POINTER (port.lisp or pointer.lisp)
-----------------------------------
;;; Originally in CLIM
pointer-button-state
pointer-position

3.3.10 Text size

TEXT SIZE (medium.lisp)
-----------------------
;;; Originally in CLIM-INTERNALS
text-style-character-width
;;; Originally in CLIM
text-size
text-style-ascent
text-style-descent
text-style-height
text-style-mapping
text-style-width

3.3.11 Additional output destinations

A backend implementation may register additional output destination types for the :output-destination keyword parameter accepted by some commands. Doing so allows the command to be invoked with *standard-output* bound to a stream provided by the backend that redirects the command’s output to a non-default destination such as a vector graphics or raster image file.

To support this protocol in a backend, three things are required:

1. A new output destination class (usually a subclass of clim-backend:output-destination or one of its subclasses).
2. A method on clim-backend:invoke-with-standard-output specialized to the new output destination class.
3. A call to clim-backend:register-output-destination-type in order to register the new output destination.

Generic Function: invoke-with-standard-output [clim-backend] continuation destination ¶

Call continuation (with no arguments) with *standard-output* rebound according to destination.

Function: register-output-destination-type [clim-backend] name class-name ¶

Register class-name as an additional output destination type under the name name. class-name must name a subclass of clim-backend:output-destination. A method on clim-backend:invoke-with-standard-output must be applicable to an instance of class-name.

3.3.12 Miscellaneous

MISC
----
;;; Originally in CLIM-EXTENSIONS
medium-miter-limit          ; determine a draw for miter < sina/2

3.3.13 Obsolete

NO LONGER NEEDED IN BACKEND
---------------------------
queue-callback                  ; moved to clim-core
medium-clipping-                ; moved to clim-basic

3.4.1 Postscript fonts

Font mapping is a cons, the car of which is the name of the font (FontName field in the AFM file), and the cdr is the size in points. Before establishing the mapping, an information about this font should be loaded with the function load-afm-file.

3.4.2 Additional functions

Package clim-postscript exports the following functions:

Function: load-afm-file afm-filename ¶

Loads a description of a font from the specified AFM file.

4.7.1 Page abstraction

Function: page-initial-position [clime] stream ¶

Function: page-final-position [clime] stream ¶

Both functions return two values, x and y coordinates of the respective position. Initial position is where the cursor is placed on a fresh page, and the final position is where the cursor is placed right before the page ends. Coordinates depend on current margins and text alignment.

Function: stream-page-region [clime] stream ¶

This function returns a region which corresponds to the stream page format. This region corresponds the stream margins.

Macro: with-temporary-margins [clime] (stream &key (move-cursor t) left right top bottom) &body body ¶

Execute body in a dynamic environment where stream’s margins are augmented with left, right, top and bottom. Not all margins have to be specified. If they are not current margin values are taken as defaults.

Each margin must be in one of following formats: (:relative space) or (:absolute space). space may be specified as for :x-spacing and :y-spacing for horizontal and vertical margins accordingly. If a margin is “absolute” then it corresponds to its exact placement in stream coordinates. “relative” margins are relative to the stream viewport region.

If the Boolean move-cursor is T then the cursor is left where it was placed after the last operation. Otherwise upon completion of body, the cursor position is restored to its previous value.

Programmers using clime:with-temporary-margins should begin body with a call to the function clim:stream-set-cursor-position which will set the cursor to clime:page-initial-position.

4.7.2 FILLING-OUTPUT extension

The macro clim:filling-output behaves the same as before with a few additions:

:after-line-break-subsequent is complementary to :after-line-break-initially, it decides whether :after-line-break is printed for lines after the first break. It defaults to T.

:after-line-break-composed decides whether after-line-break from the external filling-output should be called as well (defaults to T).

:after-line-break may be a string or a function accepting two arguments: a stream and a flag indicating whether it is a soft newline or not. The function will be executed conditionally depending on values of :after-line-break-initially and :after-line-break-subsequent flags.

The macro preserves a text-style, ink and indentation from state in which it was invoked. That means in particular that indenting-output may be called from inside filling-output and after-line-break will be printed without this indent.

4.10.1 Extended Text Styles

McCLIM extends the legal values for the family and face arguments to make-text-style to include strings (in additional to the portable keyword symbols), as permitted by the CLIM spec, section 11.1.

Each backend defines its own specific syntax for these family and face names.

The CLX backend maps the text style family to the X font’s foundry and family values, separated by a dash. The face is mapped to weight and slant in the same way. For example, the following form creates a text style for -misc-fixed-bold-r-*-*-18-*-*-*-*-*-*-*:

(make-text-style "misc-fixed" "bold-r" 18)

In the GTK backend, the text style family and face are used directly as the Pango font family and face name. Please refer to Pango documentation for details on the syntax of face names. Example:

(make-text-style "Bitstream Vera Sans" "Bold Oblique" 54)

4.10.2 Listing Fonts

McCLIM’s font listing functions allow applications to list all available fonts available on a port and create text style instances for them.

Example:

* (find "Bitstream Vera Sans Mono"
        (clim-extensions:port-all-font-families (clim:find-port))
        :key #'clim-extensions:font-family-name
        :test #'equal)
#<CLIM-GTKAIRO::PANGO-FONT-FAMILY Bitstream Vera Sans Mono>

* (clim-extensions:font-family-all-faces *)
(#<CLIM-GTKAIRO::PANGO-FONT-FACE Bitstream Vera Sans Mono, Bold>
 #<CLIM-GTKAIRO::PANGO-FONT-FACE Bitstream Vera Sans Mono, Bold Oblique>
 #<CLIM-GTKAIRO::PANGO-FONT-FACE Bitstream Vera Sans Mono, Oblique>
 #<CLIM-GTKAIRO::PANGO-FONT-FACE Bitstream Vera Sans Mono, Roman>)

* (clim-extensions:font-face-scalable-p (car *))
T

* (clim-extensions:font-face-text-style (car **) 50)
#<CLIM:STANDARD-TEXT-STYLE "Bitstream Vera Sans Mono" "Bold" 50>

Class: font-family [clim-extensions] ¶

Class precedence list: font-family, standard-object, slot-object, t

The protocol class for font families. Each backend defines a subclass of font-family and implements its accessors. Font family instances are never created by user code. Use port-all-font-families to list all instances available on a port.

Class: font-face [clim-extensions] ¶

Class precedence list: font-face, standard-object, slot-object, t

The protocol class for font faces Each backend defines a subclass of font-face and implements its accessors. Font face instances are never created by user code. Use font-family-all-faces to list all faces of a font family.

Generic Function: port-all-font-families [clim-extensions] port &key invalidate-cache &allow-other-keys ¶

Returns the list of all font-family instances known by PORT. With INVALIDATE-CACHE, cached font family information is discarded, if any.

Generic Function: font-family-name [clim-extensions] font-family ¶

Return the font family’s name. This name is meant for user display, and does not, at the time of this writing, necessarily the same string used as the text style family for this port.

Generic Function: font-family-port [clim-extensions] font-family ¶

Return the port this font family belongs to.

Generic Function: font-family-all-faces [clim-extensions] font-family ¶

Return the list of all font-face instances for this family.

Generic Function: font-face-name [clim-extensions] font-face ¶

Return the font face’s name. This name is meant for user display, and does not, at the time of this writing, necessarily the same string used as the text style face for this port.

Generic Function: font-face-family [clim-extensions] font-face ¶

Return the font family this face belongs to.

Generic Function: font-face-all-sizes [clim-extensions] font-face ¶

Return the list of all font sizes known to be valid for this font, if the font is restricted to particular sizes. For scalable fonts, arbitrary sizes will work, and this list represents only a subset of the valid sizes. See font-face-scalable-p.

Generic Function: font-face-text-style [clim-extensions] font-face &optional size ¶

Return an extended text style describing this font face in the specified size. If size is nil, the resulting text style does not specify a size.

4.12.1 Interactive backend as a medium

When the macro is used with an interactive backend then the default method opens a window stream with open-window-stream. options are as for this function except for that the :port keyword parameter is supplied by the default method.

The only valid value of destination in this default method is nil.

4.12.2 PostScript

This backend symbol designator is :ps.

Valid values of destination are:

• a string or a pathname denoting the file to create
• a character or a binary output stream the file contents will be written to

This backend accepts the following options:

• device-type
• orientation
• multi-page
• scale-to-fit
• header-comments

4.12.3 PDF

This backend symbol designator is :pdf.

Valid values of destination are:

• a string or a pathname denoting the file to create
• a binary output stream the file contents will be written to

This backends accepts the same set of options as the PostScript backend.

4.12.4 SVG

This backend symbol designator is :svg. To make this backend available load the system "mcclim-svg".

Valid values of destination are:

• a string or a pathname denoting the file to create
• an output stream the file contents will be written to

This backend accepts the following options:

• scale-to-fit - scale and move graphics so they fill whole viewport
• width - width in :units units, defaults to :compute
• height - height in :units units, defaults to :compute
• dpi - density used to calculate device units, defaults to 96
• units - graft units, defaults to :device
• orientation - graft orientation, defaults to :default
• preview - opens the file with xdg-open

4.12.5 RasterImage

This backend symbol designator is :raster.

Valid values of destination are:

• a string or a pathname
• a binary output stream
• a keyword :pattern

This backend accepts the following options:

• width - defaults to :compute
• height - defaults to :compute
• format - output format (unless implicit from the destination)
• target - when the destination is :pattern, then try to reuse the target
• recording-p - when true, then the second returned value is the history

format is a symbol that names the type of the image. Valid values are :png, :jpg, :jpeg, tiff, tif, gif, pbm, pgm, and ppm. Its default value is :png.

4.12.6 Adding new backends

Describe here howe to specialize invoke-with-output-to-drawing-stream.

5.1.1 Debugger usage

To get up and running quickly with Debugger:

1. With Quicklisp loaded, invoke in REPL:

   (ql:quickload 'clim-debugger)

2. Run simple test condition:

   (clim-debugger:with-debugger () (error "test"))

The debugger is inspired by SLIME’s debugger and uses Swank to gain portability across implementations. The application is still under development and some details may change in the future.

Clicking frame with the mouse pointer toggles the display of its details and selects it. Each locale value may be inspected by selection with mouse pointer. The selected frame is distinguished from others with red color. The Eval in frame command evaluates expression in the selected frame.

5.1.2 Keyboard shortcuts

Warning: these key accelerators may change in the future.

M-p

Mark previous frame active

M-n

Mark next frame active

m

Show more frames

e

Eval in active frame

TAB

Toggle active frame details

[0-9]

Invoke nth restart

q

Quit debugger

5.1.3 Debugger API

function: debugger [clim-debugger] condition me-or-my-encapsulation ¶

Starts debugger with condition. me-or-my-encapsulation should be supplied by the Lisp implementation allowing to encapsulate or supply different debugger for recursive debugger calls.

macro: with-debugger [clim-debugger] options &body body ¶

Executes the code in body invoking the CLIM debugger when an unhandled condition is signalled. The macro binds *debugger-hook* to #'debugger. Bindings are inherited by new threads. options are not used at the moment.

function: install-debugger [clim-debugger] ¶

Installs clim-debugger globally (no need to wrap body in with-debugger).

5.2.1 Usage

• Quick Start
• The Inspector Window
• Objects and Places
• Evaluating Forms
• Navigating
• Handling of Specific Object Types
• Updating the Inspected Object

Next: Objects and Places, Previous: Quick Start, Up: Usage   [Contents][Index]

5.2.1.2 The Inspector Window

After starting the inspector, a window similar to the one shown below should appear:

The central pane shows the tree of objects currently being inspected. In the above example, the root object is an instance of a class named FOO with three slots, A, B and C. Commands can be issued by clicking on objects in the central pane or by typing command names into the pane below it. The bottom pane shows available commands for the object under the mouse pointer and how to invoke them.

By default, Clouseau will display a CLIM interactor pane for typing named commands and printing command output. The keyboard shortcut C-i (control key and "i" key pressed at the same time) toggles visibility of the interactor pane.

---

Next: Evaluating Forms, Previous: The Inspector Window, Up: Usage   [Contents][Index]

5.2.1.3 Objects and Places

Within the currently displayed object tree, each visible object is either collapsed, meaning it is displayed compactly and objects contained in it are not displayed, or expanded, meaning that it is displayed in more detail and objects immediately contained in it are displayed (those objects are initially collapsed but may be expanded). The collapsed representation of an object may be something like #<STANDARD-CLASS SALAD-MIXIN>. To expand collapsed objects, left-click on them. Left-click on them again and they will go back to a collapsed form.

Note: When collapsing objects, make sure not to click on one of the object’s children since that expands the child instead of collapsing the object. The object that would be affected by a mouse click at the current pointer position is always indicated by surrounding it with a black rectangle that is updated as the pointer moves. In addition, the pointer-documentation pane at the bottom of the window always describes the available actions for the object currently under the pointer.

An expanded object is related to its children through “places”. For example, a standard object has a place for each of its slots and a child object for each of its bound slots. Other examples of places include:

• Elements of lists (including “key” and “value” places in association lists and property lists)
• Elements of arrays
• “Key” and “value” places in hash-tables
• Fill pointer and length of a vector

Places are generally visually represented as some kind of bullet or arrow symbol. Examples include: •, ⁃ and →. Immutable places (such as the length of a non-adjustable vector) are displayed in orange, mutable places (such as object slots, vector elements or the length of an adjustable array) are displayed in purple.

Places provide their own commands which are to some extent independent of the respective objects they contain. The applicable commands for a given place can be seen by right-clicking it. Some common place commands are:

Copy Place Value

This command copies the value of the place into another place. The source place must have a value (i.e. if it is a slot, it must be bound). The target place must be mutable and accept the type of object stored in the source place. This command can be invoked by clicking the source place and dragging it onto the target place.

Swap Place Values

This command swaps the values of two places. It is similar to Copy Place Value except that it requires the source place to be mutable as well. It can be invoked via drag-and-drop by holding down the control key.

Set Place

This command sets the value of a place to the result of evaluating a form. Only mutable places support this. The command can be invoked by holding down the meta key and left-clicking the place. It will ask for a form to evaluate, evaluate the specified form and attempt to set the place to the value produced by evaluating the form. See Evaluating Forms.

Remove Place Value

This command removes the value of a place. Not all mutable places support this. Here are some examples of places that do:

• If the place corresponds to a slot in a standard object or structure object, the slot is made unbound.
• If the slot corresponds to the symbol function of a symbol, the symbol function is removed.
• List, array and hash-table elements can be removed as well.

Set Place To True

Some places have specialized commands. For example, if the type of a place is known to be Boolean and the current value is false, this command sets the value of the place to t. Similarly, Set Place To False sets the value to nil.

Increment Place

If the value of a place is an integer x, this command replaces the value of the place with the integer x + 1. Similarly, Decrement Place replaces the value with x - 1. These commands will be particularly handy when it will become possible to bind them to mousewheel-up and mousewheel-down gestures.

---

(let* ((list  (list #C(1 0))) ; mutable object
       (frame (nth-value 1 (clouseau:inspect        ; make inspector, keep frame
                            list :new-process t)))) ; runs in its own thread
  ;; Now change the object by replacing the car of the cons cell, then
  ;; notify the inspector. Repeat 30 times a second.
  (loop :for i :from 0 :by 0.1
        :do (setf (first list) (complex (* 1 (cos i)) (* 1 (sin i))))
            (setf (clouseau:root-object frame :run-hook-p t) list)
            (sleep 1/30)))

5.2.2 Extending Clouseau

Sometimes Clouseau’s built-in inspection abilities aren’t enough, and you want to extend it to inspect one of your own classes in a special way. Clouseau supports this, and it’s fairly simple and straightforward.

• Running Example
• State and Style of Presented Objects
• Defining Inspection Methods for Objects

(cl:in-package #:clim-user)

(defclass sample ()
  ((%data :initarg :data
          :accessor data
          :type list
          :initform '()))
  (:documentation "A statistical sample"))

(defgeneric sample-size (sample)
  (:documentation "Return the size of a statistical sample"))

(defmethod sample-size ((sample sample))
  (length (data sample)))

(defmethod print-object ((object sample) stream)
  (print-unreadable-object (object stream :type t)
    (format stream "n=~D" (sample-size object))))

(defparameter *my-sample*
  (make-instance 'sample
                 :data '(12.8 3.7 14.9 15.2 13.66
                         8.97 9.81 7.0 23.092)))

(defgeneric sum (sample)
  (:documentation "The sum of all numbers in a statistical
sample"))

(defmethod sum ((sample sample))
  (reduce #'+ (data sample)))

(defgeneric mean (sample)
  (:documentation "The mean of the numbers in a statistical
sample"))

(defmethod mean ((sample sample))
  (/ (sum sample) (sample-size sample)))

(defgeneric standard-deviation (sample)
  (:documentation "Find the standard deviation of the numbers
in a sample. This measures how spread out they are."))

(defmethod standard-deviation ((sample sample))
  (let ((mean (mean sample)))
    (sqrt (/ (loop for x in (data sample)
                   sum (expt (- x mean) 2))
             (1- (sample-size sample))))))

Next: Defining Inspection Methods for Objects, Previous: Running Example, Up: Extending Clouseau   [Contents][Index]

5.2.2.2 State and Style of Presented Objects

Let us start by taking a closer look at how the inspector presents inspected objects. Each occurrence of an inspected object on the screen ⁴ has an associated state which in turn stores a presentation style for the object. The state and style control how an object is presented and which commands can be applied to it. Object states and thus styles for each occurrence of an object are independent from those associated with other occurrences of the same object.

The state characterizes the object and the class of the state can depend on the particular object. State classes are generally subclasses of clouseau:inspected-object. Objects are presented with clim:present using the name of the class of the state as the presentation type. The class of the state therefore determines which commands are applicable to a given object.

The style indicates how the object or certain parts of the object should currently be presented. The style is stored in the state and can be replaced with a different style via certain commands such as Expand and Collapse. Clouseau comes with a basic hierarchy of styles:

The figure below illustrates for a vector as an example of an inspected object which parts of the visible output are produced by the clouseau:inspect-object-using-state methods specialized to the respective style keywords. The colors of the borders correspond the colors in the previous figure.

---

Previous: State and Style of Presented Objects, Up: Extending Clouseau   [Contents][Index]

5.2.2.3 Defining Inspection Methods for Objects

We can define specialized inspection methods for our objects. To do this, we define methods on clouseau:inspect-object-using-state which expects the object, the associated state, the current style and a target stream as its arguments. To change how sample objects are presented in the :collapsed and :expanded styles, we could define methods which are specialized to those styles. However, because we defined print-object for the sample class to be as informative as we want the simple representation to be, we don’t need to define a clouseau:inspect-object-using-state method for the :collapsed style. We will, define methods for the :expanded-header and :expanded-body styles, though:

(defmethod clouseau:inspect-object-using-state
    ((object sample)
     (state  clouseau:inspected-instance)
     (style  (eql :expanded-header))
     (stream t))
  (format stream "SAMPLE n=~D" (sample-size object)))

(defmethod clouseau:inspect-object-using-state
    ((object sample)
     (state  clouseau:inspected-instance)
     (style  (eql :expanded-body))
     (stream t))
  (clouseau:formatting-place (object 'clouseau:reader-place 'mean
                              present-place present-object)
    (write-string "mean" stream) ; label
    (present-place stream)       ; place indicator for the "slot"
    (present-object stream))     ; the value of the "slot" is the object
  (fresh-line stream)
  (clouseau:formatting-place (object 'clouseau:reader-place 'standard-deviation
                              present-place present-object)
    (write-string "std. dev." stream) ; label
    (present-place stream)            ; place indicator for the "slot"
    (present-object stream)))         ; the value of the "slot" is the object

With the above methods in place, our object is presented like this for the :expanded style:

This is already pretty functional: our statistical summaries are presented as a label, an immutable place and a value. The places and values behave as expected with respect to presentation highlighting and available commands.

Presenting the place indicators using the usual style would make their nature more obvious. What we also want is something visually more closely adapted to our needs. It would be nice if we could just have a table of things like \overline {x} = 12.125776 and have them come out formatted nicely. Before we attempt mathematical symbols, let’s focus on getting the basic layout right. For this, we can use CLIM’s table formatting, Clouseau’s convenience function clouseau:format-place-row and the clouseau:reader-place place class:

(defmethod clouseau:inspect-object-using-state
    ((object sample)
     (state  clouseau:inspected-instance)
     (style  (eql :expanded-body))
     (stream t))
  (formatting-table (stream)
    (clouseau:format-place-row
     stream object 'clouseau:reader-place 'mean :label "mean")
    (clouseau:format-place-row
     stream object 'clouseau:reader-place 'standard-deviation
     :label "std. dev.")))

clouseau:format-place-row creates one instance of clouseau:reader-place for each of our statistical functions mean and standard-deviation. Each of these place instances together with the values returned by the respective function are then presented as a table row with three cells corresponding to the label, the place and the value.

This refinement gets us most of the way towards the goal:

Finally, for our amusement and further practice, we’ll try to get some mathematical symbols — in this case we’ll just need \overline {x}. We can get this by printing an italic x and drawing a line over it:

(defun xbar (stream)
  "Draw an x with a bar over it"
  (with-room-for-graphics (stream)
    (with-text-face (stream :italic)
      (princ #\x stream)
      (draw-line* stream 0 0 (text-size stream #\x) 0))))

(defmethod clouseau:inspect-object-using-state
    ((object sample)
     (state  clouseau:inspected-instance)
     (style  (eql :expanded-body))
     (stream t))
  (formatting-table (stream)
    (clouseau:format-place-row
     stream object 'clouseau:reader-place 'mean
     :label #'xbar)
    (clouseau:format-place-row
     stream object 'clouseau:reader-place 'standard-deviation
     :label #\S :label-style '(:text-face :italic))))

Finally, to illustrate the use of the :expanded-header style, suppose that we want the ‘n=9’ (or whatever the sample size n equals) part to have an italicized n: easily:

(defmethod clouseau:inspect-object-using-state
    ((object sample)
     (state  clouseau:inspected-instance)
     (style  (eql :expanded-header))
     (stream t))
  (clouseau::inspect-class-as-name (class-of object) stream)
  (write-char #\Space stream)
  (with-drawing-options (stream :text-family :serif :text-face :italic)
    (write-char #\n stream))
  (format stream "=~D" (sample-size object)))

Our final version looks like this:

For more examples of how to extend the inspector, you can look at the files in the Apps/Clouseau/src/objects/ directory.

---

5.2.3 API

The following symbols are exported from the clouseau package:

• Functions for Invoking Clouseau
• Functions for Extending Clouseau
• Other Functions
• Deprecated Functions

5.3.1 Usage

• Quick start
• Commands

5.3.2 The #! macro character

Although there are commands for running external programs, the #! macro character tries to provide a nicer interface. It allows you to run external programs as a lisp function call, and attempts to transform the arguments in some meaningful way. Several transformations are performed:

• Keywords are converted to options. Single character keywords are turned into an option with a single dash (e.g., :v becomes -v). Longer keywords become an option preceded by two dashes (e.g., :verbose becomes --verbose)
• Sequences are flattened into separate arguments
• Wild pathnames are expanded (currently subject to brokenness in the directory function of various CL environments)

My apologies to anyone doing something more useful with this macro character if I have clobbered your readtable.

5.3.3 Calling commands from lisp

Calling CLIM commands from Lisp is straightforward. By convention, the pretty names used at the interactor map to a function name which implements the command body by upcasing the name, replacing spaces with hyphens, and prepending COM- (e.g., Show Directory becomes COM-SHOW-DIRECTORY).

5.3.4 Command output destinations

McCLIM’s implementation of the clim:define-command macro accepts a :provide-output-destination-keyword keyword argument which allows redirecting the output of the command from *standard-output* to some other destination. The Listener code supplies this argument for many of the defined commands. As a result, many Listener commands can be invoked with the :output-destination keyword, for example

CLIM-USER> ,Show Class Superclasses (class) standard-class
  (keywords) :output-destination
  (output-destination) Postscript File
  (destination file) /tmp/output.ps

will redirect the command’s output to the file /tmp/output.ps.

5.3.5 Debugger integration

When a command executed in the Listener signals an error, the default behavior consists in invoking the McCLIM Debugger (see Debugger). This behavior can be controlled by supplying a Boolean value for the :debugger keyword argument when calling the clim-listener:run-listener function.