Skip to main content
`Ctrl`+`K`

# `ThreadPoolPushButton`: Button to execute a threaded task

ThreadPoolPushButton module

class ThreadPoolPushButton(parent=None, text=None, icon=None)

  ThreadPoolPushButton provides a simple push button to execute a threaded task with user feedback when the task is running.

  The task can be defined with the method setCallable. It takes a python function and arguments as parameters.

  WARNING: This task is run in a separate thread.

  Everytime the button is pushed a new runner is created to execute the function with defined arguments. An animated waiting icon is displayed to show the activity. By default the button is disabled when an execution is requested. This behaviour can be disabled by using setDisabledWhenWaiting.

  When the button is clicked a beforeExecuting signal is sent from the Qt main thread. Then the task is started in a thread pool and the following signals are emitted from the thread pool. Right before calling the registered callable, the widget emits a started signal. When the task ends, its result is emitted by the succeeded signal, but if it fails the signal failed is emitted with the resulting exception. At the end, the finished signal is emitted.

  The task can be programatically executed by using executeCallable.

      >>> # Compute a value
      >>> import math
      >>> button = ThreadPoolPushButton(text="Compute 2^16")
      >>> button.setCallable(math.pow, 2, 16)
      >>> button.succeeded.connect(print) # python3

      >>> # Compute a wrong value
      >>> import math
      >>> button = ThreadPoolPushButton(text="Compute sqrt(-1)")
      >>> button.setCallable(math.sqrt, -1)
      >>> button.failed.connect(print) # python3

  beforeExecuting

    Signal emitted just before execution of the callable by the main Qt thread. In synchronous mode (direct mode), it can be used to define dynamically setCallable, or to execute something in the Qt thread before the execution, or both.

  started

    Signal emitted from the thread pool when the defined callable is started.

    WARNING: This signal is emitted from the thread performing the task, and might be received after the registered callable has been called. If you want to perform some initialisation or set the callable to run, use the beforeExecuting signal instead.

  finished

    Signal emitted from the thread pool when the defined callable is finished

  succeeded

    Signal emitted from the thread pool when the callable exit with a success.

    The parameter of the signal is the result returned by the callable.

  failed

    Signal emitted emitted from the thread pool when the callable raises an exception.

    The parameter of the signal is the raised exception.

  executeCallable()

    Execute the defined callable in QThreadPool.

    First emit a beforeExecuting signal. If callable is not defined, nothing append. If a callable is defined, it will be started as a new thread using the QThreadPool system. At start of the thread the started will be emitted. When the callable returns a result it is emitted by the succeeded signal. If the callable fail, the signal failed is emitted with the resulting exception. Then the finished signal is emitted.

  setCallable(function, *args, **kwargs)

    Define a callable which will be executed on QThreadPool everytime the button is clicked.

    To retrieve the results, connect to the succeeded signal.

    WARNING: The callable will be called in a separate thread.

    Parameters:

      - function (callable) – A callable Python object

      - args (List) – List of arguments to call the function.

      - kwargs (dict) – Dictionary of arguments used to call the function.