[cells-gtk-cvs] CVS update: public_html/cgtk-primer.html
Peter Denno
pdenno at common-lisp.net
Sat Oct 8 15:03:01 UTC 2005
Update of /project/cells-gtk/cvsroot/public_html
In directory common-lisp.net:/tmp/cvs-serv17280/public_html
Modified Files:
cgtk-primer.html
Log Message:
Messy, some errors, but I'm going to use it anyway.
Date: Sat Oct 8 17:03:00 2005
Author: pdenno
Index: public_html/cgtk-primer.html
diff -u public_html/cgtk-primer.html:1.4 public_html/cgtk-primer.html:1.5
--- public_html/cgtk-primer.html:1.4 Sat Oct 1 21:03:15 2005
+++ public_html/cgtk-primer.html Sat Oct 8 17:03:00 2005
@@ -25,18 +25,101 @@
<h1>Introduction</h1>
-Here we will discuss the most important parts of the cell-gtk GTK binding, and how
-cells can be used in defining cells-gtk GUIs. As of this writing, we have begun
-the discussion of cells. This minimal introduction might be sufficient to get you
-started. We'll see.
+<strong>[This is Work In Progress currently. My apologies.]</strong><p/>
-<h1>Cells slots</h1>
+Here we will discuss the most important parts of the cells-gtk GTK binding, and how
+cells can be used in defining cells-gtk GUIs. This minimal introduction might be
+sufficient to get you started. We'll see.
+
+<h2>Cells, Cell slots, and all that...</h2>
+
+The example from <a href='http://bc.tech.coop/blog/030911.html'>Bill Clementson's Blog</a>
+is a nice starting point. Read it and come back here.<p/>
+
+...Welcome back. Perhaps you came back with the impression that Cells is a way to manage
+the relationship among the values in the slots of a CLOS object. That would be good.
+You might also imagine that if the slots describe the state of some real world object like a motor,
+you could use Cells to control the object -- to orchestrate how all its parts work together
+toward some goal. That also would be good. Now, if that object were a GTK-based GUI... no
+I'm getting ahead of myself. Let's look at the basic idea of Cells, it is similar to
+<a href="http://en.wikipedia.org/wiki/Constraint_satisfaction">constraint satisfaction</a>.
+That is, you have values, and rules that govern the relationships among the values,
+and whenever the network is pushed out of a consistent state (i.e. whenever the rules
+no longer hold), the objective is to get it back to a consistent one by updating some values.
+In Bill's example, <em>status fuelpump</em> and <em>temp</em> are cells -- slots in
+a motor CLOS object whose values are managed by the cells constraint network.
+The constraint network itself might be depicted as this:
+<p/>
+[graph]
+<p/>
+In this graph the nodes are values and edges have rules attached. The collection of edges
+into a node together with the rule are the cell.
+<!-- (hmmm is this going to work?) --> The green nodes
+are values controlled by cells and the empty nodes are regular 'unmanaged' values
+(such as you get by reading the value from regular CLOS slot).
+<p/>
+Cells such as <em>temp</em>, which have no edges leading into them, are called 'c-input cells'.
+A c-input cell gives you an opportunity to push the network out of a consistent state,
+so that it must find another consistent state (raise the temperature, force the motor
+and fuel pump to stop). They are one way the network interacts with its environment.
+(Thinking about GUI: Part of the 'environment' of your Cells-GTK application are lisp objects,
+the state of which you'd like to communicate to the user.)
+<p/>
+Another way that the cells network can interact with its environment is through
+c-output (or c-echo) methods. These are 'observers' of a cell that are invoked when the
+value of that cell is modified. They are sort of the converse of the c-input: modify
+a c-input value and the network reacts; when the network reacts, it can modify
+values outside the network with a c-output.
+<p/>
+So what about the values <em>inside</em> the network -- the nodes with edges pointing into them?
+Observing those with c-output methods and using c-input and setf to modify them would be
+bad form. If you program that way, you aren't doing anything that couldn't be done without Cells.
+Drop Cells-GTK and go back to programming in C-based GTK or Java. The result will be that you
+hand back to the programmer the burden of keeping track of every change to the GUI.
+C-input cells are intended (small apps like Bill's aside) to be used to 'instrument'
+(or "put sensors on") your code. If you have a legacy code that you are building a Cells-GTK GUI for, ....
+<p/>
+
+
+<!--
+[They are what allow the object represented by the network to interact with its environment.]
+-->
+<p/>
+
+
+<p/>
+Now reiterating the ideas above:
+
+<ul>
+ <li>A <strong>cell</strong> is a slot in a CLOS object whose value is managed by accessors that are
+ part of a cells constraint network.
+ <li>A <strong>cells constraint network</strong> is a collection of cells that are interrelated through
+ reference to each other or through reference to other lisp objects, through any level of indirection.
+ <li>A <strong>c-input cell</strong> is a cell whose value may be set through explicit procedural code,
+ using setf on the slot. Note: setf-ing the cell causes the values of other cells to be recomputed --
+ provided the cell is referenced by other cells in a cells constraint network.</li>
+ <li>A <strong>c-formula cell</strong> is a cell whose value is obtained through evaluation of a formula.
+ Note: The usual semantics of :initform do not apply when :initform is given by c-formula.
+ Instead of just setting the value at initialization, a formula (derived from the supplied lisp form)
+ specifies the dynamic relationship between the slot's value and other aspects of the program state.
+ <li>A <strong>c-output method</strong> is a method on a cell that is evaluated when the value of the
+ cell changes.
+</ul>
-The cells defmodel provides for the declaration of several kinds of "cell slots,"
+Cells provides for the declaration of several kinds of "cell slots,"
but for the purpose of talking about cells-gtk, we can limit the discussion to
-just a few kinds. However, first we should point out that by specifying
+just the c-input and c-formula cells. How do you recognize what kind of cell slot
+is being used? Well, first we should point out that by specifying
:cell nil in a defmodel slot definition, the slot defined is an ordinary CLOS
-slot and none of the following pertains.
+slot. The rest are specified using :initform on the slot. The following defmodel
+defines a c-input cell, a c-formula cell and a regular CLOS slot.
+
+<pre>
+(defmodel example ()
+ ((control-me :initform (c-input (some-form-foo)) :accessor control-me)
+ (im-computed :initform (c-formula (some-form-bar)) :accessor im-computed)
+ (im-clos :cell nil :initform nil)))
+</pre>
<tt>
<pre>
@@ -62,7 +145,6 @@
<li>A <strong>cell slot</strong> is specified by :cell t (advanced options aside)
or by omitting the :cell option, since in defmodel, the default is t.</li>
-
<li>An <strong>invariant cell slot</strong> is a cell slot that is initialized
by an ordinary lisp form, either by an :initarg in make-instance, an :initform
in the slot definition, or :default-initargs in the defmodel. The value of an
@@ -87,6 +169,10 @@
are consistent at some point after the values of some of them are changed.</li>
</ul>
+<h2>Cells and Cells-GTK</h2>
+
+<h2>Good Cells Technique</h2>
+
This all may seem abstract, but it has practical
value in the design of your GUI. For example, I might set the :sensitivity
of a button, the :text in a label or :fraction of a progress-bar based on
@@ -150,8 +236,32 @@
<h1>Family: Referencing cells throughout the defmodel hierarchy.</h1>
The <strong>defmodel</strong> macro defines a part-subpart relationship
-among components of the interface. The relationship is made by the
-<strong>:kids</strong> :initarg or :default-initargs, of the parent model.
+among components of the interface. The relationship is made by the <strong>:kids</strong> initarg.
+<strong>:kids</strong> is given a list of children. In a cells-gtk defmodel some kids might be GTKContainer
+(vbox, hbox, etc) -- things that in the GTK world, have kids of their own. It may be a natural coding practice
+in that case for the defmodel to define a fairly deep ancestory hierarchy, laying out the arrangement of widgets.
+(You're free to break things up wherever seem reasonable for your application). It might look like this:
+
+<pre>
+(defmodel my-app (gtk-app)
+ ()
+ (:default-initargs
+ :md-name :my-app
+ :kids
+ (list
+ (mk-vbox
+ :kids
+ (list
+ (mk-hbox
+ :kids
+ (list (mk-combo-box :md-name :my-combo) ...))
+ (mk-hbox
+ :kids
+ (list (make-instance 'my-subpart))))))))
+</pre>
+The point of the Family methods is to allow things a different places in this hierarchy (e.g. :my-combo
+to reference :my-app).
+
<p/>
<em>More will be written about this soon.</em>
More information about the Cells-gtk-cvs
mailing list