Common Lisp CFFI bindings to the IUP Portable User Interface library
Compatibility
IUP 3.29
Introduction
Shared Libraries
Get the Tecgraf shared libraries (.so and .dll files) from the Tecgraf
project pages and install them per your operating system. Usually this
means setting LD_LIBRARY_PATH on Linux or PATH on Windows.
- https://www.tecgraf.puc-rio.br/iup/
- https://www.tecgraf.puc-rio.br/cd/
- https://www.tecgraf.puc-rio.br/im/
There is, however, a companion project which can be used to download and install the Tecgraf IUP, CD and IM shared libraries for x86/64-bit Linux and Windows automatically:
(ql:quickload "tecgraf-libs")This downloads the archives from each of the project pages according to the platform your lisp is running on (Linux or Windows). It unpacks the archives, and copies all of the shared libraries to a single directory.
It is a one-off step is is not needed subsequently.
NOTE: On Linux, the tecgraf-libs system needs the patchelf
command available (usually available via sudo apt install
patchelf). patchelf is used to set the shared library .so files
origin to the library’s location so that the multiple shared libraries
loaded via CFFI uses are found relative to each other.
NOTE: On Windows, the environment variable `PATH` should be modified so it points to the directory where the libs are downloaded. This has to be done before starting your Lisp implementation. Example of doing it and starting CCL:
SET PATH=C:\mylisp\projects\tecgraf-libs\libs; wx86cl64.exe
To tell CFFI to find these libraries, use:
(ql:quickload "cffi")
(pushnew (asdf:system-relative-pathname :tecgraf-libs #p"libs/")
cffi:*foreign-library-directories*)Loading IUP
(First, read the previous part on getting the Tecgraf libraries and installing).
Requirements:
Download/clone the following systems:
- lispnik/`tecgraf-base`
- lispnik/`pffft`
Those are required by Iup.
Then load iup.asd in the usual way (e.g. `(ql:quickload “iup”)`
NOTE: For SBCL, you need to set a larger heap size to compile the
bindings, e.g. --dynamic-space-size 2048
Running GUI Applications on Windows using SLIME or SLY
On Windows, it is necessary to start your Lisp indrectly via CMD.EXE, e.g.
for SLY, in your Emacs configuration, include something like:
(setq sly-lisp-implementations
'((ccl ("cmd" "/c" "wx86cl64"))
(sbcl ("cmd" "/c" "sbcl.exe" "--dynamic-space-size" "2048"))))Similarly use slime-lisp-implementations if your are using SLIME.
This is not specific to IUP or the bindings. It also works for running other graphical application libraries like CL-SDL2.
Hello, World!
;;; Generated from org-mode, do not edit
(eval-when (:compile-toplevel :load-toplevel :execute)
(ql:quickload "iup"))
(defpackage #:iup-examples.hello
(:use #:common-lisp)
(:export #:hello))
(in-package #:iup-examples.hello)(defun hello ()
(iup:with-iup ()
(let* ((label (iup:label :title (format nil "Hello, World!~%IUP ~A~%~A ~A"
(iup:version)
(lisp-implementation-type)
(lisp-implementation-version))))
(dialog (iup:dialog label :title "Hello, World!")))
(iup:show dialog)
(iup:main-loop))))#-sbcl (hello)
#+sbcl
(sb-int:with-float-traps-masked
(:divide-by-zero :invalid)
(hello))
Callbacks
Simple Example
;;; Generated from org-mode, do not edit
(eval-when (:compile-toplevel :load-toplevel :execute)
(ql:quickload "iup"))
(defpackage #:iup-examples.callback
(:use #:common-lisp)
(:export #:callback))
(in-package #:iup-examples.callback)(defun callback ()
(iup:with-iup ()
(let* ((button1
(iup:button :title "Test &1"
:expand :yes
:tip "Callback inline at control creation"
:action (lambda (handle)
(message "button1's action callback")
iup:+default+)))
(button2
(iup:button :title "Test &2"
:expand :yes
:tip "Callback set later using (SETF (IUP:CALLBACK ..) ..)"))
(button3
(iup:button :title "Test &3"
:expand :yes
:tip "Callback example using symbol-referenced function at control creation"
:action 'test3-callback))
(button4
(iup:button :title "Test &4"
:expand :yes
:tip "Callback example using symbol-referenced function later using (SETF (IUP:CALLBACK ..) ..)"))
(vbox
(iup:vbox (list button1 button2 button3 button4)
:gap "10"
:margin "10x10"
:alignment :acenter))
(dialog
(iup:dialog vbox :title "Callback Example")))
(setf (iup:callback button2 :action)
(lambda (handle)
(message "button2's action callback")
iup:+default+))
(setf (iup:callback button4 :action) 'test4-callback)
(iup:show dialog)
(iup:main-loop))))
(defun test3-callback (handle)
(message "button3's action callback")
iup:+default+)
(defun test4-callback (handle)
(message "button4's action callback")
iup:+default+)
(defun message (message)
(iup:message "Callback Example" message))#-sbcl (callback)
#+sbcl
(sb-int:with-float-traps-masked
(:divide-by-zero :invalid)
(callback))
Color Mixer
Consider capturing state by creating a closure over the controls that make up state:
;;; Generated from org-mode, do not edit
(eval-when (:compile-toplevel :load-toplevel :execute)
(ql:quickload "iup"))
(defpackage #:iup-examples.mixer
(:use #:common-lisp)
(:export #:mixer))
(in-package #:iup-examples.mixer)
(defun make-mixer-action (r g b button label)
(lambda (handle)
(declare (ignore handle))
(let ((color (format nil "~A ~A ~A"
(floor (iup:attribute r :value 'number))
(floor (iup:attribute g :value 'number))
(floor (iup:attribute b :value 'number)))))
(setf (iup:attribute button :fgcolor) color
(iup:attribute label :title) color)
(iup:refresh button))
iup:+default+))
(defun mixer ()
(iup:with-iup ()
(let* ((button (iup:flat-button :expand :yes :canfocus :no))
(label (iup:label :expand :horizontal :title "#x00000" :alignment "ACENTER:ACENTER"))
(r (iup:val :expand :horizontal :min 0 :max 255))
(g (iup:val :expand :horizontal :min 0 :max 255))
(b (iup:val :expand :horizontal :min 0 :max 255))
(vbox (iup:vbox
(list (iup:grid-box
(list (iup:label :title "&Red") r
(iup:label :title "&Green") g
(iup:label :title "&Blue") b)
:numdiv 2
:cgapcol 10
:cgaplin 5)
button
label)
:cmargin 5
:cgap 5
:margin "x5"))
(dialog (iup:dialog vbox :title "Color Mixer Example" :size "QUARTERxQUARTER")))
(loop :with action := (make-mixer-action r g b button label)
:for handle :in (list r g b)
:do (setf (iup:callback handle :valuechanged_cb) action))
(iup:show dialog)
(iup:main-loop))))
#-sbcl (mixer)
#+sbcl
(sb-int:with-float-traps-masked
(:divide-by-zero :invalid)
(mixer))
Idle Action
;;; Generated from org-mode, do not edit
(eval-when (:compile-toplevel :load-toplevel :execute)
(ql:quickload "iup"))
(defpackage #:iup-examples.idle
(:use #:common-lisp)
(:export #:idle))
(in-package #:iup-examples.idle)There is a global callback for running functions when IUP event loop
is idle. See also IUP: Idle Action. In Lisp, it can be set using
(SETF IUP:IDLE-ACTION). Note: Idle actions run a lot more often than
you’d expect. Try the following example application to get an idea for
just how often.
An idle action function should return IUP:+DEFAULT+, IUP:+CLOSE+
or IUP:+IGNORE+. IUP:+DEFAULT will cause the idle action function
to be called repeatedly. IUP:+IGNORE+ will run idle action
once. IUP:+CLOSE+ will exit the event loop.
(defun idle ()
(iup:with-iup ()
(let* ((counter (iup:label :fontsize 24
:title 0
:expand :yes
:alignment :acenter))
(start-button (iup:button :title "&Start" :expand :horizontal))
(stop-button (iup:button :title "S&top" :expand :horizontal))
(do-nothing nil)
(do-nothing-toggle (iup:toggle :title "Do nothing"
:action (lambda (handle state)
(setf do-nothing (not do-nothing))
iup:+default+)))
(vbox (iup:vbox (list counter
(iup:hbox (list start-button stop-button do-nothing-toggle)
:cgap 5))
:margin "5x5"))
(dialog (iup:dialog vbox
:title (format nil "Idle Example on ~A" (lisp-implementation-type))
:size "QUARTERxQUARTER")))
(setf (iup:callback start-button :action)
(lambda (handle)
(setf (iup:idle-action)
(lambda ()
(unless do-nothing
(setf (iup:attribute counter :title)
(1+ (iup:attribute counter :title 'number))))
iup:+default+))
iup:+default+))
(setf (iup:callback stop-button :action)
(lambda (handle)
(setf (iup:idle-action) nil)
iup:+default+))
(iup:show dialog)
(iup:main-loop))))#-sbcl (idle)
#+sbcl
(sb-int:with-float-traps-masked
(:divide-by-zero :invalid)
(idle))
Canvas
In this example, we’ll port the Sierpinski Carpet fractal that appeared the chapter on graphics in Common Lisp Recipes: A Problem-Solution Approach.
We need a spinner (an up and down arrow-controlled number field) and a
canvas to draw on to get started. In this example, rather than specify
the callbacks inline, as anonymous lamba forms, we will create
separate functions and set them later using (SETF
IUP:CALLBACK). *LEVELS* will keep track how deep to draw the
fractal.
;;; Generated from org-mode, do not edit
(eval-when (:compile-toplevel :load-toplevel :execute)
(ql:quickload '("iup" "iup-cd" "cd")))
(defpackage #:iup-examples.sierpinksi
(:use #:common-lisp)
(:export #:sierpinksi))
(in-package #:iup-examples.sierpinksi)(defparameter *levels* 0)
(defun sierpinski ()
(iup:with-iup ()
(let* ((canvas (iup:canvas :rastersize "200x200"))
(spin (iup:text :spin "YES" :spinmin 0 :spinmax 4))
(vbox (iup:vbox (list canvas spin) :alignment "ACENTER"))
(dialog (iup:dialog vbox :title "Sierpinski Carpet")))
(setf (iup:callback canvas :map_cb) 'canvas-map
(iup:callback canvas :unmap_cb) 'canvas-unmap
(iup:callback canvas :action) 'canvas-redraw
(iup:callback spin :spin_cb) 'canvas-spin
*levels* 0)
(iup:show-xy dialog iup:+center+ iup:+center+)
(iup:main-loop))))Notes on Callback Naming
Each IUP widget supports a number of callbacks. In IUP, these are
strings. In the Lisp bindings, they can be specified as keywords. For
example, :UNMAP_CB. These are rather unlispy names, but do come from
IUP via its introspection mechanism. In a future version of these
bindings, it might be possible to have lispier
names. e.g. :UNMAP-CALLBACK.
CD, a 2D Graphics Library
IUP has support for CD, a cross platform 2D Graphics Library. We have support in Lisp via CD bindings.
The following code is entirely CD dependent and can be used in non-IUP canvas applications.
(defun sierpinski-draw (canvas level)
(multiple-value-bind
(w h)
(cd:size canvas)
(labels ((square (x y x-size y-size)
(cd:box canvas x (+ x x-size) y (+ y y-size)))
(recurse (x y x-size y-size level)
(let ((x-step (/ x-size 3))
(y-step (/ y-size 3)))
(square (+ x x-step) (+ y y-step) x-step y-step)
(when (plusp level)
(dolist (x-next (list x (+ x x-step) (+ x x-step x-step)))
(dolist (y-next (list y (+ y y-step) (+ y y-step y-step)))
(recurse x-next y-next x-step y-step (1- level))))))))
(recurse 0 0 w h level))))For example, we can write it to PDF and print out to hang on your wall:
(ql:quickload "cd-pdf")
(let ((canvas (cd:create-canvas (cd-pdf:context-pdf) "docs/sierpinski.pdf")))
(unwind-protect
(sierpinski-draw canvas 4)
(cd:kill canvas)))In our IUP example however, we’ll use it with IUP’s CD support and
arrange for the canvas to be draw on via CANVAS-REDRAW which will be
triggered by the canvas widget’s action callback.
(defparameter *canvas* nil)
(defun canvas-redraw (handle x y)
(cd:activate *canvas*)
(cd:clear *canvas*)
(setf (cd:foreground *canvas*) cd:+red+)
(sierpinski-draw *canvas* *levels*)
(cd:flush *canvas*)
iup:+default+)We can ignore HANDLE, X, and Y in our callback handler in this
example. Those are IUP widget that triggered the callback and location
on the canvas.
First we activate the canvas to draw on, clear whatever was there, set
a drawing color for the the foreground of the canvas, then draw to the
canvas using SIERPINSKI-DRAW.
The last step is to flush the canvas. This triggers a backing buffer swap, so all of the drawing appears instantly. If we don’t do this, we don’t see anything on the screen because it will still be in the off-screen drawing buffer.
Attributes
It is a good idea to separate your UI presentation from its undelying
model. In our case, the UI “model” is a special variable *LEVELS*
which holds the depth to draw the fractal as an integer. We need this
updated when the user clicks on the spinner widget.
(defun canvas-spin (handle pos)
(setf *levels* (iup:attribute handle :value 'number))
(canvas-redraw nil nil nil)
iup:+default+)We can get the number from the spinner widget and assign it to
*LEVELS* using IUP:ATTRIBUTE. It takes a IUP handle from which to
get the :VALUE attribute.
IUP widget value attributes are mostly strings. The third argument,
~’INTEGER~ converts the string to an integer for convenience, rather
than having to PARSE-INTEGER ourselves.
Fiddly bits
Lastly, we need to associate the CD canvas with a IUP canvas, but we
can’t do this until we have the handle of the IUP canvas, so we can’t
set it up in the LET* form in our main function like we did with
everything else.
Luckily IUP provides callbacks for when the component is “mapped” onto the user’s display which allow us to deal with this dependency in an elegant manner.
(defun canvas-map (handle)
(setf *canvas* (cd:create-canvas (iup-cd:context-iup-dbuffer) handle))
iup:+default+)
(defun canvas-unmap (handle)
(cd:kill *canvas*)
iup:+default+)#-sbcl (sierpinski)
#+sbcl
(sb-int:with-float-traps-masked
(:divide-by-zero :invalid)
(sierpinski))
Using IUP Additional Controls
The cells control “creates a grid widget (set of cells) that enables several application-specific drawing, such as: chess tables, tiles editors, degrade scales, drawable spreadsheets and so forth”.
It’s included in the standard IUP distribution downloads, but it’s not
automatically loaded. The Lisp bindings do the same thing, so to use
it, we need to depend on IUP-CONTROLS.
;;; Generated from org-mode, do not edit
(eval-when (:compile-toplevel :load-toplevel :execute)
(ql:quickload '("iup" "iup-controls" "cd")))
(defpackage #:iup-examples.cells-checkerboard
(:use #:common-lisp)
(:export #:cells-checkerboard))
(in-package #:iup-examples.cells-checkerboard)We start with the same boiler plate, but this time we need to call
IUP-CONTROLS:OPEN ahead of using the cells control.
(defun cells-checkerboard ()
(iup:with-iup ()
(iup-controls:open)
(let* ((cells (iup-controls:cells
:draw_cb 'draw
:width_cb 'width
:height_cb 'height
:nlines_cb 'nlines
:ncols_cb 'ncols
:mouseclick_cb 'click))
(vbox (iup:vbox (list cells)))
(dialog (iup:dialog vbox :title "Cells Checkerboard" :rastersize "440x480" :shrink "YES")))
(iup:show-xy dialog iup:+center+ iup:+center+)
(iup:main-loop))))Cells has a number of callbacks related rows, columns, sizing etc.
(defun nlines (handle) 8)
(defun ncols (handle) 8)
(defun height (handle i) 50)
(defun width (handle j) 50)When DRAW is called, we get a canvas on which to draw:
(defun draw (handle i j xmin xmax ymin ymax canvas)
(if (or (and (oddp i) (oddp j)) (and (oddp (1+ i)) (oddp (1+ j))))
(setf (cd:foreground canvas) cd:+black+)
(setf (cd:foreground canvas) cd:+white+))
(cd:box canvas xmin xmax ymin ymax)
iup::+default+)When out click callback is called:
(defun click (handle button pressed line column x y status)
(iup:message
"Clicked!"
(format nil "Callback arguments~%~S"
(list :button button
:pressed pressed
:line line
:column column
:x x
:y y
:status (iup:status-plist status))))
iup:+default+)#-sbcl (cells-checkerboard)
#+sbcl
(sb-int:with-float-traps-masked
(:divide-by-zero :invalid)
(cells-checkerboard))
(lol button 49)
Detachable Box
;;; Generated from org-mode, do not edit
(eval-when (:compile-toplevel :load-toplevel :execute)
(ql:quickload "iup"))
(defpackage #:iup-examples.detached
(:use #:common-lisp)
(:export #:detached))
(in-package #:iup-examples.detached)(defun detached ()
(iup:with-iup ()
(let* ((button1 (iup:button :title "Detach Me!"
:action 'button-detach-callback
:expand :yes
:handlename "detach"))
(multi-line (iup:multi-line :expand :yes
:visiblelines 5))
(hbox (iup:hbox (list button1 multi-line) :margin "10x0"))
(dbox (iup:detach-box hbox :orientation :vertical
:detached_cb 'detached-callback
:handlename "dbox"))
(label (iup:label :title "Label"
:expand :vertical))
(button2 (iup:button :title "Restore me!"
:expand :yes
:active :no
:action 'button-restore-callback
:handlename "restore"))
(text (iup:text :expand :horizontal))
(dialog (iup:dialog (iup:vbox (list dbox label button2 text)
:margin "10x10"
:gap 10)
:title "IupDetachBox Example"
:rastersize "300x300")))
(iup:show dialog)
(iup:main-loop))))Handle Names
Instead of accessing other elements via lexical scope, it’s sometimes
useful to refer to them by name. This example uses the HANDLENAME
attribute to associate a name with an IUP handle.
(defun detached-callback (handle new-parent x y)
(setf (iup:attribute new-parent :title) "New Dialog"
(iup:attribute (iup:handle "restore") :active) :yes
(iup:attribute (iup:handle "detach") :active) :no)
iup:+default+)
(defun button-restore-callback (button)
(setf (iup:attribute (iup:handle "dbox") :restore) nil
(iup:attribute button :active) :no
(iup:attribute (iup:handle "detach") :active) :yes)
iup:+default+)
(defun button-detach-callback (button)
(setf (iup:attribute (iup:handle "dbox") :detach) nil
(iup:attribute button :active) :no
(iup:attribute (iup:handle "restore") :active) :yes)
iup:+default+)#-sbcl (detached)
#+sbcl
(sb-int:with-float-traps-masked
(:divide-by-zero :invalid)
(detached))
Tabs Example
Demonstrates the use of (SETF IUP:ATTRIBUTE) for setting attributes
not available via control’s constructor function.
;;; Generated from org-mode, do not edit
(eval-when (:compile-toplevel :load-toplevel :execute)
(ql:quickload "iup"))
(defpackage #:iup-examples.tabs
(:use #:common-lisp)
(:export #:tabs))
(in-package #:iup-examples.tabs)(defun tabs ()
(iup:with-iup ()
(let* ((vbox1 (iup:vbox
(list (iup:label :title "Inside Tab A")
(iup:button :title "Button A"))))
(vbox2 (iup:vbox
(list (iup:label :title "Inside Tab B")
(iup:button :title "Button B"))))
(tabs1 (iup:tabs (list vbox1 vbox2)))
(vbox3 (iup:vbox
(list (iup:label :title "Inside C")
(iup:button :title "Button C"))))
(vbox4 (iup:vbox
(list (iup:label :title "Inside D")
(iup:button :title "Button D"))))
(tabs2 (iup:tabs (list vbox3 vbox4)))
(box (iup:hbox (list tabs1 tabs2) :margin "10x10" :gap "10"))
(dialog (iup:dialog box :title "IUP Tabs" :size "200x80")))
(setf (iup:attribute vbox1 :tabtitle) "Tab A"
(iup:attribute vbox2 :tabtitle) "Tab B"
(iup:attribute vbox3 :tabtitle) "Tab C"
(iup:attribute vbox4 :tabtitle) "Tab D")
(iup:show dialog)
(iup:main-loop))))#-sbcl (tabs)
#+sbcl
(sb-int:with-float-traps-masked
(:divide-by-zero :invalid)
(tabs))
Plotting
Example ./examples/plot.lisp
OpenGL
For this example, we’ll take advantage for cl-opengland and cl-glu. Don’t forget to depend on iup-gl (part of these bindings) as well.
Much of this example is tedious old-style OpenGL. We’ll only highlight
the IUP/OpenGL integration points here. It suffices to say, we’ve got
a function CUBE which draws OpenGL things to the current buffer.
;;; Generated from org-mode, do not edit
(eval-when (:compile-toplevel :load-toplevel :execute)
(ql:quickload '("iup" "iup-gl" "cl-opengl" "cl-glu")))
(defpackage #:iup-examples.cube
(:use #:common-lisp)
(:export #:cube))
(in-package #:iup-examples.cube)(defvar *canvas* nil)
(defvar *tt* 0.0)
(defvar *vertices*
#((-1 -1 1) (-1 1 1)
(1 1 1) (1 -1 1)
(-1 -1 -1) (-1 1 -1)
(1 1 -1) (1 -1 -1)))
(defun polygon (a b c d)
(gl:begin :polygon)
(apply #'gl:vertex (aref *vertices* a))
(apply #'gl:vertex (aref *vertices* b))
(apply #'gl:vertex (aref *vertices* c))
(apply #'gl:vertex (aref *vertices* d))
(gl:end))
(defun color-cube ()
(gl:color 1 0 0)
(gl:normal 1 0 0)
(polygon 2 3 7 6)
(gl:color 0 1 0)
(gl:normal 0 1 0)
(polygon 1 2 6 5)
(gl:color 0 0 1)
(gl:normal 0 0 1)
(polygon 0 3 2 1)
(gl:color 1 0 1)
(gl:normal 0 -1 0)
(polygon 3 0 4 7)
(gl:color 1 1 0)
(gl:normal 0 0 -1)
(polygon 4 5 6 7)
(gl:color 0 1 1)
(gl:normal -1 0 0)
(polygon 5 4 0 1))(defun cube ()
(iup:with-iup ()
(iup-gl:open)
(setf *canvas*
(iup-gl:canvas :rastersize "640x480"
:buffer "DOUBLE"
:action 'repaint
:resize_cb 'resize))
(let* ((dialog (iup:dialog *canvas* :title "IUP OpenGL")))
;; FIXME (iup-cffi::%iup-set-function :idle_action 'idle)
(setf (iup:attribute *canvas* :depthsize) "16")
(iup:show dialog)
(iup:main-loop))))Our example has three callbacks: repaint, resize and a global idle
function callback which we’ll use to rotate a cube relative to time
variable *TT*.
(defun repaint (handle posx posy)
(iup-gl:make-current handle)
(gl:clear-color 0.3 0.3 0.3 1.0)
(gl:clear :color-buffer-bit :depth-buffer-bit)
(gl:enable :depth-test)
(gl:matrix-mode :modelview)
(gl:with-pushed-matrix
(gl:translate 0 0 0)
(gl:scale 1 1 1)
(gl:rotate *tt* 0 0 1)
(color-cube))
(iup-gl:swap-buffers handle)
iup::+default+)
(defun resize (handle width height)
(iup-gl:make-current handle)
(gl:viewport 0 0 width height)
(gl:matrix-mode :modelview)
(gl:load-identity)
(gl:matrix-mode :projection)
(gl:load-identity)
(glu:perspective 60 (/ 4 3) 1 15)
(glu:look-at 3 3 3 0 0 0 0 0 1)
iup::+default+);;; FIXME
;; (cffi:defcallback idle-cb :int ()
;; (incf tt)
;; (iup-gl:make-current canvas)
;; (repaint canvas)
;; iup::+default+)#-sbcl (cube)
#+sbcl
(sb-int:with-float-traps-masked
(:divide-by-zero :invalid)
(cube))
Trees
This is a port of the Lua tree example from the IUP documentation. It goes one step further by allowing the tree to be expanded recursively as branches open.
;;; Generated from org-mode, do not edit
(eval-when (:compile-toplevel :load-toplevel :execute)
(ql:quickload '("iup" "iup-controls" "uiop")))
(defpackage #:iup-examples.tree
(:use #:common-lisp)
(:export #:tree))
(in-package #:iup-examples.tree)(defun get-dir (pathname)
(assert (uiop:directory-pathname-p pathname))
(loop for pathname in (uiop:directory* (make-pathname :name :wild :defaults pathname))
if (uiop:directory-pathname-p pathname)
collect pathname into dirs
else
collect pathname into files
finally (return (values dirs files))))
(defun fill-tree (tree id pathname)
(multiple-value-bind
(dirs files)
(get-dir pathname)
(dolist (file files)
(setf (iup:attribute tree :addleaf) (namestring file)))
(dolist (dir dirs)
(setf (iup:attribute tree :addbranch) (namestring dir)))
(setf (iup:attribute tree :title) (namestring pathname))))(defun map-callback (handle)
(fill-tree handle 0 "/")
iup:+default+)
(defun branchopen-callback (handle id)
(setf (iup:attribute handle (format nil "DELNODE~A" id)) "CHILDREN")
(fill-tree handle id (iup:attribute handle (format nil "TITLE~A" id)))
iup:+default+)
(defun tree ()
(iup:with-iup ()
(let* ((tree (iup:tree :minsize "200x300"
:map_cb 'map-callback
:branchopen_cb 'branchopen-callback))
(dialog (iup:dialog tree :title "Tree Example")))
(iup:show dialog)
(iup:main-loop))))#-sbcl (tree)
#+sbcl
(sb-int:with-float-traps-masked
(:divide-by-zero :invalid)
(tree))
Built-in Dialogs
IUP includes a number of dialogs, including one that embeds the Scintilla editor control.
;;; Generated from org-mode, do not edit
(eval-when (:compile-toplevel :load-toplevel :execute)
(ql:quickload '("iup" "iup-scintilla")))
(defpackage #:iup-examples.dialogs
(:use #:common-lisp)
(:export #:dialogs))
(in-package #:iup-examples.dialogs)(defun dialogs ()
(iup:with-iup ()
(iup-scintilla:open)
(flet ((button (title callback)
(iup:button :title title
:action callback
:expand :horizontal)))
(let* ((dialog (iup:dialog
(iup:vbox (list (button "File Dialog" 'file-dialog)
(button "Message Dialog" 'message-dialog)
(button "Color Dialog" 'color-dialog)
(button "Font Dialog" 'font-dialog)
(button "Scintilla Dialog" 'scintilla-dialog)
(button "Layout Dialog" 'layout-dialog)))
:title "IUP Predefined Dialogs")))
(iup:show dialog)
(iup:main-loop)))))
Using IUP:POPUP for Modal Dialogs
Often a UI designs for grabbing the user’s attention via modal dialogs
where the dialog is shown above the rest of the application and
prevents interaction with the rest of the application. IUP:POPUP
lets you achive this.
File Dialog
(defun file-dialog (handle)
(let ((dialog (iup:file-dialog)))
(unwind-protect
(progn
(iup:popup dialog iup:+center+ iup:+center+)
(iup:message "File Dialog Example"
(format nil "Selected ~A" (iup:attribute dialog :value))))
(iup:destroy dialog)))
iup:+default+)NOTE: Because modal dialogs are often created over the course of a
program’s runtime, they need to be destroyed after use, via
IUP:DESTROY.
Message Dialog
Message dialogs are like IUP:MESSAGE except that they allow for more
configuration (result buttons, etc.).
(defun message-dialog (handle)
(let ((dialog (iup:message-dialog
:dialogtype :warning
:buttons :retrycancel)))
(unwind-protect
(progn
(setf (iup:attribute dialog :value) "Heap exhausted, game over.")
(iup:popup dialog iup:+center+ iup:+center+)
(iup:message "Message Dialog"
(format nil "Got button response ~S"
(iup:attribute dialog :buttonresponse))))
(iup:destroy dialog)))
iup:+default+)
Color Dialog
(defun color-dialog (handle)
(let ((dialog (iup:color-dialog
:title "IUP Color Dialog"
:showhex "YES"
:showcolortable "YES"
:showalpha "YES")))
(unwind-protect
(progn
(iup:popup dialog iup:+center+ iup:+center+)
(iup:message "Result"
(format nil "Got button response ~S~%Got color ~A RGB (~A HSI, ~A)"
(iup:attribute dialog :status)
(iup:attribute dialog :value)
(iup:attribute dialog :valuehsi)
(iup:attribute dialog :valuehex))))))
iup:+default+)
Font Dialog
(defun font-dialog (handle)
(let ((dialog (iup:font-dialog :title "IUP Font Dialog")))
(unwind-protect
(progn
(iup:popup dialog iup:+center+ iup:+center+)
(iup:message "Result"
(format nil "Got button response ~S~%Got font ~S"
(iup:attribute dialog :status)
(iup:attribute dialog :value))))
(iup:destroy dialog)))
iup:+default+)
Scintilla Dialog
(defun scintilla-dialog (handle)
(let ((dialog (iup-scintilla:scintilla-dialog :title "IUP Scintilla Dialog")))
(unwind-protect
(iup:popup dialog iup:+center+ iup:+center+)
(iup:destroy dialog))))
(There is also a separate, more customizable Scintilla control:
IUP-SCINTILLA:SCINTILLA.)
IUP Layout Dialog
The layout dialog lets you visually inspect and edit an existing dialog and it’s children or create a new dialog from scretch. It is extremely useful for experimenting and iterating on UI design.
You can use it as a visual GUI builder, similar to Glade in GTK+.
You can export a dialog and load it from file via IUP:LOAD. The
export format is a IUP LED file.
(defun layout-dialog (handle)
(let ((dialog (iup:layout-dialog nil)))
(unwind-protect
(iup:popup dialog iup:+center+ iup:+center+)
(iup:destroy dialog)))
iup:+default+)
Get Text Dialog
List Dialog
Get Param Dialog
Alarm Dialog
#-sbcl (dialogs)
#+sbcl
(sb-int:with-float-traps-masked
(:divide-by-zero :invalid)
(dialogs))Application Icons and IUP-IM
In this example, we’ll set the application icon via an arbitrary image
file, demonstrating the use of the IUP-IM system. The IM-IUP
system provides support in our IUP bindings for interoperability with
IM, an imaging toolkit, also by Tecgraf.
;;; Generated from org-mode, do not edit
(eval-when (:compile-toplevel :load-toplevel :execute)
(ql:quickload '("iup" "iup-im")))
(defpackage #:iup-examples.icon
(:use #:common-lisp)
(:export #:icon))
(in-package #:iup-examples.icon)Here we load an image from the filesystem using IUP-IM:LOAD-IMAGE
and associate the global handle name lispalien with it. We can use
this handle name in labels, buttons, etc. to set the image that should
be used. In the case of dialogs however, we can use the handle name to
specify the image that should be displayed in the application’s title
bar.
IM supports a large number of formats. Here we use a .ICO file.
(defun icon ()
(iup:with-iup ()
(let ((icon (iup-im:load-image (asdf:system-relative-pathname "iup" "examples/lispalien.ico"))))
(setf (iup:handle "lispalien") icon))
(let* ((label (iup:flat-label :image "lispalien" :expand :yes))
(dialog (iup:dialog label :title "Icon from File"
:icon "lispalien"
:size "THIRDxTHIRD")))
(iup:show dialog)
(iup:main-loop))))#-sbcl (icon)
#+sbcl
(sb-int:with-float-traps-masked
(:divide-by-zero :invalid)
(icon))
Drag and Drop
File Drag and Drop from Applications
;;; Generated from org-mode, do not edit
(eval-when (:compile-toplevel :load-toplevel :execute)
(ql:quickload '("iup" "ironclad")))
(defpackage #:iup-examples.drophash
(:use #:common-lisp)
(:export #:drophash))
(in-package #:iup-examples.drophash)This example demonstrates how to receive files via a drag and drop operation from another other application as well as sliding box layout and techniques for keeping the UI responsive during computationally intensive operations.
We’ll create a simple GUI wrapper for computing file digests using Ironclad, a cryptographic toolkit written in Common Lisp. The drop down lists all the digest algorithms Ironclad supports, and a label will be used to receive file drops. Once the digest is computed, they are appended to a result panel.
(defun drophash ()
(iup:with-iup ()
(let* ((list (iup:list :dropdown :yes
:expand :horizontal
:handlename "list"))
(label (iup:flat-label :title "Drop files for hash"
:alignment "ACENTER:ACENTER"
:font "Helvetica, 24"
:dropfilestarget :yes
:dropfiles_cb 'drop-files-callback
:expand :yes))
(frame (iup:frame label))
(results (iup:multi-line :expand :yes
:readonly :yes
:visiblelines 7
:handlename "results"))
(vbox (iup:vbox (list list
frame
(iup:sbox results :direction :north))
:margin "10x10"
:cgap 5))
(dialog (iup:dialog vbox
:title "Drop Hash"
:size "HALFxHALF")))
(loop for digest in (ironclad:list-all-digests)
for i from 1
do (setf (iup:attribute list i) digest)
finally (setf (iup:attribute list :valuestring) 'ironclad:sha256))
(iup:show dialog)
(iup:main-loop))))When files are dropped onto the drop target (in this case, an IUP flat label), the drop files callback is called. If multiple files are dropped at the same time, then the callback will be invoked for each file.
(defun drop-files-callback (handle filename num x y)
(let* ((digest
(intern (iup:attribute (iup:handle "list") :valuestring) "IRONCLAD"))
(digest-hex
(ironclad:byte-array-to-hex-string
(ironclad:digest-file digest
filename))))
(setf (iup:attribute (iup:handle "results") :append)
(format nil "~A ~A" filename digest-hex)))
(iup:flush)
iup:+default+)When multiple files are dropped, the callback will be invoked in rapid
succession and the UI will seem unresponsive. This is why the example
calls IUP:FLUSH after each file is processed. IUP:FLUSH will run
any pending UI operations (such as the append to the results text
box).
This helps, and indeed the results pane updates in real-time as files are processed, however the UI will become unresponsive again when the digest of large files are computed.
It is best not to do any computationally expensive operations in the UI thread. We’ll cover off-loading from the UI thread as well as revisit this example for better responsiveness later.
#-sbcl (drophash)
#+sbcl
(sb-int:with-float-traps-masked
(:divide-by-zero :invalid)
(drophash))
Examples
Checkout the examples directory for the examples in this document as well as these other examples.
LTK Demonstration Port
Includes example usage of IUP:TIMER for canvas animations.
Bindings Generation Internals
There are dozens of IUP controls and each control has dozens of callbacks and attributes. Fortunately IUP controls can be introspected to gain information on what the control is, what its callbacks and attributes are (and their arguments and types).
The iup-classesdb system uses this information to to automatically
generate binding metadata from which the bindings are generated. This
provides for a much nicer development experience:
The following sections describe how this works in more detail.
Maintainer
The maintainer is typically someone with access to the Git repository for these bindings. When a new release of IUP comes out, the maintainer needs to update the metadata so that any new or removed controls, attributes or callbacks are reflected in the Lisp bindings:
(*) --> "(asdf:load-system :iup-classesdb)" as Load
Load --> "(iup-classesdb:regenerate)" as Regen
Regen --> "classesdb.lisp-sexp" as Sexp
Sexp --> (*)
~classesdb.lisp-sexp~ is the output metadata. The maintainer typically commits this file to version control so the metadata is available for everyone.
User
The first time the user compiles the IUP bindings,
classesdb.lisp-sexp is processed by macros at compile time and
generates all function definitions for IUP controls. Note, that
classesdb.lisp-sexpr is not actually needed when the user loads the
system.
For the curious, the generation looks like the following, for each IUP
system: IUP, IUP-CONTROLS, IUP-GL, IUP-GLCONTROLS, IUP-PLOT,
IUP-MGLPLOT, IUP-OLECONTROL, IUP-SCINTILLA, IUP-WEB and
IUP-TUIO.
(iup::defiupclasses "IUP")The process is roughly:
- load each shared library
- introspect for the available IUP classes (i.e. metadata about controls) availabe
- For each class, generate the bindings in its own package.
(*) --> "(asdf:compile-system :iup)" as Load
"classesdb.lisp-sexp" as Sexpr --> Load
Load --> (*)(*) --> "(asdf:load-system :iup)" as Load
Load --> (*)
Why classesdb.lisp-sexp?
Extracting the metadata actually requires a complete GUI stack running. On Linux, this means having an X11 display available. This turns out to be a bit of a problem for continuous integration systems.
Although there are embedded X11 servers that can be used, I didn’t
know what might be necessary for Windows or even macOS (when it’s
supported) for CI/CD. Hence the classesdb.lisp-sexp is the
maintainer’s job to regenerate when necessary.
Example IUP 3.25 to 3.26
Among other changes, IUP 3.26 introduced IupMultiBox as a new control
container with 19 attributes and defaults. Regenerating
classesdb.lisp-sexp automatically collected these changes so that
the corresponding Lisp function IUP:MULTIBOX is created and exported
automatically from the IUP package.
Interactive Development
TBD