McCLIM User’s Manual ¶

1.2.1 A bit of terminology ¶

application frame

An application frame (simply a frame) pieces together the application state, its visual appearance and user interactions. A frame is an instance of the class defined with define-application-frame.

command table

A command table is an object that mediates between the frame and the user. They store commands, menus and presentation translators.

command

A command represents a user interaction that modifies the frame.

action

An action represents a user interaction that causes side-effects without progressing the command loop.

presentation

A presentation links screen output to objects.

pane

A pane is an interactive object that defines a visual appearance of the application. Available panes come in three types:

layout panes

Spatially organizes other panes.

gadgets

Reusable components for rudimentary interactions. Frequently used CLIM gadgets are push-buttons, sliders, etc.

CLIM stream panes

Extensible components for presenting application specific information, like application-pane and interactor-pane.

output history

An output history is a display list that captures the output displayed to CLIM stream pane.

input context

An input context is a dynamic state denoting the set of presentation types that are currently relevant pending operations and associated handlers.

In other words it defines what kinds of objects the system is currently expecting the user to interact with.

gesture

A gesture is a named set of events recognized by CLIM. Most notably the gesture :select means pressing the left pointer button and the gesture :menu means pressing the right button.

1.2.2 Conceptual model ¶

Three central ideas in CLIM are that a frame holds the application state, presentations link screen output to objects and commands modify the state.

A default interaction model works in a read-execute-display-loop where CLIM reads a command from the user, executes it to update the application state and redisplays panes.

While reading the command the user interacts with the application to supply the command itself, or to cause side effects.

Commands participate in the command loop and trigger redisplay; actions are for immediate side effects that do not.

1.2.3 The first application ¶

Here is a structural overview of the application; real definitions are provided in subsequent sections and are concluded with a full listing.

(defpackage "FIRST-APP"
  ;; Imports symbols from McCLIM.
  (:use "CLIM-LISP" "CLIM" "CLIM-EXTENSIONS")
  ;; The package will only export the frame name.
  (:export "STUDY"))
(in-package "FIRST-APP")

(define-application-frame study ()
  ((shelf :initarg :shelf :accessor shelf)
   (book :initform nil :accessor book))
  (:panes ...)
  (:layouts ...))

(defclass book ()
  ((title :initarg :title :reader title)
   (author :initarg :author :reader author)))

(define-presentation-method present ...)
(define-presentation-method accept ...)

(define-study-command (com-read-book :name t) ...)
(define-study-command (com-stop-reading-book :name t) ...)

(define-presentation-to-command-translator act-take-book ...)
(define-presentation-to-command-translator act-drop-book ...)
(define-presentation-action act-copy-book ...)

(defun display-study (frame stream) ...)

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

Figure 1.2: Screenshot of the first application.

1.2.4 Package definition ¶

(defpackage "FIRST-APP"
  ;; Imports symbols from McCLIM.
  (:use "CLIM-LISP" "CLIM" "CLIM-EXTENSIONS")
  ;; The package will only export the frame name.
  (:export "STUDY"))
(in-package "FIRST-APP")

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

The package for the application uses three packages: CLIM-LISP, CLIM and CLIM-EXTENSIONS. 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, the CLIM package is the one that contains all the symbols needed for using CLIM, and the package CLIM-EXTENSIONS contains all the symbols defined for McCLIM extensions.

In our example, we export the symbol that corresponds to the frame class that may be used to start our application using functions run-frame-top-level and find-application-frame.

1.2.5 Application frame ¶

