[snow-cvs] r14 - trunk/docs

[Alessio Stalla]

Author: astalla
Date: Wed Nov  4 17:33:00 2009
New Revision: 14

Log:
Updated tutorial with $ syntax.


Modified:
   trunk/docs/tutorial.html

Modified: trunk/docs/tutorial.html
==============================================================================
--- trunk/docs/tutorial.html	(original)
+++ trunk/docs/tutorial.html	Wed Nov  4 17:33:00 2009
@@ -161,7 +161,7 @@
 ...
 </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.
+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 libraries 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">
@@ -173,7 +173,7 @@
 </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.
+Snow supports several types of data binding; some are more indicated for Lisp applications, others 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">
@@ -181,7 +181,7 @@
 (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:
+<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 provided by JGoodies); 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"))
@@ -204,14 +204,23 @@
                     *x* (c? (* 2 (my-slot *x*)))
                     (lambda (new-value) (setf (my-slot *x*) new-value))))
 </pre></li>
-
+</ul>
+<h4>Syntactic sugar</h4>
+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 <code>(in-readtable snow:syntax)</code>, for example placing it in every source file right after the <code>(in-package :snow-user)</code> form at the top of the file.<br />
+This special syntax is accessed by using the prefix $. It covers the following cases:
+<ul>
+<li><code>$foo</code> is equivalent to <code>(make-simple-data-binding foo)</code>.</li>
+<li><code>$(c? ...)</code> is equivalent to <code>(make-cell-data-binding (c? ...))</code>.</li>
+<li><code>$(slot ...)</code> is equivalent to <code>(make-slot-data-binding ...)</code>.</li>
+<li><code>${bean.path}</code> is a bit more complex. This syntax resembles that of the "Expression Language" used in JSP and JSF. First, <code>bean</code> is used as the name of a bean: the function stored in the special variable <code>*bean-factory*</code> is called with it as an argument to produce a Java object. The default function simply reads and evaluates <code>bean</code> 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<sup><a href="#notes_2">2</a></sup>. Then, once the bean has been obtained, two things can happen: if <code>path</code> 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 <code>(make-bean-data-binding bean path)</code>; else, a property path data binding is constructed, as by <code>(make-property-data-binding bean path-as-list)</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.
+I haven't covered which widgets are supported and how much of their API is supported. At this stage, Snow is in a early stage of development, 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 />
 <h3>Footnotes</h3>
 <ol>
   <li><a name="notes_1" />If you <i>really</i> 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.</li>
+  <li><a name="notes_2" />Snow provides a convenient Java class - <code>org.armedbear.lisp.Callback</code> - that you can subclass to create your custom callback function. You have just to implement the appropriate overload of the <code>call</code> method, or alternatively use one of the static methods <code>Callback.fromXXX</code> to create a Callback from several kinds of Java callbacks.</li>
 </ol>
 </body>
 </html>