Snow Tutorial

Last modified 2009-11-26

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 come prepackaged with ABCL 0.16, 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, I don't know about Macs). 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.6.2.jar snow.Snow'.
  • Also, Snow has its own version of Cells built in. It is a random, but fairly recent version from CVS, with some fixes to make it run on ABCL. I'm looking forward to having those fixes merged with trunk, so you'll be able to freely update Cells independently.
  • Last but not least, Snow is built with ASDF, so if you are brave enough you can 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).

(frame (:title "Snow Example")
  (button :text "Hello, world!"
          :on-action (lambda (event)
                       (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...)

(frame ()
  (print self)) 

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

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

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

(button :on-action (let ((tmp *some-thread-local-variable*))
                     (lambda (event)
                       (let ((*some-thread-local-variable* tmp))
                         ...do stuff...))))

(in-package :snow-user)

(defun create-main-frame (&rest args)
  ...snow code...)

...
Snow.evalResource(new FileReader("file.lisp"));	
JFrame mainFrame = (JFrame) Snow.getInvocable().invokeFunction("create-main-frame", args);
...

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-cells-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-cells-data-binding
                      *x* (c? (* 2 (my-slot *x*)))
                      (lambda (new-value) (setf (my-slot *x*) new-value))))
  

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.