hscommon.gui.progress_window¶

`ProgressWindow`(finish_func[, error_func])	Cross-toolkit GUI-enabled progress window.
`ProgressWindowView`	Expected interface for `ProgressWindow`’s view.

class hscommon.gui.progress_window.ProgressWindow(finish_func, error_func=None)¶

Cross-toolkit GUI-enabled progress window.

This class allows you to run a long running, job enabled function in a separate thread and allow the user to follow its progress with a progress dialog.

To use it, you start your long-running job with run() and then have your UI layer regularly call pulse() to refresh the job status in the UI. It is advised that you call pulse() in the main thread because GUI toolkit usually only support calling UI-related functions from the main thread.

We subclass GUIObject and ThreadedJobPerformer. Expected view: ProgressWindowView.

Parameters:

Parameters:	finish_func – A function `f(jobid)` that is called when a job is completed. `jobid` is an arbitrary id passed to `run()`. error_func – A function `f(jobid, err)` that is called when an exception is raised and unhandled during the job. If not specified, the error will be raised in the main thread. If it’s specified, it’s your responsibility to raise the error if you want to. If the function returns `True`, `finish_func()` will be called as if the job terminated normally.

finish_func – A function f(jobid) that is called when a job is completed. jobid is an arbitrary id passed to run().
error_func – A function f(jobid, err) that is called when an exception is raised and unhandled during the job. If not specified, the error will be raised in the main thread. If it’s specified, it’s your responsibility to raise the error if you want to. If the function returns True, finish_func() will be called as if the job terminated normally.

cancel()¶: Call for a user-initiated job cancellation.

pulse()¶

Update progress reports in the GUI.

Call this regularly from the GUI main run loop. The values might change before ProgressWindowView.set_progress() happens.

If the job is finished, pulse() will take care of closing the window and re-raising any exception that might have been raised during the job (in the main thread this time). If there was no exception, finish_func(jobid) is called to let you take appropriate action.

run(jobid, title, target, args=())¶

Starts a threaded job.

The target function will be sent, as its first argument, a Job instance which it can use to report on its progress.

Parameters:	jobid – Arbitrary identifier which will be passed to `finish_func()` at the end. title – A title for the task you’re starting. target – The function that does your famous long running job. args – additional arguments that you want to send to `target`.

jobdesc_textfield = None¶: TextField. It contains that title you gave the job on run().

progressdesc_textfield = None¶: TextField. It contains the job textual update that the function might yield during its course.

class hscommon.gui.progress_window.ProgressWindowView¶

Expected interface for ProgressWindow’s view.

Not actually used in the code. For documentation purposes only.

Our view, some kind window with a progress bar, two labels and a cancel button, is expected to properly respond to its callbacks.

It’s also expected to call ProgressWindow.cancel() when the cancel button is clicked.

close()¶: Close the dialog.

set_progress(progress)¶

Set the progress of the progress bar to progress.

Not all jobs are equally responsive on their job progress report and it is recommended that you put your progressbar in “indeterminate” mode as long as you haven’t received the first set_progress() call to avoid letting the user think that the app is frozen.

Parameters:	progress (int) – a value between `0` and `100`.

show()¶: Show the dialog.