Common Lisp bindings for the Tk GUI toolkit

cage e6c6a0a5fa - added a few documentation strings for megawidgets. 2 days ago
src e6c6a0a5fa - added a few documentation strings for megawidgets. 2 days ago
Changelog 477b42dfc6 - removed email from changelog. 2 weeks ago
README.org c8e4cad1c4 - updated README. 1 week ago
README.txt c8e4cad1c4 - updated README. 1 week ago
TODO.org aa667f0286 - updated changelog and TODO. 1 month ago
nodgui.asd 2f6dc3ea03 - fixed description field. 4 days 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-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 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 (cl-syntax:use-syntax nodgui-event-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 (cl-syntax:use-syntax nodgui-force-escape-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 | |----------------+-------------+-----+-----| | Debian testing | x | ? | ? | |----------------+-------------+-----+-----| | 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 (cl-syntax:use-syntax nodgui-color-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 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.