diff --git a/src/sugar3/graphics/palettemenu.py b/src/sugar3/graphics/palettemenu.py index 39130625..b05871ef 100644 --- a/src/sugar3/graphics/palettemenu.py +++ b/src/sugar3/graphics/palettemenu.py @@ -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,40 +168,39 @@ 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. - __gtype_name__ = 'SugarPaletteMenuItem' + 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. - __gsignals__ = { - 'activate': (GObject.SignalFlags.RUN_FIRST, None, []) - } + Args: + text_label (str): a text to display in the menu - def __init__(self, text_label=None, icon_name=None, text_maxlen=60, - xo_color=None, file_name=None, accelerator=None): + icon_name (str): the name of a sugar icon to be displayed. Takse + precedence over file_name - """ - text_label -- str - a text to display in the menu. + text_maxlen (int): the desired maximum width of the label, in + characters. By default set to 60 chars - icon_name -- str - the name of a sugar icon to be displayed. Takse precedence - over file_name. + xo_color (:class:`sugar.graphics.XoColor`): the color to be applied to + the icon - text_maxlen -- int - the desired maximum width of the label, in characters. - By default is 60. + file_name (str): the path to a svg file used as icon - xo_color -- sugar.graphics.XoColor - the color to be applied to the icon. + accelerator (str): a text used to display the keyboard shortcut + associated to the menu + ''' - 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' - """ + __gsignals__ = { + 'activate': (GObject.SignalFlags.RUN_FIRST, None, []) + } + def __init__(self, text_label=None, icon_name=None, text_maxlen=60, + xo_color=None, file_name=None, accelerator=None): 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 = '' % style.COLOR_WHITE.get_html() + \ text_label + '' 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: