Building A Temperature Conversion Application

Now that we have a working system for making windows and starting an event loop, we want to add stuff to the window. We'll be building a temperature conversion application, so we'll need a place to type a number. To make it easy on ourselves, we'll only have one place to type the number, and then we'll have two buttons: one to convert from Fahrenheit to Celsius, and one for the reverse. They'll change the value of the number in the field where the original temperature was typed.

Understanding how to get a window open was challenging--we had to learn the inner workings of MacOS's GUI framework AppKit and how to use ClozureCL's Cocoa bridge to write Objective-C code in Common Lisp--but now that we understand the basics of working with AppKit, building the actual GUI isn't going to be that challenging.

Building the GUI is going to be fairly similar to building a CRUD application.

1. We'll display a text input and buttons in a window.
2. We'll code up a controller that has two actions: f-to-c and c-to-f.
3. We'll write the code that models the "business logic" of converting temperatures.
4. We'll wire up the model and controller code with the "views"--GUI widgets.

It'll end up feeling familiar to all my fellow web developers.

One important goal we have, however, is to write our code in a way that makes it hotswappable and interactive just like all Lisp code. We'll first muddle our way through the naive way before we upgrade to the more sophisticated approach. Future native application development will be made much easier after we learn the principles.

First, let's just summarize what we covered in the last article:

1. We learned how to interact with MacOS's GUI framework AppKit via ClozureCL's Cocoa bridge.
2. We learned some of the details of Objective-C's syntax so we could understand how to write our Lisp code.
3. We learned why we need an AppKit delegate to close our application and reopen the window in development.

Let's walk through the final code of that project piece by piece.

We begin by loading the Cocoa bridge.

We set up a delegate--an Objective-C object that AppKit asks whether it should quit the application when the window closes, and that we send a message to when we want the window reopened.

We split making a window and opening a window so that we can call make-window in the reopenWindow: method above without calling run again--which starts an event loop.

We wrote a function that sends a message on the main thread to the application's delegate that tells it to reopen the window.

And we wrote the entry-point for starting the application.

It was a lot to learn right from the beginning--selectors, delegates, main threads and event loops, an Objective-C and AppKit crash course, etc.

Thankfully, the next step in learning native programming isn't going to be quite as humbling. First, let's make the basic widgets, starting with a button.

Making a button is easy thanks to ClozureCL's bridge--it has a convenient ns-button class that does the work of building the button in Objective-C. We just pass an ns-rect with the :with-frame argument. You can safely run this code without blowing up your REPL--you don't need to do it on the main thread.

#<NS-BUTTON <NSButton: 0x10542c8f0> (#x10542C8F0)>

We can make a small alias around ns:make-ns-rect to make future code easier to write.

Then we can rewrite the make-instance call.

The x and y coordinates refer to a position inside the view that the button will live in--for us, that will be the window's content view. If you're coming from the web, there's a trap here: the origin is the bottom-left corner, and y grows upward. A button at 0 0 sits in the bottom-left corner of the window, not the top-left.

Let's keep it in a variable so we can play with it.

A new button's title is an ns-string.

#<NS-STRING "Button" (#xAFF1CB6628A66459)>

Which you can get back as a Lisp string using objc:lisp-string-from-nsstring.

"Button"

...which isn't very helpful. We change it by sending the button the setTitle: message.

The #@ in front of the string is important. A Lisp string is not an Objective-C string, and AppKit only understands its own NSString objects. #@"F to C" is ClozureCL's reader macro for writing an NSString constant directly in your Lisp code.

We also need somewhere to type the temperature. Unsurprisingly, AppKit's text input is called NSTextField, and it's made exactly the same way as the button.

#<NS-TEXT-FIELD <NSTextField: 0x105445700> (#x105445700)>

Notice the y of 70. Since y grows upward, the text field is going to sit above the button we made at a y of 20.

Making widgets in the REPL is safe, but we can't see them. A widget only appears on screen after it's added to a window. So let's start with the make-window function from last time, using our new rect function.

Every window comes with a contentView--the view that fills the window below the title bar. Think of it as the <body> of the window. Widgets are views too, and we add them to the content view with addSubview:.

Then we add the two buttons side by side under the text field.

If you still have the application running from last time, close the window, compile the new make-window, and call (reopen-window). Otherwise, compile the whole file and start the application with the process-interrupt line. You should see a small window with a text field and two buttons.

