Merge pull request #349 from quozl/2016-347-toolbutton

Write documentation for sugar3.graphics.ToolButton

examples/toolbutton.py

@@ -0,0 +1,35 @@
+from gi.repository import Gtk
+
+from sugar3.graphics.toolbarbox import ToolbarBox
+from sugar3.graphics.toolbutton import ToolButton
+
+import common
+
+
+test = common.Test()
+
+vbox = Gtk.VBox()
+test.pack_start(vbox, True, True, 0)
+
+toolbar_box = ToolbarBox()
+vbox.pack_start(toolbar_box, False, False, 0)
+
+separator = Gtk.SeparatorToolItem()
+toolbar_box.toolbar.insert(separator, -1)
+
+
+def __clicked_cb(button):
+    n = int(button.get_tooltip())
+    button.set_tooltip(str(n+1))
+    print "tool button click count %d" % n
+
+tool_button = ToolButton(icon_name='view-radial', tooltip='0')
+tool_button.connect('clicked', __clicked_cb)
+tool_button.set_hide_tooltip_on_click(False)
+tool_button.set_accelerator('<Space>')
+toolbar_box.toolbar.insert(tool_button, -1)
+
+test.show_all()
+
+if __name__ == '__main__':
+    common.main(test)

src/sugar3/graphics/radiotoolbutton.py

@@ -40,22 +40,24 @@ from sugar3.graphics import toolbutton
 
 class RadioToolButton(Gtk.RadioToolButton):
     '''
-    An implementation of a "push" button.
+    The RadioToolButton class manages a Gtk.RadioToolButton styled for
+    Sugar.
 
     Args:
-        icon_name (string): name of icon to be used
+        icon_name (string): name of icon to be used.
 
     Keyword Args:
 
         accelerator (string): keyboard shortcut to be used to
-        activate this button
+            activate this button.
 
-        tooltip (string): tooltip to be displayed when user hovers over button
+        tooltip (string): tooltip to be displayed when user hovers
+            over button.
 
-        xo_color (sugar3.graphics.xocolor.XoColor): XoColor of 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
+            is hidden when user clicks on button.
     '''
 
     __gtype_name__ = 'SugarRadioToolButton'
@@ -88,11 +90,10 @@ class RadioToolButton(Gtk.RadioToolButton):
 
     def set_tooltip(self, tooltip):
         '''
-        Sets the tooltip of the radiotoolbutton. Displays when
+        Set the tooltip.
-        user hovers over the button with cursor.
 
         Args:
-            tooltip (string): tooltip to be added to the button
+            tooltip (string): tooltip to be set.
         '''
         if self.palette is None or self._tooltip is None:
             self.palette = Palette(tooltip)
@@ -106,7 +107,7 @@ class RadioToolButton(Gtk.RadioToolButton):
 
     def get_tooltip(self):
         '''
-        Returns the tooltip
+        Return the tooltip.
         '''
         return self._tooltip
 
@@ -115,18 +116,18 @@ class RadioToolButton(Gtk.RadioToolButton):
 
     def set_accelerator(self, accelerator):
         '''
-        Sets keyboard shortcut that activates this button
+        Set keyboard shortcut that activates this button.
 
         Args:
             accelerator (string): accelerator to be set. Should be in
-            form <modifier>Letter
+            form <modifier>Letter.
         '''
         self._accelerator = accelerator
         toolbutton.setup_accelerator(self)
 
     def get_accelerator(self):
         '''
-        Returns accelerator string
+        Return accelerator string.
         '''
         return self._accelerator
 
@@ -135,7 +136,7 @@ class RadioToolButton(Gtk.RadioToolButton):
 
     def set_icon_name(self, icon_name):
         '''
-        Sets name of icon
+        Set name of icon.
 
         Args:
             icon_name (string): name of icon
@@ -147,7 +148,7 @@ class RadioToolButton(Gtk.RadioToolButton):
 
     def get_icon_name(self):
         '''
-        Returns icon name
+        Return icon name, or None if there is no icon name.
         '''
         if self.props.icon_widget is not None:
             return self.props.icon_widget.props.icon_name
@@ -159,10 +160,10 @@ class RadioToolButton(Gtk.RadioToolButton):
 
     def set_xo_color(self, xo_color):
         '''
-        Sets XoColor of button icon
+        Set XoColor of button icon.
 
         Args:
-            xo_color (sugar3.graphics.xocolor.XoColor): xocolor to be set
+            xo_color (sugar3.graphics.xocolor.XoColor): xocolor to be set.
         '''
         if self._xo_color != xo_color:
             self._xo_color = xo_color
@@ -171,7 +172,7 @@ class RadioToolButton(Gtk.RadioToolButton):
 
     def get_xo_color(self):
         '''
-        Returns xocolor
+        Return xocolor.
         '''
         return self._xo_color
 
@@ -202,7 +203,7 @@ class RadioToolButton(Gtk.RadioToolButton):
 
     def do_draw(self, cr):
         '''
