# $Id: ProgressBar.py,v 1.22 2006/06/05 09:20:23 marcusva Exp $ # # Copyright (c) 2004-2006, Marcus von Appen # All rights reserved. # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are met: # # * Redistributions of source code must retain the above copyright notice, # this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above copyright notice, # this list of conditions and the following disclaimer in the documentation # and/or other materials provided with the distribution. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" # AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE # ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE # LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR # CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF # SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS # INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE # POSSIBILITY OF SUCH DAMAGE. """A self-filling widget for progress states.""" from BaseWidget import BaseWidget from Constants import * import base class ProgressBar (BaseWidget): """ProgressBar () -> ProgressBar A widget class, which can display a progress state. The Progressbar widget is a graphical state indicator, which can interactively show the effort of an operation by a filling bar. Its value ranges from 0 to 100 (percent) and can increase or decrease. To allow high interactivity, each value changing method of the ProgressBar will raise a SIG_VALCHANGED event. The increment of the ProgressBar can be set with the 'step' attribute or set_step() method. To allow a high resolution for long running tasks and operations, which should be visualized using the ProgressBar, the increment accepts floating point values. progressbar.step = 0.1 progressbar.set_step (10) The 'value' attribte and set_value() method allow setting the ProgressBar value directly without calling the respective increment or decerement methods. progressbar.value = 50.0 progressbar.set_value (3) The ProgressBar value can be in- or decreased using the increase() and decrease() methods. Those will in- or decrease the current value by the value of the 'step' attribute until either 100 or 0 is reached. progressbar.increase() progressbar.decrease() Dependant on the width of the ProgressBar the filled range per in- or decreasement can differ. The complete width is always used as the maximum value of 100, thus longer progressBar widgets allow better visible changes, if a finer grained increment is given. The ProgressBar uses a default size for itself by setting the 'size' attribute to a width of 104 pixels and a height of 24 pixels. Default action (invoked by activate()): None Mnemonic action (invoked by activate_mnemonic()): None Signals: SIG_VALCHANGED - Invoked, when the value of the ProgressBar changed. Attributes: step - Step range. value - Current value. text - The text to display on the ProgressBar. """ def __init__ (self): BaseWidget.__init__ (self) # The current value, max is 100 (%), min is 0 (%) and step range. self._value = 0 self._step = 0.1 self._text = None self._signals[SIG_VALCHANGED] = [] self.minsize = 104, 24 # Use a fixed size. def set_focus (self, focus=True): """P.set_focus (focus=True) -> None Overrides the set_focus() behaviour for the ProgressBar. The ProgressBar class is not focusable by default. It is an information displaying class only, so it does not need to get the input focus and thus it will return false without doing anything. """ return False def set_text (self, text): """P.set_text (...) -> None Sets the text to display on the ProgressBar. Sets the text text to display on the ProgressBar. The text will be centered on it. Raises a TypeError, if the passed argument is not a string or unicode. """ if type (text) not in (str, unicode): raise TypeError ("text must be a string or unicode") self._text = text self.dirty = True def set_step (self, step=0.1): """P.set_step (...) -> None Sets the step range for in- or decreasing the ProgressBar value. The step range is the value used by the increase and decrease methods of the ProgressBar. Raises a TypeError, if the passed argument is not a float or integer. """ if type (step) not in (float, int): raise TypeError ("step must be a float or integer") self._step = step def set_value (self, value): """P.set_value (...) -> None Sets the current value of the ProgressBar. Sets the current value of the ProgressBar and raises a SIG_VALCHANGED event, if the new value differs from the old one. Raises a TypeError, if the passed argument is not a float or integer. Raises a ValueError, if the passed argument, is not within the allowed range of 0.0 to 100.0. """ if type (value) not in (float, int): raise TypeError ("value must be a float or integer") if (0.0 > value) or (100.0 < value): raise ValueError ("value must be in the range from 0.0 to 100.0") if value != self._value: self._value = value self.run_signal_handlers (SIG_VALCHANGED) self.dirty = True def increase (self): """P.increase () -> None Increases the current value by one step. """ val = self.value if val < 100.0: val += self.step if val > 100.0: val = 100.0 self.value = val def decrease (self): """P.decrease () -> None Decreases the current value by one step. """ val = self.value if val > 0.0: val -= self.step if val < 0.0: val = 0.0 self.value = val def draw_bg (self): """P.draw_bg () -> Surface Draws the ProgressBar background surface and returns it. Creates the visible surface of the ProgressBar and returns it to the caller. """ return base.GlobalStyle.engine.draw_progressbar (self) def draw (self): """P.draw () -> None Draws the ProgressBar surface and places its text on it. """ BaseWidget.draw (self) if self.text: sf_text = base.GlobalStyle.engine.draw_string (self.text, self.state, self.__class__, self.style) rect = sf_text.get_rect () rect.center = self.image.get_rect ().center self.image.blit (sf_text, rect) value = property (lambda self: self._value, lambda self, var: self.set_value (var), doc = "The current value.") step = property (lambda self: self._step, lambda self, var: self.set_step (var), doc = "The step range of the ProgressBar.") text = property (lambda self: self._text, lambda self, var: self.set_text (var), doc = "The text to display on the ProgressBar.")