;;; This macro is like DEFCLASS with additional options.
(define-application-frame study ()
  ((shelf :initarg :shelf :accessor shelf)
   (book :initform nil :accessor book))
  ;; :PANES option specifies named sub-windows, their types and initargs.
  (:panes
   (app :application :display-function 'display-study :width 1280)
   (int :interactor))
  ;; :LAYOUTS option arranges panes in a hierarchy.
  (:layouts
   (default (vertically () app int))
   (onlyapp app)))

Each CLIM application is represented by an application frame. As a CLIM user, you typically define a class that contains slots with the application specific data. It is considered good style to not store the state outside of the frame (i.e in global variables).

The macro define-application-frame defines a new frame class. It works similar to defclass, but also allows you to specify additional options, like panes and layouts.

In our example, we have defined an application frame called study, which becomes a CLOS class that automatically inherits from standard CLIM application frame class. It contains slots storing the shelf and the current book (if any).

The :panes option allows us to define named panes. Each pane is defined by a list where the first element is the pane’s name and remaining elements denote its type and initialization arguments.

In our case we define two named panes:

app

The application pane that displays the current application state by calling a function display-study.

int

The interactor pane that reads commands from the user. It works like a command line in the terminal.

The :layouts option allows us to specify how panes are arranged in the frame. Each layout is defined by a list where the first element is the layout’s name and the second form evaluates to a pane. Macros like vertically or tabling create a pane that composes other panes.

In our case we define two layouts:

default

This layout arranges panes one below another – the application pane at the top, and the interactor pane at the bottom. It is useful for power users who want to have access to the command line.

onlyapp

This layout uses only the application pane. It presents an uncluttered interface without the command line. It makes a useful default for non-technical users.

1.2.6 Presentation type ¶

;;; Standard classes are implicit presentation types, that is there is
;;; no need to separately call DEFINE-PRESENTATION-TYPE for them.
;;; (defclass book () ((title :initarg :title :reader title) (author
;;; :initarg :author :reader author)))

;;; The presentation method PRESENT defines how we should display the
object.  (define-presentation-method present ((book book) (type book)
stream view &key acceptably for-context-type) (declare (ignore
acceptably for-context-type)) (with-text-face (stream :bold) (princ
(title book) stream)) (princ " by " stream) (with-text-face (stream
:italic) (princ (author book) stream)))

(define-presentation-method accept ((type book) stream view &key default
    default-type) (declare (ignore default default-type))
    (with-application-frame (frame) (completing-from-suggestions
    (stream) (dolist (book (shelf frame)) (suggest (format nil "~a by
    ~a" (title book) (author book)) book)))))

Presentation types may be abstract, or they may be associated with the standard-class. standard-class instances are implicitly treated as unparametrized presentation types associated with that class.

We define only one presentation type book. It stores the information about the book title and its author.

The presentation method present draws the object on the screen. Objects presented with the function present are recognized by CLIM when their presentation type matches the input context.

The presentation method accept is responsible for parsing input into the object of the requested presentation type. Standard classes don’t have default readable representation, so we need to specialize the parser to allow typing a book from keyboard (and to enable completions).

CLIM operates on CLIM stream panes. That means in particular, that we can mix standard Common Lisp and CLIM-specific operators. In this case we add the additional style to the book’s title and author in present and add the autocompleter for reading books in accept.

1.2.7 Defining commands ¶

;;; DEFINE-STUDY-COMMAND is a macro defined by
;;; DEFINE-APPLICATION-FRAME. It adds a new command to the command table
;;; associated with the frame.  (define-study-command (com-read-book
;;; :name t) ((book 'book)) (with-application-frame (frame) (when (book
;;; frame) (com-stop-reading-book)) (setf (shelf frame) (remove book
;;; (shelf frame))) (setf (book frame) book)))

(define-study-command (com-stop-reading-book :name t) ()
    (with-application-frame (frame) (let ((book (book frame))) (when
    book (push (book frame) (shelf frame)) (setf (book frame) nil)))))

Code that modifies the application state should be put in commands. This ensures that CLIM redisplays the frame in a coordinated manner.

When we’ve defined the application frame, we’ve also created a corresponding command table with the same name, and a macro define-study-command. This macro defines a new command and adds it to the command table study.

In our application we define two commands: one to pick up the book, and another to return it on the shelf. To access the frame we use the macro with-application-frame that binds a variable to the current frame.

Notice that commands, in order to be available from the interactor, must have an option of :name t. The reason is that some commands will be available only from menus or by some other mechanism. To put the command in the menu, you may add another option :menu t.

Command arguments are specified as the command name, its presentation type (evaluated) and some other options that we don’t use here. When CLIM reads the command argument, its presentation type becomes part of the input context, so it is possible to either type it with keyboard (when the interactor is present), or click objects presented on the screen with the pointer.

Command: Read Book flatland Command: Stop Reading Book

Notice that after we type in the interactor Read Book , we can use tab to autocomplete words from the suggestions provided by our presentation method accept.

1.2.8 Presentation translators ¶

(define-presentation-to-command-translator act-take-book (book
    com-read-book study :gesture :select :tester ((object frame) (and
    (null (book frame)) (member object (shelf frame))))) (object)
    `(,object))

(define-presentation-to-command-translator act-drop-book (book
    com-stop-reading-book study :gesture :select :tester ((object frame)
    (eql object (book frame)))) (object) `())

(define-presentation-action act-copy-book (book nil study :gesture nil)
    (object window) (publish-selection window :clipboard
    (present-to-string object 'book) 'string))

Besides using the application by typing commands in the interactor, it is possible to define interactions directly using objects presented on the screen, by using menu and by using keyboard accelerators.

Presentation translators can be used to implement interactions that work on objects presented on the screen.

When the user moves the pointer above a presentation, CLIM looks for applicable translators from its presentation type to presentation types in the current input context. If such translators exist, it highlights the presentation type.

Presentation translator may be activated by either making a gesture that is specified for it, or by selecting it from a presentation menu opened by clicking on the presentation with the right pointer button.

Presentation to command translators are defined with the operator define-presentation-to-command-translator. As the name suggests, they are used to translate presentations to commands.

The name is used to identify the translator. The required arguments in the first lambda list denote the presentation type to match with the presentation, the command name of the command that will be returned by the translator, and the command table that the translator belongs to. Then we have the activation gesture and the tester. The tester may be used to further narrow the translator applicability based on the object.

Presentation to action translators are defined with the operator define-presentation-action. Actions, unlike commands, do not progress the command loop and do not implicitly cause the redisplay of the frame. They are defined for side effects that may happen while we wait for a command, i.e to send notifications.

The name is used to identify the translator. The required arguments in the first lambda list denote the presentation type to match with the presentation, the presentation type to matching with the input context, and the command table that the translator belongs to. Then we have the activation gesture and the tester. The tester may be used to further narrow the translator applicability based on the object.

We define two translators to commands that are used to implement the style where it is enough to click on a book on the shelf to read it (unless the desk is already occupied), and by clicking on a book on the desk that book is returned to the shelf.

The presentation action is used to copy the book title and author to the clipboard. It is available from the menu that opens when we right-click on the presentation. Note that the target presentation is nil, this is because nil is an universal subtype, so the action will be applicable disregarding of the current input context. :gesture nil means, that the action is only available from the presentation menu, not via a direct pointer gesturs.

1.2.9 Display function ¶

;;; The display function for the "app" pane.  (defun display-study
(frame stream) (format stream "Books on the shelf:~%") (indenting-output
(stream 15) (dolist (book (shelf frame)) (present book 'book :stream
stream :single-box t) (terpri stream)))
(stream-increment-cursor-position stream 0 20) (let ((book (book
frame))) (if (null book) (format stream "Not reading anything.")  (progn
(format stream "Currently reading ") (present (book frame) 'book :stream
stream :single-box t) (format stream ".")))))

application panes are streams that are typically used to display application specific data. These streams can be used in ordinary input and output operators, such as format and read, and in CLIM specific operators, such as present, accept and draw-line.

A display function is called with the frame and the pane as arguments. In our example we first present all available books, and then display what is currently being read. Note that books are presented with the function present to create a link between graphical output and the underlying object.

We use an option :single-box to draw a rectangle when the presentation is highlighted – otherwise borders would be drawn around each individual object that is part of the presentation.

1.2.10 Running the application ¶

(defpackage "FIRST-APP"
  ;; Imports symbols from McCLIM.
  (:use "CLIM-LISP" "CLIM" "CLIM-EXTENSIONS")
  ;; The package will only export the frame name.
  (:export "STUDY"))
(in-package "FIRST-APP")

;;; This macro is like DEFCLASS with additional options.
(define-application-frame study ()
  ((shelf :initarg :shelf :accessor shelf)
   (book :initform nil :accessor book))
  ;; :PANES option specifies named sub-windows, their types and initargs.
  (:panes
   (app :application :display-function 'display-study :width 1280)
   (int :interactor))
  ;; :LAYOUTS option arranges panes in a hierarchy.
  (:layouts
   (default (vertically () app int))
   (onlyapp app)))

;;; Standard classes are implicit presentation types, that is there is no need
;;; to separately call DEFINE-PRESENTATION-TYPE for them.
(defclass book ()
  ((title :initarg :title :reader title)
   (author :initarg :author :reader author)))

;;; The presentation method PRESENT defines how we should display the object.
(define-presentation-method present
    ((book book) (type book) stream view &key acceptably for-context-type)
  (declare (ignore acceptably for-context-type))
  (with-text-face (stream :bold)
    (princ (title book) stream))
  (princ " by " stream)
  (with-text-face (stream :italic)
    (princ (author book) stream)))

(define-presentation-method accept
    ((type book) stream view &key default default-type)
  (declare (ignore default default-type))
  (with-application-frame (frame)
    (completing-from-suggestions (stream)
      (dolist (book (shelf frame))
        (suggest (format nil "~a by ~a" (title book) (author book)) book)))))


;;; DEFINE-STUDY-COMMAND is a macro defined by DEFINE-APPLICATION-FRAME. It adds
;;; a new command to the command table associated with the frame.
(define-study-command (com-read-book :name t)
    ((book 'book))
  (with-application-frame (frame)
    (when (book frame)
      (com-stop-reading-book))
    (setf (shelf frame) (remove book (shelf frame)))
    (setf (book frame) book)))

(define-study-command (com-stop-reading-book :name t)
    ()
  (with-application-frame (frame)
    (let ((book (book frame)))
      (when book
        (push (book frame) (shelf frame))
        (setf (book frame) nil)))))

(define-presentation-to-command-translator act-take-book
    (book com-read-book study
     :gesture :select
     :tester ((object frame)
              (and (null (book frame))
                   (member object (shelf frame)))))
    (object)
  `(,object))

(define-presentation-to-command-translator act-drop-book
    (book com-stop-reading-book study
     :gesture :select
     :tester ((object frame)
              (eql object (book frame))))
    (object)
  `())

(define-presentation-action act-copy-book
    (book nil study :gesture nil)
    (object window)
  (publish-selection window :clipboard (present-to-string object 'book) 'string))

;;; The display function for the "app" pane.
(defun display-study (frame stream)
  (format stream "Books on the shelf:~%")
  (indenting-output (stream 15)
    (dolist (book (shelf frame))
      (present book 'book :stream stream :single-box t)
      (terpri stream)))
  (stream-increment-cursor-position stream 0 20)
  (let ((book (book frame)))
    (if (null book)
        (format stream "Not reading anything.")
        (progn
          (format stream "Currently reading ")
          (present (book frame) 'book :stream stream :single-box t)
          (format stream ".")))))

Above is a complete program listing. In mere 100 lines of code we’ve implemented an application that defines various user interactions and displays formatted output.

(defun make-test-shelf ()
  (flet ((make-book (title author)
           (make-instance 'book :title title :author author)))
    (list (make-book "Flatland: A Romance of Many Dimensions" "Edwin Abbott Abbott")
          (make-book "The Lord of the Rings" "J. R. R. Tolkien")
          (make-book "Moomins" "Tove Jansson")
          (make-book "The Little Prince" "Antoine de Saint-Exupery"))))

;;; FIND-APPLICATION-FRAME ensures that a frame of the specified type exists,
;;; and if it doesn't it creates a new one.
(find-application-frame 'study :shelf (make-test-shelf) :current-layout 'onlyapp)

;;; RUN-FRAME-TOP-LEVEL is used to start an application that has been already
;;; created. The frame state persists after closing so it can be opened again.
(defvar *app*
  (make-application-frame 'study :shelf (make-test-shelf) :current-layout 'onlyapp))
(run-frame-top-level *app*)

To run an application we can use find-application-frame. It ensures that a frame instance of the specified class is running, and if not it starts a new one (when possible - in a separate process). Additional arguments are passed as initargs to the frame.

Alternatively use run-frame-top-level to start a frame that already exists. This is useful when we care about the frame state. The function runs synchronously, so if we want to run it in a separate thread then we need to create it manually.

The initarg :current-layout allows the user to specify the initial layout. It is possible to change it at runtime by calling the function (setf frame-current-layout).

1.2.11 Event flow of interactions ¶

We’ve mentioned that CLIM operates inside the command loop and that while a command is being read, auxilliary interactions are possible. This is possible, because a command loop runs inside an event loop that is part of the underlying implementation.

Presentation translators are the primary example where CLIM runs user-defined code in response to an event. So what happens when you click a presentation?

The frame button press handler visits presentations below the pointer and tries to find the innermost applicable presentation. Applicability is decided by testing translators available in the command table:

• presentation type must be a subtype of translator source type
• input context must be a supertype of translator target type
• the event must match the specified translator gesture name
• the presentation translator tester returns true for presentation

If more than one presentation translator matches the same innermost presentation, then ties are resolved using the translator with the highest priority which may be specified when defining a translator. When there is no winner, then one of translators is chosen.

When the presentation translator is chosen, it is called to translate the presentation to the input context type, and the program control is transferred to the handler. Internally the input context will be established with a macro with-input-context. For example:

(with-input-context (`(command :command-table ,command-table))
    (object)
    (simple-event-loop frame)
  (t (throw :command object)))

the command processor will then execute the command and redisplay the frame and start the next command loop iteration.

It may happen, that the presentation translator will return nil instead of the new presentation, or signal a serious-condition. In that case, despite of evaluating the translator body, then input handler is not invoked. That’s how presentation actions are implemented.

1.2.12 Exercises ¶

• add the rating system

  Add a new slots to the book called “rate” and define a command com-rate-book that accepts one argument of type integer.

• implement sorting books on the shelf

  Define a command com-sort-shelf that accepts an argument of type '(completion (:author :title :rating :unsorted)).

• books taken from the shelf should still be visible

  After taking the book from the shelf keep the reference to it on the shelf, that is present the book but make it unavailable. The function present accepts a keyword argument :sensitive, use it to disable translators for the object.

  To show that the book is not available, wrap a call to present in surrounding-output-with-border (stream :shape :crossout).

• add to the menu a command com-switch-layout

  This command should alternate between default and onlyapp layouts and should be available in the menu. The command should not be available in the command line.

1.3.1 Displaying 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.3.2 Using incremental redisplay ¶

While the example in the previous section is a very simple way of structuring an application (let commands arbitrarily modify the data structure, and simply erase the pane and redisplay the structure after each iteration of the command loop), the visual result is not so great when many objects are to be displayed. There is most often a noticeable flicker between the moment when the pane is cleared and the objects are drawn. Sometimes this is inevitable (as when nearly all objects change), but most of the time, only an incremental modification has been made, and most of the objects are still in the same place as before.

In simple toolkits, the application programmer would have to figure out what has changed since the previous display, and only display the differences. CLIM offers a mechanism called incremental redisplay that automates a large part of this task. As we mentioned earlier, CLIM captures output in the form of output records. The same mechanism is used to obtain incremental redisplay.

To use incremental redisplay, client code remains structured in the simple way that was mention above: after each iteration of the command loop, the display function output the entire data structure as usual, except that it helps the incremental redisplay mechanism by telling CLIM which piece of output corresponds to which piece of output during the previous iteration of the command loop. It does this by giving some kind of unique identity to some piece of output, and some means of indicating whether the contents of this output is the same as it was last time. With this information, the CLIM incremental redisplay mechanism can figure out whether some output is new, has disappeared, or has been moved, compared to the previous iteration of the command loop. As with re-exposure, CLIM guarantees that the result is identical to that which would have been obtained, had all the output records been output in order to a blank pane.

The next example illustrates this idea. It is a simple application that displays a fixed number (here 20) of lines, each line being a number. Here is the code:

(in-package :common-lisp-user)

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

(in-package :app)

(define-application-frame superapp ()
  ((numbers :initform (loop repeat 20 collect (list (random 100000000)))
            :accessor numbers)
   (cursor :initform 0 :accessor cursor))
  (:pointer-documentation t)
  (:panes
    (app :application
         :height 400 :width 600
         :incremental-redisplay t
         :display-function 'display-app)
    (int :interactor :height 200 :width 600))
  (:layouts
    (default (vertically () app int))))

;; As usual, the displaying code relates to a pane, not the application frame.
(defun display-app (frame pane)

  (loop
     ;; Taking items one-by-one from the frame slot 'numbers'...
     for current-element in (numbers frame)

     ;; ...and increasing line-by-line...
     for line from 0

     ;; ...print a star if the cursor is on that line...
     ;; (Note that here, there is no incremental redisplay. The output
     ;; record of the star will be printed at each call of the display
     ;; function, i.e. at each iteration of the command loop.)
     do (princ (if (= (cursor frame) line) "*" " ") pane)

     ;; ...and incrementally update the rendering instructions of the
     ;; number on that line.
     ;; (Note that 'numbers' was defined as a list of lists, each
     ;; sublist holding an individual number. The reason for that is
     ;; explained below, but this is why (car current-element) is
     ;; needed.)
     do (updating-output (pane :unique-id   current-element
                               :id-test     #'eq
                               :cache-value (car current-element)
                               :cache-test  #'eql)
          (format pane "~a~%" (car current-element)))))


;;
;; Command definitions
;;

;; Increase the value of the number on the current line.
(define-superapp-command (com-add :name t) ((number 'integer))
  (incf (car (elt (numbers *application-frame*)
                  (cursor *application-frame*)))
        number))

;; Move the cursor one line down (increasing the cursor position),
;; looping back to the beginning if going too far.
(define-superapp-command (com-next :name t) ()
  (incf (cursor *application-frame*))
  (when (= (cursor *application-frame*)
           (length (numbers *application-frame*)))
    (setf (cursor *application-frame*) 0)))

;; Move the cursor one line up
(define-superapp-command (com-previous :name t) ()
  (decf (cursor *application-frame*))
  (when (minusp (cursor *application-frame*))
    (setf (cursor *application-frame*)
          (1- (length (numbers *application-frame*))))))

;; Command to quit the app
(define-superapp-command (com-quit :name t) ()
  (frame-exit *application-frame*))


;; Exported function to launch an instance of the application frame
(defun app-main ()
  (run-frame-top-level (make-application-frame 'superapp)))

We store the numbers in a slot called numbers of the application frame. However, we store each number in its own list. This is a simple way to provide a unique identity for each number. We could not use the number itself, because two numbers could be the same and the identities would not be unique. Instead, we use the cons cell that store the number as the unique identity. By using :id-test #'eq we inform CLIM that it can figure out whether an output record is the same as one that was issued previous time by using the function eq to compare them. But there is a second test that has to be verified, namely whether an output record that was issued last time has to be redisplayed or not. That is the purpose of the cache-value. Here we use the number itself as the cache value and eql as the test to determine whether the output is going to be the same as last time.

For convenience, we display a * at the beginning of the current line, and we provide two commands next and previous to navigate between the lines.

Notice that in the declaration of the pane in the application frame, we have given the option :incremental-redisplay t. This informs CLIM not to clear the pane after each command-loop iteration, but to keep the output records around and compare them to the new ones that are produced during the new iteration.

1.3.3 Using presentation types ¶

• What is a presentation type
• A simple 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))

1.3.4 Using views ¶

The CLIM specification mentions a concept called a view, and also lists a number of predefined views to be used in various different contexts.

In this chapter we show how the view concept can be used in some concrete programming examples. In particular, we show how to use a single pane to show different views of the application data structure at different times. To switch between the different views, we supply a set of commands that alter the stream-default-view feature of all CLIM extended output streams.

The example shown here has been stripped to a bare minimum in order to illustrate the important concepts. A more complete version can be found in Examples/views.lisp in the McCLIM source tree.

Here is the example:

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

;;; part of application "business logic"
(defclass person ()
  ((%last-name :initarg :last-name :accessor last-name)
   (%first-name :initarg :first-name :accessor first-name)
   (%address :initarg :address :accessor address)
   (%membership-number :initarg :membership-number :reader membership-number)))

;;; constructor for the PERSON class.  Not strictly necessary.
(defun make-person (last-name first-name address membership-number)
  (make-instance 'person
                 :last-name last-name
                 :first-name first-name
                 :address address
                 :membership-number membership-number))

;;; initial list of members of the organization we imagine for this example
(defparameter *members*
  (list (make-person "Doe" "Jane" "123, Glencoe Terrace" 12345)
        (make-person "Dupont" "Jean" "111, Rue de la Republique" 54321)
        (make-person "Smith" "Eliza" "22, Trafalgar Square" 121212)
        (make-person "Nilsson" "Sven" "Uppsalagatan 33" 98765)))

;;; the CLIM view class that corresponds to a list of members, one member
;;; per line of text in a CLIM application pane.
(defclass members-view (view) ())

;;; since this view does not take any parameters in our simple example,
;;; we need only a single instance of it.
(defparameter *members-view* (make-instance 'members-view))

;;; the application frame.  It contains instance-specific data
;;; such as the members of our organization.
(define-application-frame views ()
  ((%members :initform *members* :accessor members))
  (:panes
   (main-pane :application :height 500 :width 500
              :display-function 'display-main-pane
              ;; notice the initialization of the default view of
              ;; the application pane.
              :default-view *members-view*)
   (interactor :interactor :height 100 :width 500))
  (:layouts
   (default (vertically ()
              main-pane
              interactor))))

;;; the trick here is to define a generic display function
;;; that is called on the frame, the pane AND the view,
;;; whereas the standard CLIM display functions are called
;;; only on the frame and the pane.
(defgeneric display-pane-with-view (frame pane view))

;;; this is the display function that is called in each iteration
;;; of the CLIM command loop.  We simply call our own, more elaborate
;;; display function with the default view of the pane.
(defun display-main-pane (frame pane)
  (display-pane-with-view frame pane (stream-default-view pane)))

;;; now we can start writing methods on our own display function
;;; for different views.  This one displays the data each member
;;; on a line of its own.
(defmethod display-pane-with-view (frame pane (view members-view))
  (loop for member in (members frame)
        do (with-output-as-presentation
               (pane member 'person)
             (format pane "~a, ~a, ~a, ~a~%"
                     (membership-number member)
                     (last-name member)
                     (first-name member)
                     (address member)))))

;;; this CLIM view is used to display the information about
;;; a single person.  It has a slot that indicates what person
;;; we want to view.
(defclass person-view (view)
  ((%person :initarg :person :reader person)))

;;; this method on our own display function shows the detailed
;;; information of a single member.
(defmethod display-pane-with-view (frame pane (view person-view))
  (let ((person (person view)))
    (format pane "Last name: ~a~%First Name: ~a~%Address: ~a~%Membership Number: ~a~%"
            (last-name person)
            (first-name person)
            (address person)
            (membership-number person))))

;;; entry point to start our applciation
(defun views-example ()
  (run-frame-top-level (make-application-frame 'views)))

;;; command to quit the application
(define-views-command (com-quit :name t) ()
  (frame-exit *application-frame*))

;;; command to switch the default view of the application pane
;;; (which is the value of *standard-output*) to the one that
;;; shows a member per line.
(define-views-command (com-show-all :name t) ()
  (setf (stream-default-view *standard-output*) *members-view*))

;;; command to switch to a view that displays a single member.
;;; this command takes as an argument the person to display.
;;; In this application, the only way to satisfy the demand for
;;; the argument is to click on a line of the members view.  In
;;; more elaborate application, you might be able to type a
;;; textual representation (using completion) of the person.
(define-views-command (com-show-person :name t) ((person 'person))
  (setf (stream-default-view *standard-output*)
        (make-instance 'person-view :person person)))

The example shows a stripped-down example of a simple database of members of some organization.

The main trick used in this example is the display-main-pane function that is declared to be the display function of the main pane in the application frame. The display-main-pane function trampolines to a generic function called display-pane-with-view, and which takes an additional argument compared to the display functions of CLIM panes. This additional argument is of type view which allows us to dispatch not only on the type of frame and the type of pane, but also on the type of the current default view. In this example the view argument is simply taken from the default view of the pane.

A possibility that is not obvious from reading the CLIM specification is to have views that contain additional slots. Our example defines two subclasses of the CLIM view class, namely members-view and person-view.

The first one of these does not contain any additional slots, and is used when a global view of the members of our organization is wanted. Since no instance-specific data is required in this view, we follow the idea of the examples of the CLIM specification to instantiate a singleton of this class and store that singleton in the stream-default-view of our main pane whenever a global view of our organization is required.

The person-view class, on the other hand, is used when we want a closer view of a single member of the organization. This class therefore contains an additional slot which holds the particular person instance we are interested in. The method on display-pane-with-view that specializes on person-view displays the data of the particular person that is contained in the view.

To switch between the views, we provide two commands. The command com-show-all simply changes the default view of the main pane to be the singleton instance of the members-view class. The command com-show-person is more complicated. It takes an argument of type person, creates an instance of the person-view class initialized with the person that was passed as an argument, and stores the instance as the default view of the main pane.

1.3.5 Using command tables ¶

A command table is an object that is used to determine what commands are available in a particular context and the ways in which commands can be executed.

Simple applications do not manage command tables explicitly. A default command table is created as a result of a call to the macro define-application-frame and that command table has the same name as the application frame.

Each command table has a name and that CLIM manages a global namespace for command tables.

Function: find-command-table [clim] name &key (errorp t) ¶

This function returns the command table with the name name. If there is no command table with that name, then what happens depends on the value of errorp. If errorp is true, then an error of type command-table-not-found is signaled. If errorp is false, otherwise nil is returned.

1.3.6 Using menu bar ¶

Menu bar has become essential part of every GUI system, including McCLIM. Ideally, McCLIM should try to use the menu bar provided by host window system via McCLIM backends, but the current clx-backend doesn’t supports native menu bars. That’s why it has some quirks of its own, like you need to keep mouse button pressed while accessing the sub-menus.

• Creating Menu bar
• Modifying Menu bar

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

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

2.2.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.2.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.3.1 Computing the native transformation ¶

2.3.2 Computing the native region ¶

2.3.3 Moving and resizing sheets and regions ¶

2.3.4 Scrolling ¶

2.4.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.4.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.5.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.5.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.5.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.5.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.6.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.6.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.9.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.9.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.11.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.11.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.11.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.11.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.11.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.11.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.