Common Lisp bindings for the Tk GUI toolkit https://www.autistici.org/interzona/nodgui.html

cage ff99a2b006 - Updated README to point out that works on ECL.. 3 weeks ago
src ff99a2b006 - Updated README to point out that works on ECL.. 3 weeks ago
Changelog 477b42dfc6 - removed email from changelog. 6 months ago
README.org ff99a2b006 - Updated README to point out that works on ECL.. 3 weeks ago
README.txt ff99a2b006 - Updated README to point out that works on ECL.. 3 weeks ago
TODO.org aa667f0286 - updated changelog and TODO. 7 months ago
nodgui.asd 4a26594308 - moved from cl-syntax to named-readtables. 3 weeks ago

README.org

NODGUI

"No Drama GUI"

Common Lisp bindings for the Tk GUI toolkit.

Dependency

Programs

  • TCL/TK interpreter (version >= 8.6)
  • https://www.tcl.tk

Lisp libraries

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

All of the above libraries are available on quicklisp.

Widget pack

This library define a few additional widgets (called "MegaWidget").

All these widget are defined in file src/nogui-mw.lisp, there should be a decent quantity of documentation as docstrings on the sources.

Probably checking the excellent quickdocs could be useful too (note that the documentation there does not always reflects the latest version of this library).

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 autocompleted pressing the TAB key.
  • treelist ::
  • Display a tree-like structure by a set of listboxes.

screenshot

  • tooltip ::
  • Display a little informative box for the widget under the mouse pointer position.

screenshot

License for the image.

  • gtree ::
  • Render a tree.

screenshot

  • searchable-listbox ::
  • A [[https://www.tcl.tk/man/tcl8.6/TkCmd/listbox.htm#M12][listbox]] with an entry to filter its contents
  • autocomplete-listbox ::
  • Acts like 'searchable-listbox' but the items added comes from the results from apply 'autocomplete-function-hook' to the content of the text entry. This function is triggered after a character is inserted into the entry.
date-picker
A widget to choose a date

screenshot

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

screenshot

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 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:
    2. #+BEGIN_SRC lisp (defargs spinbox () cursor state style takefocus validate validatecommand xscrollcommand command format from increment to values wrap) #+END_SRC

    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)

    1. for the meaning of this symbols refers to the
    2. [[https://www.tcl.tk/man/tcl8.6/TkCmd/contents.htm][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.

    #+BEGIN_SRC lisp (grid-columnconfigure tk :all :weight 1) (grid-rowconfigure tk :all :weight 1) #+END_SRC

    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
    2. i.e. ~#$$~ instead of ~""~ (a string), the macro will parse and check for trivial errors in the event definition syntax at compile time. #+BEGIN_SRC lisp (named-readtables:in-readtable nodgui.syntax:nodgui-syntax) ; do not forget that!

      [...]

      (bind tk #$$ (lambda (event) ... #+END_SRC

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

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

      #+BEGIN_SRC lisp (named-readtables:in-readtable nodgui.syntax:nodgui-syntax)

      [...]

      (tclize `([list ,#[loop for r from 0 below h collect (tclize `([list ,#[loop ... #+END_SRC

      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.

      1. The function postscript
      2. returns a postscript file as string instead of write a file on disk;
      1. Support for images in GIF, PNG, TGA, JPEG and raw RGB format,
      2. limited manipulation for the latest three is provided (scaling and rotation).
      1. Compatible only with TK 8.6;
      1. A general refactoring.
      1. Integrated with cl-colors library (can use X11 color names or
      2. rgb struct, see [[Colors Name]]).
      1. 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 | x2 | |---------------+-------------+-------------------+----------------| | MacOS | ? | ? | ? | |---------------+-------------+-------------------+----------------| | Win | ? | ? | ? |

      Notes

      Colors Name

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

      • with a reader macro (#%...%) at read time:
      • #+BEGIN_SRC lisp (named-readtables:in-readtable nodgui.syntax:nodgui-syntax) ; do not forget that!

      [...]

      #%red% #+END_SRC

      at runtime using:

      #+BEGIN_SRC lisp (rgb->tk cl-colors:+red+) #+END_SRC

      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,2019 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.

      3 It requires ASDF update 4 Using version from git repository


      1. DEFINITION NOT FOUND
      2. DEFINITION NOT FOUND
      3. DEFINITION NOT FOUND
      4. DEFINITION NOT FOUND