-        Implementation method for drawing the button
+        Implementation method for drawing the button.
         '''
         if self.palette and self.palette.is_up():
             allocation = self.get_allocation()
@@ -221,19 +222,19 @@ class RadioToolButton(Gtk.RadioToolButton):
 
     def get_hide_tooltip_on_click(self):
         '''
-        Returns True if the tooltip is hidden when a user
+        Return True if the tooltip is hidden when a user
-        clicks on the button, otherwise returns false
+        clicks on the button, otherwise return 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
+        Set whether or not the tooltip is hidden when a user
-        clicks on the radiotoolbutton.
+        clicks on the button.
 
         Args:
             hide_tooltip_on_click (bool): True if the tooltip is
-            hidden on click, and False otherwise
+            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
@@ -244,7 +245,8 @@ class RadioToolButton(Gtk.RadioToolButton):
 
     def do_clicked(self):
         '''
-        Implementation method for hiding the tooltip when the button is clicked
+        Implementation method for hiding the tooltip when
+        the button is clicked.
         '''
         if self._hide_tooltip_on_click and self.palette:
             self.palette.popdown(True)

src/sugar3/graphics/toolbutton.py

@@ -17,6 +17,27 @@
 # Boston, MA 02111-1307, USA.
 
 """
+The toolbutton module provides the ToolButton class, which is a
+Gtk.ToolButton with icon and tooltip styled for Sugar.
+
+Example:
+    Add a tool button to a window
+
+        from gi.repository import Gtk
+        from sugar3.graphics.toolbutton import ToolButton
+
+        def __clicked_cb(button):
+            print "tool button was clicked"
+
+        w = Gtk.Window()
+        w.connect('destroy', Gtk.main_quit)
+        b = ToolButton(icon_name='dialog-ok', tooltip='a tooltip')
+        b.connect('clicked', __clicked_cb)
+        w.add(b)
+        w.show_all()
+
+        Gtk.main()
+
 STABLE.
 """
 
@@ -58,6 +79,22 @@ def setup_accelerator(tool_button):
 
 
 class ToolButton(Gtk.ToolButton):
+    '''
+    The ToolButton class manages a Gtk.ToolButton styled for Sugar.
+
+    Keyword Args:
+        icon_name(string): name of themed icon.
+
+        accelerator (string): keyboard shortcut to be used to
+            activate this button.
+
+        tooltip (string): tooltip to be displayed when user hovers
+            over button.
+
+        hide_tooltip_on_click (bool): Whether or not the tooltip
+            is hidden when user clicks on button.
+
+    '''
 
     __gtype_name__ = 'SugarToolButton'
 
@@ -88,8 +125,12 @@ class ToolButton(Gtk.ToolButton):
         return True
 
     def set_tooltip(self, tooltip):
-        """ Set a simple palette with just a single label.
+        '''
-        """
+        Set the tooltip.
+
+        Args:
+            tooltip (string): tooltip to be set.
+        '''
         if self.palette is None or self._tooltip is None:
             self.palette = Palette(tooltip)
         elif self.palette is not None:
@@ -101,15 +142,30 @@ class ToolButton(Gtk.ToolButton):
         Gtk.ToolButton.set_label(self, tooltip)
 
     def get_tooltip(self):
+        '''
+        Return the tooltip.
+        '''
         return self._tooltip
 
     tooltip = GObject.property(type=str, setter=set_tooltip,
                                getter=get_tooltip)
 
     def get_hide_tooltip_on_click(self):
+        '''
+        Return True if the tooltip is hidden when a user
+        clicks on the button, otherwise return False.
+        '''
         return self._hide_tooltip_on_click
 
     def set_hide_tooltip_on_click(self, hide_tooltip_on_click):
+        '''
+        Set whether or not the tooltip is hidden when a user
+        clicks on the button.
+
+        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
 
@@ -118,21 +174,39 @@ class ToolButton(Gtk.ToolButton):
         setter=set_hide_tooltip_on_click)
 
     def set_accelerator(self, accelerator):
+        '''
+        Set accelerator that activates the button.
+
+        Args:
+            accelerator(string): accelerator to be set.
+        '''
         self._accelerator = accelerator
         setup_accelerator(self)
 
     def get_accelerator(self):
+        '''
+        Return accelerator that activates the button.
+        '''
         return self._accelerator
 
     accelerator = GObject.property(type=str, setter=set_accelerator,
                                    getter=get_accelerator)
 
     def set_icon_name(self, icon_name):
+        '''
+        Set name of icon.
+
+        Args:
+            icon_name (string): name of icon
+        '''
         icon = Icon(icon_name=icon_name)
         self.set_icon_widget(icon)
         icon.show()
 
     def get_icon_name(self):
+        '''
+        Return icon name, or None if there is no icon name.
+        '''
         if self.props.icon_widget is not None:
             return self.props.icon_widget.props.icon_name
         else:
@@ -164,6 +238,9 @@ class ToolButton(Gtk.ToolButton):
         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
@@ -180,5 +257,9 @@ class ToolButton(Gtk.ToolButton):
         return False
 
     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)