API docstrings from pydocweb

3 files changed, 140 insertions, 3 deletions

diff --git a/src/sugar/graphics/alert.py b/src/sugar/graphics/alert.py
index 541079f..12e4763 100644
--- a/src/sugar/graphics/alert.py
+++ b/src/sugar/graphics/alert.py
@@ -1,3 +1,31 @@
+"""
+Alerts appear at the top of the body of your activity.
+
+At a high level, Alert and its different variations (TimeoutAlert,
+ConfirmationAlert, etc.) have a title, an alert message and then several
+buttons that the user can click. The Alert class will pass "response" events
+to your activity when any of these buttons are clicked, along with a
+response_id to help you identify what button was clicked.
+
+
+Examples
+--------
+create a simple alert message.
+
+.. code-block:: python
+  from sugar.graphics.alert import Alert
+  ...
+       # Create a new simple alert
+        alert = Alert()
+        # Populate the title and text body of the alert.
+        alert.props.title=_('Title of Alert Goes Here')
+        alert.props.msg = _('Text message of alert goes here')
+        # Call the add_alert() method (inherited via the sugar.graphics.Window superclass of Activity)
+        # to add this alert to the activity window.
+        self.add_alert(alert)
+        alert.show()
+
+"""
 # Copyright (C) 2007, One Laptop Per Child
 #
 # This library is free software; you can redistribute it and/or
@@ -28,7 +56,8 @@ from sugar.graphics.icon import Icon
 _ = lambda msg: gettext.dgettext('sugar-toolkit', msg)
 
 class Alert(gtk.EventBox):
-    """UI interface for Alerts
+    """
+    UI interface for Alerts
 
     Alerts are used inside the activity window instead of being a
     separate popup window. They do not hide canvas content. You can
@@ -40,7 +69,9 @@ class Alert(gtk.EventBox):
         'title': the title of the alert,
         'message': the message of the alert,
         'icon': the icon that appears at the far left
+
     See __gproperties__
+
     """
 
     __gtype_name__ = 'SugarAlert'
@@ -209,7 +240,43 @@ class Alert(gtk.EventBox):
 
 
 class ConfirmationAlert(Alert):
-    """This is a ready-made two button (Cancel,Ok) alert"""
+    """
+    This is a ready-made two button (Cancel,Ok) alert.
+
+    A confirmation alert is a nice shortcut from a standard Alert because it
+    comes with 'OK' and 'Cancel' buttons already built-in. When clicked, the
+    'OK' button will emit a response with a response_id of gtk.RESPONSE_OK,
+    while the 'Cancel' button will emit gtk.RESPONSE_CANCEL.
+
+    Examples
+    --------
+
+    .. code-block:: python
+      from sugar.graphics.alert import ConfirmationAlert
+      ...
+        #### Method: _alert_confirmation, create a Confirmation alert (with ok and cancel buttons standard)
+        # and add it to the UI.
+        def _alert_confirmation(self):
+            alert = ConfirmationAlert()
+            alert.props.title=_('Title of Alert Goes Here')
+            alert.props.msg = _('Text message of alert goes here')
+            alert.connect('response', self._alert_response_cb)
+            self.add_alert(alert)
+
+
+        #### Method: _alert_response_cb, called when an alert object throws a response event.
+        def _alert_response_cb(self, alert, response_id):
+            #remove the alert from the screen, since either a response button was clicked or
+            #there was a timeout
+            self.remove_alert(alert)
+
+            #Do any work that is specific to the type of button clicked.
+            if response_id is gtk.RESPONSE_OK:
+                print 'Ok Button was clicked. Do any work upon ok here ...'
+            elif response_id is gtk.RESPONSE_CANCEL:
+                print 'Cancel Button was clicked.'
+
+    """
 
     def __init__(self, **kwargs):
         Alert.__init__(self, **kwargs)
diff --git a/src/sugar/graphics/notebook.py b/src/sugar/graphics/notebook.py
index bc6bab5..e159bb3 100644
--- a/src/sugar/graphics/notebook.py
+++ b/src/sugar/graphics/notebook.py
@@ -49,6 +49,23 @@ class Notebook(gtk.Notebook):
         self.show()
 
     def do_set_property(self, pspec, value):
+        """
+        Set notebook property
+
+        Parameters
+        ----------
+        pspec :
+            property for which the value will be set
+
+        Returns
+        -------
+        None
+
+        Raises
+        ------
+        AssertionError
+
+        """
         if pspec.name == 'can-close-tabs':
             self._can_close_tabs = value
         else:
@@ -93,6 +110,21 @@ class Notebook(gtk.Notebook):
         return event_box
 
     def add_page(self, text_label, widget):
+        """
+        Adds a page to the notebook.
+
+        Parameters
+        ----------
+        text_label :
+
+        widget :
+
+        Returns
+        -------
+        Boolean
+          Returns TRUE if the page is successfully added to th notebook.
+
+        """
         # Add a new page to the notebook
         if self._can_close_tabs:
             eventbox = self._create_custom_tab(text_label, widget)
diff --git a/src/sugar/graphics/radiotoolbutton.py b/src/sugar/graphics/radiotoolbutton.py
index e2636dc..1fb18cc 100644
--- a/src/sugar/graphics/radiotoolbutton.py
+++ b/src/sugar/graphics/radiotoolbutton.py
@@ -24,6 +24,10 @@ from sugar.graphics.palette import Palette, ToolInvoker
 from sugar.graphics import toolbutton
 
 class RadioToolButton(gtk.RadioToolButton):
+    """
+    An implementation of a "push" button.
+
+    """
     __gtype_name__ = 'SugarRadioToolButton'
 
     def __init__(self, **kwargs):
@@ -43,7 +47,17 @@ class RadioToolButton(gtk.RadioToolButton):
             self._palette_invoker.detach()
 
     def set_tooltip(self, tooltip):
-        """ Set a simple palette with just a single label.
+        """
+        Set a simple palette with just a single label.
+
+        Parameters
+        ----------
+        tooltip:
+
+        Returns
+        -------
+        None
+
         """
         if self.palette is None or self._tooltip is None:
             self.palette = Palette(tooltip)
@@ -61,10 +75,34 @@ class RadioToolButton(gtk.RadioToolButton):
     tooltip = gobject.property(type=str, setter=set_tooltip, getter=get_tooltip)
 
     def set_accelerator(self, accelerator):
+        """
+        Sets the accelerator.
+
+        Parameters
+        ----------
+        accelerator:
+
+        Returns
+        -------
+        None
+
+        """
         self._accelerator = accelerator
         toolbutton.setup_accelerator(self)
 
     def get_accelerator(self):
+        """
+        Returns the accelerator for the button.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        ------
+        accelerator:
+
+        """
         return self._accelerator
 
     accelerator = gobject.property(type=str, setter=set_accelerator,