Skip to content

FunctionGui#

Available in backends:

Signals#

  • called(object) - Emitted with the result after the function is called.
  • changed(object) - Emitted with self when any sub-widget in the container changes.
  • label_changed(str) - Emitted when the widget label changes.
  • native_parent_changed(object) - Emitted with the backend widget when the widget parent changes.

FunctionGui #

Bases: Container, Generic[_P, _R]

Wrapper for a container of widgets representing a callable object.

Parameters:

  • function (Callable) –

    A callable to turn into a GUI

  • call_button (bool | str | None, default: None ) –

    If True, create an additional button that calls the original function when clicked. If a str, set the button text. by default False when auto_call is True, and True otherwise. The button can be accessed from the .call_button property.

  • layout (str, default: 'vertical' ) –

    The type of layout to use. Must be horizontal or vertical by default "horizontal".

  • scrollable (bool, default: False ) –

    Whether to enable scroll bars or not. If enabled, scroll bars will only appear along the layout direction, not in both directions.

  • labels (bool, default: True ) –

    Whether labels are shown in the widget. by default True

  • tooltips (bool, default: True ) –

    Whether tooltips are shown when hovering over widgets. by default True

  • app (Application | str | None, default: None ) –

    A backend to use, by default None (use the default backend.)

  • visible (bool, default: None ) –

    Whether to immediately show the widget. If False, widget is explicitly hidden. If None, widget is not shown, but will be shown if a parent container is shown, by default None.

  • auto_call (bool, default: False ) –

    If True, changing any parameter in either the GUI or the widget attributes will call the original function with the current settings. by default False

  • result_widget (bool, default: False ) –

    Whether to display a LineEdit widget the output of the function when called, by default False

  • param_options (dict, default: None ) –

    A dict of name: widget_options dict for each parameter in the function. Will be passed to magic_signature by default None

  • name (str, default: None ) –

    A name to assign to the Container widget, by default function.__name__

  • persist (bool, default: False ) –

    If True, when parameter values change in the widget, they will be stored to disk (in ~/.config/magicgui/cache) and restored when the widget is loaded again with persist = True. By default, False.

  • raise_on_unknown (bool, default: False ) –

    If True, raise an error if a parameter annotation is not recognized.

Raises:

  • TypeError –

    If unexpected keyword arguments are provided

__signature__: MagicSignature property #

Return a MagicSignature object representing the current state of the gui.

call_button: PushButton | None property #

Return the call button.

call_count: int property #

Return the number of times the function has been called.

result_name: str property writable #

Return a name that can be used for the result of this magicfunction.

return_annotation: Any property #

Return annotation for inspect.Signature conversion.

ForwardRefs will be resolve when setting the annotation.

__call__(*args: _P.args, **kwargs: _P.kwargs) -> _R #

Call the original function with the current parameter values from the Gui.

You may pass a update_widget=True keyword argument to update the widget values to match the current parameter values before calling the function.

It is also possible to override the current parameter values from the GUI by providing args/kwargs to the function call. Only those provided will override the ones from the gui. A called signal will also be emitted with the results.

Returns:

  • result ( Any ) –

    whatever the return value of the original function would have been.

Examples:

gui = FunctionGui(func, show=True)

# then change parameters in the gui, or by setting:  gui.param.value = something

gui()  # calls the original function with the current parameters

__get__(obj: object, objtype: type | None = None) -> FunctionGui #

Provide descriptor protocol.

This allows the @magicgui decorator to work on a function as well as a method. If a method on a class is decorated with @magicgui, then accessing the attribute on an instance of that class will return a version of the FunctionGui in which the first argument of the function is bound to the instance. (Just like what you'd expect with the @property decorator.)

Returns:

  • bound ( FunctionGui ) –

    A new FunctionGui instance.

Examples:

>>> class MyClass:
...     @magicgui
...     def my_method(self, x=1):
...         print(locals())
...
>>> c = MyClass()
>>> c.my_method  # the FunctionGui that can be used as a widget

# calling it works as usual, with `c` provided as `self`
>>> c.my_method(x=34)
{'self': <__main__.MyClass object at 0x7fb610e455e0>, 'x': 34}

__init__(function: Callable[_P, _R], call_button: bool | str | None = None, layout: str = 'vertical', scrollable: bool = False, labels: bool = True, tooltips: bool = True, app: AppRef | None = None, visible: bool | None = None, auto_call: bool = False, result_widget: bool = False, param_options: dict[str, dict] | None = None, name: str | None = None, persist: bool = False, raise_on_unknown: bool = False, **kwargs: Any) #

__repr__() -> str #

Return string representation of instance.

__set__(obj: Any, value: Any) -> NoReturn #

Prevent setting a magicgui attribute.

copy() -> FunctionGui #

Return a copy of this FunctionGui.

reset_call_count() -> None #

Reset the call count to 0.