# Snow Tutorial

#### Last modified 2010-02-08

1. Getting and Installing Snow
2. Building Snow from source (optional)
3. The Snow REPL
4. Basic Concepts
5. Layout
6. Event handling
7. Embedding Snow
8. Data Binding
9. What's more?

### Getting and Installing Snow

You can download the latest Snow binary distribution from http://common-lisp.net/projects/snow/. It contains Snow and all its dependencies in a single Zip file. Since Snow can be used both in Lisp and Java applications, procedures for installing it can vary in each of the two cases.

- #### Java applications:

  simply make sure snow.jar and all the jars in the lib/ folder are in the classpath of your application. Snow uses JSR-223 and is built with Java 1.6, so that's the minimum Java version you can use. However, it should be possible to run Snow on 1.5 as well, but you'll need to recompile both Snow and ABCL from sources with a JSR-223 implementation in your classpath. See the Embedding Snow section below for details about using Snow inside your Java application.

- #### Lisp applications:

  - Snow comes prepackaged with a modified version of ABCL 0.18.1, and it wraps the ABCL launcher with its own, that makes sure to load Snow prior to your application. So you can just follow the procedure for Java applications above, and use the snow.Snow class in place of org.armedbear.lisp.Main as the main Java class to launch, e.g. via a shell script. The only difference is that, when launched with no command-line switches, Snow will pop up a GUI repl. You can pass a dummy --no-gui-repl switch to inhibit that. If you are new to Java, the classpath is a list of search places that the JVM uses to resolve classes (think asdf:*central-registry* if you will). It can be set with the environment variable CLASSPATH or with the -classpath command line switch to the java bytecode interpreter (the 'java' command). It is a list of directories and/or .jar files, separated by a platform-dependent character (':' on Linux, ';' on Windows). So for example, you can launch Snow on Linux with '`java -classpath snow.jar:lib/abcl.jar:lib/binding-2.0.6.jar:lib/commons-logging.jar:lib/miglayout-3.7.1.jar snow.Snow`'.
  - The snow.jar files contains prepackaged and precompiled the Lisp libraries it uses (Cells, named-readtables, cl-utilities). Currently there's no way to use other versions of those libraries loaded from outside the jar; you have to recompile Snow with your own versions from scratch. If you are brave enough you can also extract the contents of snow.jar (it is a regular zip file), it will create a directory tree full of .lisp source files, fasls and compiled Java classes (.class files). You will then be able to load Snow with ASDF using your own version of ABCL and/or Cells, provided you still meet the requirements about the classpath for Java applications. (there are two .asd files, one in snow/ and one in snow/swing). Essentially this latter option is what Snow does under the cover to load the Lisp part of itself.

Currently Snow, when run from the jar, requires a temporary directory to load itself; make sure your application has write permissions on your OS's tmp directory. Snow should automatically clear its temporary files when the application exits.

### Building Snow from source (optional)

Snow is built using the Ant program (a Java make-like tool). You can get it from <http://ant.apache.org/>. To obtain the source code for Snow, either download a source release from the project page or, if you want the latest & greatest stuff, follow the instructions at <http://common-lisp.net/faq.shtml> to checkout it from the SVN repository. Once you have the source in a given directory, you should find a lib/ subdirectory in it: libraries will go there. Refer to the README file in the lib directory for instructions on how to obtain the libraries. Once you have the libraries in place, cd to Snow's source directory and issue the command `ant snow.jar` to build Snow. `ant snow.clean` removes all compiled files.

### The Snow REPL

Being based on Lisp, Snow offers a REPL (read-eval-print-loop), an interactive prompt that allows you to evaluate arbitrary pieces of code. If you launch Snow through its main class (snow.Snow) with no command-line arguments, it will show a window containing the REPL. It should print
`SNOW-USER(1):`
SNOW-USER is the active package (namespace), (1) is the line number of the REPL. Now, the obligatory hello world:

    (frame (:title "Snow Example")
      (button :text "Hello, world!"
              :on-action (lambda ()
                           (print "Hello, world!")))
      (pack self)
      (show self))

