Browse Source

Added documentation for timers

Alfio Puglisi 4 months ago
parent
commit
cca0d36249
2 changed files with 41 additions and 2 deletions
  1. 38 0
      docs/tutorial.rst
  2. 3 2
      guietta/guietta.py

+ 38 - 0
docs/tutorial.rst

@@ -959,6 +959,44 @@ child Gui instance inside the group box, keeping it visible.
 
 See also the `groupbox example <https://github.com/alfiopuglisi/guietta/blob/master/guietta/examples/groupbox.py>`_
 
+Timers
+------
+
+Sometimes it is useful to regularly repeat an action every x seconds,
+for example to regularly update your GUI.
+
+Guietta includes a built-in timer that can be started like this::
+
+    gui.timer_start(f, interval=0.1)
+
+after this call, whenever the message loop is running (that is, after
+*run()* or *get()* has been called as well), the *f* function will be called
+every 0.1 seconds. *f* may be any Python callable, and must accept
+one argument, that will be set to the *Gui* object instance. For example,
+this code will update a widget showing the number of seconds passed
+since timer_start::
+
+
+    def regular_update(gui):
+        gui.mywidget = 'Seconds: '+str(gui.timer_count())
+
+    gui.timer_start(regular_update, interval=1)
+
+
+The time resolution is the one offered by the underlying QTimer object
+and is never better than a millisecond.
+
+If an exception is raised while executing *f*, the usual exception rules
+described `here <tutorial.html#exception-handling>`_ apply.
+
+If the timer is no longer needed, the *gui.timer_stop()* method will stop
+the regular calls. Another call to *gui.timer_start()* can be used
+to restart it, possibly with a different function and/or interval.
+
+The number of times that the timer callback has been called 
+since the Gui object has been built is returned by the *gui.timer_count()*
+method. This counter is not resetted to zero by a *gui.timer_stop()* call.
+
 Packaging your application
 -----------------------------
 

+ 3 - 2
guietta/guietta.py

@@ -1804,7 +1804,7 @@ class Gui:
         return self._original_names
 
     def proxy(self, name):
-        '''Returns the *guietta property* for the a (normalized) widget name.
+        '''Returns the *guietta property* for a (normalized) widget name.
 
         A guietta property is an instance of the *GuiettaProperty* class,
         with two attributes: get() and set()
@@ -1990,7 +1990,7 @@ class Gui:
     def timer_start(self, callback, interval=1.0):
         '''Set up a timer to call *callback* every *interval* seconds.
         
-        The callback will receive the Gui instance as the first argument.
+        The callback will receive the Gui instance as its only argument.
         '''
         self._timer = QTimer()
         self._user_timer_callback = _exception_wrapper(callback,
@@ -1999,6 +1999,7 @@ class Gui:
         self._timer.start(interval*1000)
 
     def timer_stop(self):
+        '''Stops the timer'''
         if self._timer is not None:
             self._timer.stop()