napari.qt#

Classes

QtToolTipLabel

A QLabel that provides instant tooltips on mouser hover.

QtViewer

Qt view for the napari Viewer model.

QtViewerButtons

Button controls for the napari viewer.

Window

Application window that contains the menu bar and viewer.

Functions

napari.qt.create_worker(func: function | generator, *args, _start_thread: bool | None = None, _connect: dict[str, Callable | Sequence[Callable]] | None = None, _progress: bool | dict[str, int | bool | str] | None = None, _worker_class: type[GeneratorWorker] | type[FunctionWorker] | None = None, _ignore_errors: bool = False, **kwargs) FunctionWorker | GeneratorWorker[source]#

Convenience function to start a function in another thread.

By default, uses Worker, but a custom WorkerBase subclass may be provided. If so, it must be a subclass of Worker, which defines a standard set of signals and a run method.

Parameters:
  • func (Callable) – The function to call in another thread.

  • _start_thread (bool, optional) – Whether to immediaetly start the thread. If False, the returned worker must be manually started with worker.start(). by default it will be False if the _connect argument is None, otherwise True.

  • _connect (Dict[str, Union[Callable, Sequence]], optional) – A mapping of "signal_name" -> callable or list of callable: callback functions to connect to the various signals offered by the worker class. by default None

  • _progress (Union[bool, Dict[str, Union[int, bool, str]]], optional) – Can be True, to provide indeterminate progress bar, or dictionary. If dict, requires mapping of ‘total’ to number of expected yields. If total is not provided, progress bar will be indeterminate. Will connect progress bar update to yields and display this progress in the viewer. Can also take a mapping of ‘desc’ to the progress bar description. Progress bar will become indeterminate when number of yields exceeds ‘total’. By default None.

  • _worker_class (Type[WorkerBase], optional) – The :class`WorkerBase` to instantiate, by default FunctionWorker will be used if func is a regular function, and GeneratorWorker will be used if it is a generator.

  • _ignore_errors (bool, optional) – If False (the default), errors raised in the other thread will be reraised in the main thread (makes debugging significantly easier).

  • *args – will be passed to func

  • **kwargs – will be passed to func

Returns:

worker – An instantiated worker. If _start_thread was False, the worker will have a .start() method that can be used to start the thread.

Return type:

WorkerBase

Raises:
  • TypeError – If a worker_class is provided that is not a subclass of WorkerBase.

  • TypeError – If _connect is provided and is not a dict of {str: callable}

  • TypeError – If _progress is provided and function is not a generator

Examples

def long_function(duration):
    import time
    time.sleep(duration)

worker = create_worker(long_function, 10)
napari.qt.thread_worker(function: Callable | None = None, start_thread: bool | None = None, connect: dict[str, Callable | Sequence[Callable]] | None = None, progress: bool | dict[str, int | bool | str] | None = None, worker_class: type[GeneratorWorker] | type[FunctionWorker] | None = None, ignore_errors: bool = False)[source]#

Decorator that runs a function in a separate thread when called.

When called, the decorated function returns a WorkerBase. See create_worker() for additional keyword arguments that can be used when calling the function.

The returned worker will have these signals:

  • started: emitted when the work is started

  • finished: emitted when the work is finished

  • returned: emitted with return value

  • errored: emitted with error object on Exception

It will also have a worker.start() method that can be used to start execution of the function in another thread. (useful if you need to connect callbacks to signals prior to execution)

If the decorated function is a generator, the returned worker will also provide these signals:

  • yielded: emitted with yielded values

  • paused: emitted when a running job has successfully paused

  • resumed: emitted when a paused job has successfully resumed

  • aborted: emitted when a running job is successfully aborted

And these methods:

  • quit: ask the thread to quit

  • toggle_paused: toggle the running state of the thread.

  • send: send a value into the generator. (This requires that your

    decorator function uses the value = yield syntax)

