Skip to content


Folders and files

Last commit message
Last commit date

Latest commit


Repository files navigation

Common Lisp CFFI bindings to the IUP Portable User Interface library




IUP 3.29


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.

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;

To tell CFFI to find these libraries, use:

(ql:quickload "cffi")

(pushnew (asdf:system-relative-pathname :tecgraf-libs #p"libs/")

Loading IUP

(First, read the previous part on getting the Tecgraf libraries and installing).


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"
           (dialog (iup:dialog label :title "Hello, World!")))
      (iup:show dialog)
#-sbcl (hello)

    (:divide-by-zero :invalid)

./docs/screenshots/helloworld.png ./docs/screenshots/helloworld-2.png


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:button :title "Test &2"
                         :expand :yes
                         :tip "Callback set later using (SETF (IUP:CALLBACK ..) ..)"))
             (iup:button :title "Test &3"
                         :expand :yes
                         :tip "Callback example using symbol-referenced function at control creation"
                         :action 'test3-callback))
             (iup:button :title "Test &4"
                         :expand :yes
                         :tip "Callback example using symbol-referenced function later using (SETF (IUP:CALLBACK ..) ..)"))
             (iup:vbox (list button1 button2 button3 button4)
                       :gap "10"
                       :margin "10x10"
                       :alignment :acenter))
             (iup:dialog vbox :title "Callback Example")))
      (setf (iup:callback button2 :action)
            (lambda (handle)
              (message "button2's action callback")
      (setf (iup:callback button4 :action) 'test4-callback)
      (iup:show dialog)

(defun test3-callback (handle)
  (message "button3's action callback")

(defun test4-callback (handle)
  (message "button4's action callback")

(defun message (message)
  (iup:message "Callback Example" message))
#-sbcl (callback)

    (:divide-by-zero :invalid)

./docs/screenshots/callback-1.png ./docs/screenshots/callback-2.png

./docs/screenshots/callback-3.png ./docs/screenshots/callback-4.png

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

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

#-sbcl (mixer)

    (:divide-by-zero :invalid)



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))
           (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))))
      (setf (iup:callback stop-button :action)
            (lambda (handle)
              (setf (iup:idle-action) nil)
      (iup:show dialog)
#-sbcl (idle)

    (:divide-by-zero :invalid)




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

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)
        (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")))
       (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*)

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.


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)

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

(defun canvas-unmap (handle)
  (cd:kill *canvas*)
#-sbcl (sierpinski)

    (:divide-by-zero :invalid)

./docs/screenshots/sierpinski.png ./docs/screenshots/sierpinski-02.png

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

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)

When out click callback is called:

(defun click (handle button pressed line column x y status)
   (format nil "Callback arguments~%~S"
    (list :button button
          :pressed pressed
          :line line
          :column column
          :x x
          :y y
          :status (iup:status-plist status))))
#-sbcl (cells-checkerboard)

    (:divide-by-zero :invalid)

./docs/screenshots/checkerboard-01.png ./docs/screenshots/checkerboard-02.png

./docs/screenshots/checkerboard-03.png ./docs/screenshots/checkerboard-04.png

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

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)

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

(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)
#-sbcl (detached)

    (:divide-by-zero :invalid)

./docs/screenshots/detach-01.png ./docs/screenshots/detach-02.png

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)
#-sbcl (tabs)

    (:divide-by-zero :invalid)

./docs/screenshots/tabs-01.png ./docs/screenshots/tabs-02.png


Example ./examples/plot.lisp




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

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

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:translate 0 0 0)
    (gl:scale 1 1 1)
    (gl:rotate *tt* 0 0 1)
  (iup-gl:swap-buffers handle)

(defun resize (handle width height)
  (iup-gl:make-current handle)
  (gl:viewport 0 0 width height)
  (gl:matrix-mode :modelview)
  (gl:matrix-mode :projection)
  (glu:perspective 60 (/ 4 3) 1 15)
  (glu:look-at 3 3 3 0 0 0 0 0 1)
;; (cffi:defcallback idle-cb :int ()
;;   (incf tt)
;;   (iup-gl:make-current canvas)
;;   (repaint canvas)
;;   iup::+default+)
#-sbcl (cube)

    (:divide-by-zero :invalid)




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
          collect pathname into files
        finally (return (values dirs files))))

(defun fill-tree (tree id pathname)
        (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 "/")

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

(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)
#-sbcl (tree)

    (:divide-by-zero :invalid)


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

./docs/screenshots/dialogs-01.png ./docs/screenshots/dialogs-02.png

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)))
           (iup:popup dialog iup:+center+ iup:+center+)
           (iup:message "File Dialog Example"
                        (format nil "Selected ~A" (iup:attribute dialog :value))))
      (iup:destroy dialog)))

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.

./docs/screenshots/filedialog-01.png ./docs/screenshots/filedialog-02.png

./docs/screenshots/filedialog-03.png ./docs/screenshots/filedialog-04.png

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

./docs/screenshots/messagedialog-01.png ./docs/screenshots/messagedialog-02.png

./docs/screenshots/messagedialog-03.png ./docs/screenshots/messagedialog-04.png

Color Dialog

(defun color-dialog (handle)
  (let ((dialog (iup:color-dialog
                 :title "IUP Color Dialog"
                 :showhex "YES"
                 :showcolortable "YES"
                 :showalpha "YES")))
           (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))))))

./docs/screenshots/colordialog-01.png ./docs/screenshots/colordialog-02.png

./docs/screenshots/colordialog-03.png ./docs/screenshots/colordialog-04.png

Font Dialog

(defun font-dialog (handle)
  (let ((dialog (iup:font-dialog :title "IUP Font Dialog")))
           (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)))

./docs/screenshots/fontdialog-01.png ./docs/screenshots/fontdialog-02.png

./docs/screenshots/fontdialog-03.png ./docs/screenshots/fontdialog-04.png

Scintilla Dialog

(defun scintilla-dialog (handle)
  (let ((dialog (iup-scintilla:scintilla-dialog :title "IUP Scintilla Dialog")))
         (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)))
         (iup:popup dialog iup:+center+ iup:+center+)
      (iup:destroy dialog)))



Get Text Dialog

List Dialog

Get Param Dialog

Alarm Dialog

#-sbcl (dialogs)

    (:divide-by-zero :invalid)

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)
#-sbcl (icon)

    (:divide-by-zero :invalid)

./docs/screenshots/icon-01.png ./docs/screenshots/icon-02.png

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

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"))
           (ironclad:digest-file digest
    (setf (iup:attribute (iup:handle "results") :append)
          (format nil "~A     ~A" filename digest-hex)))

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)

    (:divide-by-zero :invalid)




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.


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.


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:

  1. load each shared library
  2. introspect for the available IUP classes (i.e. metadata about controls) availabe
  3. 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



Common Lisp CFFI bindings to the IUP Portable User Interface library (pre-ALPHA)








No releases published


No packages published