twisting 0.6.3

twisting is based on twisted deferred thread with GTK

Requirements

To be effective the twisting needs the twisted library in addition with gtk. Then we have to do the following imports at the beginning of the main entry file of the application:

# twisted install
from twisted.internet import gtk2reactor
# install the gtk2 reactor
gtk2reactor.install()
# twisted import
from twisted.internet import reactor

Before we started the application with traditional gtk main thread starting:

# gtk thread start gtk.main()

Now we use the twisted reactor start after as follow:

# twisted reactor start
reactor.run()

Note: your main graphic window must be created before the reactor start like with gtk.

Framework overview

The gui part of the twisting framework offer the following functionalities:

1. gui elements to display the tasks progress

• taskbox object: attach to a task to inform about the task progression

• progress window: contains all the task boxes that can be hidden

• progress box: can be use in a parent window to inform about the average progression

2. several tasks management

• add task: create a thread and a taskox attach to a working method

• pause/play task: automatically managed by the framework

• stop task: return a flag to the main loop

• remove a taskbox from the progress window (stopped automatically)

nb: each task correspond with a gui widget displaying the progress status of the task

3. callbacks

• result callback: set when we add the task and call with a result by the twisted deferred thread when the worker loop ended

• error callback: set when we add the task and call by the twisted deferred thread on error

• all tasks finished callback: call by the progress window when all tasks are finished, can be used for message display, progress window hide or i don’t know…

Framework best practice

Here we explain the standard use of the framework step by step.

1. Create the progress window

The progress window is a singleton and must be created before the reactor start or in the gtk workflow with the following lines:

# progress window import
from twisting import ProgressManager
# Progress manager init
ProgressManager(all_finish_callback=on_all_tasks_finished, ui=True)

2. Set a progress bar for more progress info

The progress bar can be added every where and will be updated by the progress window to display progress average depending of the current tasks in progress. To do so we create the progress box and set it to the progress window:

# progress box import
from twisting.gui_worker import ProgressManager
import gtk

# create the box
progress_bar = gtk.ProgressBar()
# add the box
ProgressManager().set_parent(self.main_window, progress_bar)

Note: we prefer to set a parent to the progress window to use the transient function of gtk

3. Add a new task

We add a task to the progress window with the add function. The thread and the taskbox will be created, attached and start automatically by the progress window:

# add the task
ProgressManager().add_task(
        id_, pretty_name,
        self.task_function,
        end_callback=self.end_callback,
        error_callback=self.error_callback)

Some details:

• id_ corresponds to an unique id for the task

• pretty_name will be displayed in the task box widget

• task_function is the function that will be threaded using twisted and that should manage the task loop depending of the twisting framework api

• end_callback is the result callback for twisted receiving the task_function result whatever it is

• error_callback is the error callback for twisted receiving a twisted object failure in parameter

4. The threaded task loop function

The loop function receive the corresponding taskbox in parameters. Then we have to inform the taskbox of the number of iterations to init the good progress ratio:

# set the number of iterations
taskbox.set_max_pulse(100)

To hide a maximum of the thread management we will use the state_method given by the framework. It should be import a follow:

# state_machine function import
from twisting import state_machine

For each task iteration this method will update the progess info, check for Pause or Stop event. The thread pause is directly managed in that function. If an event Stop is catched the function returns True, it means that the threaded function must exit. The method must be called with the taskbox instance to poll the taskbox event queue:

# IN THE LOOP
# check for stop or pause events
if state_machine(taskbox):
    # we quit
    return stop_result

At the end we call the taskbox finish method throw a twisted thread to stop the progress in the task box and display an ending message. Then we return the work result that will be send to the result callback by the twisted:

# call the finish action throw the parent event queue
reactor.callFromThread(taskbox.finish)
# we finish
return end_result