Table of Contents


"No Drama GUI"

Common Lisp bindings for the Tk GUI toolkit.



Figure 1: A date picker widget


Figure 2: A canvas with some shapes painted on it


Use quicklisp or point to this repository



Lisp libraries

  • alexandria;
  • cl-ppcre-unicode;
  • cl-lex;
  • cl-yacc;
  • clunit2;
  • cl-syntax;
  • cl-colors2.

All of the above libraries are available on quicklisp.


Where is the documentation?

nodgui is just the results of a code refactoring of LTK with some syntax sugar on top. This means that the original documentation can be almost used as a good reference also for this library; the chapters that are still valid are listed below:

Please note that all the documentation about the widgets is outdated instead.

The rest of the documentation are the readme file and the rare docstrings at the moment.

If you wants to help please open a pull request.

Where can i found documentation about a widget?
It is actually very simple: let's suppose you want to use a spinbox widget in your program and you have no idea how to do, the idea to solve this problem is like:
  1. open the file src/spinbox.lisp an look at the top of this file:

    (defargs spinbox ()

    the symbols listed are all the options for the spinbox TK command (in TCL language everything is a command) or the configuration variable that you can pass as initarg for (make instance 'spinbox ...) and, sometimes, changed after object instancing via configure (see the general documentation)

  2. for the meaning of this symbols refers to the original TK documentation

    As a general rule choose the link to the command with its name prefixed with "ttk::" (if exists).

    In our example point to:

    and not

    You can easly understand what all the options above are for.

How can I access the root window?
The root window is bound to the special variable *tk*.
I have a bunch of widgets placed in a grid and I want those to scale themselves when the window is resized, there is a way to accomplish this?

Sure! Use grid-(column|row)-configure.

(grid-columnconfigure *tk* :all :weight 1)
(grid-rowconfigure    *tk* :all :weight 1)

You can replace :all with a row or column indices to apply this behaviour only to a subset of the columns or rows.

What are the differences between nodgui and LTK?
The two libraries begin to diverge a bit now, the API is compatible with ltk no more.
  1. A reader macro for events i.e. #$<Alt-q>$ instead of "<Alt-q>" (a string), the macro will parse and check for trivial errors in the event definition syntax at compile time.

    (cl-syntax:use-syntax 'nodgui-event-syntax) ; do not forget that!
    (bind *tk* #$<Alt-q>$ (lambda (event) ...

    Please note that a string is still accepted as event specifier.

  2. A DSL for TCL code that allow to mix TCL code and lisp expression, check for example the following code to create a bitmap:

    (cl-syntax:use-syntax 'nodgui-force-escape-syntax)
    (tclize `([list
                ,#[loop for r from 0 below h collect
                    (tclize `([list ,#[loop

    The tclize macro will transforms the backquoted forms in tcl code, the unquoted forms will be evaluated before the translation occurs.

    Please always wrap the unquoted form in #[ ... 'a space' ] because this will force escaping of the data (e.g. from: '{' to \{).

    You should put a space before the closing square brackets, this is an annoyng bug that will be solved soon or later.

  3. The function postscript returns a postscript file as string instead of write a file on disk;
  4. Support for images in GIF, PNG, TGA, JPEG and raw RGB format, limited manipulation for the latest three is provided (scaling and rotation).
  5. Compatible only with TK 8.6;
  6. A general refactoring.
  7. Integrated with cl-colors library (can use X11 color names or rgb struct, see Colors Name).
  8. Some bugs fixed (and more added of course :-) )
Where can i find more code examples?
check the file src/demo-tests.lisp
Can I contribute to this project?

Yes, of course! Please open an issue or a pull request on the web repository, if you do not feel comfortable with coding documentation improvements are very welcome too! :)

Also i would appreciate testing if the library works on different environment than mine (debian GNU/Linux with SBCL).


All tk commands as of version 8.4 with support information. "-" means not supported by purpose (look comment), "x" means supported, though some options may not be supported.

command supported comment
bell x  
bind x  
bindtags modify modify the tag list of a widget that
    describes which events it gets
bitmap - see image
button x  
canvas x  
checkbutton x  
clipboard x (canvas get missing… tricky…)
colors - see Colors Name
console - only on some platforms
cursors x  
destroy x  
entry x  
event create create and manage virtual events
focus x focus management functions
frame x  
busy x  
grid x  
image x  
keysyms x  
label x  
labelframe x  
listbox x  
loadTk -  
lower x  
menu x  
menubutton x  
message x  
option -  
options - only helpfile
pack x  
panedwindow x  
photo x support for PNG, GIF, JPEG and raw RGB(A) format.
place x geometry manager using coordinates
radiobutton x  
raise x  
scale x  
scrollbar x  
spinbox x  
text x  
tk_bisque - only for tk backwards compatibility
tk_getOpenFile x  
tk_getSaveFile x  
tk_menuSetFocus -  
tk_messageBox x  
tk_setPalette -  
tkerror -  
tkvars -  
toplevel x  
treeview x  
winfo x  
wm x  

support of all config args as keywords to make-instance:

bitmap -
button x
canvas x
checkbutton x
entry x
frame x
label x
labelframe x
listbox x
panedwindow x
radiobutton x
scale x
scrollbar x
spinbox x
text x
toplevel x


OS / compiler SBCL 1.4.14 ECL CCL 1.11.5
GNU/Linux x ? x1
MacOS ? ? ?
Win ? ? ?


Colors Name

Color name from library cl-color can be used as follows:

  • with a reader macro (#%...%) at read time:

    (cl-syntax:use-syntax 'nodgui-color-syntax) ; do not forget that!

    at runtime using:

    (rgb->tk cl-colors:+red+)

    the list of supported colors name can be found in: this file.


This software is Copyright (c) 2003-2010 Peter Herth

Portions Copyright (c) 2005-2010 Thomas F. Burdick

Portions Copyright (c) 2006-2010 Cadence Design Systems

Portions Copyright (c) 2010 Daniel Herring

Portions Copyright (c) 2018 cage

The authors grant you the rights to distribute and use this software as governed by the terms of the Lisp Lesser GNU Public License (, known as the LLGPL.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

This single file is released under LLGPL



It requires ASDF update

This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Italy License.

Distribuited software and source code published are licensed under the GNU General Public License version 3.0 or later if not specified otherwise.