Write documentation for sugar3.graphics.ProgressIcon

- add one example,

- part of feature Sugar3 Docs,
  https://wiki.sugarlabs.org/go/Features/Sugar3_Docs

examples/progressicon.py

@@ -0,0 +1,58 @@
+from gi.repository import Gtk
+from gi.repository import GObject
+
+from sugar3.graphics.toolbarbox import ToolbarBox
+from sugar3.graphics.progressicon import ProgressIcon
+from sugar3.graphics import style
+
+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)
+
+icon = ProgressIcon(
+      pixel_size=style.LARGE_ICON_SIZE,
+      icon_name='computer-xo',
+      stroke_color=style.COLOR_BUTTON_GREY.get_svg(),
+      fill_color=style.COLOR_WHITE.get_svg())
+test.pack_start(icon, True, True, 0)
+icon.show()
+
+icon2 = ProgressIcon(
+    pixel_size=style.LARGE_ICON_SIZE,
+    icon_name='computer-xo',
+    stroke_color=style.COLOR_BUTTON_GREY.get_svg(),
+    fill_color=style.COLOR_WHITE.get_svg(),
+    direction='horizontal')
+test.pack_start(icon2, True, True, 0)
+icon2.show()
+
+test.show_all()
+
+progress = 0
+
+
+def timeout_cb():
+    global progress
+    progress += 0.05
+    icon.update(progress)
+    icon2.update(progress)
+    if progress >= 1:
+        return False
+    return True
+
+
+GObject.timeout_add(50, timeout_cb)
+
+
+if __name__ == '__main__':
+    common.main(test)

src/sugar3/graphics/progressicon.py

@@ -14,6 +14,9 @@
 # License along with this library; if not, write to the
 # Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 # Boston, MA 02111-1307, USA.
+'''
+A progress icon is a progress indicator in the form of an icon.
+'''
 
 from gi.repository import Gtk
 from sugar3.graphics.icon import get_surface
@@ -21,18 +24,23 @@ from sugar3.graphics import style
 
 
 class ProgressIcon(Gtk.DrawingArea):
-    """Display the progress filling the icon.
-
+    '''
+    Display the progress filling the icon.
     This class is compatible with the sugar3.graphics.icon.Icon class.
-
     Call update(progress) with the new progress to update the icon.
-
     The direction defaults to 'vertical', in which case the icon is
     filled from bottom to top.  If direction is set to 'horizontal',
     it will be filled from right to left or from left to right,
     depending on the system's language RTL setting.
-
-    """
+    Args:
+      pixel_size (integer): sets the icon size
+         [e.g. pixel_size=style.LARGE_ICON_SIZE]
+      icon_name (string): Name of icon
+         [e.g. icon_name='test_icon']
+      stroke_color (string): Stroke color means border color.
+      fill_color (string): The main (inside) color of progressicon
+         [e.g. fill_color=style.COLOR_BLUE.get_svg()
+    '''
     def __init__(self, icon_name, pixel_size, stroke_color, fill_color,
                  direction='vertical'):
         Gtk.DrawingArea.__init__(self)
@@ -87,13 +95,23 @@ class ProgressIcon(Gtk.DrawingArea):
         cr.paint()
 
     def do_get_preferred_width(self):
+        '''
+        Calculate the minimum and natural width of the progressicon.
+        '''
         width = self._stroke.get_width()
         return (width, width)
 
     def do_get_preferred_height(self):
+        '''
+        Calculate the minimum and natural height of the progressicon.
+        '''
         height = self._stroke.get_height()
         return (height, height)
 
     def update(self, progress):
+        '''
+        Updates progressicon with progress's value.
+        Example: update(0.9)
+        '''
         self._progress = progress
         self.queue_draw()