Add section on the SelectWidget changes [...] (quixote/doc/upgrading.txt)

Update of /home/cvs/quixote/doc
In directory hewson:/tmp/cvs-serv12915

Modified Files:
	upgrading.txt 
Log Message:
Add section on the SelectWidget changes
   -- please proofread, as I'm not sure I understood all of the ramifications
      of the changes


Index: upgrading.txt
===================================================================
RCS file: /home/cvs/quixote/doc/upgrading.txt,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- upgrading.txt	31 Dec 2002 20:06:50 -0000	1.2
+++ upgrading.txt	2 Jan 2003 18:48:17 -0000	1.3
@@ -9,6 +9,62 @@
 Changes from 0.5 to 0.6
 -----------------------
 
+SelectWidget Changes
+********************
+
+The constructor arguments to ``SelectWidget`` and its subclasses have
+changed.  This only affects applications that use the form framework
+located in the ``quixote.form`` package.
+
+In Quixote 0.5, the ``SelectWidget`` constructor had this signature::
+
+     def __init__ (self, name, value=None,
+                   allowed_values=None,
+                   descriptions=None,
+                   size=None,
+                   sort=0):
+
+``allowed_values`` was the list of objects that the user could choose,
+and ``descriptions`` was a list of strings that would actually be
+shown to the user in the generated HTML.
+
+In Quixote 0.6, the signature has changed slightly::
+
+     def __init__ (self, name, value=None,
+                   allowed_values=None,
+                   descriptions=None,
+                   options=None,
+                   size=None,
+                   sort=0):
+
+The ``quote`` argument is gone, and the ``options`` argument has been 
+added.  If an ``options`` argument is provided, ``allowed_values`` 
+and ``descriptions`` must not be supplied.
+
+The ``options`` argument, if present, must be a list of tuples with
+1,2, or 3 elements.  3-tuples must be of the form ``(value:any,
+description:any, key:string)``; 1- and 2-tuples 
+
+    * ``value`` is the object that will be returned if the user chooses 
+      this item, and must always be supplied.
+  
+    * ``description`` is a string or htmltext instance which will be
+      shown to the user in the generated HTML.  It will be passed
+      through the htmlescape() functions, so for an ordinary string
+      special characters such as '&' will be converted to '&'.
+      htmltext instances will be left as they are.
+
+    * If supplied, ``key`` will be used in the value attribute 
+      of the option element (``<option value="...">``).  
+      If not supplied, keys will be generated; ``value`` is checked for a 
+      ``_p_oid`` attribute and if present, that string is used; 
+      otherwise the description is used.
+
+In the common case, most applications won't have to change anything,
+though the ordering of selection items may change due to the
+difference in how keys are generated.
+
+
 File Upload Changes
 *******************