Evaluating this will show a window containing a single button which, when pressed, will output "Hello, world!". The terminology should be familiar to Swing developers.
The REPL is great for experimenting: the code you input is immediately executed by an interpreter. You can also compile your code, either on the fly in the REPL or from a file; this is outside the scope of this tutorial, but you can find more information in any decent tutorial or book about Common Lisp (I suggest the free ebook Practical Common Lisp by Peter Seibel, available at http://gigamonkeys.com/book/). However, experiments sometimes go wrong; if you make a mistake - for example, evaluating an unexisting function - you will end in the debugger. Try typing the function call

    (oh-no!)

- you should see something like this:
The restarts are the actions the system can perform to recover the situation; this is an important feature of Common Lisp, worth studying by itself. You'll always be able to choose the TOP-LEVEL restart, which will bring you back to the REPL.
You can quit the REPL (and terminate the application) any time by closing the REPL window, or by typing (quit)1.

### Basic Concepts

As you can see from the previous examples, Snow code consists of a tree of widgets; nesting in the code means nesting in the widget hierarchy, for example:

    (frame (:visible-p t)
      (panel (:layout "wrap")
        (label :text "1")
        (label :text "2")
        (label :text "3"))
      (panel ()
        (label :text "4")
        (label :text "5")
        (label :text "6"))
      (pack self))

Creates a frame with two children, both panels with 3 children each - one has labels from 1 to 3, the other from 4 to 6.
You can set the properties of the widgets using keyword-value pairs like `:visible-p t` which means `setVisible(true)` (-p is a suffix traditionally used in Lisp to name predicates, T is the canonical true value). Containers must have their properties set in a list after the widget name -

    (panel (...here go the properties...) ...here goes the body...)

- the list serves to separate them from the body. Non-containers have no body and thus their properties do not require to be wrapped in a list:

    (label ...here go the properties...)

#### How does this work?

The Snow API consists of a set of macros that can be used to declaratively construct a tree of widgets. These macros are designed in such a way to make the tree structure of Lisp source code closely mirror the GUI widget tree structure (in the general case). The macros expand to code that uses functions to create widgets, but usually you won't deal with those functions directly. The main user-level aspects of the Snow API are:

#### macro `with-gui`

The macro `with-gui (&rest args) &body body` is used to run Snow code in the appropriate context (i.e., in a GUI-backend-specific thread, with some special bindings established). All Snow code must be run in the dynamic scope of a with-gui invocation; consequences are undefined if this rule is violated. This usually means that you should only use with-gui in the top-level function(s) that create the GUI. Moreover, if you write code that dinamically changes your GUI after it has been created independently on event handling you should wrap that code in with-gui too.
Snow automatically takes care of setting up the right environment inside event-handling callbacks, so you're not required to use with-gui there, even if you modify the GUI. Code run from the Snow REPL is also automatically evaluated in the right context.
Examples:

    ;; This function presumably is called to initialize the GUI so with-gui is required.
    (defun make-main-frame (title)
      (with-gui ()
        (frame (:title title)
          (make-some-button))))

    ;; This function is meant to be only called by GUI-making functions: it can assume that with-gui has been called by some other function higher on the call stack, and can avoid using it.
    (defun make-some-button ()
      (button :text "Some" :on-action #'handle-some-action))

    ;; This function is an event handler: Snow will automatically run it in the proper context, so with-gui is not required
    (defun handle-some-action ()
      (print "Hooray!"))

#### lexical variable `self`

Holds the current widget being processed. Example:

    (frame ()
      (print self))

will output something like:

    #<javax.swing.JFrame ...frame.toString()... {identityHashCode}>

#### special variable `*parent*`

Holds the current parent widget. When *parent* is non-nil, any widget created through a macro will be automatically added to the container referenced by *parent*. All Snow widget macros process the forms in their body in the following way:

- if the form is a list, its car is a symbol, and this symbol has a property named widget-p, then the form is wrapped in a `(let ((*parent* self)) ...)` i.e., it is evaluated in a dynamic context where the parent is the widget created by the macro.
- else, the form is wrapped in a `(let ((*parent* nil)) ...)`, i.e., it is evaluated in a dynamic context where no parent widget is defined (and thus widgets created by the form are not added to any widget).

These rules make the nesting of Snow widget macros work in an intuitive way:

- a widget defined at the top level in the body of another (container) widget w will be added to w. Example: `(frame () (panel ()))` will result in a frame with a panel child.
- widgets appearing in code in the body of another widgets, but not at top level, will not be added. Example: `(frame () (let ((p (panel ())))))` will result in a frame with no children, and will create an "orphan" panel.

Snow provides operators to alter this default behavior:

- `(dont-add form)` will always execute form in a dynamic context in which no parent widget is defined.
- `(child widget &rest args)` will force the result of evaluating widget to be added to *parent*.

#### widget id

Additionally, all widget macros support a pseudo-property called `id` which can be set to a symbol and has several uses:

- if a lexical variable with the same name (symbol) as the id exists, it will be assigned the widget.
- if the widget is a container, a lexical variable with the same name as the id will be bound to the widget around the body of the container. Example:

      (frame (:id foo)
        (print foo))

  will output something like:

      #<javax.swing.JFrame ...frame.toString()... {identityHashCode}>

- if a Java backing bean is present (see further below), and it has a property with the same name as the id, it will be injected the widget through the setter method of that property. The name of the id symbol will be translated from lisp-hyphenated-convention to javaCamelCasedConvention.

#### special variable `*backing-bean*`

This variable is usually set from Java code embedding Snow (see the appropriate section). It is used to delegate some things to a Java object instead of coding them in Lisp. Apart from the injection of widgets to properties matching their :id mentioned above, a backing bean can also be used to implement event handlers; see Event handling for more information.

### Layout

By default, Snow uses MiG Layout as the layout manager to organize components inside a container. When you create a component that will be automatically added to `*parent*` by Snow, you can use the pseudo-property `:layout` to specify (as a string) additional information for the layout manager. Here's a quick cheat sheet of the constraints you can use with MiG Layout: http://www.migcalendar.com/miglayout/cheatsheet.html (look for "Component Constraints").
You can use another layout instead of MiG: to do so, use the `layout-manager` property of the container. The values you can pass are:

- a keyword (supported ones are `:default`, `:mig`, `:border`, `:box`) to select the layout manager by name; the names refer to layout managers available in Swing;
- a list whose car is one of the symbols above, and whose cdr is a list of the arguments passed to the layout manager (e.g. `(list :box :y)` to have components be laid out in a vertical stack);
- a Java object which can be used by Swing as a layout manager (e.g. `(new "java.awt.FlowLayout")`).

### Event handling

Certain widgets can trigger events on certain types of user actions. These events can be handled by user code. Event-handling callbacks can be set using properties named `:on-event-name` (for example, `:on-action` for handling clicks on buttons, or ActionEvents in Swing/AWT parlance). Currently very few events are supported! I'll add new ones in future releases.
A callback for an event can be:

- a Lisp function with no arguments. An object representing the event will be available as the value of the special variable *event*.
- an appropriate native Java event handler for the event (e.g., an instance of `java.awt.ActionListener`).
- a string. In this case, a backing bean must be used, or an error will be signaled. The string will be used as the name of a method to call on the backing bean. The method must have a single argument, of type appropriate for the event to handle (e.g. java.awt.MouseEvent for mouse events).

Events happen on a dedicated thread (in Swing's terminology, the EDT - Event Dispatching Thread). This thread is used to paint components too, so make sure your events don't take too much to be handled, or you'll freeze the GUI.

### Embedding Snow

Snow can easily be embedded in a Java application; it leverages the JSR-223 implementation in ABCL. The snow.Snow class has some static methods that can be used to load some Snow source code from a .lisp file (or classpath resource), or to obtain an instance of `javax.script.ScriptEngine` which you can use for more advanced stuff (e.g. explicitly calling specific Lisp functions).
However, a Java application wishing to use Snow for its GUI will typically rely on a simple abstraction called a Snowlet. Snowlets are objects that represent a resource to be evaluated in a Snow-aware context. There are two types of Snowlets: interpreted and compiled. They can be obtained via two static methods in the class snow.Snow, `getInterpretedSnowlet` and `getCompiledSnowlet`. Interpreted Snowlets can be only evaluated once. Compiled Snowlets can be evaluated infinite times and execute faster, but take longer to be created.
A typical Snow file will have the following structure:

#### `file.lisp`

    (in-package :snow-user)
    (in-readtable snow:syntax)

    ...snow code...

and will be used like this:

#### `MyClass.java`

    ...
    Snowlet s = Snow.getInterpretedSnowlet(getClass().getResource("file.lisp"));
    s.setBackingBean(this);
    s.eval();
    ...

You can look at the Snow Examples to get a better idea.

### Data Binding

Keeping the GUI state in sync with the application objects state is generally tedious and error-prone. Data Binding is the process of automating the synchronization of state between two objects, in this case a GUI component and an application-level object. Snow supports several kinds of data binding, and it uses two libraries to do so: JGoodies Binding on the Java side and Cells on the Lisp side.

#### General concepts

There are two general ways to bind or connect a widget to some object's property: one is by using the `:binding` property of the widget, letting the framework choose which property of the widget to bind, e.g. the text property for a text field; for example:

    (text-field :binding (make-simple-data-binding x))

the other is to provide as the value of a widget's property an object representing the binding, as in

    (button :enabled-p (make-simple-data-binding x))

this will connect the specific property of the widget with the user-provided object or property.

#### Types of data binding

Snow supports several types of data binding; some are more indicated for Lisp applications, others for Java applications.

- Binding to a variable. Syntax: `(make-simple-data-binding <variable>)`
  This is the simplest form of data binding: you connect a widget's property to a suitably instrumented Lisp variable. Such a variable must be initialized with `(make-var <value>)`, read with `(var <name>)`, and written with `(setf (var <name>) <value>)`. Example:

      (defvar *x* (make-var "Initial value"))
      (setf (var *x*) "new value")
      (button :text (make-simple-data-binding *x*))

- Binding to a Presentation Model. Syntax: `(make-bean-data-binding <object> <property> ...other args...)`
  This kind of binding uses Martin Fowler's Presentation Model pattern as implemented by JGoodies Binding. You implement, in Java, a suitable subclass of `PresentationModel` (in simple cases, you can just use the base class provided by JGoodies); you then bind a widget to a model returned by an instance of this class for a bean property. Example:

      (defvar *presentation-model* (new "my.presentation.Model"))
      (text-field :text (make-bean-data-binding *presentation-model* "myProperty"))

  The presentation model acts as a glue between the GUI and the application logic, and provides advanced functionality (e.g. it lets you control when to synchronize the state). You can tune it with additional arguments to `make-bean-data-binding`; for example, you can obtain a buffered model with `:buffered-p t`.
- Binding to a bean property, arbitrarily nested. Syntax: `(make-property-data-binding <bean> <property path>)`
  This is a convenient way to adapt a pre-existing bean with the binding framework. It connects a property path, which can be expressed in "dot notation"; to properly observe changes, every object which is part of the path must support the standard Java Bean facility for listening to property changes. Example:

      (defvar *x* (new "Person"))
      (text-field :text (make-property-data-binding *x* "address.street"))

- Binding to a Cells-powered slot of a CLOS object. Syntax: `(make-slot-data-binding <object> <slot-accessor-name>)`
  You can use this kind of binding to connect a widget property to a slot of a CLOS object using the Cells dataflow library. Example:

      (defvar *x* (make-instance 'my-class :my-slot (c-in 42)))
      (text-field :text (make-slot-data-binding *x* 'my-slot-accessor))

- Binding to a calculated expression using Cells. Syntax: `(make-cell-data-binding <expression> [writer])`
  This is useful to bind a widget to a quick-and-dirty Cells expression without creating a class instance specifically to hold it in a slot. You can optionally provide a writer function so that the widget will be able to alter the value of the expression when its value changes. Example:

      (defvar *x* (make-instance 'my-class :slot (c-in 42)))
      (text-field :text (make-cell-data-binding
                          (c? (* 2 (my-slot *x*)))
                          (lambda (new-value) (setf (my-slot *x*) new-value))))

  Note: Snow's variables (introduced with make-var) are in fact Cells objects and can be used in Cells expression too. So for example, `(c? (1+ (var foo)))` is a valid expression that evaluates to 1 + the value of foo and is updated anytime the value of foo is changed.

#### Syntactic sugar

To avoid the verbosity of make-foo-data-binding, Snow provides convenient syntax to cover the most common cases of data binding. You can enable this special syntax by evaluating the form `(in-readtable snow:syntax)`, for example placing it in every source file right after the `(in-package :snow-user)` form at the top of the file.
This special syntax is accessed by using the prefix $. It covers the following cases:

- `$foo` is equivalent to `(make-simple-data-binding foo)`.
- `$(c? ...)` is equivalent to `(make-cell-data-binding (c? ...))`.
- `$(slot ...)` is equivalent to `(make-slot-data-binding ...)`.
- `${bean.path}` is a bit more complex. This syntax resembles that of the "Expression Language" used in JSP and JSF. First, `bean` is used as the name of a bean: the function stored in the special variable `*bean-factory*` is called with it as an argument to produce a Java object. The default function simply reads and evaluates `bean` as the name of a Lisp variable, but you can customize this behavior: for example, you can provide a callback that gets the bean from a Spring application context2. Then, once the bean has been obtained, two things can happen: if `path` is a simple property (i.e. it has no dots) and the bean is an instance of JGoodies PresentationModel, a binding to the property is asked to the presentation model, as by `(make-bean-data-binding bean path)`; else, a property path data binding is constructed, as by `(make-property-data-binding bean path-as-list)`.

### What's more?

I haven't covered which widgets are supported and how much of their API is supported. At this point, Snow is in a early stage of development, so only a little of the Swing API is covered. The best way to learn about Snow usage is to look at the examples included with it. Looking at the debugger (debugger.lisp), inspector (inspector.lisp) and the REPL (repl.lisp and swing.lisp), included as part of the Snow distribution, can be useful as well. Also, I haven't talked about how to use your custom widgets with Snow, and probably other things. Drop me a line at alessiostalla @ Google's mail service, and I'll be happy to help you.

### Footnotes

1. If you really mess things up, you can change the package of the REPL to one where the symbol QUIT is not visible. If you find yourself in this situation, type (ext:quit) to exit.
2. Snow provides a convenient Java class - `org.armedbear.lisp.Callback` - that you can subclass to create your custom callback function. You have just to implement the appropriate overload of the `call` method, or alternatively use one of the static methods `Callback.fromXXX` to create a Callback from several kinds of Java callbacks.