Add docs for sugar3.graphics.palettemenu
This commit is contained in:
Sam Parkinson
parent
7c804354a0
commit
61882e3df2
@ -13,6 +13,75 @@
|
||||
# You should have received a copy of the GNU General Public License
|
||||
# along with this program; if not, write to the Free Software
|
||||
# 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 Gtk
|
||||
@ -22,11 +91,39 @@ from sugar3.graphics import style
|
||||
|
||||
|
||||
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):
|
||||
Gtk.VBox.__init__(self)
|
||||
|
||||
def append_item(self, item_or_widget, horizontal_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
|
||||
if (isinstance(item_or_widget, PaletteMenuItem) or
|
||||
isinstance(item_or_widget, PaletteMenuItemSeparator)):
|
||||
@ -56,7 +153,9 @@ class PaletteMenuBox(Gtk.VBox):
|
||||
|
||||
|
||||
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'
|
||||
|
||||
@ -69,6 +168,30 @@ class PaletteMenuItemSeparator(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'
|
||||
|
||||
@ -78,31 +201,6 @@ class PaletteMenuItem(Gtk.EventBox):
|
||||
|
||||
def __init__(self, text_label=None, icon_name=None, text_maxlen=60,
|
||||
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)
|
||||
self.set_above_child(True)
|
||||
|
||||
@ -172,19 +270,47 @@ class PaletteMenuItem(Gtk.EventBox):
|
||||
style.COLOR_BLACK.get_gdk_color())
|
||||
|
||||
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_label + '</span>'
|
||||
self.label.set_markup(text)
|
||||
|
||||
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,
|
||||
padding=style.DEFAULT_PADDING)
|
||||
self._hbox.reorder_child(icon, 0)
|
||||
|
||||
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)
|
||||
|
||||
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() &
|
||||
Gtk.StateFlags.INSENSITIVE)
|
||||
if is_sensitive == sensitive:
|
||||
|
||||
Loading…
Reference in New Issue
Block a user