Merge branch 'doc-combobox' of https://github.com/samdroid-apps/sugar-toolkit-gtk3

src/sugar3/graphics/combobox.py

@@ -15,9 +15,15 @@
 # Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 # Boston, MA 02111-1307, USA.
 
-"""
-STABLE.
-"""
+'''
+The combobox module provides a combo box; a button like widget which
+creates a list popup when clicked.  It's best used outside of a
+toolbar when the user needs to choose from a *short* list of items.
+
+Example:
+
+.. literalinclude:: ../examples/combobox.py
+'''
 
 from gi.repository import GObject
 from gi.repository import Gtk
@@ -25,7 +31,11 @@ from gi.repository import GdkPixbuf
 
 
 class ComboBox(Gtk.ComboBox):
-
+    '''
+    This class provides a simple wrapper based on the :class:`Gtk.ComboBox`.
+    This lets you make a list of items, with a value, label and optionally an
+    icon.
+    '''
     __gtype_name__ = 'SugarComboBox'
 
     def __init__(self):
@@ -43,6 +53,13 @@ class ComboBox(Gtk.ComboBox):
         self.set_row_separator_func(self._is_separator, None)
 
     def get_value(self):
+        '''
+        The value of the currently selected item; the same as the `value`
+        argument that was passed to the `append_item` func.
+
+        Returns:
+            object, value of selected item
+        '''
         row = self.get_active_item()
         if not row:
             return None
@@ -61,7 +78,22 @@ class ComboBox(Gtk.ComboBox):
         del info
         return fname
 
-    def append_item(self, action_id, text, icon_name=None, file_name=None):
+    def append_item(self, value, text, icon_name=None, file_name=None):
+        '''
+        This function adds another item to the bottom of the combo box list.
+
+        If either `icon_name` or `file_name` are supplied and icon column
+        will be added to the combo box list.
+
+        Args:
+            value (object):  the value that will be returned by `get_value`,
+                when this item is selected
+            text (str):  the user visible label for the item
+            icon_name (str):  the name of the icon in the theme to use for
+                this item, optional and conflicting with `file_name`
+            file_name (str):  the path to a sugar (svg) icon to use for this
+                item, optional and conflicting with `icon_name`
+        '''
         if not self._icon_renderer and (icon_name or file_name):
             self._icon_renderer = Gtk.CellRendererPixbuf()
 
@@ -93,12 +125,24 @@ class ComboBox(Gtk.ComboBox):
         else:
             pixbuf = None
 
-        self._model.append([action_id, text, pixbuf, False])
+        self._model.append([value, text, pixbuf, False])
 
     def append_separator(self):
+        '''
+        Add a separator to the bottom of the combo box list.  The separator
+        can not be selected.
+        '''
         self._model.append([0, None, None, True])
 
     def get_active_item(self):
+        '''
+        Get the row of data for the currently selected item.
+
+        Returns:
+            row of data in the format::
+
+                [value, text, pixbuf, is_separator]
+        '''
         index = self.get_active()
         if index == -1:
             index = 0
@@ -109,6 +153,9 @@ class ComboBox(Gtk.ComboBox):
         return self._model[row]
 
     def remove_all(self):
+        '''
+        Remove all list items from the combo box.
+        '''
         self._model.clear()
 
     def _is_separator(self, model, row, data):