Add docs for sugar3.graphics.palettemenu

This commit is contained in:
Sam Parkinson 2015-09-15 20:48:48 +10:00
parent 7c804354a0
commit 61882e3df2

View File

@ -13,6 +13,75 @@
# You should have received a copy of the GNU General Public License # You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software # along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
'''
The palettemenu module is the main port of call for making palettes. It
covers creating menu items, seperators and placing them in a box.
Example:
Create a palette menu with 2 items with a seperator in the middle.
.. code-block:: python
from gi.repository import Gtk
from gettext import gettext as _
from sugar3.graphics.palette import Palette
from sugar3.graphics.palettemenu import PaletteMenuBox
from sugar3.graphics.palettemenu import PaletteMenuItem
from sugar3.graphics.palettemenu import PaletteMenuItemSeparator
class ItemPalette(Palette):
def __init__(self):
Palette.__init__(
self, primary_text='List Item')
box = PaletteMenuBox()
self.set_content(box)
box.show()
menu_item = PaletteMenuItem(
_('Edit'), icon_name='toolbar-edit')
menu_item.connect('activate', self.__edit_cb)
box.append_item(menu_item)
menu_item.show()
sep = PaletteMenuItemSeparator()
box.append_item(sep)
sep.show()
menu_item = PaletteMenuItem(
_('Delete'), icon_name='edit-delete')
box.append_item(menu_item)
menu_item.show()
def __edit_cb(self, menu_item):
print 'Edit...'
# Usually the Palette instance is returned in a create_palette function
p = ItemPalette()
p.popup()
Gtk.main()
Add a palettebox to a toolbutton:
.. code-block:: python
image = ToolButton('insert-picture')
image.set_tooltip(_('Insert Image'))
self._image_id = image.connect('clicked', self.__image_cb)
toolbar_box.toolbar.insert(image, -1)
palette = image.get_palette()
box = PaletteMenuBox()
palette.set_content(box)
box.show()
menu_item = PaletteMenuItem(_('Floating'))
menu_item.connect('activate', self.__image_cb, True)
box.append_item(menu_item)
menu_item.show()
'''
from gi.repository import GObject from gi.repository import GObject
from gi.repository import Gtk from gi.repository import Gtk
@ -22,11 +91,39 @@ from sugar3.graphics import style
class PaletteMenuBox(Gtk.VBox): class PaletteMenuBox(Gtk.VBox):
'''
The PaletteMenuBox is a box that is useful for making palettes. It
supports adding :class:`sugar3.graphics.palettemenu.PaletteMenuItem`,
:class:`sugar3.graphics.palettemenu.PaletteMenuItemSeparator` and
it automatically adds padding to other widgets.
'''
def __init__(self): def __init__(self):
Gtk.VBox.__init__(self) Gtk.VBox.__init__(self)
def append_item(self, item_or_widget, horizontal_padding=None, def append_item(self, item_or_widget, horizontal_padding=None,
vertical_padding=None): vertical_padding=None):
'''
Add a menu item, seperator or other widget to the end of the palette
(simmilar to `Gtk.Box.pack_start`).
If an item is appended
(a :class:`sugar3.graphics.palettemenu.PaletteMenuItem` or a
:class:`sugar3.graphics.palettemenu.PaletteMenuItemSeparator`) no
padding will be added, as that is handled by the item. If a widget is
appended (:class:`Gtk.Widget` subclass) padding will be added.
Args:
item_or_widget (:class:`Gtk.Widget` or menu item or seperator):
item or widget to add the the palette
horizontal_padding (int): by default,
:class:`sugar3.graphics.style.DEFAULT_SPCAING` is applied
vertical_padding (int): by default,
:class:`sugar3.graphics.style.DEFAULT_SPCAING` is applied
Returns:
None
'''
item = None item = None
if (isinstance(item_or_widget, PaletteMenuItem) or if (isinstance(item_or_widget, PaletteMenuItem) or
isinstance(item_or_widget, PaletteMenuItemSeparator)): isinstance(item_or_widget, PaletteMenuItemSeparator)):
@ -56,7 +153,9 @@ class PaletteMenuBox(Gtk.VBox):
class PaletteMenuItemSeparator(Gtk.EventBox): class PaletteMenuItemSeparator(Gtk.EventBox):
"""Contains a HSeparator and has the proper height for the menu.""" '''
Horizontal seperator to put in a palette
'''
__gtype_name__ = 'SugarPaletteMenuItemSeparator' __gtype_name__ = 'SugarPaletteMenuItemSeparator'
@ -69,6 +168,30 @@ class PaletteMenuItemSeparator(Gtk.EventBox):
class PaletteMenuItem(Gtk.EventBox): class PaletteMenuItem(Gtk.EventBox):
'''
A palette menu item is a line of text, and optionally an icon, that the
user can activate.
The `activate` signal is usually emitted when the item is clicked. It has
no arguments. When a menu item is activated, the palette is also closed.
Args:
text_label (str): a text to display in the menu
icon_name (str): the name of a sugar icon to be displayed. Takse
precedence over file_name
text_maxlen (int): the desired maximum width of the label, in
characters. By default set to 60 chars
xo_color (:class:`sugar.graphics.XoColor`): the color to be applied to
the icon
file_name (str): the path to a svg file used as icon
accelerator (str): a text used to display the keyboard shortcut
associated to the menu
'''
__gtype_name__ = 'SugarPaletteMenuItem' __gtype_name__ = 'SugarPaletteMenuItem'
@ -78,31 +201,6 @@ class PaletteMenuItem(Gtk.EventBox):
def __init__(self, text_label=None, icon_name=None, text_maxlen=60, def __init__(self, text_label=None, icon_name=None, text_maxlen=60,
xo_color=None, file_name=None, accelerator=None): xo_color=None, file_name=None, accelerator=None):
"""
text_label -- str
a text to display in the menu.
icon_name -- str
the name of a sugar icon to be displayed. Takse precedence
over file_name.
text_maxlen -- int
the desired maximum width of the label, in characters.
By default is 60.
xo_color -- sugar.graphics.XoColor
the color to be applied to the icon.
file_name -- str
the path to a svg file used as icon.
accelerator -- str
a text used to display the keyboard shortcut associated
to the menu.
"""
Gtk.EventBox.__init__(self) Gtk.EventBox.__init__(self)
self.set_above_child(True) self.set_above_child(True)
@ -172,19 +270,47 @@ class PaletteMenuItem(Gtk.EventBox):
style.COLOR_BLACK.get_gdk_color()) style.COLOR_BLACK.get_gdk_color())
def set_label(self, text_label): def set_label(self, text_label):
'''
Sets the text to display in the menu.
Args:
text_label (str): text label
'''
text = '<span foreground="%s">' % style.COLOR_WHITE.get_html() + \ text = '<span foreground="%s">' % style.COLOR_WHITE.get_html() + \
text_label + '</span>' text_label + '</span>'
self.label.set_markup(text) self.label.set_markup(text)
def set_image(self, icon): def set_image(self, icon):
'''
Sets the icon widget. Usually this will be a
:class:`sugar3.graphics.icon.Icon`.
Args:
icon (:class:`Gtk.Widget`): icon widget
'''
self._hbox.pack_start(icon, expand=False, fill=False, self._hbox.pack_start(icon, expand=False, fill=False,
padding=style.DEFAULT_PADDING) padding=style.DEFAULT_PADDING)
self._hbox.reorder_child(icon, 0) self._hbox.reorder_child(icon, 0)
def set_accelerator(self, text): def set_accelerator(self, text):
'''
Sets the text used to display the keyboard shortcut associated with
the menu.
Args:
text (str): accelerator text
'''
self._accelerator_label.set_text(text) self._accelerator_label.set_text(text)
def set_sensitive(self, sensitive): def set_sensitive(self, sensitive):
'''
Sets whether the widget should be activateable by the user and changes
the widget's appearence to the appropriate state.
Args:
sensitive (bool): if `True`, the widget will be activateable by
the user. Otherwise, it will not be activateable
'''
is_sensitive = bool(not self.get_state_flags() & is_sensitive = bool(not self.get_state_flags() &
Gtk.StateFlags.INSENSITIVE) Gtk.StateFlags.INSENSITIVE)
if is_sensitive == sensitive: if is_sensitive == sensitive: