hscommon.gui.progress_window — dupeGuru 4.0.4 documentation

# dupeGuru 4.0.4 documentation

## 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

    - 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.