From 4f7ab56c3e2b3514aa36869fb64066b7b5609ab7 Mon Sep 17 00:00:00 2001
From: Hrishi <hrishipatel99@gmail.com>
Date: Tue, 3 Jan 2017 12:40:54 +0530
Subject: [PATCH] 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            | 58 +++++++++++++++++++++++++++++
 src/sugar3/graphics/progressicon.py | 30 ++++++++++++---
 2 files changed, 82 insertions(+), 6 deletions(-)
 create mode 100644 examples/progressicon.py

diff --git a/examples/progressicon.py b/examples/progressicon.py
new file mode 100644
index 00000000..bb6ae124
--- /dev/null
+++ b/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)
diff --git a/src/sugar3/graphics/progressicon.py b/src/sugar3/graphics/progressicon.py
index 0153ae20..32748710 100644
--- a/src/sugar3/graphics/progressicon.py
+++ b/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()