Interzona

nodgui

Table of Contents

Introduction

"No Drama GUI"

Common Lisp bindings for the Tk GUI toolkit.

Screenshots

date-picker.png

Figure 1: A date picker widget

canvas.png

Figure 2: A canvas with some shapes painted on it

Download

Use quicklisp or point to this repository

Dependency

Programs

Lisp libraries

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

All of the above libraries are available on quicklisp.

FAQ

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 ()
    cursor
    state
    style
    takefocus
    validate
    validatecommand
    xscrollcommand
    command
    format
    from
    increment
    to
    values
    wrap)
    

    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:

    https://www.tcl.tk/man/tcl8.6/TkCmd/ttk_spinbox.htm

    and not

    https://www.tcl.tk/man/tcl8.6/TkCmd/spinbox.htm

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

Status

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
font    
frame x  
grab    
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  
selection    
send    
spinbox x  
text x  
tk    
tk_bisque - only for tk backwards compatibility
tk_chooseColor    
tk_chooseDirectory    
tk_dialog    
tk_focusFollowsMouse    
tk_focusNext    
tk_focusPrev    
tk_getOpenFile x  
tk_getSaveFile x  
tk_menuSetFocus -  
tk_messageBox x  
tk_optionMenu    
tk_popup    
tk_setPalette -  
tk_textCopy    
tk_textCut    
tk_textPaste    
tkerror -  
tkvars -  
tkwait    
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
image  
label x
labelframe x
listbox x
menu  
menubutton  
message  
panedwindow x
photo  
radiobutton x
scale x
scrollbar x
spinbox x
text x
toplevel x

Compatibility

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

Notes

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!
    
    [...]
    
    #%red%
    

    at runtime using:

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

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

License

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 (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

Footnotes:

1

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.