Learn Clojure by Example: JavaFX GUI with Cljfx

Clojure is a dialect of Lisp that runs on the JVM. JavaFX is a modern GUI toolkit for the JVM. You could use JavaFX directly with Clojure's Java interop, but Cljfx provides a declarative and functional wrapper for JavaFX. Instead of building yet another calculator, we're going to use Cljfx to build a GUI for generating a tone.

You'll need Clojure installed. We also need a way to pull the Cljfx dependency into our app. It seems deps.edn would be the easiest way to accomplish this for a short tutorial example such as this, but I develop on Debian and found that the new command line tools for Clojure that enable this haven't made it into Debian yet. I could install Clojure from the Clojure website, but the point of this tutorial is to be easy to follow by someone not familiar with Clojure. It's a lot easier to direct a person to apt install clojure (or whatever package manager your preferred distro uses). This tutorial is a living document maintained on GitHub along with the example code. Whenever the Clojure command line tools become available on Debian, it's possible I'll revisit this tutorial and update it.

The Clojure build tool Leiningen is capable of managing dependencies (and a whole lot more). There is also a build tool for Clojure called Boot. I found more plentiful tutorials and beginner resources for Leiningen, plus Leiningen is available as a Debian package, so for this tutorial, Leiningen it is. Install Clojure and Leiningen from your distro's repo. Debian also has an OpenJFX package, but Leiningen was able to pull OpenJFX in as a dependency of Cljfx. The version pulled in by Leiningen is probably more up to date than whatever might be sitting in your distro's repos.

After that, we need to create a Leiningen project directory. This can be accomplished with lein new app bleep, but that created a directory full of subdirectories and files that were unnecessary for a short little example like this. I created the directory structure (mkdir -p cljfx/src/bleep) and created cljfx/project.clj and cljfx/src/bleep/core.clj with the minimum needed to create a window with Cljfx.

project.clj

(defproject bleep "0.1.0-SNAPSHOT"
  :dependencies [[org.clojure/clojure "1.10.0"]
                 [cljfx "1.7.12"]
                 [com.jsyn/jsyn "20170815"]]
  :main bleep.core)

core.clj

(ns bleep.core
  (:gen-class)
  (:require [cljfx.api :as fx])
  (:import [javafx.application Platform]
           [com.jsyn JSyn]
           [com.jsyn.unitgen LineOut SineOscillator]))

(defn hello-world [& args]
  {:fx/type :label
   :text "Hello, World!"})

(defn root [& args]
  {:fx/type :stage
   :showing true
   :title "Bleep"
   :scene {:fx/type :scene
           :root {:fx/type :v-box
                  :padding 25
                  :spacing 40
                  :children [{:fx/type hello-world}]}}})

(def renderer
  (fx/create-renderer))

(defn -main [& args]
  (Platform/setImplicitExit true)
  (renderer {:fx/type root}))

The project file (project.clj) is the file that tells Leiningen about your project (such as its dependencies). Typically with Leiningen, your code will live in the src subdirectory in a subdirectory that matches the top-level namespace of your project. All this can be changed with your project.clj, but we'll be sticking to convention for this example. In this subdirectory is core.clj.

Begin the file with a namespace declaration. The namespace should have a (:gen-class) declaration in the ns form at the top for Leiningen. Since we'll be using Cljfx to create our GUI, we need to require it. We'll mostly be using JavaFX via Cljfx, but you can also access JavaFX classes directly. Let's import (a way to get Java code into Clojure) the JavaFX Platform class. We'll also import the Java JSyn library for use later in generating the tone.

Leiningen needs a -main function (note the leading dash is part of the function name). This is the function that will get called when you run your app with Leiningen or when you compile it to a standalone JAR. We use the setImplicitExit method from the JavaFX Platform class to make sure the JavaFX runtime shuts down when the window is closed.

Cljfx is declarative instead of imperative or object oriented like many GUI libraries. You describe the layout with a map of key-value pairs instead of creating controls with methods or functions. The :fx/type key has a value of a kebab-cased keyword derived from a JavaFX class name. The other keys of the map are the kebab-cased properties of that class. You can refer to the JavaFX documentation for a list of classes and their properties. JavaFX is well documented and has a large number of controls available.

JavaFX defines the user interface by means of a stage and a scene. The stage is the top-level JavaFX container (the window). The scene is the container for all content. To add a JavaFX class to the map, you convert the class name to kebab-case. For example, JavaFX has a VBox pane used to lay out controls vertically. This would be written :v-box in the Cljfx map. The VBox class has a padding property. We can set this to 25 by adding a :padding key to the map with a value of 25.

