Merge lp:~codeforger/simplegc/ProgressBar into lp:simplegc

[Michael Rochester]

Implimented a progress bar widget

[Sam Bull (dreamsorcerer)]

Images - 'overlay':
  This is not a valid image. It should simply draw the text onto the widget. Also, the text could be used as a string with an argument which you format with the current percentage, e.g. "Percent: %s%%".

Documentation is incomplete, there is no documentation for pulse() or percent. Try compiling the documentation and viewing it before finalising it.

can_focus defaults to False, so that line can simply be removed.

bar_percent and percent should be renamed to fraction, to better portray their 0-1 value.

throbber_speed:
  Should not move throbber once each time pulse is called. A smooth animation should be achieved if pulse() is called, say once every 250ms. You could instead use a throbber_step to decide how far it should move for each pulse, but the pulse animation should continue for 250ms after the last pulse() call. throbber_step should also be a fraction (0-1), not a pixel number.
  Note: GTK defaults to 0.1. Perhaps have the progress bar take 1 second to get from one side to the other, and use the step to define how far it will travel before it stops. This means if people have slow update loops, they can set the step to say, 0.5 to last half a second between updates.

Looking at GtkProgressBar, it makes more sense to switch between activity/percentage mode automatically when pulse() or fraction are used, thus losing the activity_mode config argument.

throbber_x can be a class attribute...

throbber_velocity seems to be the same variable as throbber_speed, there is no reason for this to exist.

Do the images need to be hidden everytime config() is called? Looks like something that should be in init.

Bar image is not drawn to full image:
  draw.rect(image, self._settings["col"], (2, 2, size[0] - 4, size[1] - 4))
Instead, you should set the size to be smaller, fill the whole image, and set it's position to the offset.
"bar": ((1, 0), (1, 0)) should be "bar": ((1, -4), (1, -4))

Same goes for throbber image.

update() is non-standard:
  This function doesn't get documented as it should be the same as all others, so you're warning will not be visible to users. I also don't understand why they would be clipped in 'pulse' (activity) mode, or why it would be unusual in 'default' (percentage) mode.

  Why is everything being blitted here? This should be done automatically by the widget, the only thing that should be happening here is moving the throbber's position when in activity mode.

self._throbber_velocity *= -1
Shouldn't be doing multiplication, if you want to invert it, just negate it:
self._throbber_velocity = -self._throbber_velocity

review: Needs Fixing

[Sam Bull (dreamsorcerer)]

Code's looking good, just sort out a few formatting problems:

46: *Displays
104: No reason for line wrapping.
117: Huh? What has that to do with rounding?
138: Pointless docstring, which is not displayed anyway.
162/197: Docstring should be lined up, not indented further.
191: Remove leading/trailing space.

Switching modes is a significant activity and should not be done in a property method. Leave the fraction property as read-only.

Does the text property make sense? Under what case would you need to retrieve the text? I can't think of a reason, and then setting the text makes more sense as a config argument.

review: Needs Fixing

[Michael Rochester (codeforger)]

On Wed, Aug 7, 2013 at 10:49 AM, Sam Bull <email address hidden> wrote:

> 46: *Displays
> 104: No reason for line wrapping.
> 117: Huh? What has that to do with rounding?
> 138: Pointless docstring, which is not displayed anyway.
> 162/197: Docstring should be lined up, not indented further.
> 191: Remove leading/trailing space.
>

These line numbers bear no relevance to the code, most of them point to
empty lines, and furthur more the entire file is only 165 lines long :/

[lp:~codeforger/simplegc/ProgressBar]

361. By Michael Rochester on 2013-08-07

made requested tweaks

362. By Michael Rochester on 2013-08-07

made requested tweaks

[Sam Bull (dreamsorcerer)]

Set the fraction of the bar, then run pulse(). The progress bar is still displayed in addition to the throbber.

review: Needs Fixing

[lp:~codeforger/simplegc/ProgressBar]

363. By Michael Rochester on 2014-04-20

fixed bug where text did not show.

364. By Michael Rochester on 2014-04-20

fixed issue where if bar was displayed in fraction mode and then switched to pulse mode, the bar remained visible.

[Michael Rochester (codeforger)]

> Set the fraction of the bar, then run pulse(). The progress bar is still
> displayed in addition to the throbber.

This is fixed in revision 364

[Sam Bull (dreamsorcerer)]