You can type in the field and you can click the buttons. Nothing happens when you click them, of course. We haven't told them what to do yet.

In web programming, if we want an interface to do something, we use a <form>.

When you click the button, it sends a message to the server (a request), which gets routed to the controller at do-this. The controller does something and replies to the message.

The same is true in AppKit. A button holds two things: a target and an action. The target is an object. The action is a selector--the name of a method. When you click the button, AppKit sends the action message to the target. This is called the target-action pattern, and it's used everywhere in AppKit.

So we need an object with two methods. converter is our controller. Just like the delegate, it needs to be an Objective-C object so that AppKit can send it messages. It also needs to know about the text field, because that's where it will read the temperature from and write the converted temperature to.

Just to reiterate, converter will be the target for our buttons, and each button will specify an action--the method that converter should call.

Now we need the two actions. An action method always has the same shape: it takes one argument--the sender, which is the widget that was clicked--and returns nothing, which is :void in Objective-C. Since it takes an argument, the selector's name ends with a :. For now, the actions will just write something into the text field so that we know the buttons are working.

Objective-C's naming convention is camelCase, so our f-to-c and c-to-f actions become fToC: and cToF:. All that's left is the wiring.

In make-window, we make the controller and hand it the text field, then we set the target and action of each button.

You might wonder why the variable is named controller and not converter. It's because I tried converter first and ClozureCL refused to compile the function.

Close the window, compile, and call (reopen-window) again. Click the buttons and the text field tells you which button you clicked. The view is talking to the controller.

Now for the "business logic". This will just be some simple, relaxing Lisp.

Because it's just Lisp, we can test it in the REPL without opening a window at all. Water boils at 212 degrees Fahrenheit.

100

And we can go back the other way.

212

Since we wrote the fractions as 5/9 and 9/5, Common Lisp does the math with rational numbers and we never lose any precision. That also means that a temperature that doesn't divide evenly comes back as a fraction.

340/9

That is the correct answer, but nobody wants to read 340/9 on a thermometer. We'll leave the logic precise and round the number only when we display it. format can do that for us.

"37.8"

Keeping the logic away from the GUI like this is the same separation we make in web applications, and for the same reasons. We can test it, reuse it, and when we later build the UI again with a different toolkit, this code won't change at all.

We have the views, the controller, and the logic. Now we connect them. When a button is clicked, we want to:

1. Read the number in the text field.
2. Convert it.
3. Write the result back into the text field.

Both actions do the same thing with a different conversion, so we'll write one function that takes the conversion as an argument.

doubleValue asks the text field to read its text as a number and gives us a Lisp double float. If the text isn't a number at all--it's empty, or somebody typed "hot"--we get 0.0d0 instead of an error. Good enough for now. setStringValue: needs an NSString, and since our string is made at runtime by format, we convert it with objc:make-nsstring.

Then we rewrite the actions to call it.

Compile those three forms, but this time don't close the window. Type 212 into the text field that's already open and click "F to C". It says 100.0. Click "C to F" and it goes back to 212.0.

We redefined two Objective-C methods and the running application picked them up immediately. That's the Lisp experience we want. The same is true of convert-field and the conversion functions: redefine them and the very next click uses the new definition.

So the behavior of our application is already hotswappable. The trouble is everything else.

Let's say we want to change the title of a button. We change the string in make-window, compile it, and... nothing. The window on the screen was built by the old make-window, and it has no idea that a new one exists. To see the change we have to close the window and call (reopen-window), and whatever we typed in the old window is gone.

That's the "edit, refresh the page" loop of web development. It's fine for three widgets. It won't be fine for a real application where getting back to the screen you were working on takes ten clicks.

What we really want is to reach into the running application from the REPL and change it. Let's imagine we had saved the window in a variable named *window* and tried to give it a title from the REPL.

Terminating app due to uncaught exception 'NSInternalInconsistencyException',
reason: 'NSWindow geometry should only be modified on the main thread!'

No debugger, just a dead Lisp process and that message left behind in the *sly-inferior-lisp* buffer. It's the same lesson we learned last time when we tried to open a window: your REPL does not run on the main thread, and AppKit insists that its windows and views are only touched from the main thread. Some messages will kill the process like this one did, and some will just freeze your REPL. Either way, you're restarting Lisp.

