# --------------------------------------------------------------------------------- # # PYGAUGE wxPython IMPLEMENTATION # # Mark Reed, @ 28 Jul 2010 # Latest Revision: 05 Sep 2012, 21.00 GMT # # TODO List # # 1. Indeterminate mode (see wx.Gauge) # 2. Vertical bar # 3. Bitmap support (bar, background) # 4. UpdateFunction - Pass a function to PyGauge which will be called every X # milliseconds and the value will be updated to the returned value. # 5. Currently the full gradient is drawn from 0 to value. Perhaps the gradient # should be drawn from 0 to range and clipped at 0 to value. # 6. Add a label? # # For All Kind Of Problems, Requests Of Enhancements And Bug Reports, Please # Write To The: # # wxPython Mailing List!!! # # End Of Comments # --------------------------------------------------------------------------------- # """ :class:`PyGauge` is a generic :class:`Gauge` implementation. Description =========== :class:`PyGauge` supports the determinate mode functions as :class:`Gauge` and adds an meth:~PyGauge.Update` function which takes a value and a time parameter. The `value` is added to the current value over a period of `time` milliseconds. Usage ===== Usage example:: import wx import wx.lib.agw.pygauge as PG class MyFrame(wx.Frame): def __init__(self, parent): wx.Frame.__init__(self, parent, -1, "PyGauge Demo") panel = wx.Panel(self) gauge1 = PG.PyGauge(panel, -1, size=(100, 25), style=wx.GA_HORIZONTAL) gauge1.SetValue(80) gauge1.SetBackgroundColour(wx.WHITE) gauge1.SetBorderColor(wx.BLACK) gauge2 = PG.PyGauge(panel, -1, size=(100, 25), style=wx.GA_HORIZONTAL) gauge2.SetValue([20, 80]) gauge2.SetBarColor([wx.Colour(162, 255, 178), wx.Colour(159, 176, 255)]) gauge2.SetBackgroundColour(wx.WHITE) gauge2.SetBorderColor(wx.BLACK) gauge2.SetBorderPadding(2) gauge2.SetDrawValue(draw=True, drawPercent=True, font=wx.SMALL_FONT, colour=wx.BLUE) gauge2.Update([30, 0], 2000) gauge3 = PG.PyGauge(panel, -1, size=(100, 25), style=wx.GA_HORIZONTAL) gauge3.SetValue(50) gauge3.SetBarColor(wx.GREEN) gauge3.SetBackgroundColour(wx.WHITE) gauge3.SetBorderColor(wx.BLACK) sizer = wx.BoxSizer(wx.VERTICAL) sizer.Add(gauge1, 0, wx.ALIGN_CENTER_VERTICAL|wx.ALL, 20) sizer.Add(gauge2, 0, wx.ALIGN_CENTER_VERTICAL|wx.ALL, 20) sizer.Add(gauge3, 0, wx.ALIGN_CENTER_VERTICAL|wx.ALL, 20) panel.SetSizer(sizer) sizer.Layout() # our normal wxApp-derived class, as usual app = wx.App(0) frame = MyFrame(None) app.SetTopWindow(frame) frame.Show() app.MainLoop() Supported Platforms =================== :class:`PyGauge` has been tested on the following platforms: * Windows (Windows XP, Windows 7); License And Version =================== :class:`PyGauge` is distributed under the wxPython license. :class:`PyGauge` has been kindly contributed to the AGW library by Mark Reed. Latest Revision: Andrea Gavana @ 05 Sep 2012, 21.00 GMT Version 0.1 """ import wx import copy class PyGauge(wx.PyWindow): """ This class provides a visual alternative for :class:`Gauge`. It currently only support determinate mode (see :meth:`PyGauge.SetValue() ` and :meth:`PyGauge.SetRange() `). """ def __init__(self, parent, id=wx.ID_ANY, range=100, pos=wx.DefaultPosition, size=(-1,30), style=0): """ Default class constructor. :param `parent`: parent window. Must not be ``None``; :param `id`: window identifier. A value of -1 indicates a default value; :param `pos`: the control position. A value of (-1, -1) indicates a default position, chosen by either the windowing system or wxPython, depending on platform; :param `size`: the control size. A value of (-1, -1) indicates a default size, chosen by either the windowing system or wxPython, depending on platform; :param `style`: the underlying :class:`PyWindow` window style. """ wx.PyWindow.__init__(self, parent, id, pos, size, style) self._size = size self._border_colour = None self._barColour = self._barColourSorted = [wx.Colour(212,228,255)] self._barGradient = self._barGradientSorted = None self._border_padding = 0 self._range = range self._value = [0] self._valueSorted = [0] self._timerId = wx.NewId() self._timer = None self._drawIndicatorText = False self.Bind(wx.EVT_PAINT, self.OnPaint) self.Bind(wx.EVT_ERASE_BACKGROUND, self.OnEraseBackground) self.Bind(wx.EVT_TIMER, self.OnTimer) def DoGetBestSize(self): """ Gets the size which best suits :class:`PyGauge`: for a control, it would be the minimal size which doesn't truncate the control, for a panel - the same size as it would have after a call to `Fit()`. :note: Overridden from :class:`PyWindow`. """ return wx.Size(self._size[0], self._size[1]) def GetBorderColour(self): """ Returns the :class:`PyGauge` border colour. """ return self._border_colour def SetBorderColour(self, colour): """ Sets the :class:`PyGauge` border colour. :param `colour`: an instance of :class:`Colour`. """ self._border_colour = colour SetBorderColor = SetBorderColour GetBorderColor = GetBorderColour def GetBarColour(self): """ Returns the :class:`PyGauge` main bar colour. """ return self._barColour[0] def SetBarColour(self, colour): """ Sets the :class:`PyGauge` main bar colour. :param `colour`: an instance of :class:`Colour`. """ if type(colour) != type([]): self._barColour = [colour] else: self._barColour = list(colour) self.SortForDisplay() SetBarColor = SetBarColour GetBarColor = GetBarColour def GetBarGradient(self): """ Returns a tuple containing the gradient start and end colours. """ if self._barGradient == None: return None return self._barGradient[0] def SetBarGradient(self, gradient): """ Sets the bar gradient. :param `gradient`: a tuple containing the gradient start and end colours. :note: This overrides the bar colour previously set with :meth:`PyGauge.SetBarColour`. """ if type(gradient) != type([]): self._barGradient = [gradient] else: self._barGradient = list(gradient) self.SortForDisplay() def GetBorderPadding(self): """ Gets the border padding. """ return self._border_padding def SetBorderPadding(self, padding): """ Sets the border padding. :param `padding`: pixels between the border and the progress bar. """ self._border_padding = padding def GetRange(self): """ Returns the maximum value of the gauge. """ return self._range def SetRange(self, range): """ Sets the range of the gauge. The gauge length is its value as a proportion of the range. :param `range`: The maximum value of the gauge. """ if range <= 0: raise Exception("ERROR:\n Gauge range must be greater than 0.") self._range = range def GetValue(self): """ Returns the current position of the gauge. """ return self._value[0] def SetValue(self, value): """ Sets the current position of the gauge. :param `value`: an integer specifying the current position of the gauge. """ if type(value) != type([]): self._value = [value] else: self._value = list(value) self.SortForDisplay() for v in self._value: if v < 0 or v > self._range: raise Exception("ERROR:\n Gauge value must be between 0 and its range.") def OnEraseBackground(self, event): """ Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`PyGauge`. :param `event`: a :class:`EraseEvent` event to be processed. :note: This method is intentionally empty to reduce flicker. """ pass def OnPaint(self, event): """ Handles the ``wx.EVT_PAINT`` event for :class:`PyGauge`. :param `event`: a :class:`PaintEvent` event to be processed. """ dc = wx.BufferedPaintDC(self) rect = self.GetClientRect() dc.SetBackground(wx.Brush(self.GetBackgroundColour())) dc.Clear() colour = self.GetBackgroundColour() dc.SetBrush(wx.Brush(colour)) dc.SetPen(wx.Pen(colour)) dc.DrawRectangleRect(rect) if self._border_colour: dc.SetPen(wx.Pen(self.GetBorderColour())) dc.DrawRectangleRect(rect) pad = 1 + self.GetBorderPadding() rect.Deflate(pad,pad) if self.GetBarGradient(): for i, gradient in enumerate(self._barGradientSorted): c1,c2 = gradient w = rect.width * (float(self._valueSorted[i]) / self._range) r = copy.copy(rect) r.width = w dc.GradientFillLinear(r, c1, c2, wx.EAST) else: for i, colour in enumerate(self._barColourSorted): dc.SetBrush(wx.Brush(colour)) dc.SetPen(wx.Pen(colour)) w = rect.width * (float(self._valueSorted[i]) / self._range) r = copy.copy(rect) r.width = w dc.DrawRectangleRect(r) if self._drawIndicatorText: dc.SetFont(self._drawIndicatorText_font) dc.SetTextForeground(self._drawIndicatorText_colour) drawValue = self._valueSorted[i] if self._drawIndicatorText_drawPercent: drawValue = (float(self._valueSorted[i]) * 100) / self._range drawString = self._drawIndicatorText_formatString.format(drawValue) rect = self.GetClientRect() (textWidth, textHeight, descent, extraLeading) = dc.GetFullTextExtent(drawString) textYPos = (rect.height-textHeight)/2 if textHeight > rect.height: textYPos = 0-descent+extraLeading textXPos = (rect.width-textWidth)/2 if textWidth>rect.width: textXPos = 0 dc.DrawText(drawString, textXPos, textYPos) def SetDrawValue(self, draw=True, drawPercent=True, font=None, colour=wx.BLACK, formatString=None): """ Sets whether percentage or current value should be drawn on the gauge for precise indication. :param bool `draw`: a boolean value, which if ``True`` tells to start drawing value or percentage. If set to ``False`` nothing will be drawn and other parameters will be ignored; :param bool `drawPercent`: a boolean value which indicates that a percent should be drawn instead of value passed in :meth:`SetValue`; :param Font `font`: a font with which indication should be drawn, if ``None``, then ``wx.NORMAL_FONT`` will be used. Usually text would be displayed centered in the control, but if the text font is too large to be displayed (either in width or height) the corresponding coordinate will be set to zero; :param Colour `colour`: the colour with which indication should be drawn, if ``None`` then ``wx.BLACK`` will be used; :param string `formatString`: a string specifying format of the indication (should have one and only one number placeholder). If set to ``None``, will use ``{:.0f}`` format string for values and ``{:.0f}%`` format string for percentages. As described in http://docs.python.org/library/string.html#format-specification-mini-language. .. note:: `formatString` will override addition of percent sign (after value) even if `drawPercent` is ``True``. .. versionadded:: 0.9.7 """ if not draw: # Will not draw anything unless this is True self._drawIndicatorText = False return self._drawIndicatorText = True self._drawIndicatorText_drawPercent = drawPercent if font is None or not isinstance(font, wx.Font): self._drawIndicatorText_font = wx.NORMAL_FONT else: self._drawIndicatorText_font = font if colour is None or not isinstance(colour, wx.Colour): self._drawIndicatorText_colour = wx.BLACK else: self._drawIndicatorText_colour = colour if formatString is not None: error_occurred = True try: # This is to test if format string is valid. If not, it will be replaced with default one. formatString.format(12.345) error_occurred = False except Exception as e: print "We have exception:%s"%e if error_occurred: formatString = None # Here formatString is either valid formatting string, or None in case of error or None passed if formatString is None: if self._drawIndicatorText_drawPercent: self._drawIndicatorText_formatString = "{:.0f}%" else: self._drawIndicatorText_formatString = "{:.0f}" else: self._drawIndicatorText_formatString = formatString def OnTimer(self,event): """ Handles the ``wx.EVT_TIMER`` event for :class:`PyGauge`. :param `event`: a :class:`TimerEvent` event to be processed. """ if self._timerId == event.GetId(): stop_timer = True for i, v in enumerate(self._value): self._value[i] += self._update_step[i] if self._update_step[i] > 0: if self._value[i] > self._update_value[i]: self._value[i] = self._update_value[i] else: stop_timer = False else: if self._value[i] < self._update_value[i]: self._value[i] = self._update_value[i] else: stop_timer = False if stop_timer: self._timer.Stop() self.SortForDisplay() self.Refresh() def Update(self, value, time=0): """ Update the gauge by adding `value` to it over `time` milliseconds. The `time` parameter **must** be a multiple of 50 milliseconds. :param `value`: The value to be added to the gauge; :param `time`: The length of time in milliseconds that it will take to move the gauge. """ if type(value) != type([]): value = [value] if len(value) != len(self._value): raise Exception("ERROR:\n len(value) != len(self.GetValue())") self._update_value = [] self._update_step = [] for i, v in enumerate(self._value): if value[i]+v <= 0 or value[i]+v > self._range: raise Exception("ERROR:\n Gauge value must be between 0 and its range. ") self._update_value.append(value[i] + v) self._update_step.append(float(value[i])/(time/50)) #print self._update_ if not self._timer: self._timer = wx.Timer(self, self._timerId) self._timer.Start(100) def SortForDisplay(self): """ Internal method which sorts things so we draw the longest bar first. """ if self.GetBarGradient(): tmp = sorted(zip(self._value,self._barGradient)); tmp.reverse() a,b = zip(*tmp) self._valueSorted = list(a) self._barGradientSorted = list(b) else: tmp = sorted(zip(self._value,self._barColour)); tmp.reverse() a,b = zip(*tmp) self._valueSorted = list(a) self._barColourSorted = list(b)