Merged to 0.2 branch.

review: Approve

Unmerged revisions

364. By Michael Rochester on 2014-04-20

fixed issue where if bar was displayed in fraction mode and then switched to pulse mode, the bar remained visible.

363. By Michael Rochester on 2014-04-20

fixed bug where text did not show.

362. By Michael Rochester on 2013-08-07

made requested tweaks

361. By Michael Rochester on 2013-08-07

made requested tweaks

360. By Michael Rochester on 2013-08-01

finalized tweaks that were requested

359. By Michael Rochester on 2013-06-25

made all requested changed

358. By Michael Rochester on 2013-06-03

Improved efficiency of pulse().

357. By Michael Rochester on 2013-06-03

Changed behaviour to be more like the GTK toolkit. Also some usability tweaks.

356. By Michael Rochester on 2013-06-01

implimented a progress bar widget

=== modified file 'docs/sgc.widgets.rst'
--- docs/sgc.widgets.rst	2013-03-22 17:46:43 +0000
+++ docs/sgc.widgets.rst	2014-04-20 13:44:42 +0000
@@ -116,6 +116,19 @@
 
         .. automethod:: config
 
+:mod:`progress` Module
+--------------------------
+
+.. automodule:: sgc.widgets.progress
+
+    .. autoclass:: sgc.widgets.progress.ProgressBar
+        :members:
+        :undoc-members:
+        :show-inheritance:
+        :exclude-members: update, groups, selected
+
+        .. automethod:: config
+
 :mod:`radio_button` Module
 --------------------------
 

=== modified file 'sgc/__init__.py'
--- sgc/__init__.py	2013-03-23 16:16:35 +0000
+++ sgc/__init__.py	2014-04-20 13:44:42 +0000
@@ -31,6 +31,7 @@
 from widgets.fps_counter import FPSCounter
 from widgets.input_box import InputBox
 from widgets.label import Label
+from widgets.progress import ProgressBar
 from widgets.radio_button import Radio
 from widgets.scroll_box import ScrollBox
 from widgets.settings import Keys

