{
    "info": {
        "author": "Florent PIGOUT",
        "author_email": "florent.pigout@gmail.com",
        "bugtrack_url": null,
        "classifiers": [],
        "description": "How to use a progress window\n============================\n\nRequirements\n------------\n\nTo be effective the twisting needs the twisted library in addition with\ngtk. Then we have to do the following imports at the beginning of the main\nentry file of the application::\n\n    # twisted install\n    from twisted.internet import gtk2reactor\n    # install the gtk2 reactor\n    gtk2reactor.install()\n    # twisted import\n    from twisted.internet import reactor\n\nBefore we started the application with traditional gtk main thread starting:\n\n    *# gtk thread start*\n    *gtk.main()*\n\nNow we use the twisted reactor start after as follow::\n\n    # twisted reactor start\n    reactor.run()\n\n**Note:** *your main graphic window must be created before the reactor start\nlike with gtk.*\n\nFramework overview\n------------------\n\nThe gui part of the twisting framework offer the following functionalities:\n\n    ``1. gui elements to display the tasks progress``\n        - *taskbox object:* attach to a task to inform about the task\n          progression\n        - *progress window:* contains all the task boxes that  can be hidden\n        - *progress box:* can be use in a parent window to inform about the\n          average progression\n\n    ``2. several tasks management``\n        - *add task:* create a thread and a taskox attach to a working method\n        - *pause/play task:* automatically managed by the framework\n        - *stop task:* return a flag to the main loop\n        - *remove* a taskbox from the progress window *(stopped automatically)*\n\n        *nb: each task correspond with a gui widget displaying the progress\n        status of the task*\n\n    ``3. callbacks``\n        - *result callback:*  set when we add the task and call with a result\n          by the twisted deferred thread when the worker loop ended\n        - *error callback:*  set when we add the task and call by the twisted\n          deferred thread on error\n        - *all tasks finished callback:* call by the progress window when all\n          tasks are finished, can be used for message display, progress window\n          hide or i don't know...\n\nFramework best practice\n-----------------------\n\nHere we explain the standard use of the framework step by step.\n\n\n**1. Create the progress window**\n    The progress window is a singleton and must be created before the reactor\n    start or in the gtk workflow with the following lines::\n\n        # progress window import\n        from twisting import ProgressManager\n        # Progress manager init\n        ProgressManager(all_finish_callback=on_all_tasks_finished, ui=True)\n\n\n**2. Set a progress bar for more progress info**\n    The progress bar can be added every where and will be updated by the\n    progress window to display progress average depending of the current tasks\n    in progress. To do so we create the progress box and set it to the\n    progress window::\n\n        # progress box import\n        from twisting.gui_worker import ProgressManager\n        import gtk\n\n        # create the box\n        progress_bar = gtk.ProgressBar()\n        # add the box\n        ProgressManager().set_parent(self.main_window, progress_bar)\n\n    **Note:** *we prefer to set a parent to the progress window to use the\n    transient function of gtk*\n\n\n**3. Add a new task**\n    We add a task to the progress window with the add function. The thread and\n    the taskbox will be created, attached and start automatically by the\n    progress window::\n\n        # add the task\n        ProgressManager().add_task(\n                id_, pretty_name,\n                self.task_function,\n                end_callback=self.end_callback,\n                error_callback=self.error_callback)\n\n    Some details:\n\n        - ``id_`` corresponds to an unique id for the task\n        - ``pretty_name`` will be displayed in the task box widget\n        - ``task_function`` is the function that will be threaded using twisted\n          and that should manage the task loop depending of the twisting\n          framework api\n        - ``end_callback`` is the result callback for twisted receiving the\n          *task_function* result whatever it is\n        - ``error_callback`` is the error callback for twisted receiving a\n          twisted object failure in parameter\n\n\n**4. The threaded task loop function**\n    The loop function receive the corresponding taskbox in parameters. Then we\n    have to inform the taskbox of the number of iterations to init the good\n    progress ratio::\n\n        # set the number of iterations\n        taskbox.set_max_pulse(100)\n\n    To hide a maximum of the thread management we will use the ``state_method``\n    given by the framework. It should be import a follow::\n\n        # state_machine function import\n        from twisting import state_machine\n\n    For each task iteration this method will update the progess info, check for\n    ``Pause`` or ``Stop`` event. The thread pause is directly managed in that\n    function. If an event ``Stop`` is catched the function returns ``True``, it\n    means that the threaded function must exit. The method must be called with\n    the taskbox instance to poll the taskbox event queue::\n\n        # IN THE LOOP\n        # check for stop or pause events\n        if state_machine(taskbox):\n            # we quit\n            return stop_result\n\n    At the end we call the taskbox finish method throw a twisted thread to stop\n    the progress in the task box and display an ending message. Then we return\n    the work result that will be send to the result callback by the twisted::\n\n        # call the finish action throw the parent event queue\n        reactor.callFromThread(taskbox.finish)\n        # we finish\n        return end_result",
        "description_content_type": null,
        "docs_url": null,
        "download_url": "UNKNOWN",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "http://bitbucket.org/florent/twisting",
        "keywords": null,
        "license": "BSD",
        "maintainer": null,
        "maintainer_email": null,
        "name": "twisting",
        "package_url": "https://pypi.org/project/twisting/",
        "platform": "UNKNOWN",
        "project_url": "https://pypi.org/project/twisting/",
        "project_urls": {
            "Download": "UNKNOWN",
            "Homepage": "http://bitbucket.org/florent/twisting"
        },
        "release_url": "https://pypi.org/project/twisting/0.6.3/",
        "requires_dist": null,
        "requires_python": null,
        "summary": "twisting is based on twisted deferred thread with GTK",
        "version": "0.6.3"
    },
    "last_serial": 801084,
    "releases": {
        "0.6": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "b3340b402ff1f74ebd972e93d9725f66",
                    "sha256": "0839ef797f50e00457aa390cf4f1581ac0aed6618e01c5a6cc3a3f70a0996cd0"
                },
                "downloads": -1,
                "filename": "twisting-0.6-py2.5.egg",
                "has_sig": false,
                "md5_digest": "b3340b402ff1f74ebd972e93d9725f66",
                "packagetype": "bdist_egg",
                "python_version": "2.5",
                "requires_python": null,
                "size": 65452,
                "upload_time": "2009-01-27T00:03:00",
                "url": "https://files.pythonhosted.org/packages/e0/dd/fbdbcba36f1bf308948771fc73abf96601cefbf5fd2ad2bb88487cc977e8/twisting-0.6-py2.5.egg"
            }
        ],
        "0.6.2": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "cf7e4c62d61afd3f449e3c34fc145ee6",
                    "sha256": "76895c3cf8b1cf065bc485d3e1eb9f0c913093f1d79c0a4efc6b8647d7d2d096"
                },
                "downloads": -1,
                "filename": "twisting-0.6.2-py2.5.egg",
                "has_sig": false,
                "md5_digest": "cf7e4c62d61afd3f449e3c34fc145ee6",
                "packagetype": "bdist_egg",
                "python_version": "2.5",
                "requires_python": null,
                "size": 65876,
                "upload_time": "2009-03-29T19:19:24",
                "url": "https://files.pythonhosted.org/packages/9e/04/cfcfa0942f39b914a2e7c827f529554e7f7907e8c50810d2bde50e09c9f5/twisting-0.6.2-py2.5.egg"
            }
        ],
        "0.6.3": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "dff64063ade1158070cbdfecf45b8037",
                    "sha256": "ea71ffc63ab8ff0225a959fbd89bec61cf7c2d5ebbb3b2042f9362b853d9d590"
                },
                "downloads": -1,
                "filename": "twisting-0.6.3-py2.5.egg",
                "has_sig": false,
                "md5_digest": "dff64063ade1158070cbdfecf45b8037",
                "packagetype": "bdist_egg",
                "python_version": "2.5",
                "requires_python": null,
                "size": 66039,
                "upload_time": "2009-03-30T23:00:20",
                "url": "https://files.pythonhosted.org/packages/47/cd/55a6030dc7dd57bc1ee888beedfc57bccc6bc2c1892d6ae91b5ffb46e4d2/twisting-0.6.3-py2.5.egg"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "dff64063ade1158070cbdfecf45b8037",
                "sha256": "ea71ffc63ab8ff0225a959fbd89bec61cf7c2d5ebbb3b2042f9362b853d9d590"
            },
            "downloads": -1,
            "filename": "twisting-0.6.3-py2.5.egg",
            "has_sig": false,
            "md5_digest": "dff64063ade1158070cbdfecf45b8037",
            "packagetype": "bdist_egg",
            "python_version": "2.5",
            "requires_python": null,
            "size": 66039,
            "upload_time": "2009-03-30T23:00:20",
            "url": "https://files.pythonhosted.org/packages/47/cd/55a6030dc7dd57bc1ee888beedfc57bccc6bc2c1892d6ae91b5ffb46e4d2/twisting-0.6.3-py2.5.egg"
        }
    ]
}