nodgui
Table of Contents
No Drama GUI
Common Lisp bindings for the Tk GUI toolkit.
Quick links
Latest News
2025-04-02 version 0.7.3.5
- [bugfix]
- wrapped message-box's body with 'with-read-data' macro, to prevent race conditions.
2025-03-29 version 0.7.3.4
- [improvements]
- added functions to customize commands of chance and close buttons in a virtual-keyboard widget.
2025-03-29 version 0.7.3.3
- [improvements]
- added a compiler macro for 'pixmap:assemble-color';
- added hints to optimize 'nodgui.sanitize:%tkescape';
- [pixel buffer] fixed clamping and wrapping of texture coordinates.
Introduction
Screenshots
Figure 1: A screenshot of software "fulci", made using nodgui
Figure 2: A little game written whith the help of nodgui
Dependency
Programs
- TCL/TK interpreter (version >= 8.6) https://www.tcl.tk
Lisp libraries
- alexandria;
- bordeaux-threads;
- cl-colors2;
- cl-opengl;
- cl-ppcre-unicode;
- cl-unicode;
- sdl2;
- sdl2-ttf;
- clunit2;
- esrap;
- flexi-streams;
- jpeg-turbo;
- named-readtables;
- parse-number;
- pngload;
- zpng.
All of the above libraries are available on quicklisp.
C Libraries
- libsdl2 https://www.libsdl.org/
- turboJpeg (high level api for libjpeg-turbo) https://www.libjpeg-turbo.org/
TCL/TK libraries (optional)
Installing
install the tk interpreter (example on a Debian system follows)
# apt-get install tk
optionally install tklib
# apt-get install tklib
optionally install tcllib
# apt-get install tcllib
optionally install tkimg
# apt-get install libtk-img
install libsd2
# apt-get install libsdl2-dev
install opengl
# apt-get install libg-dev
install libturbojpeg
# apt-get install libturbojpeg0-dev
open a REPL and type
(ql:quickload "nodgui")try it!
(nodgui.demo:demo)
also try the minigame, it is fun!
(asdf:make nodgui/game) (main::main)
Source code
Optionally you can install the library getting the source code from project's repository.
Widget pack
This library define a few additional widgets more than the standard TK ones.
There should be a decent quantity of documentation as docstrings on the sources.
Probably checking the excellent quickdocs or the excellent as well quickref could be useful too (note that the documentation there does not always reflects the latest version of this library).
MegaWidget
All these widget, written in common lisp, are defined in file
src/nogui-mw.lisp.
MegaWidget list
- history-entry
- An entry widget keeping the history of previous input (which can be browsed through with cursor up and down), the input can be also auto-completed pressing the TAB key.
- treelist
Display a tree-like structure by a set of listboxes.
- tooltip
Display a little informative box for the widget under the mouse pointer position.
- gtree
Render a tree.
- searchable-listbox
- A listbox with an entry to filter its contents
- autocomplete-listbox
- Acts like
searchable-listboxbut the items added comes from the results from applyautocomplete-function-hookto the content of the text entry. This function is triggered after a character is inserted into the entry. - autocomplete-entry
an entry that shows candidate for completion
- date-picker
A widget to choose a date
- password-entry
- A widget to input a password (the actual characters are not shown when typed, a placeholder is rendered instead).
- progress-bar-star
a progress bar that display stars to show progress
- password manipulation dialog windows
- change-password-dialog;
- add-password-dialog;
- password-input-dialog.
- virtual-keyboard
on screen keyboard with configurable layout
Tklib
Some more widget in nodgui derive from wrapping and, in some case, extending the widget set contained in tklib
To use these widget in nodgui tklib must be installed on your system, fortunately this library is widely available at least on GNU/Linux.
On Debian just a couple of commands are needed:
$ su - (root)# apt-get install tklib
Tklib derived widgets
- calendar
- A widget to choose a date;
- notify-window
- show a fading out notification text to the user; on the top right of the screen;
- dot-plot
- draw a scatter plot (with optional error bars) on a canvas.
- bar-chart
- draw an histogram
- equalizer-bar
- swap-list
Pixels blitting
The default TK canvas widget is good at drawing graphics primitives but the performance when trying to render a block of pixels is very poor.
This library is able to embed an SDL window to allow pixels rendering fast enough to get (with the help of compiler optimization) a decent animation at 60 frames per seconds.
Figure 3: Demo of a canvas with many rectangles rendered
3D rendering
Embedding SDL allow also for 3D hardware accelerated rendering, using openGL.
Figure 4: A screenshot of a procedural generated 3D terrain
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).
Status
All tk commands as of version 8.4 with support information. - means not supported by purpose (look comment), ✓ means supported, though some options may not be supported.
| command | supported | comment |
|---|---|---|
bell |
✓ | |
bind |
✓ | |
bindtags |
modify | modify the tag list of a widget that |
| describes which events it gets | ||
bitmap |
- | see image |
button |
✓ | |
canvas |
✓ | |
checkbutton |
✓ | |
clipboard |
✓ | (canvas get missing… tricky…) |
colors |
- | see Colors Name |
console |
- | only on some platforms |
cursors |
✓ | |
destroy |
✓ | |
entry |
✓ | |
event |
✓ | create and manage virtual events and event aliases |
focus |
✓ | focus management functions |
font |
✓ | |
font_chooser |
✓ | |
frame |
✓ | |
grab |
||
busy |
✓ | |
grid |
✓ | |
image |
✓ | |
keysyms |
✓ | |
label |
✓ | |
labelframe |
✓ | |
listbox |
✓ | |
loadTk |
- | |
lower |
✓ | |
menu |
✓ | |
menubutton |
✓ | |
message |
✓ | |
option |
- | |
options |
- | only helpfile |
pack |
✓ | |
panedwindow |
✓ | |
photo |
✓ | support for PNG, GIF, JPEG and raw RGB(A) format. |
place |
✓ | geometry manager using coordinates |
radiobutton |
✓ | |
raise |
✓ | |
scale |
✓ | |
scrollbar |
✓ | |
selection |
||
send |
||
spinbox |
✓ | |
text |
✓ | |
tk |
||
tk_bisque |
- | only for tk backwards compatibility |
tk_chooseColor |
||
tk_chooseDirectory |
||
tk_dialog |
||
tk_focusFollowsMouse |
||
tk_focusNext |
||
tk_focusPrev |
||
tk_getOpenFile |
✓ | |
tk_getSaveFile |
✓ | |
tk_menuSetFocus |
- | |
tk_messageBox |
✓ | |
tk_optionMenu |
||
tk_popup |
||
tk_setPalette |
- | |
tk_textCopy |
||
tk_textCut |
||
tk_textPaste |
||
tkerror |
- | |
tkvars |
- | |
tkwait |
||
toplevel |
✓ | |
treeview |
✓ | |
winfo |
✓ | |
wm |
✓ |
support of all config args as keywords to make-instance:
| command | supported |
|---|---|
bitmap |
- |
button |
✓ |
canvas |
✓ |
checkbutton |
✓ |
entry |
✓ |
frame |
✓ |
image |
|
label |
✓ |
labelframe |
✓ |
listbox |
✓ |
menu |
|
menubutton |
|
message |
|
panedwindow |
✓ |
photo |
|
radiobutton |
✓ |
scale |
✓ |
scrollbar |
✓ |
spinbox |
✓ |
text |
✓ |
toplevel |
✓ |
Notes
Colors Name
Color name from library cl-color can be used as follows:
with a reader macro (
#%...%) at read time:(named-readtables:in-readtable nodgui.syntax:nodgui-syntax) ; do not forget that! [...] #%red%at runtime using:
(nodgui.utils:make-tk-color cl-colors:+red+) ; or (nodgui.utils:make-tk-color :red)the list of supported colors name can be found in: this file.
Nodgui lite
The package contains an ASDF file that specify an alternative system that will build a stripped down version of nodgui that removes some dependencies related to fast 2D and 3D rendering and also drops support for JPEG file format; this version of the library could be useful if there are problems with CFFI dependencies, the flip side of the coin will be the loss of canvas with fast pixel drawing, hardware accelerated canvas for 3D rendering and also the support for JPEG bitmap.
Nodgui tips
License
This software is Copyright © cage.
Derived from:
- © Peter Herth;
- © Thomas F. Burdick;
- © Cadence Design Systems;
- © Daniel Herring.
The authors grant you the rights to distribute and use this software as governed by the terms of the Lisp Lesser GNU Public License (http://opensource.franz.com/preamble.html), 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
