twisting 0.6.3
twisting is based on twisted deferred thread with GTK
License: BSD

How to use a progress window
============================

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