Cljfx provides a renderer function created with fx/create-renderer that you pass the map describing your user interface to. You can call renderer multiple times to dynamically change the GUI. Now let's replace the Hello World label with a slider:

(defn frequency-slider [{:keys [frequency]}]
  {:fx/type :slider
   :min 20
   :max 20000
   :value frequency})

Instead of placing the definition of your entire UI into one big map, you can compose the UI from reusable functions. This also makes your code more readable, because you don't have a deeply nested map. These functions can be used just like any other JavaFX class. The :fx/type key is the function name, and the other keys of the map are the arguments to the function. We can add the frequency-slider we created above to the :children vector of the :v-box in the root map like this:

[{:fx/type frequency-slider
  :frequency 440}]

The range of frequencies audible by humans is typically between 20 Hz and 20 KHz (we lose the ability to hear some of those higher frequencies as we age). The musical note A above middle C is 440 Hz. Since A4 serves as a general tuning standard, it seems like a sensible default, but if you run the above with lein run, this is what you'll see:

The scale of 20 to 20,000 is so large that 440 doesn't appear to move the slider at all. Ideally, 440 would fall about the middle of the slider. To achieve this, let's use a logarithmic scale.

I found a Stack Overflow answer on how to map a slider to a logarithmic scale. The code given in the answer is JavaScript, but it was easy enough to port to Clojure.

; Scale used by slider
(def min-position 0)
(def max-position 2000)
; Range of frequencies
(def min-frequency 20)
(def max-frequency 20000)

; Logarithmic scale for frequency (so middle A [440] falls about in the middle)
; Adapted from https://stackoverflow.com/questions/846221/logarithmic-slider

(def min-freq (Math/log min-frequency))
(def max-freq (Math/log max-frequency))
(def frequency-scale (/ (- max-freq min-freq) (- max-position min-position)))
; Convert slider position to frequency
(defn position->frequency [position]
  (int (Math/round (Math/exp (+ min-freq (* frequency-scale (- position min-position)))))))
; Convert frequency to slider position
(defn frequency->position [freq]
  (int (Math/round (/ (- (Math/log freq) min-freq) (+ frequency-scale min-position)))))

I added some global parameters to the top of the script. I came up with the range of 0-2,000 by trial and error. It seemed to strike the best balance between each step of the slider making a noticeable change to the frequency while still allowing the user to narrow in on a specific frequency with just the slider.

Then we create two functions: one that takes the position on the slider and returns the frequency (position->frequency) and another that takes a frequency and returns the position on the slider (frequency-position). Now let's set the initial position of our slider with the frequency->position function:

(defn frequency-slider [{:keys [frequency]}]
  {:fx/type :slider
   :min min-position
   :max max-position
   :value (frequency->position frequency)})

Underneath the slider is a text field showing the current frequency.

(defn frequency-controls [{:keys [frequency]}]
  {:fx/type :h-box
   :alignment :center
   :spacing 20
   :children [{:fx/type :h-box
               :alignment :center
               :spacing 5
               :children [{:fx/type :text-field
                           :text (str frequency)}
                          {:fx/type :label
                           :text "Hz"}]}]})

Add this to the :children vector of the :v-box in the root map:

[{:fx/type frequency-slider
  :frequency frequency}
 {:fx/type frequency-controls
  :frequency frequency}]

At this point, we are starting to have a nice looking interface, but it doesn't do anything. If you slide the slider, nothing happens. If your experience is mostly with object-oriented GUI libraries, the way Cljfx does things will be a little unfamiliar. If you've used the JavaScript library React, it employs a similar model. Global state is stored in an atom. When you update that atom, all the relevant controls are updated accordingly.

; Cljfx global state
(def *state
  (atom {:frequency 440}))

Add middleware to the renderer that maps incoming data from the global state atom to the component description to be rendered:

(def renderer
  (fx/create-renderer
    :middleware (fx/wrap-map-desc assoc :fx/type root)))

Then modify -main to use fx/mount-renderer instead of calling renderer directly. This will watch the global state atom for changes and rerender the GUI accordingly.

(defn -main [& args]
  (Platform/setImplicitExit true)
  (fx/mount-renderer *state renderer))