We already know one way around this--it's how reopen-window works. We add a method to the delegate and use performSelectorOnMainThread: to send it the message. But that would mean writing a new Objective-C method for every single thing we ever want to do to the running application. ENOUGH WITH THE BUREAUCRACY!

What we want is to be able to write any Lisp code at all and say, "run this on the main thread".

The problem is that performSelectorOnMainThread: doesn't know what a Lisp function is. It only knows how to send a message to an Objective-C object. So we'll give it what it wants: an Objective-C object whose only job is to hold a Lisp function and to call it when it receives a message.

That's the only Objective-C method we'll need to write for this, ever. Now we write the Lisp function that uses it. It makes a caller that holds our function, asks AppKit to send the caller the callLispFunction: message on the main thread, and waits for it to finish.

The release at the end is new. Objective-C objects aren't garbage collected like Lisp objects are. Each one keeps a count of how many owners it has, and it's freed when the count reaches zero. We made the caller, so we own it, and when we're done with it we need to say so. Since we make a new caller for every call, we'd leak a little memory every time if we didn't.

This already works, but it throws away whatever our function returns. In a REPL we want to ask the running application questions, too. The function we pass and the function that calls it run on different threads, but a closure doesn't care about that. We can wrap our function in a lambda that saves the result in a variable, and return it after the main thread is done.

There's one more thing to take care of. If our function signals an error, it signals it on the main thread, in the middle of the application's event loop. I want the error in the REPL where I can debug it. We can do the same trick again: catch the error on the main thread, save it, and signal it again in the thread that asked.

Finally, since we're going to be typing this a lot, a small macro saves us from writing the lambda every time.

To poke at the window from the REPL, we need to be able to access it. We'll save it in a global variable when we make it.

There is one catch. By default, a window that isn't managed by a window controller is released when it's closed. Our variable would be left pointing at freed memory, and the next message we sent to it would crash the process. We tell the window not to do that with setReleasedWhenClosed:.

Reopening the window was the one thing we could already do on the main thread, and it took a delegate method and a function to do it. Now it's one line, and we can delete the reopenWindow: method from the delegate.

Compile the new definitions, close the old window, and call (reopen-window). We don't even need to restart Lisp to switch over to the new code. Now let's try setting the title again--the same code that killed our Lisp process before.

NIL

The title bar changes while the application is running, and the REPL is still alive. We can ask questions, too.

"Temperature"

And if we make a mistake, we get an ordinary Lisp error in an ordinary Lisp debugger. Abort it and both the REPL and the application carry on as if nothing happened.

We can now change anything in the running application from the REPL, but changing things by hand isn't the same as changing the code. We still have the original trouble: when we edit make-window, the open window doesn't change.

Why did the two methods update the moment we compiled them, when the buttons don't? Because AppKit sends fToC: every time the button is clicked, and it looks the method up every time it sends it. Code that gets called over and over is hotswappable for free. make-window gets called once. By the time we compile a new one, the old one has already done its work and nobody is going to call the new one.

So that's the whole problem: the code that builds the window needs to run again, and it needs to do it without throwing the window away.

make-window can't be run again as it is, because it does two jobs. It makes a window, and it makes the content of the window. We split open-window last time for the same kind of reason, so let's split again. First, the buttons are getting repetitive, so they get a function of their own. It takes a Lisp string for the title, so we can finally have our arrows.

Then we move the widgets out of make-window and into a function that builds a fresh content view--an NSView, the plain rectangle that all widgets are built on--with everything already in it.

That leaves make-window with only the window to worry about. Instead of adding widgets to the content view the window came with, it replaces the whole content view with ours using setContentView:.

If a window's content view can be replaced when the window is made, it can be replaced at any time after that, too--as long as it's done on the main thread.

Compile the new definitions, close the window, and call (reopen-window) one last time. Now go to make-content, change the two titles to "F → C" and "C → F", compile the function, and evaluate this in the REPL.

The buttons change in the open window. The window never closed and the Lisp process never restarted.

It works, and I don't like it. We compile the function and then we have to go to the REPL and tell the application that we compiled the function. When I redefine a Lisp function, the next call uses it. I don't call (refresh) on my functions. As far as I'm concerned, this is unacceptable. Lisp can do better!

The thing that knows make-content has changed is the form that defines it. So let's have that form do the refreshing. We'll write a macro that defines the function just as defun would, and then, if there's a window open, refreshes it.

The empty () does nothing but make it look like a defun. Now we change one word in make-content.

