From c92d0009df2311bb7d7a025c3886e1e3f7639ca1 Mon Sep 17 00:00:00 2001 From: James Cameron Date: Mon, 12 Dec 2016 15:06:12 +1100 Subject: [PATCH] Write documentation for sugar3.graphics.ToolButton - add two examples, - document critical properties as keyword arguments in the class init, - ensure documentation is consistent between RadioToolButton and ToolButton, (as some of the text is similar), - part of feature Sugar3 Docs, https://wiki.sugarlabs.org/go/Features/Sugar3_Docs - follow How To Guide https://wiki.sugarlabs.org/go/Features/Sugar3_Docs/How_To_Write Derived from work by - Hrishi (31176ea) and - radicalonion (db89aca). --- examples/toolbutton.py | 35 +++++++++++ src/sugar3/graphics/radiotoolbutton.py | 52 ++++++++-------- src/sugar3/graphics/toolbutton.py | 85 +++++++++++++++++++++++++- 3 files changed, 145 insertions(+), 27 deletions(-) create mode 100644 examples/toolbutton.py diff --git a/examples/toolbutton.py b/examples/toolbutton.py new file mode 100644 index 00000000..fe670e42 --- /dev/null +++ b/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('') +toolbar_box.toolbar.insert(tool_button, -1) + +test.show_all() + +if __name__ == '__main__': + common.main(test) diff --git a/src/sugar3/graphics/radiotoolbutton.py b/src/sugar3/graphics/radiotoolbutton.py index 3d7e74d9..0f578510 100644 --- a/src/sugar3/graphics/radiotoolbutton.py +++ b/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 - user hovers over the button with cursor. + Set the tooltip. 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 Letter + form 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 - clicks on the button, otherwise returns false + 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): ''' - Sets whether or not the tooltip is hidden when a user - clicks on the radiotoolbutton. + 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 + 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) diff --git a/src/sugar3/graphics/toolbutton.py b/src/sugar3/graphics/toolbutton.py index 63a6da3b..1d339fbe 100644 --- a/src/sugar3/graphics/toolbutton.py +++ b/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)