In most of the other examples, I would now write a function for each control that updates the other controls when its value changes. For example, the slider must update the text field, and the text field must update the slider. Imagine in the future I decide to add a meter to the UI that also needs to be updated whenever the frequency changes. I would have to remember to add code to update the meter to both the slider and the text field. With Cljfx, the slider just has to update the value in the global state atom. Then the text field and any controls we add in the future that depend on the frequency will automatically update. Here's a function that will update the global state atom:

; Update frequency in global state if it's a valid frequency
(defn set-frequency [freq]
  (when (and (>= freq min-frequency) (<= freq max-frequency))
    (swap! *state assoc :frequency freq)))

Then we can add an :on-value-changed property to the :slider that calls this function:

:on-value-changed #(set-frequency (position->frequency %))

and add an :on-text-changed property to the :text-field:

:on-text-changed #(set-frequency (read-string %))

And that's it. When one changes, the other does too. Once you get your head around it, it's a really elegant way to handle UI state.

It might be helpful to have a couple buttons to increase or decrease the frequency by an octave. An octave is "the interval between one musical pitch and another with double its frequency."

(defn octave-button [{:keys [frequency label modifier]}]
  {:fx/type :button
   :text label
   :on-action (fn [_] (set-frequency (* frequency modifier)))})

Now just add these buttons to the :children vector of the :h-box in the frequency-controls map:

[{:fx/type octave-button
  :frequency frequency
  :label "<"
  :modifier 0.5}
 {:fx/type :h-box
  :alignment :center
  :spacing 5
  :padding {:top 0 :bottom 0 :left 20 :right 20}
  :children [{:fx/type :text-field
              :text (str frequency)
              :on-text-changed #(set-frequency (read-string %))}
             {:fx/type :label
              :text "Hz"}]}
 {:fx/type octave-button
  :frequency frequency
  :label ">"
  :modifier 2}]

If you slide the slider, the text field updates accordingly. If you type a number in the text field, the slider updates accordingly. All good, right? What if a user (and you know they will) enters a number higher than 20,000 or a letter?

JavaFX has a TextFormatter class for this purpose. The TextFormatter uses a filter that can intercept and modify user input and a value converter that converts the value of the text field to a specified type whenever the field loses focus or the user hits Enter. The filter should be a function that accepts a Java TextFormatter.Change object and either returns that object or returns null (nil in Clojurese) to reject the change.

; Text field limited to entering numbers within range that updates specified
; key in global state atom (state-key)
(defn num-filter [change]
  (let [input (.getControlNewText change)
        numified (read-string input)]
    (if (or (= input "") (number? numified))
        change
        nil)))
(defn number-field [{:keys [min-value max-value init-value state-key label]}]
  {:fx/type :h-box
   :alignment :center
   :spacing 5
   :padding {:top 0 :bottom 0 :left 20 :right 20}
   :children [{:fx/type :text-field
               :pref-column-count (+ 1 (count (str max-value)))
               :text-formatter {:fx/type :text-formatter
                                :value-converter :number
                                :filter num-filter
                                :value init-value
                                :on-value-changed #(cond (< % min-value) (swap! *state assoc state-key min-value)
                                                         (> % max-value) (swap! *state assoc state-key max-value)
                                                         :else (swap! *state assoc state-key %))}}
              {:fx/type :label
               :text label}]})

Cljfx doesn't provide wrappers for the methods of TextFormatter.Change, but we can call the getControlNewText() method using Clojure's Java interop. This method returns the complete new text wich will be used on the control after the change. We can check this value to determine if we want to accept the change or not.

A caveat here is that the value of :filter must be a top-level️ function. I wish I could define :filter as an anonymous function. This would allow me to do something like also preventing the user from even entering a number higher than the allowed range rather than just reverting to the maximum value once the value is committed.

:filter #(let [input (.getControlNewText %])
               numified (read-string input)]
           (if (or (= input "") (and (number? numified) (<= max-value)))
               %
               nil))

If you try the above, it will throw a Replace forbidden error. That's because :filter is a constructor argument of TextFormatter that cannot be modified afterward. If you use an anonymous function, every call to number-field (whenever the UI is being rerendered due to a change of state) will try to create a new instance of the filter function, which is forbidden. But by making num-filter a top-level function, it is now out of the scope of max-value. I tried passing max-value to it by wrapping num-filter with a function that takes max-value and calling that function in :filter, but that still resulted in Replace forbidden. I also tried defining max-value at the top-level and wrapping the map inside number-field with binding to reassign the value of max-value, but since num-filter is being passed to the TextFormatter and called later it is called outside the scope of the binding and still unable to see max-value. I finally gave up and fell back on just having the field revert to max-value once the value is committed. If anyone has a solution for getting max-value to the num-filter function, I welcome pull requests.

