Welcome to CL-DORMOUSE
, a windowing `graphical' user interface library, built on top of
the Doryen Library (libtcod).
Dormouse ('Doryen' + 'Mouse', groan
) 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.
Like libtcod, dormouse is designed with a view towards making it quicker and easier for hobbyists to write roguelike games. It can be used to write any application that uses libtcod and requires higher-level 'GUI' features.Features in detail
- Full mouse support, including drag and drop events from one window to another.
- Move and resize windows with the mouse.
- Each window's foreground, background, and text can be displayed in any 32-bit colour.
- 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, or define 'live' areas of the string which generate special events when clicked with the mouse (acting like dialog buttons).
- 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.
Where can I get it?
- And any combination of the above, through the magic of multiple inheritance...
- Window objects 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/
The Doryen library can be found at:http://doryen.eptalys.net/libtcod/
Installation and Usage(to be expanded soon)
This section assumes you have a working Common Lisp setup, that you have the ASDF library installed, and that you know where to put new libraries so that ASDF can find them.
- Install ITERATE (common lisp iteration library): http://common-lisp.net/project/iterate/
- Download and install libtcod. Compile if necessary.
- Download and install CL-TCOD (common lisp bindings to libtcod): http://bitbucket.org/eeeickythump/cl-tcod/
- Make sure your lisp can load CL-TCOD successfully. If it complains about being unable to find the libtcod library, you may need to copy libtcod.so or libtcod.dll to where lisp can find it. (On windows, put it somewhere in your PATH.) Libtcod in turn needs to be able to find SDL.dll / libsdl.so
- Download CL-DORMOUSE from the link above. Extract it to a directory where ASDF can find it.
- Run your lisp and make sure you can load asdf, and asdf can load CL-TCOD and DORMOUSE.
The following is a minimal 'hello world' application:
(:use :cl :tcod :dormouse)
(defun my-test ()
(let ((msgwin nil))
(dormouse:start-gui :title "Testing")
(make-instance '<Log-Window> :tlx 30 :tly 10 :width 20 :height 6
:title "log" :foreground :cornsilk
(add-message msgwin "Press control-F1 or control-Esc to quit")
Save it in a file, load it, and run (my-new-package:my-test) at the lisp prompt to try it.Is there documentation?
Documentation for the library API is autogenerated and can be found in the 'html' subdirectory. It is about 60% complete at the moment.Is there a demo?
Yes. Load the ASDF system :gui-demo and call (gui-demo:gui-demo) to run it.
(asdf:oos 'asdf:load-op :gui-demo)
A screenshot of the demo is attached to this post. (There is also a screenshot from my (far from playable) game.)
In addition, the demo is downloadable as an executable file
from the cl-dormouse repository. Currently this is only available for 32-bit windows systems:Download link