Merge branch 'doc-palettemenu' of https://github.com/samdroid-apps/sugar-toolkit-gtk3

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,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: