[snow-cvs] r11 - in trunk: docs src/java/snow/binding src/lisp/snow

[Alessio Stalla]

Author: astalla
Date: Mon Oct 26 18:48:55 2009
New Revision: 11

Log:
Updated tutorial. Fixed a bug with EL binding and zero-length property paths.


Modified:
   trunk/docs/tutorial.html
   trunk/src/java/snow/binding/BeanPropertyPathBinding.java
   trunk/src/lisp/snow/data-binding.lisp

Modified: trunk/docs/tutorial.html
==============================================================================
--- trunk/docs/tutorial.html	(original)
+++ trunk/docs/tutorial.html	Mon Oct 26 18:48:55 2009
@@ -13,10 +13,11 @@
 	<li><a href="#layout">Layout</a></li>
 	<li><a href="#events">Event handling</a></li>
 	<li><a href="#embedding">Embedding Snow</a></li>
+	<li><a href="#ch008">Data Binding</a></li>
 	<li><a href="#more">What's more?</a></li>
 </ol>
 <a name="ch001" /><h3>Getting and Installing Snow</h3>
-You can download the latest Snow binary distribution from <a href="http://alessiostalla.altervista.org/software/snow/index.php">http://alessiostalla.altervista.org/software/snow/index.php</a>. 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.
+You can download the latest Snow binary distribution from <a href="http://common-lisp.net/projects/snow/">http://common-lisp.net/projects/snow/</a>. 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.
 <ul>
   <li><h4>Java applications:</h4>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 <a href="#embedding">Embedding Snow</a> section below for details about using Snow inside your Java application.</li>
   <li><h4>Lisp applications:</h4>
@@ -159,6 +160,35 @@
 JFrame mainFrame = (JFrame) Snow.getInvocable().invokeFunction("create-main-frame", args);
 ...
 </pre>
+<a name="ch008" /><h3>Data Binding</h3>
+Keeping the GUI state in sync with the application objects state is generally tedious and error-prone. <i>Data Binding</i> 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 library to do so: <a href="https://binding.dev.java.net/">JGoodies Binding</a> on the Java side and <a href="http://common-lisp.net/projects/cells/">Cells</a> on the Lisp side.
+<h4>General concepts</h4>
+There are two general ways to <i>bind</i> or <i>connect</i> a widget to some object's property: one is by using the <code>:binding</code> 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:
+<pre class="paste-area">
+(text-field :binding (make-simple-data-binding x))
+</pre>
+the other is to provide as the value of a widget's property an object representing the binding, as in
+<pre class="paste-area">
+(button :enabled-p (make-simple-data-binding x))
+</pre>
+this will connect the specific property of the widget with the user-provided object or property.
+<h4>Types of data binding</h4>
+Snow supports several types of data binding; some are more indicated for Lisp applications, other for Java applications.
+<ul>
+<li><b>Binding to a variable.</b> Syntax: <code>(make-simple-data-binding <variable>)</code><br />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 <code>(make-var <value>)</code>, read with <code>(var <name>)</code>, and written with <code>(setf (var <name>) <value>)</code>. Example:
+<pre class="paste-area">
+(defvar *x* (make-var "Initial value"))
+(setf (var *x*) "new value")
+(button :text (make-simple-data-binding *x*))
+</pre></li>
+<li><b>Binding to a Presentation Model.</b> Syntax: <code>(make-bean-data-binding <object> <property> ...other args...)</code><br />This kind of binding uses Martin Fowler's <i>Presentation Model</i> pattern as implemented by JGoodies Binding. You implement, in Java, a suitable subclass of <code>PresentationModel</code> (in simple cases, you can just use the base class); you then bind a widget to a model returned by an instance of this class for a bean property. Example:
+<pre class="paste-area">
+(defvar *presentation-model* (new "my.presentation.Model"))
+(text-field :text (make-bean-data-binding *presentation-model* "myProperty"))
+</pre>
+You can tune the presentation model with additional arguments to <code>make-bean-data-binding</code>; for example, you can obtain a buffered model with <code>:buffered-p t</code>.</li>
+
+</ul>
 <a name="more" /><h3>What's more?</h3>
 I haven't covered which widgets are supported and how much of their API is supported. At this stage, Snow is little more than a prototype, so very little of the Swing API is covered. The best way to learn about Snow usage is to look at the examples included with Snow: the debugger (debugger.lisp), inspector (inspector.lisp) and the REPL (repl.lisp and swing/swing.lisp). 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.
 <hr />

Modified: trunk/src/java/snow/binding/BeanPropertyPathBinding.java
==============================================================================
--- trunk/src/java/snow/binding/BeanPropertyPathBinding.java	(original)
+++ trunk/src/java/snow/binding/BeanPropertyPathBinding.java	Mon Oct 26 18:48:55 2009
@@ -47,7 +47,6 @@
 
     private String propertyName;
     private Object object;
-    private Method removeMethod;
     private BeanPropertyPathBinding nextListener;
     private BeanPropertyPathBinding prevListener;
     private String[] nextPropertyPath;

Modified: trunk/src/lisp/snow/data-binding.lisp
==============================================================================
--- trunk/src/lisp/snow/data-binding.lisp	(original)
+++ trunk/src/lisp/snow/data-binding.lisp	Mon Oct 26 18:48:55 2009
@@ -134,11 +134,12 @@
 				obj (apply #'jvector "java.lang.String" path))))
 
 (defun make-el-data-binding-from-expression (el-expr)
-  (print el-expr)
   (let* ((splitted-expr (split-sequence #\. el-expr))
 	 (obj (funcall *bean-factory* (car splitted-expr)))
 	 (path (cdr splitted-expr)))
-    (make-el-data-binding obj path)))
+    (if path
+	(make-el-data-binding obj path)
+	(make-simple-data-binding (make-var obj)))))
 
 (defreadtable snow:syntax
   (:merge :standard)