sugarlabs/sugar-toolkit-gtk3
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Write documentation for sugar3.graphics.ToolButton

Browse Source 
- 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 <hrishipatel99@gmail.com> (31176ea) and

- radicalonion <ndefilippis98@gmail.com> (db89aca).
This commit is contained in:
James Cameron 2016-12-12 15:06:12 +11:00
parent 5efba3eb7d
commit c92d0009df
3 changed files with 145 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
examples/toolbutton.py Normal file
View File

@ -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)

52
src/sugar3/graphics/radiotoolbutton.py
View File

@ -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 <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
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)

85
src/sugar3/graphics/toolbutton.py
View File

@ -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)