Now let's replace the baseline :text-field and the :h-box surrounding it with our new number-field:

{:fx/type number-field
 :min-value min-frequency
 :max-value max-frequency
 :init-value frequency
 :state-key :frequency
 :label "Hz"}

Let's use this number-field again to create a field to specify the duration of the beep in milliseconds. First, let's add a key to our global state atom to track duration:

(def *state
  (atom {:frequency 440
         :duration 200}))

Then create our duration field:

(defn general-controls [{:keys [frequency duration]}]
  {:fx/type :h-box
   :spacing 20
   :children [{:fx/type number-field
               :min-value 1
               :max-value 600000 ; 10 minutes
               :init-value duration
               :state-key :duration
               :label "ms"}]})

Add this to the :children vector of the :v-box in the root map:

[{:fx/type frequency-slider
  :frequency frequency}
 {:fx/type frequency-controls
  :frequency frequency}
 {:fx/type general-controls
  :frequency frequency
  :duration duration}]

Frequency is rather abstract. Let's also give the user the ability to select a musical note. We can store the corresponding frequencies for A4-G4 in a map.

; Notes -> frequency (middle A-G [A4-G4])
; http://pages.mtu.edu/~suits/notefreqs.html
(def notes {"A" 440.00
            "B" 493.88
            "C"261.63
            "D" 293.66
            "E" 329.63
            "F" 349.23
            "G" 292.00})

We'll give the user a drop-down menu. Whenever a note is selected from the drop-down menu, we'll look up the frequency in the map and set that frequency in the global state atom. We'll add it on to general-controls:

(defn general-controls [{:keys [frequency duration]}]
  {:fx/type :h-box
   :spacing 20
   :children [{:fx/type number-field
               :min-value 1
               :max-value 600000 ; 10 minutes
               :init-value duration
               :state-key :duration
               :label "ms"}
              {:fx/type :h-box
               :alignment :center
               :spacing 5
               :children [{:fx/type :label
                           :text "♪"}
                          {:fx/type :choice-box
                           :items ["A" "B" "C" "D" "E" "F" "G"]
                           :on-value-changed #(set-frequency (notes %))}]}]})

Finally, let's make some noise.

; Generate a tone using JSyn
; Adapted from https://github.com/daveyarwood/javasynth/blob/master/src/javasynth/getting_started.clj
(defn generate-tone [frequency duration amplitude]
  (let [synth (doto (. JSyn createSynthesizer) .start)
        out (LineOut.)
        sine (SineOscillator. frequency)]
    (.set (. sine -amplitude) amplitude)
    (.add synth out)
    (.add synth sine)
    (.connect (. sine -output) (. out -input))
    (let [now (. synth getCurrentTime)]
      (.start out)
      (. synth (sleepUntil (+ now (/ duration 1000))))
      (.stop synth))))

We'll use the Java JSyn library we imported at the very beginning to generate the tone. Leiningen will pull in this dependency alongside Cljfx. Java has a standard Sound API that could be used to generate a sine tone without any external dependencies, but it's a little too low-level for what I'm trying to accomplish with this tutorial. This is a tutorial about building a GUI with Clojure and not about sound processing with Clojure. If you're interested, I did find a well-written tutorial about using Clojure's Java interop to generate a sine tone with Clojure via the Java Sound API. Wire this function up to a button between the duration and note selector, and you're ready to make some noise.

(defn general-controls [{:keys [frequency duration]}]
  {:fx/type :h-box
   :spacing 20
   :children [{:fx/type number-field
               :min-value 1
               :max-value 600000 ; 10 minutes
               :init-value duration
               :state-key :duration
               :label "ms"}
              {:fx/type :button
               :text "Play"
               :on-action (fn [_] (generate-tone frequency duration 0.5))}
              {:fx/type :h-box
               :alignment :center
               :spacing 5
               :children [{:fx/type :label
                           :text "♪"}
                          {:fx/type :choice-box
                           :items ["A" "B" "C" "D" "E" "F" "G"]
                           :on-value-changed #(set-frequency (notes %))}]}]})

You can check out the entire example on GitHub. This started as a personal learning project to explore the state of GUI programming in Lisp and has become a series of tutorials on building GUIs with various dialects of Lisp.