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

[Michael Rochester]

Implimented a progress bar widget

[lp:~codeforger/simplegc/ProgressBar]

357. By Michael Rochester on 2013-06-03

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

358. By Michael Rochester on 2013-06-03

Improved efficiency of pulse().

[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

[lp:~codeforger/simplegc/ProgressBar]

359. By Michael Rochester on 2013-06-25

made all requested changed

360. By Michael Rochester on 2013-08-01

finalized tweaks that were requested

361. By Michael Rochester on 2013-08-07

made requested tweaks

362. By Michael Rochester on 2013-08-07

made requested tweaks

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.

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	2013-08-01 09:20:40 +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	2013-08-01 09:20:40 +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	2013-08-01 09:20:40 +0000
@@ -0,0 +1,165 @@
+# 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. Displayed 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", "text_col"):
+            if key in kwargs:
+                self._settings[key] = kwargs[key]
+
+        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
+
+            # Stored locally to prevent rounding failures.
+            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):
+        image.fill((0, 0, 0, 0))
+
+    def update(self, time):
+        """
+          Update the progress bar each frame.
+        """
+        if self._activity_mode:
+            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)
+            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
+            self._images["throbber"]._show = True
+        self._throbber_move_timer = self._settings["pulse_duration"] * 1000
+
+    @property
+    def text(self):
+        return self._settings["text"]
+
+    @text.setter
+    def text(self, text):
+        self._settings["text"] = 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))
+
+    @property
+    def fraction(self):
+        """ Returns the current fraction the bar is at as a float. """
+        return self._bar_fraction
+
+    @fraction.setter
+    def 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.)