Write docs for sugar3.graphics.radiotoolbutton

examples/radiotoolbutton.py

@@ -0,0 +1,47 @@
+from gi.repository import Gtk
+
+from sugar3.graphics.radiotoolbutton import RadioToolButton
+from sugar3.graphics.radiopalette import RadioPalette, RadioMenuButton
+from sugar3.graphics.xocolor import XoColor
+from sugar3.graphics import style
+
+
+window = Gtk.Window()
+window.show()
+window.connect("destroy", Gtk.main_quit)
+
+box = Gtk.HBox()
+window.add(box)
+box.show()
+
+
+def echo(button, label):
+    if not button.props.active:
+        return
+    print label
+
+
+palette = RadioPalette()
+# Adding 3 RadioToolButtons to a palette
+
+button1 = RadioToolButton(icon_name='document-save', accelerator="<ctrl>S",
+                          xo_color=XoColor("white"))
+button1.connect('toggled', lambda button: echo(button, 'document-save'))
+palette.append(button1, 'menu.document-save')
+
+button2 = RadioToolButton(icon_name='document-open', accelerator="<ctrl>O",
+                          xo_color=XoColor("white"), group=button1)
+button2.connect('toggled', lambda button: echo(button, 'document-open'))
+palette.append(button2, 'menu.document-open')
+
+button3 = RadioToolButton(icon_name='document-send', accelerator="<ctrl>F",
+                          xo_color=XoColor("white"), group=button1)
+button3.connect('toggled', lambda button: echo(button, 'document-send'))
+palette.append(button3, 'menu.document-send')
+
+button = RadioMenuButton(palette=palette)
+box.pack_start(button, False, False, 1)
+button.show()
+
+if __name__ == '__main__':
+    Gtk.main()

src/sugar3/graphics/radiotoolbutton.py

@@ -16,9 +16,19 @@
 # Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 # Boston, MA 02111-1307, USA.
 
-"""
-STABLE.
-"""
+'''
+Provides a RadioToolButton class, similar to a "push" button.
+A group of RadioToolButtons can be set, so that only one can be
+selected at a time. When a button is clicked, it depresses and
+is shaded darker.
+
+It is also possible to set a tooltip to be dispalyed when the
+user scrolls over it with their cursor as well as an accelerator
+keyboard shortcut.
+
+Example:
+    .. literalinclude:: ../examples/radiotoolbutton.py
+'''
 
 from gi.repository import Gtk
 from gi.repository import GObject
@@ -29,7 +39,24 @@ from sugar3.graphics import toolbutton
 
 
 class RadioToolButton(Gtk.RadioToolButton):
-    """An implementation of a "push" button."""
+    '''
+    An implementation of a "push" button.
+
+    Args:
+        icon_name (string): name of icon to be used
+
+    Keyword Args:
+
+        accelerator (string): keyboard shortcut to be used to
+        activate this button
+
+        tooltip (string): tooltip to be displayed when user hovers over button
+
+        xo_color (sugar3.graphics.xocolor.XoColor): XoColor of button
+
+        hide_tooltip_on_click (bool): Whether or not the tooltip
+            is hidden when user clicks on button
+    '''
 
     __gtype_name__ = 'SugarRadioToolButton'
 
@@ -60,6 +87,13 @@ class RadioToolButton(Gtk.RadioToolButton):
             self._palette_invoker.detach()
 
     def set_tooltip(self, tooltip):
+        '''
+        Sets the tooltip of the radiotoolbutton. Displays when
+        user hovers over the button with cursor.
+
+        Args:
+            tooltip (string): tooltip to be added to the button
+        '''
         if self.palette is None or self._tooltip is None:
             self.palette = Palette(tooltip)
         elif self.palette is not None:
@@ -71,28 +105,50 @@ class RadioToolButton(Gtk.RadioToolButton):
         Gtk.RadioToolButton.set_label(self, tooltip)
 
     def get_tooltip(self):
+        '''
+        Returns the tooltip
+        '''
         return self._tooltip
 
     tooltip = GObject.property(type=str, setter=set_tooltip,
                                getter=get_tooltip)
 
     def set_accelerator(self, accelerator):
+        '''
+        Sets keyboard shortcut that activates this button
+
+        Args:
+            accelerator (string): accelerator to be set. Should be in
+            form <modifier>Letter
+        '''
         self._accelerator = accelerator
         toolbutton.setup_accelerator(self)
 
     def get_accelerator(self):
+        '''
+        Returns accelerator string
+        '''
         return self._accelerator
 
     accelerator = GObject.property(type=str, setter=set_accelerator,
                                    getter=get_accelerator)
 
     def set_icon_name(self, icon_name):
+        '''
+        Sets name of icon
+
+        Args:
+            icon_name (string): name of icon
+        '''
         icon = Icon(icon_name=icon_name,
                     xo_color=self._xo_color)
         self.set_icon_widget(icon)
         icon.show()
 
     def get_icon_name(self):
+        '''
+        Returns icon name
+        '''
         if self.props.icon_widget is not None:
             return self.props.icon_widget.props.icon_name
         else:
@@ -102,12 +158,21 @@ class RadioToolButton(Gtk.RadioToolButton):
                                  getter=get_icon_name)
 
     def set_xo_color(self, xo_color):
+        '''
+        Sets XoColor of button icon
+
+        Args:
+            xo_color (sugar3.graphics.xocolor.XoColor): xocolor to be set
+        '''
         if self._xo_color != xo_color:
             self._xo_color = xo_color
             if self.props.icon_widget is not None:
                 self.props.icon_widget.props.xo_color = xo_color
 
     def get_xo_color(self):
+        '''
+        Returns xocolor
+        '''
         return self._xo_color
 
     xo_color = GObject.property(type=object, setter=set_xo_color,
@@ -136,6 +201,9 @@ class RadioToolButton(Gtk.RadioToolButton):
         type=object, setter=set_palette_invoker, getter=get_palette_invoker)
 
     def do_draw(self, cr):
+        '''
+        Implementation method for drawing the button
+        '''
         if self.palette and self.palette.is_up():
             allocation = self.get_allocation()
             # draw a black background, has been done by the engine before
@@ -152,9 +220,21 @@ class RadioToolButton(Gtk.RadioToolButton):
         return False
 
     def get_hide_tooltip_on_click(self):
+        '''
+        Returns True if the tooltip is hidden when a user
+        clicks on the button, otherwise returns false
+        '''
         return self._hide_tooltip_on_click
 
     def set_hide_tooltip_on_click(self, hide_tooltip_on_click):
+        '''
+        Sets whether or not the tooltip is hidden when a user
+        clicks on the radiotoolbutton.
+
+        Args:
+            hide_tooltip_on_click (bool): True if the tooltip is
+            hidden on click, and False otherwise
+        '''
         if self._hide_tooltip_on_click != hide_tooltip_on_click:
             self._hide_tooltip_on_click = hide_tooltip_on_click
 
@@ -163,5 +243,8 @@ class RadioToolButton(Gtk.RadioToolButton):
         setter=set_hide_tooltip_on_click)
 
     def do_clicked(self):
+        '''
+        Implementation method for hiding the tooltip when the button is clicked
+        '''
         if self._hide_tooltip_on_click and self.palette:
             self.palette.popdown(True)