magicgui type registration#
magicgui uses
type hints to infer the appropriate widget type
for a given function parameter. It allows third party packages
(like napari) to register support for their types using
register_type(). napari registers
a number of types, additionally specifying, where appropriate:
widget type for the parameter type
function for updating inputs for the widget
return callback, for return types
This enables magicgui widgets to be easily created via type annotations.
Note
This page provides implementation details on napari-specific type registration
in magicgui and is aimed at napari developers.
For information about using magicgui (for users and plugin developers) see
Creating widgets.
Registration details#
napari types are either registered via the
@register_type decorator when they are
defined or in
napari/types.py.
For the full list of types registered, see Parameter annotations.
Layer types#
The ‘layer’ types registered are Layer and its subclasses, and
<LayerType>Data types.
All these types provide a choices callable when they are registered with
magicgui. This means that annotating with these types creates a
CategoricalWidget, which will have a dropdown
selection whose options will be updated via the
choices callable.
This callable is either get_layers_data or get_layers.
These functions retrieve the closest parent Viewer of the native
CategoricalWidget widget and returns a list of
Layer or tuple of format ('layer name', <LayerType>Data).
This callable is set to the choices attribute of the
CategoricalWidget in its
reset_choices() method and thus
gets called via CategoricalWidget’s choices setter.
napari add_dock_widget() checks if the dock widget has
a reset_choices attribute and if so, connects it to layer events.
Note that magicgui ContainerWidget’s will call
reset_choices on all subwidgets. This means that when the dock widget is a
ContainerWidget, any subwidgets (e.g.,
CategoricalWidgets) are updated
whenever layers change.
Note that add_dock_widget() will
connect any existing reset_choices widget attribute to layer events for all widgets,
not just magicgui widgets.
The ‘layer’ types also specify a return_callback function that adds the layer
to the closest parent Viewer of the native widget when a ‘layer’ type is a return
annotation.
Viewer type#
Viewer differs from the layer types. napari simply specifies
that the closest parent Viewer (technically a public proxy of
the Viewer that prevents private attribute access) be bound to
the widget (technically it’s bound to a hidden child
EmptyWidget). This allows the Viewer
to be used in the magicgui widget.
Note
When widget is not a magicgui widget, the Viewer is provided
via a wrapper napari adds around widget contributions.