Skip to content

magicgui.widgets.create_widget#

magicgui.widgets.create_widget(value=Undefined, annotation=None, name='', param_kind='POSITIONAL_OR_KEYWORD', label=None, gui_only=False, app=None, widget_type=None, options=None, is_result=False, raise_on_unknown=True) #

Create and return appropriate widget subclass.

This factory function can be used to create a widget appropriate for the provided value and/or annotation provided. See Type Mapping Docs for details on how the widget type is determined from type annotations.

Parameters:

  • value (Any, default: Undefined ) –

    The starting value for the widget, by default None

  • annotation (Any, default: None ) –

    The type annotation for the parameter represented by the widget, by default None.

  • name (str, default: '' ) –

    The name of the parameter represented by this widget. by default ""

  • param_kind (str, default: 'POSITIONAL_OR_KEYWORD' ) –

    The :attr:inspect.Parameter.kind represented by this widget. Used in building signatures from multiple widgets, by default "POSITIONAL_OR_KEYWORD"

  • label (str, default: None ) –

    A string to use for an associated Label widget (if this widget is being shown in a Container widget, and labels are on). By default, name will be used. Note: name refers the name of the parameter, as might be used in a signature, whereas label is just the label for that widget in the GUI.

  • gui_only (bool, default: False ) –

    Whether the widget should be considered "only for the gui", or if it should be included in any widget container signatures, by default False

  • app (str, default: None ) –

    The backend to use, by default None

  • widget_type (str or Type[WidgetProtocol] or None, default: None ) –

    A class implementing a widget protocol or a string with the name of a magicgui widget type (e.g. "Label", "PushButton", etc...). If provided, this widget type will be used instead of the type autodetermined from value and/or annotation above.

  • options (dict, default: None ) –

    Dict of options to pass to the Widget constructor, by default dict()

  • is_result (boolean, default: False ) –

    Whether the widget belongs to an input or an output. By default, an input is assumed.

  • raise_on_unknown (bool, default: True ) –

    Raise exception if no widget is found for the given type, by default True

Returns:

  • Widget –

    An instantiated widget subclass

Raises:

Examples:

from magicgui.widgets import create_widget

# create a widget from a string value
wdg = create_widget(value="hello world")
assert wdg.value == "hello world"

# create a widget from a string annotation
wdg = create_widget(annotation=str)
assert wdg.value == ""