Bitbucket is a code hosting site with unlimited public and private repositories. We're also free for small teams!

Close

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.

Features

  • 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/.

Dependencies

Installation

  • 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.

    :::cl
    (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")
          (main-gui-loop)))

Demonstration

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")
(gui-demo:gui-demo)

Recent activity

Paul Sexton

Commits by Paul Sexton were pushed to eeeickythump/cl-dormouse

a10792a - Windows have a new slot, 'close-on-escape?'. If true, and the escape key is pressed while the window has focus, and is not otherwise handled, the ...
Paul Sexton

Commits by Paul Sexton were pushed to eeeickythump/cl-dormouse

2eecc4e - Any window class can now behave modally, by specialising the 'modal?' generic function. console-draw-char-at is now a plain function, for better performance. 'defstar' library is ...
Paul Sexton

Commits by Paul Sexton were pushed to eeeickythump/cl-dormouse

75a9d8e - Mouse movement now generates <Mouse-Move-Event> events, via 'send-mouse-move-event'. A distinction is now drawn between 'raising' and 'unhiding' windows. 'raise-window' raises a visible window to the ...
psex001

Commits by psex001 were pushed to eeeickythump/cl-dormouse

9cccb40 - - main gui loop rewritten for compatibility with libtcod 1.5.1rc1. - new window class: Meter-Window, draws one or more horizontal bar charts, the value of ...
eeeickythump

Commits by eeeickythump were pushed to eeeickythump/cl-dormouse

f917f87 - Added functions to save and restore global interface state, intended for use when a program needs to switch between mutually exclusive GUIs. Added themes, allowing ...
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.