<astyle="font-size: 120%"href="https://www.udemy.com/course/common-lisp-programming/?couponCode=LISPY-XMAS2023"title="This course is under a paywall on the Udemy platform. Several videos are freely available so you can judge before diving in. vindarel is (I am) the main contributor to this Cookbook."> Discover our contributor's Lisp course with this Christmas coupon.</a>
📕 <ahref="index.html#download-in-epub">Get the EPUB and PDF</a>
</p>
<divid="content"
<p>Lisp has a long and rich history and so does the development of
Graphical User Interfaces in Lisp. In fact, the first GUI builder was
written in Lisp (and sold to Apple. It is now Interface Builder).</p>
<p>Lisp is also famous and unrivalled for its interactive development
capabilities, a feature even more worth having to develop GUI
applications. Can you imagine compiling one function and seeing your
GUI update instantly? We can do this with many GUI frameworks today,
even though the details differ from one to another.</p>
<p>Finally, a key part in building software is how to build it and ship
it to users. Here also, we can build self-contained binaries, for
the three main operating systems, that users can run with a double
click.</p>
<p>We aim here to give you the relevant information to help you choose
the right GUI framework and to put you on tracks. Don’t hesitate to
<ahref="https://github.com/LispCookbook/cl-cookbook/issues/">contribute</a>, to
send more examples and to furnish the upstream documentations.</p>
<h2id="introduction">Introduction</h2>
<p>In this recipe, we’ll present the following GUI toolkits:</p>
<ul>
<li><ahref="https://www.tcl.tk">Tk</a> with <ahref="http://www.peter-herth.de/ltk/ltkdoc/">Ltk</a> and <ahref="https://notabug.org/cage/nodgui">nodgui</a></li>
<li><ahref="https://doc.qt.io/archives/qt-4.8/index.html">Qt4</a> with <ahref="https://github.com/Shinmera/qtools">Qtools</a></li>
<li><ahref="http://webserver2.tecgraf.puc-rio.br/iup/">IUP</a> with <ahref="https://github.com/lispnik/iup/">lispnik/iup</a></li>
<li><ahref="https://www.gtk.org/">Gtk3</a> with <ahref="https://github.com/Ferada/cl-cffi-gtk/">cl-cffi-gtk</a>
<ul>
<li>if you want Gtk4 bindings, see <ahref="https://github.com/bohonghuang/cl-gtk4">cl-gtk4</a>. They are new bindings, released in September, 2022.</li>
</ul>
</li>
<li><ahref="https://github.com/Immediate-Mode-UI/Nuklear">Nuklear</a> with <ahref="https://github.com/borodust/bodge-nuklear">Bodge-Nuklear</a></li>
</ul>
<p>In addition, you might want to have a look to:</p>
which is proprietary and made by LispWorks. It is a complete and cross-platform
toolkit (Windows, Gtk+, Cocoa), very praised by its users. LispWorks
also has <ahref="http://www.lispworks.com/products/lw4mr.html">iOS and Android
runtimes</a>. Example
software built with CAPI include <ahref="https://scorecloud.com/">ScoreCloud</a>. It is possible to
try it with the LispWorks free demo.</li>
<li><ahref="https://franz.com/products/allegro-common-lisp/acl_ide.lhtml">Allegro CL’s IDE and Common Graphics windowing system</a> (proprietary): Allegro’s IDE is a general environment for developing applications. It works in concert with a windowing system called Common Graphics. The IDE is available for Allegro CL’s Microsoft Windows, on Linux platforms, Free BSD and on the Mac.
<ul>
<li>NEW! 🎉 since Allegro CL 10.1 (released in March of 2022), the IDE, and the Common Graphics GUI toolkit, runs in the browser. It is called <ahref="https://franz.com/ftp/pri/acl/cgjs/doc.html">CG/JS</a>.</li>
used to build applications such as <ahref="https://opusmodus.com/">Opusmodus</a>.</li>
<li>Clozure CL’s built-in <ahref="https://ccl.clozure.com/docs/ccl.html#the-objective-c-bridge">Objective-C bridge</a> and <ahref="https://github.com/plkrueger/CocoaInterface/">CocoaInterface</a>, a Cocoa interface for CCL. Build Cocoa user interface windows dynamically using Lisp code and bypass the typical Xcode processes.
<ul>
<li>the bridge is good at catching ObjC errors and turning them into Lisp errors, so one can have an iterative REPL-based development cycle for a macOS GUI application.</li>
</ul>
</li>
<li><ahref="https://common-lisp.net/project/mcclim/">McCLIM</a> and <ahref="https://github.com/earl-ducaine/cl-garnet">Garnet</a> are toolkit in 100% Common Lisp. McClim even has <ahref="https://techfak.de/~jmoringe/mcclim-broadway-7.ogv">a prototype</a> running in the browser with the Broadway protocol and Garnet has an ongoing interface to Gtk.</li>
<li><ahref="https://github.com/Shirakumo/alloy">Alloy</a>, another very new toolkit in 100% Common Lisp, used for example in the <ahref="https://github.com/shinmera/kandria">Kandria</a> game.</li>
<li><ahref="https://gitlab.com/eql">eql, eql5, eql5-android</a>, embedded Qt4 and Qt5 Lisp, embedded in ECL, embeddable in Qt. Port of EQL5 to the Android platform.</li>
<li>this <ahref="https://github.com/defunkydrummer/abcl-jazz">demo using Java Swing from ABCL</a></li>
<li><ahref="https://github.com/mifpasoti/Gtk-Demos">examples of using Gtk without C files with SBCL</a>, as well as GTK-server.</li>
<li>and, last but not least, <ahref="http://ceramic.github.io/">Ceramic</a>, to ship a cross-platform web app with Electron.</li>
</ul>
<p>as well as the other ones listed on <ahref="https://github.com/CodyReichert/awesome-cl#Gui">awesome-cl#gui</a> and <ahref="https://www.cliki.net/GUI">Cliki</a>.</p>
<h3id="tk-ltk-and-nodgui">Tk (Ltk and nodgui)</h3>
<p><ahref="https://www.tcl.tk">Tk</a> (or Tcl/Tk, where Tcl is the programming language) has the
infamous reputation of having an outdated look. This is not (so) true
anymore since its version 8 of 1997 (!). It is probably better than
you think.</p>
<p>This is a simple GUI with nodgui’s built-in theme (more on that below):</p>
<p>In addition to those, we can use many of the <ahref="https://ttkthemes.readthedocs.io/en/latest/themes.html">ttkthemes</a>, the <ahref="https://github.com/rdbende/Forest-ttk-theme">Forest theme</a>, and more. See <ahref="https://wiki.tcl-lang.org/page/List+of+ttk+Themes">this tcl/tk list</a>.</p>
<p>But what is Tk good for? Tk doesn’t have a great choice of widgets, but it has a useful canvas,
and it has a couple of unique features: we can develop a graphical
interface <strong>fully interactively</strong> and we can run the GUI <strong>remotely</strong>
from the core app. It is also cross-platform.</p>
<p>So, Tk isn’t native and doesn’t have the most advanced features,
but it is a used and proven GUI toolkit (and
programming language) still used in the industry. It can be a great
choice to quickly create simple GUIs, to leverage its ease of deployment, or
when stability is required.</p>
<p>There are two Lisp bindings: <ahref="http://www.peter-herth.de/ltk/ltkdoc/">Ltk</a> and <ahref="https://notabug.org/cage/nodgui">nodgui</a>. Nodgui
(“No Drama GUI”) is a fork of Ltk, with added widgets (such as an
auto-completion list widget), an asynchronous event loop and, what we
really enjoy, the surprisingly nice-looking “Yaru” theme that comes
with the library. It is also very easy to install and use any other theme of
<p><strong>Widgets</strong>: this is not the fort of Tk. It has a <strong>small set</strong> of
default widgets, and misses important ones, for example a date picker. We
can find some in extensions (such as in <strong>Nodgui</strong>), but they don’t
feel native, at all. The calendar is brought by a Tk extension and looks better.</p>
</li>
<li>
<p><strong>Interactive development</strong>: very much.</p>
</li>
<li>
<p><strong>Graphical builder</strong>: no</p>
</li>
<li><strong>Other features</strong>:
<ul>
<li><strong>remote execution</strong>: the connection between Lisp and Tcl/Tk is
done via a stream. It is thus possible to run the Lisp program on
one computer, and to display the GUI on another one. The only
thing required on the client computer is tcl/tk installed and the
remote.tcl script. See <ahref="http://www.peter-herth.de/ltk/ltkdoc/node46.html">Ltk-remote</a>.</li>
</ul>
</li>
<li><strong>Bindings documentation</strong>: short but complete. Nodgui too.</li>
<li><strong>Bindings stability</strong>: very stable</li>
<li><strong>Bindings activity</strong>: low for Ltk (mostly maintenance), active for nodgui (new features).</li>
<li><strong>Licence</strong>: Tcl/Tk is BSD-style, Ltk is LGPL.</li>
<li>Example applications:
<ul>
<li><ahref="https://notabug.org/cage/fulci/">Fulci</a> - a program to organise your movie collections.</li>
<li><ahref="https://github.com/mijohnson99/ltk-small-games">Ltk small games</a> - snake and tic-tac-toe.</li>
<li><ahref="https://github.com/VitoVan/cl-pkr">cl-pkr</a> - a cross-platform color picker.</li>
<li><ahref="https://github.com/vindarel/cl-torrents">cl-torrents</a> - searching torrents on popular trackers. CLI, readline and a simple Tk GUI.</li>
</ul>
</li>
<li>More examples:
<ul>
<li><ahref="https://peterlane.netlify.app/ltk-examples/">https://peterlane.netlify.app/ltk-examples/</a>: LTk examples for the <ahref="https://tkdocs.com/tutorial/index.html">tkdocs</a> tutorial.</li>
<li><ahref="https://peterlane.netlify.app/ltk-plotchart/">LTk Plotchart</a> - A wrapper around the tklib/plotchart library to work with LTk. This includes over 20 different chart types (xy-plots, gantt charts, 3d-bar charts etc…).</li>
</ul>
</li>
</ul>
<p><strong>List of widgets</strong></p>
<p>(please don’t suppose the list is exhaustive)</p>
<p>Do we need to present Qt and <ahref="https://doc.qt.io/archives/qt-4.8/index.html">Qt4</a>? Qt is huge and contains
everything and the kitchen sink. Qt not only provides UI widgets, but
numerous other layers (networking, D-BUS…).</p>
<p>Qt is free for open-source software, however you’ll want to check the
conditions to ship proprietary ones.</p>
<p>The <ahref="https://github.com/Shinmera/qtools">Qtools</a> bindings target Qt4. The Qt5 Lisp bindings are <ahref="https://lispcookbook.github.io/cl-cookbook/in the works">https://github.com/commonqt/commonqt5/</a> and not ready for prime time..</p>
<p>A companion library for Qtools, that you’ll want to check out once you
made your first Qtool application, is
<ahref="https://github.com/Shinmera/qtools-ui">Qtools-ui</a>, a collection of
useful widgets and pre-made components. It comes with short
<p><ahref="https://github.com/Immediate-Mode-UI/Nuklear">Nuklear</a> is a small <ahref="https://en.wikipedia.org/wiki/Immediate_mode_GUI">immediate-mode</a> GUI toolkit:</p>
<blockquote>
<p><ahref="https://github.com/Immediate-Mode-UI/Nuklear">Nuklear</a> is a minimal-state, immediate-mode graphical user interface toolkit written in ANSI C and licensed under public domain. It was designed as a simple embeddable user interface for application and does not have any dependencies, a default render backend or OS window/input handling but instead provides a highly modular, library-based approach, with simple input state for input and draw commands describing primitive shapes as output. So instead of providing a layered library that tries to abstract over a number of platform and render backends, it focuses only on the actual UI.</p>
</blockquote>
<p>its Lisp binding is <ahref="https://github.com/borodust/bodge-nuklear">Bodge-Nuklear</a>, and its higher level companions <ahref="https://github.com/borodust/bodge-ui">bodge-ui</a> and <ahref="https://github.com/borodust/bodge-ui-window">bodge-ui-window</a>.</p>
<p>Unlike traditional UI frameworks, Nuklear allows the developer to take
over the rendering loop or the input management. This might require
more setup, but it makes Nuklear particularly well suited for games,
or for applications where you want to create new controls.</p>
<ul>
<li><strong>Framework written in</strong>: ANSI C, single-header library.</li>
<li>
<p><strong>Portability</strong>: where C runs. Nuklear doesn’t contain
platform-specific code. No direct OS or window handling is done in
Nuklear. Instead <em>all input state has to be provided by platform
specific code</em>.</p>
</li>
<li>
<p><strong>Widgets choice</strong>: small.</p>
</li>
<li>
<p><strong>Graphical builder</strong>: no.</p>
</li>
<li>
<p><strong>Other features</strong>: fully skinnable and customisable.</p>
<p>It is also possible to install and load another tcl theme. For example, clone the <ahref="https://github.com/rdbende/Forest-ttk-theme">Forest ttk theme</a> or the <ahref="https://github.com/TkinterEP/ttkthemes/">ttkthemes</a>. Your project directory would look like this:</p>
<pre><code>yourgui.asd
yourgui.lisp
ttkthemes/
</code></pre>
<p>Inside <code>ttkthemes/</code>, you will find themes under the <code>png/</code> directory (the other ones are currently not supported):</p>
<pre><code>/ttkthemes/ttkthemes/png/arc/arc.tcl
</code></pre>
<p>You need to load the .tcl file with nodgui, and tell it to use this theme:</p>
<p>You might also like <ahref="https://github.com/phoe-trash/furcadia-post-splitter/blob/master/.travis.yml">this Travis CI script</a> to build a self-contained binary for the three OSes.</p>