Parameters:
  • function (callable) – Function to call in another thread. For communication between threads may be a generator function.

  • start_thread (bool, optional) – Whether to immediaetly start the thread. If False, the returned worker must be manually started with worker.start(). by default it will be False if the _connect argument is None, otherwise True.

  • connect (Dict[str, Union[Callable, Sequence]], optional) – A mapping of "signal_name" -> callable or list of callable: callback functions to connect to the various signals offered by the worker class. by default None

  • progress (Union[bool, Dict[str, Union[int, bool, str]]], optional) – Can be True, to provide indeterminate progress bar, or dictionary. If dict, requires mapping of ‘total’ to number of expected yields. If total is not provided, progress bar will be indeterminate. Will connect progress bar update to yields and display this progress in the viewer. Can also take a mapping of ‘desc’ to the progress bar description. Progress bar will become indeterminate when number of yields exceeds ‘total’. By default None. Must be used in conjunction with a generator function.

  • worker_class (Type[WorkerBase], optional) – The :class`WorkerBase` to instantiate, by default FunctionWorker will be used if func is a regular function, and GeneratorWorker will be used if it is a generator.

  • ignore_errors (bool, optional) – If False (the default), errors raised in the other thread will be reraised in the main thread (makes debugging significantly easier).

Returns:

function that creates a worker, puts it in a new thread and returns the worker instance.

Return type:

callable

Examples

@thread_worker
def long_function(start, end):
    # do work, periodically yielding
    i = start
    while i <= end:
        time.sleep(0.1)
        yield i

    # do teardown
    return 'anything'

# call the function to start running in another thread.
worker = long_function()
# connect signals here if desired... or they may be added using the
# `connect` argument in the `@thread_worker` decorator... in which
# case the worker will start immediately when long_function() is called
worker.start()
napari.qt.get_app(*, app_name: str | None = None, app_version: str | None = None, icon: str | None = None, org_name: str | None = None, org_domain: str | None = None, app_id: str | None = None, ipy_interactive: bool | None = None) QApplication[source]#

Get or create the Qt QApplication.

There is only one global QApplication instance, which can be retrieved by calling get_app again, (or by using QApplication.instance())

Parameters:
  • app_name (str, optional) – Set app name (if creating for the first time), by default ‘napari’

  • app_version (str, optional) – Set app version (if creating for the first time), by default __version__

  • icon (str, optional) – Set app icon (if creating for the first time), by default NAPARI_ICON_PATH

  • org_name (str, optional) – Set organization name (if creating for the first time), by default ‘napari’

  • org_domain (str, optional) – Set organization domain (if creating for the first time), by default ‘napari.org’

  • app_id (str, optional) – Set organization domain (if creating for the first time). Will be passed to set_app_id (which may also be called independently), by default NAPARI_APP_ID

  • ipy_interactive (bool, optional) – Use the IPython Qt event loop (‘%gui qt’ magic) if running in an interactive IPython terminal.

Returns:

[description]

Return type:

QApplication

Notes

Substitutes QApplicationWithTracing when the NAPARI_PERFMON env variable is set.

napari.qt.get_stylesheet(theme_id: str | None = None, extra: list[str] | None = None, extra_variables: dict[str, str] | None = None) str[source]#

Combine all qss files into single, possibly pre-themed, style string.

Parameters:
  • theme_id (str, optional) – Theme to apply to the stylesheet. If no theme is provided, the returned stylesheet will still have {{ template_variables }} that need to be replaced using the napari.utils.theme.template() function prior to using the stylesheet.

  • extra (list of str, optional) – Additional paths to QSS files to include in stylesheet, by default None

  • extra_variables (dict, optional) – Dictionary of variables values that replace default theme values. For example: { ‘font_size’: ‘14pt’}

Returns:

css – The combined stylesheet.

Return type:

str

napari.qt.get_current_stylesheet(extra: list[str] | None = None) str[source]#

Return the current stylesheet base on settings. This is wrapper around get_stylesheet() that takes the current theme base on settings.

Parameters:

extra (list of str, optional) – Additional paths to QSS files to include in stylesheet, by default None

Returns:

css – The combined stylesheet.

Return type:

str

napari.qt.run(*, force=False, gui_exceptions=False, max_loop_level=1, _func_name='run')[source]#

Start the Qt Event Loop

Parameters:
  • force (bool, optional) – Force the application event_loop to start, even if there are no top level widgets to show.

  • gui_exceptions (bool, optional) – Whether to show uncaught exceptions in the GUI. By default they will be shown in the console that launched the event loop.

  • max_loop_level (int, optional) – The maximum allowable “loop level” for the execution thread. Every time QApplication.exec_() is called, Qt enters the event loop, increments app.thread().loopLevel(), and waits until exit() is called. This function will prevent calling exec_() if the application already has at least max_loop_level event loops running. By default, 1.

  • _func_name (str, optional) – name of calling function, by default ‘run’. This is only here to provide functions like gui_qt a way to inject their name into the warning message.

Raises:

RuntimeError – (To avoid confusion) if no widgets would be shown upon starting the event loop.