=== added file 'sgc/widgets/progress.py'
--- sgc/widgets/progress.py	1970-01-01 00:00:00 +0000
+++ sgc/widgets/progress.py	2014-04-20 13:44:42 +0000
@@ -0,0 +1,166 @@
+# Copyright 2013 the SGC project developers.
+# See the LICENSE file at the top-level directory of this distribution
+# and at http://program.sambull.org/sgc/license.html.
+
+"""
+Progress Bar widget. Displays a bar to the user with either a percent filled
+or activity throbber.
+
+"""
+
+import pygame
+from pygame.locals import *
+from pygame import draw
+
+from _locals import *
+from base_widget import Simple
+
+
+class ProgressBar(Simple):
+    """
+    A Progress Bar.
+
+    Images:
+      'image': The background of the bar.
+      'bar': The image to be used for the percent bar
+          (bar will be cut to size, not stretched)
+      'throbber': The image used for the 'activity' throbber.
+      'overlay': This image will always be displayed on top of the widget
+          regardless of mode, it is by default blank, however passing the
+          keyword 'text' to the config function will draw this text onto this
+          surface.
+    """
+
+    _default_size = (100, 20)
+    _extra_images = {"bar": ((1, -4), (1, -4)),
+                     "throbber": ((.2, -6), (1, -6)),
+                     "overlay": ((1, 0), (1, 0))}
+    _settings_default = {"col": (118, 45, 215), "font": Font["widget"],
+                         "text": "", "text_col": (10, 10, 10), "total_time": 1,
+                         "pulse_duration": .1}
+    _surf_flags = SRCALPHA
+
+    _bar_fraction = 1.
+    _throbber_move_timer = 0
+    _activity_mode = False
+
+    def _config(self, **kwargs):
+        """
+          col: ``tuple`` (r,g,b) The color to be used for the bar, to avoid
+              saturation of the throbber use values below 200
+          pulse_duration: ``float`` time in seconds each pulse should last,
+              useful if your update loop is slower than the default of .25
+          total_time: ``float`` time in seconds the throbber should take to
+              travel the full distance of the bar.
+          font: font to be used for the text
+          text: ``str`` the text to be shown in the center of the widget
+          text_col: the color of the text
+        """
+        for key in ("col", "font", "total_time",
+                    "pulse_duration", "text_col"):
+            if key in kwargs:
+                self._settings[key] = kwargs[key]
+
+        if "text" in kwargs:
+            self._settings["text"] = kwargs["text"]
+            overlay = self._images["overlay"]
+            overlay.image.fill((0, 0, 0, 0))
+            label = self._settings["font"].render(self._settings["text"], True,
+                                                  self._settings["text_col"])
+            overlay.image.blit(label, (overlay.rect.w / 2 -
+                                       label.get_rect().w / 2,
+                                       overlay.rect.h / 2 -
+                                       label.get_rect().h / 2))
+
+        if "total_time" in kwargs or "pulse_duration" in kwargs:
+            total_time_ms = self._settings["total_time"] * 1000.
+            self._throbber_velocity = self.rect.w / total_time_ms
+
+        if "init" in kwargs:
+            self._images["bar"]._show = False
+            self._images["throbber"]._show = False
+            self._images["throbber"].pos = [0, 3]
+
+            total_time_ms = self._settings["total_time"] * 1000.
+            self._throbber_velocity = self.rect.w / total_time_ms
+
+            self._throbber_x = 0
+
+    def _draw_base(self):
+        draw.rect(self._images["image"], (100, 100, 100),
+                  (0, 0, self.rect.w, self.rect.h))
+        draw.rect(self._images["image"], (240, 240, 240),
+                  (1, 1, self.rect.w - 2, self.rect.h - 2))
+
+    def _draw_bar(self, image, size):
+        draw.rect(image, self._settings["col"],
+                  (0, 0, size[0], size[1]))
+
+    def _draw_throbber(self, image, size):
+        brightened_color = [x + 20 for x in self._settings["col"]]
+        draw.rect(image, brightened_color, (0, 0, size[0], size[1]))
+
+    def _draw_overlay(self, image, size):
+        pass
+
+    def update(self, time):
+        if self._activity_mode:
+            self._images["bar"]._show = False
+            if self._throbber_move_timer > 0:
+                self._throbber_move_timer -= time
+                # Move throbber.
+                self._throbber_x += self._throbber_velocity * time
+                self._images["throbber"].rect.x = self._throbber_x
+                # If outside box, change direction and move back in.
+                left_edge = self._images["throbber"].rect.x - 3
+                right_edge = left_edge + self._images["throbber"].rect.w + 6
+                if left_edge < 0 or right_edge > self.rect.w:
+                    self._throbber_velocity = - self._throbber_velocity
+                    self._throbber_x += self._throbber_velocity * time
+                    self._images["throbber"].rect.x = self._throbber_x
+        else:
+            bar_rect = (0, 0, self.rect.w * self._bar_fraction, self.rect.h)
+            draw.rect(self.image, (100, 100, 100),
+                      (0, 0, self.rect.w, self.rect.h))
+            draw.rect(self.image, (240, 240, 240),
+                      (1, 1, self.rect.w - 2, self.rect.h - 2))
+            self.image.set_clip(bar_rect)
+            self.image.blit(self._images["bar"].image, (2, 2))
+            self.image.set_clip(None)
+
+    def pulse(self):
+        """
+        Moves the activity mode throbber
+
+        The throbber will move for the number of seconds described by the
+            pulse_duration config argument.
+
+        Note: This will cause the Widget to change to activity mode if it
+            was in percent mode before.
+        """
+        if not self._activity_mode:
+            self._activity_mode = True
+            bar_rect = (0, 0, self.rect.w * self._bar_fraction, self.rect.h)
+            draw.rect(self.image, (100, 100, 100),
+                      (0, 0, self.rect.w, self.rect.h))
+            draw.rect(self.image, (240, 240, 240),
+                      (1, 1, self.rect.w - 2, self.rect.h - 2))
+            self._images["throbber"]._show = True
+        self._throbber_move_timer = self._settings["pulse_duration"] * 1000
+
+    @property
+    def fraction(self):
+        """Returns the current fraction the bar is at as a float."""
+        return self._bar_fraction
+
+    def set_fraction(self, fraction):
+        """
+        Sets the fraction the bar should be as a float.
+
+        Note: This will cause the Widget to change to percent mode if it
+            was in activity mode before.
+        """
+        if self._activity_mode:
+            self._activity_mode = False
+            self._images["throbber"]._show = False
+        self._bar_fraction = min(max(fraction, 0.), 1.)