nodgui
Table of Contents
No Drama GUI
Common Lisp bindings for the Tk GUI toolkit.
1. Quick links
2. Latest News
2.1. 2024-03-31 Version 0.6.1.1
- [bugfix]
- fixed error signalled from TK interpreter when passing floating point value from lisp.
2.2. 2024-03-31 Version 0.6.1.0
- [new feature]
- added procedures related to events management
- [bugfix]
- fixed escaping of strings inserted in a text widget.
2.3. 2024-03-12 Version 0.6.0.2
- [new feature]
added
command
option for configuring button widget, for example:(with-nodgui () (let ((button (make-instance 'button :text "foo"))) (configure button :command (lambda () (format t "quitting~%") (exit-nodgui)) :text "Quit" :underline 0) (pack button)))
- moved from bordeaux threads version 1 API to version 2.
- [bugfix]
- fixed inconsistency in widget initialization intargs, accepted
:orient
instead of:orientation
, the latter is not accepted byconfigure
(thanks Arkdae!); - added missing brace when generating tags for treeview;
- fixed escaping of treeview's row id;
- fixed escaping of treeview's row text (first column);
- fixed blocking of pixelbuffer demo.
- fixed inconsistency in widget initialization intargs, accepted
3. Introduction
3.1. Screenshots
Figure 1: A date picker widget
Figure 2: A canvas with some shapes painted on it
4. Dependency
4.1. Programs
- TCL/TK interpreter (version >= 8.6) https://www.tcl.tk
4.2. Lisp libraries
- alexandria;
- cl-ppcre-unicode;
- cl-lex;
- cl-yacc;
- clunit2;
- cl-colors2;
- named-readtables.
All of the above libraries are available on quicklisp.
4.3. TCL/TK libraries (optional)
5. Installing
- install the tk interpreter (example on a Debian system follows)
$ su - # apt-get install tk
- optionally install tklib
$ su - # apt-get install tklib
- open a REPL and type
(ql:quickload "nodgui")
- try it!
(nodgui.demo::demo)
5.1. Source code
Optionally you can install the library getting the source code from project's repository.
6. 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).
6.1. MegaWidget
All these widget, written in common lisp, are defined in file
src/nogui-mw.lisp
.
6.1.1. 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-listbox
but the items added comes from the results from applyautocomplete-function-hook
to 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.
6.2. 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
6.2.1. 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
6.3. 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: A screenshot of the plasma animation demo
6.4. 3D rendering
Embedding SDL allow also for 3D hardware accelerated rendering, using openGL.
Figure 4: A screenshot of a procedural generated 3D terrain
7. FAQ
8. 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).
9. 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 10.1 |
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 |
✓ |
10. Notes
10.1. 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:
(rgb->tk cl-colors:+red+)
the list of supported colors name can be found in: this file.
11. Nodgui tips
12. 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