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?

• 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.

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

(oh-no!)

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

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

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

;; 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!"))

(frame ()
  (print self)) 

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

• 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")).

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

...snow code...

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

General concepts

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

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

Types of data binding

• 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

• $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 context². 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).

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.