napari.qt¶

Classes

`QtStateButton`	Button to toggle between two states. :param button_name: A string that will be used in qss to style the button with the QtStateButton[mode=...] selector, :type button_name: str :param target: object on which you want to change the property when button pressed. :type target: object :param attribute: name of attribute on object you wish to change. :param events: event emitter that will trigger when value is changed :type events: EventEmitter :param onstate: value to use for `setattr(object, attribute, onstate)` when clicking this button :type onstate: Any :param offstate: value to use for `setattr(object, attribute, offstate)` when clicking this button. :type offstate: Any.
`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: Union[function, generator], *args, _start_thread: Optional[bool] = None, _connect: Optional[Dict[str, Union[Callable, Sequence[Callable]]]] = None, _progress: Optional[Union[bool, Dict[str, Union[int, bool, str]]]] = None, _worker_class: Optional[Union[Type[napari._qt.qthreading.GeneratorWorker], Type[napari._qt.qthreading.FunctionWorker]]] = None, _ignore_errors: bool = False, **kwargs) → Union[napari._qt.qthreading.FunctionWorker, napari._qt.qthreading.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: Optional[Callable] = None, start_thread: Optional[bool] = None, connect: Optional[Dict[str, Union[Callable, Sequence[Callable]]]] = None, progress: Optional[Union[bool, Dict[str, Union[int, bool, str]]]] = None, worker_class: Optional[Union[Type[napari._qt.qthreading.GeneratorWorker], Type[napari._qt.qthreading.FunctionWorker]]] = 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: Optional[str] = None, app_version: Optional[str] = None, icon: Optional[str] = None, org_name: Optional[str] = None, org_domain: Optional[str] = None, app_id: Optional[str] = None, ipy_interactive: Optional[bool] = None) → PyQt5.QtWidgets.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: Optional[str] = None, extra: Optional[List[str]] = None) → str[source]¶

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

Parameters

theme (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

Returns

css – The combined stylesheet.

Return type

str

napari.qt.get_current_stylesheet(extra: Optional[List[str]] = 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.

napari.components.ViewerModel

napari.qt.QtStateButton