[snow-cvs] r79 - trunk/docs

[Alessio Stalla]

Author: astalla
Date: Thu Apr 29 14:59:28 2010
New Revision: 79

Log:
Updated widget reference documentation.


Modified:
   trunk/docs/style.css
   trunk/docs/tutorial.html
   trunk/docs/widget-reference.html

Modified: trunk/docs/style.css
==============================================================================
--- trunk/docs/style.css	(original)
+++ trunk/docs/style.css	Thu Apr 29 14:59:28 2010
@@ -1,4 +1,4 @@
-pre.paste-area {
+.paste-area {
     /* Taken from paste.lisp.org */
     background-color:#F4F4F4;
     border:2px solid #AAAAAA;
@@ -37,4 +37,4 @@
 .lisp-comment {
     background-color:inherit;
     color:#007777;
-}
\ No newline at end of file
+}

Modified: trunk/docs/tutorial.html
==============================================================================
--- trunk/docs/tutorial.html	(original)
+++ trunk/docs/tutorial.html	Thu Apr 29 14:59:28 2010
@@ -145,7 +145,7 @@
 #<javax.swing.JFrame ...frame.toString()... {identityHashCode}>
 </pre>
   </li>
-  <li>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.</li>
+  <li>if a Java backing bean is used (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.</li>
 </ul>
 <h4>special variable <code>*backing-bean*</code></h4>
 This variable is usually set from Java code embedding Snow (see the <a href="#embedding">appropriate section</a>). 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 <a href="#events">Event handling</a> for more information.

Modified: trunk/docs/widget-reference.html
==============================================================================
--- trunk/docs/widget-reference.html	(original)
+++ trunk/docs/widget-reference.html	Thu Apr 29 14:59:28 2010
@@ -7,85 +7,85 @@
 <h1>Snow Widget Reference</h1>
 <h3>Common properties</h3>
 These properties are available on every widget, unless stated otherwise.
-<table border="1">
-  <tr>
-    <th>Name</th>
-    <th style="width: 30%;">Type</th>
-    <th style="width: 30%;">Description</th>
-    <th>Examples</th>
-    <th>Notes</th>
-  </tr>
-  <tr>
-    <td style="text-align: center;"><strong><code>id</code></strong></td>
-    <td style="text-align: center;">symbol</td>
-    <td>Binds a lexical variable to the current widget locally to the widget body.</td>
-    <td><pre class="paste-area">
-(frame (:id foo)
-  (print foo))</pre></td>
-    <td>For containers only.</td>
-  </tr>
-  <tr>
-    <td style="text-align: center;"><strong><code>layout-manager</code></strong></td>
-    <td>
+<hr />
+<h2><code>id</code></h2>
+<strong>Type:</strong> symbol<br />
+<strong>Description:</strong> This pseudo-property has several uses:
+<ul>
+  <li>if a lexical variable with the same name as the id exists, it will be assigned the widget.</li>
+  <li>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.</li>
+  </li>
+  <li>if a Java backing bean is used (as the value of *backing-bean*), 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.</li>
+</ul>
+<strong>Examples:</strong>
+<pre class="paste-area">
+(frame (:id foo) foo)
+==> #<javax.swing.JFrame ...frame.toString()... {identityHashCode}>
+
+(let (bar)
+  (label :id bar)
+  bar)
+==> #<javax.swing.JLabel ...label.toString()... {identityHashCode}></pre>
+<hr />
+<h2><code>layout-manager</code></h2>
+<strong>Type:</strong> a member of the following set of values:
       <ul>
         <li>one of :default, :mig, :border, :box, :flow</li>
         <li>a list whose car is one of the above and whose cdr are additional arguments</li>
         <li>a native Java layout manager.</li>
       </ul>
-    </td>
-    <td>Sets the policy for laying out the component's children.</td>
-    <td><pre class="paste-area">
+<strong>Description:</strong> Sets the policy for laying out the component's children. For containers only. If not specified, defaults to :default - which is the same as :mig, i.e., MiGLayout is used.<br />
+<strong>Examples:</strong>
+<pre class="paste-area">
 (panel (:layout-manager '(:box :y))
   (label :text "First Line")
-  (label :text "Second Line"))</pre></td>
-    <td>For containers only.</td>
-  </tr>
-  <tr>
-    <td style="text-align: center;"><strong><code>layout</code></strong></td>
-    <td style="text-align: center;">string</td>
-    <td>Constraints used to control how the component is to be laid out in its container. The possible values and their meaning depend on the layout manager of the container.</td>
-    <td><pre class="paste-area">
+  (label :text "Second Line"))</pre>
+<hr />
+<h2><code>layout</code></h2>
+<strong>Type:</strong> string<br />
+<strong>Description:</strong> Constraints used to control how the component is to be laid out in its container. The possible values and their meaning depend on the layout manager of the container.<br />
+<strong>Examples:</strong>
+<pre class="paste-area">
 (panel ()
-  (label :layout "grow, wrap"
-         :text "hello")
-  (label :text "world"))</pre></td>
-    <td><br /></td>
-  </tr>
-  <tr>
-    <td style="text-align: center;"><strong><code>enabled-p</code></strong></td>
-    <td style="text-align: center;">boolean</td>
-    <td>Controls whether the widget is enabled (able to receive user input).</td>
-    <td><br /></td>
-    <td><br /></td>
-  </tr>
-  <tr>
-    <td style="text-align: center;"><strong><code>size</code></strong></td>
-    <td style="text-align: center;">complex</td>
-    <td>Sets the size of the widget.</td>
-    <td><pre class="paste-area">
-(frame (:size #C(800 600)))</pre></td>
-    <td>The size is represented as a complex number whose real part is the Width and imaginary part is the Height.</td>
-  </tr>
-</table>
+  (label :layout "grow, wrap" :text "hello")
+  (label :text "world"))</pre>
+<hr />
+<h2><code>enabled-p</code></h2>
+<strong>Type:</strong> boolean<br />
+<strong>Description:</strong> Controls whether the widget is enabled (able to receive user input).
+<hr />
+<h2><code>size</code></h2>
+<strong>Type:</strong> complex<br />
+<strong>Description:</strong> Sets the size of the widget. The size is represented as a complex number whose real part is the Width and imaginary part is the Height.<br />
+<strong>Example:</strong>
+<pre class="paste-area">(frame (:size #C(800 600)))</pre>
+<hr />
+<h2><code>label</code></h2>
+<strong>Type:</strong> a label widget.<br />
+<strong>Description:</strong> Connects a label to this widget. Typically, clicking on the label will bring focus on the widget.<br />
+<strong>Examples:</strong>
+<pre class="paste-area">
+(let (lbl)
+  (label :id lbl :text "User Name: ")
+  (text-field :label lbl))</pre>
+Or, shorter, using an inline label:
+<pre class="paste-area">
+(text-field :label (label :text "User Name: "))</pre>
+<hr />
 <h3>Widgets</h3>
-Here's a summary of the widgets (GUI components) currently available in Snow. The "C" column indicates whether the widget is a container. You can follow the hyperlink on a widget's name to read about its properties.
+Here's a summary of the widgets (GUI components) currently available in Snow. The "C" column indicates whether the widget is a container. You can follow the hyperlink on a widget's name to read about its properties.<br /><br />
 <table border="1">
   <tr>
-    <th rowspan="2">Name</th>
-    <th rowspan="2">Description</th>
-    <th rowspan="2">C</th>
-    <th>Backend</th>
-    <th rowspan="2">Examples</th>
-    <th rowspan="2">Notes</th>
-  </tr>
-  <tr>
-    <th>Swing</th>
+    <th>Name</th>
+    <th>Description</th>
+    <th>C</th>
+    <th>Examples</th>
+    <th>Notes</th>
   </tr>
   <tr>
     <td style="text-align: center;"><strong><a href="#button_props"><code>button</code></a></strong></td>
     <td>A button with text on it.</td>
     <td><br /></td>
-    <td style="text-align: center;">Y</td>
     <td><pre class="paste-area">
 (button :text "Ok!")</pre></td>
     <td><br /></td>
@@ -94,7 +94,6 @@
     <td style="text-align: center;"><strong><code>check-box</code></strong></td>
     <td>A checkbox with optional text.</td>
     <td><br /></td>
-    <td style="text-align: center;">Y</td>
     <td><pre class="paste-area">
 (check-box :text "Enabled")</pre></td>
     <td><br /></td>
@@ -103,7 +102,6 @@
     <td style="text-align: center;"><strong><code>frame</code></strong></td>
     <td>A top-level window.</td>
     <td style="text-align: center;">Y</td>
-    <td style="text-align: center;">Y</td>
     <td><pre class="paste-area">
 (frame (:title "A frame" :on-close :exit)
   (label :text "push")
@@ -114,7 +112,6 @@
     <td style="text-align: center;"><strong><code>label</code></strong></td>
     <td>Read-only text.</td>
     <td><br /></td>
-    <td style="text-align: center;">Y</td>
     <td><pre class="paste-area">
 (label :text "Hello")</pre></td>
     <td><br /></td>
@@ -123,7 +120,6 @@
     <td style="text-align: center;"><strong><code>list-widget</code></strong></td>
     <td>Displays a list of strings.</td>
     <td><br /></td>
-    <td style="text-align: center;">Y</td>
     <td><pre class="paste-area">
 (list-widget :model (make-cons-list-model '("foo" "bar" "baz")))</pre></td>
     <td>Not named list to avoid clashing with the commonly used function by the same name in the COMMON-LISP package.</td>
@@ -132,7 +128,6 @@
     <td style="text-align: center;"><strong><code>panel</code></strong></td>
     <td>A generic container for other components.</td>
     <td style="text-align: center;">Y</td>
-    <td style="text-align: center;">Y</td>
     <td><pre class="paste-area">
 (panel ()
   (label :text "push")
@@ -143,7 +138,6 @@
     <td style="text-align: center;"><strong><code>scroll</code></strong></td>
     <td>A container for a single child, providing scrollbar support.</td>
     <td style="text-align: center;">Y</td>
-    <td style="text-align: center;">Y</td>
     <td><pre class="paste-area">
 (scroll ()
   (text-area :text "very, very, ..., long text"))</pre></td>
@@ -153,7 +147,6 @@
     <td style="text-align: center;"><strong><code>text-area</code></strong></td>
     <td>Allows the user to enter multiple lines of text.</td>
     <td><br /></td>
-    <td style="text-align: center;">Y</td>
     <td><pre class="paste-area">
 (text-area :text "type something here")</pre></td>
     <td><br /></td>
@@ -162,7 +155,6 @@
     <td style="text-align: center;"><strong><code>text-field</code></strong></td>
     <td>Allows the user to enter a single line of text.</td>
     <td><br /></td>
-    <td style="text-align: center;">Y</td>
     <td><pre class="paste-area">
 (text-field :text "type something here")</pre></td>
     <td><br /></td>
@@ -171,7 +163,6 @@
     <td style="text-align: center;"><strong><code>tree</code></strong></td>
     <td>Displays hierarchical data in the form of a tree with expandable/collapsible nodes.</td>
     <td><br /></td>
-    <td style="text-align: center;">Y</td>
     <td><pre class="paste-area">
 (tree :model (make-cons-tree-model '("foo" ("bar" "baz"))))</pre></td>
     <td><br /></td>