[wwwsearch-commits] r18439 - wwwsearch/ClientForm/trunk

[jjlee at codespeak.net]

Author: jjlee
Date: Wed Oct 12 01:31:54 2005
New Revision: 18439

Modified:
   wwwsearch/ClientForm/trunk/ClientForm.py
Log:
Update docstrings that were missed in 0.2.0a release

Modified: wwwsearch/ClientForm/trunk/ClientForm.py
==============================================================================
--- wwwsearch/ClientForm/trunk/ClientForm.py	(original)
+++ wwwsearch/ClientForm/trunk/ClientForm.py	Wed Oct 12 01:31:54 2005
@@ -1450,11 +1450,13 @@
 class ListControl(Control):
     """Control representing a sequence of items.
 
-    The value attribute of a ListControl represents the selected list items in
-    the control.
-
-    ListControl implements both list controls that take a single value and
-    those that take multiple values.
+    The value attribute of a ListControl represents the successful list items
+    in the control.  The successful list items are those that are selected and
+    not disabled.
+
+    ListControl implements both list controls that take a length-1 value
+    (single-selection) and those that take length >1 values
+    (multiple-selection).
 
     ListControls accept sequence values only.  Some controls only accept
     sequences of length 0 or 1 (RADIO, and single-selection SELECT).
@@ -1471,8 +1473,8 @@
     in the order they were listed in the HTML.
 
     ListControl items can also be referred to by their labels instead of names.
-    Use the by_label argument, and the set_value_by_label, get_value_by_label
-    methods.
+    Use the label argument to .get(), and the .set_value_by_label(),
+    .get_value_by_label() methods.
 
     Note that, rather confusingly, though SELECT controls are represented in
     HTML by SELECT elements (which contain OPTION elements, representing
@@ -2318,7 +2320,7 @@
     # select *only* the item named "cheddar"
     form["cheeses"] = ["cheddar"]
     # select "cheddar", leave other items unaffected
-    form.set("cheddar", "cheeses")
+    form.find_control("cheeses").get("cheddar").selected = True
 
     Some controls (RADIO and SELECT without the multiple attribute) can only
     have zero or one items selected at a time.  Some controls (CHECKBOX and
@@ -2331,10 +2333,12 @@
     If the ListControl is not multiple-selection, the assigned list must be of
     length one.
 
-    To check whether a control has an item, or whether an item is selected,
-    respectively:
+    To check if a control has an item, if an item is selected, or if an item is
+    successful (selected and not disabled), respectively:
 
     "cheddar" in [item.name for item in form.find_control("cheeses").items]
+    "cheddar" in [item.name for item in form.find_control("cheeses").items and
+                  item.selected]
     "cheddar" in form["cheeses"]  # (or "cheddar" in form.get_value("cheeses"))
 
     Note that some list items may be disabled (see below).
@@ -2348,9 +2352,8 @@
     in the order they were listed in the HTML.
 
     List items (hence list values, too) can be referred to in terms of list
-    item labels rather than list item names.  To use this feature, use the
-    by_label arguments to the various HTMLForm methods.  Note that each item
-    may have several labels.
+    item labels rather than list item names using the appropriate label
+    arguments.  Note that each item may have several labels.
 
     The question of default values of OPTION contents, labels and values is
     somewhat complicated: see SelectControl.__doc__ and
@@ -2362,9 +2365,8 @@
     control.  Disabled controls are not 'successful' -- they don't cause data
     to get returned to the server.  Readonly controls usually appear in
     browsers as read-only text boxes.  Readonly controls are successful.  List
-    items can also be disabled.  Attempts to select disabled items (with
-    form[name] = value, or using the ListControl.set method, for example) fail.
-    Attempts to clear disabled items are allowed.
+    items can also be disabled.  Attempts to select or deselect disabled items
+    fail with AttributeError.
 
     If a lot of controls are readonly, it can be useful to do this:
 
@@ -2423,20 +2425,19 @@
 
     Most of the these methods have very similar arguments.  See
     HTMLForm.find_control.__doc__ for details of the name, type, kind, label
-    and nr arguments.  See above for a description of by_label.  Note that
-    by_label refers to *item* labels; label refers to *control* labels (the
-    naming and the odd position of 'label' in argument lists is unfortunate,
-    but necessary for backwards-compatibility with version 0.1).
+    and nr arguments.
 
     def find_control(self,
                      name=None, type=None, kind=None, id=None, predicate=None,
                      nr=None, label=None)
 
     get_value(name=None, type=None, kind=None, id=None, nr=None,
-              by_label=False, label=None)
+              by_label=False,  # by_label is deprecated
+              label=None)
     set_value(value,
               name=None, type=None, kind=None, id=None, nr=None,
-              by_label=False, label=None)
+              by_label=False,  # by_label is deprecated
+              label=None)
 
     clear_all()
     clear(name=None, type=None, kind=None, id=None, nr=None, label=None)