Compile it. Move a button and compile it. Make the text field narrower and compile it. Every time you compile, the open window changes. We never touch the REPL. The first time the file is loaded there is no window, so *window* is nil and the macro defines the function and leaves it at that.

If you've used a frontend framework, this will feel familiar: the content is whatever make-content returns, and we "re-render" by calling it again.

It also has the problem that re-rendering has. Type 212 into the text field, then change a button's title and compile. The title changes and the 212 is gone. Of course it is: make-content made a brand new text field and threw the old one away, along with everything in it.

What we really want is a way to update the definition of make-content and then also have the GUI update so that the changes reflect a permanent change rather than a temporary, ad-hoc change.

Lisp already has a form that can help us. defvar, when initially compiled, assigns a value to a variable. If it is recompiled later with a different value, however, it retains the old value. To change the value, you have to change the value via setf. We want something like that for widgets, with one difference: a widget should be made only once, and set up every time its definition is compiled. Making a button is the part that must not happen again. Giving it a frame and a title can happen as often as we like.

So we'll need some global defvar definitions for our widgets. The controller needs one too. And since the text field will now have a name, *field*, the controller doesn't need to be handed the field when it's made, so we can drop the slot. It's cleaner.

Now the macro. A widget definition has a name, a class, and the code that sets the widget up.

define-widget does four things.

1. It defines a variable for the widget with defvar, so compiling the definition again doesn't lose the widget we already have.
2. It defines a function with the same name as the variable. In Common Lisp a symbol can name a variable and a function at the same time, and the two don't get in each other's way: *field* is the widget, and (*field*) calls the function. That function makes the widget only if there isn't one yet, then runs the setup code, then returns the widget.
3. It adds the name to *widgets*, the list of every widget the window should have.
4. If there's a window open, it calls place-widget right away, on the main thread.

place-widget calls that function by its name and puts the widget in the window if it isn't in there already. The first time, that makes the widget and adds it. Every time after, the widget is already there, and all that happens is the setup.

We won't be calling (*field*) ourselves. place-widget is its only caller. What we use is the definition, which we compile, and the variable, which we can poke at from the REPL with on-main-thread.

Here are our three widgets.

Put them above the two action methods in the file, since they're what declares *field*, and below *controller*, which the buttons use.

make-window goes back to using the content view the window came with, and places every widget on the list. It has to save the window in *window* first, because that's where place-widget looks for it.

make-button, make-content, define-content and refresh have nothing left to do. Delete them. Close the window, compile the file, and call (reopen-window), for what really is the last time.

Now type 212 into the text field and leave the cursor in it. Go to the definition of *f-to-c*, change its title to "To Celsius", and compile that one form. The title changes. The 212 is still there, and the cursor is still blinking in the field. It's the same button it was a moment ago with a new title.

Change the field's frame and compile: it moves, with its text. And adding a widget is just writing a new definition.

Compile it and a third button appears in the open window. It doesn't do anything yet, but you know how to fix that now: write a clear: method on the controller, set the button's target and action, and compile both.

There's a bonus we didn't ask for. Close the window and call (reopen-window). The 212 is still there. The widgets belong to their variables now and not to the window, so a new window gets the same old widgets.

That's hotswapping a native GUI, and it didn't take much code. The principles are these:

1. Functions or methods called within our program are hotswappable for free.
2. Keep a reference to the things you want to hotswap.
3. Split making a thing from setting it up. Make it once. Set it up as often as you like.
4. Let the definition do the updating, so that compiling is all it takes.
5. Have one way to run any code on the main thread.

The final code looks like this:

It's not much of an application, but look at what we get to keep. The logic is plain Lisp that we can test in the REPL. The controller is two tiny methods we can redefine while the application is running. Each widget is a definition we can compile again whenever we like, and the widget in the open window changes without losing what's in it. And on-main-thread lets us reach into the running application from the REPL to inspect it and change it. We'll be using it in every native application we write from here on.

We can also imagine expanding this define-widget macro so that we, the users, don't even need to worry about Objective-C and can just focus on writing Lisp--which is our long term goal. make-button had the beginnings of that (make-button took a plain Lisp string for the title argument, releasing us from the burden of knowing about and using objc:make-nsstring), so it's not much of a stretch to hide the ClozureCL bridge API behind a Lispy one.

Finally we can write a native application in Lisp the Lisp Way using the power of macros.