The Dormouse Library

cl-dormouse is a windowing 'graphical' user interface library, built on top of the Doryen Library (libtcod).

What is the Doryen Library?

The Doryen Library, or libtcod, is a library that implements a truecolour console. It can be thought of as a souped-up alternative to Curses. The console can be of any size that fits on the screen. Both keyboard and mouse events are handled. There is support for arbitrarily large character sets, and font antialiasing. BMP and PNG images can be displayed alongside text.

While libtcod is well-suited for any application where a console-based interface is desired, the main purpose of the library is to support the development of roguelike games. As such, libtcod also provides line-of-sight calculations, pathfinding, perlin noise, height maps, binary space partitioning (BSP), parsing of configuration files, and other features useful to game developers.

Libtcod is written in C and C++. Bindings for libtcod are currently available for several programming languages including Python, Lua, C#, D, and Common Lisp.

What is cl-dormouse?

cl-dormouse is a windowing "graphical" user interface built on top of libtcod. The programmer creates Window objects which are displayed on the root console. The mouse can be used to move, resize, and close windows. Keyboard and mouse events are sent to whichever window object has the focus.


  • Full mouse support, including drag and drop events from one window to another, and moving and resizing windows with the mouse.
  • True colour support: Each window's foreground, background, and text can be displayed in any 32-bit colour.
  • Simple inline formatting of strings: Text strings can contain formatting directives, similar to HTML, which can:

  • instruct the library about the colours in which parts of the string should be displayed;

  • compose accented characters;
  • define 'live' areas of the string which generate special events when clicked with the mouse (acting like dialog buttons).

  • Specialised window types: there are many subclasses of the base 'Window' class with specialised behaviour, including:

  • Viewports: windows which provide a view onto an underlying map (array), which may be much larger. Dragging with the mouse moves the viewport around the map. Intended for the main display area in roguelike games.

  • List windows: browse and select from a list of values. Items can have 'hotkeys' defined for quick selection.
  • Filtered windows: list windows that allow the user to type a 'filter string', only displaying items which contain the string.
  • Menu windows: simplified list window where a single mouse click selects and closes the window.
  • Log windows: a scrolling 'buffer' of text, with new messages added at the bottom.
  • Modal windows: prevent access to other windows, forcing the user to respond to a message or dialog.
  • Ghost windows: cannot be interacted with, useful for simply displaying some information in an area of the screen.
  • Dialog windows: present strings containing 'dialog buttons' to the user.
  • Tooltip windows: display a message when the mouse hovers over items within the window.
  • Context windows: window in which right-clicking on an item brings up a list of commands which can be applied to the item, where the commands presented will vary according to the characteristics of the right-clicked item.
  • And any combination of the above, using multiple inheritance...
  • Window dependencies: Windows can be created as 'children' of other windows, allowing hiding, showing, creation and destruction of a complex group of windows as a unit.

The latest version of cl-dormouse can be found at http://bitbucket.org/eeeickythump/cl-dormouse/.



  • Install all dependencies (see above).
  • Download cl-dormouse from its repository.
  • Run your lisp and make sure you can load ASDF, and ASDF can load cl-tcod and cl-dormouse.

Getting started

The following is a minimal 'hello world' application: Save it in a file, load it, and run (mypkg:my-test) at the lisp prompt to try it.

    (in-package :cl-user)
    (defpackage :mypkg
    (:use :cl :tcod :dormouse)
    (:export #:my-test))

    (in-package :mypkg)

    (defun my-test ()
      (let ((msgwin nil))
        (dormouse:start-gui :title "Testing")
        (setf msgwin
          (make-instance '<Log-Window> :tlx 30 :tly 10 :width 20 :height 6
                    :title "log" :foreground :cornsilk
                    :background :dark-blue))
          (add-message msgwin "Press control-F1 or control-Esc to quit")


The files gui-demo.lisp and gui-demo.asd in the root directory contain a demonstration of cl-dormouse. Run the demonstration by issuing the following commands at the Lisp prompt:

(asdf:oos 'asdf:load-op "gui-demo")