Skip to content

Backend Protocols#

Advanced Topic

Most users of magicgui will not need to worry about this section.

These Protocol classes declare the interface that backend adapters must implement in order to be used by magicgui. All magicgui Widget objects compose a backend widget implementing one of these protocols, and control it using the methods defined herein.

magicgui developers may be interested in this page, but end-users needn't worry about it.

Summary#

Widget Description
WidgetProtocol Base Widget Protocol: specifies methods that all widgets must provide.
ValueWidgetProtocol Widget that has a current value, with getter/setter and on_change callback.
ButtonWidgetProtocol The "value" in a ButtonWidget is the current (checked) state.
TableWidgetProtocol ValueWidget subclass intended for 2D tabular data, with row & column headers.
RangedWidgetProtocol Value widget that supports numbers within a provided min/max range.
CategoricalWidgetProtocol Categorical widget, that has a set of valid choices, and a current value.
SliderWidgetProtocol Protocol for implementing a slider widget.
ContainerProtocol Widget that can contain other widgets.
BaseApplicationBackend Backend Application object.
DialogProtocol Protocol for modal (blocking) containers.
SupportsChoices Widget that has a set of valid choices.
SupportsOrientation Widget that can be reoriented.
SupportsText Widget that have text (in addition to value)... like buttons.
SupportsReadOnly Widget that can be read_only.

Protocol Inheritance#

The visual hierarchy of protocols looks like this:

graph LR
    A([WidgetProtocol])-->B([ValueWidgetProtocol])
    A-->C([ContainerProtocol])
    M([SupportsText])-->E
    B-->E([ButtonWidgetProtocol])
    B-->D([RangedWidgetProtocol])
    B-->F([CategoricalWidgetProtocol])
    D-->I([SliderWidgetProtocol])
    B-->J([TableWidgetProtocol])
    K([SupportsReadOnly])-->J([TableWidgetProtocol])
    L([SupportsChoices])-->F
    N([SupportsOrientation])-->C
    N-->I
    C-->O([DialogProtocol])
    C-->P([MainWindowProtocol])

    click A "#magicgui.widgets.protocols.WidgetProtocol"
    click B "#magicgui.widgets.protocols.ValueWidgetProtocol"
    click C "#magicgui.widgets.protocols.ContainerProtocol"
    click D "#magicgui.widgets.protocols.RangedWidgetProtocol"
    click E "#magicgui.widgets.protocols.ButtonWidgetProtocol"
    click F "#magicgui.widgets.protocols.CategoricalWidgetProtocol"
    click I "#magicgui.widgets.protocols.SliderWidgetProtocol"
    click J "#magicgui.widgets.protocols.TableWidgetProtocol"
    click K "#magicgui.widgets.protocols.SupportsReadOnly"
    click L "#magicgui.widgets.protocols.SupportsChoices"
    click M "#magicgui.widgets.protocols.SupportsText"
    click N "#magicgui.widgets.protocols.SupportsOrientation"
    click O "#magicgui.widgets.protocols.DialogProtocol"
    click P "#magicgui.widgets.protocols.MainWindowProtocol"

Widget Protocols#

magicgui.widgets.protocols.WidgetProtocol #

Bases: Protocol

Base Widget Protocol: specifies methods that all widgets must provide.

_mgui_bind_parent_change_callback(callback: Callable[[Any], None]) -> None abstractmethod #

Bind callback to parent change event.

_mgui_close_widget() -> None abstractmethod #

Close widget.

_mgui_get_enabled() -> bool abstractmethod #

Get the enabled state of the widget.

_mgui_get_height() -> int abstractmethod #

Get the height of the widget.

The intention is to get the height of the widget after it is shown, for the purpose of unifying widget height in a layout. Backends may do what they need to accomplish this. For example, Qt can use sizeHint().height(), since height() may return something large if the widget has not yet been painted on screen.

_mgui_get_max_height() -> int abstractmethod #

Get the maximum height of the widget.

_mgui_get_max_width() -> int abstractmethod #

Get the maximum width of the widget.

_mgui_get_min_height() -> int abstractmethod #

Get the minimum height of the widget.

_mgui_get_min_width() -> int abstractmethod #

Get the minimum width of the widget.

_mgui_get_native_widget() -> Any abstractmethod #

Return the native backend widget instance.

This is generally the widget that has the layout.

_mgui_get_parent() -> Widget abstractmethod #

Return the parent widget of this widget.

_mgui_get_root_native_widget() -> Any abstractmethod #

Return the root native backend widget.

In most cases, this is the same as _mgui_get_native_widget. However, in cases where the native widget is in a scroll layout, this might be different.

_mgui_get_tooltip() -> str abstractmethod #

Get the tooltip for this widget.

_mgui_get_visible() -> bool abstractmethod #

Get widget visibility.

_mgui_get_width() -> int abstractmethod #

Get the width of the widget.

The intention is to get the width of the widget after it is shown, for the purpose of unifying widget width in a layout. Backends may do what they need to accomplish this. For example, Qt can use sizeHint().width(), since width() may return something large if the widget has not yet been painted on screen.

_mgui_render() -> np.ndarray abstractmethod #

Return an RGBA (MxNx4) numpy array bitmap of the rendered widget.

_mgui_set_enabled(enabled: bool) -> None abstractmethod #

Set the enabled state of the widget to enabled.

_mgui_set_height(value: int) -> None abstractmethod #

Set the height of the widget.

_mgui_set_max_height(value: int) -> None abstractmethod #

Set the maximum height of the widget.

_mgui_set_max_width(value: int) -> None abstractmethod #

Set the maximum width of the widget.

_mgui_set_min_height(value: int) -> None abstractmethod #

Set the minimum height of the widget.

_mgui_set_min_width(value: int) -> None abstractmethod #

Set the minimum width of the widget.

_mgui_set_parent(widget: Widget) -> None abstractmethod #

Set the parent widget of this widget.

_mgui_set_tooltip(value: str | None) -> None abstractmethod #

Set a tooltip for this widget.

_mgui_set_visible(value: bool) -> None abstractmethod #

Set widget visibility.

_mgui_set_width(value: int) -> None abstractmethod #

Set the width of the widget.

magicgui.widgets.protocols.ValueWidgetProtocol #

Bases: WidgetProtocol, Protocol

Widget that has a current value, with getter/setter and on_change callback.

It is worth noting that the widget is the thing that has a value. Magicgui does not maintain & synchronize an independent model.

_mgui_bind_change_callback(callback: Callable[[Any], Any]) -> None abstractmethod #

Bind callback to value change event.

_mgui_get_value() -> Any abstractmethod #

Get current value of the widget.

_mgui_set_value(value: Any) -> None abstractmethod #

Set current value of the widget.

magicgui.widgets.protocols.ButtonWidgetProtocol #

Bases: ValueWidgetProtocol, SupportsText, SupportsIcon, Protocol

The "value" in a ButtonWidget is the current (checked) state.

magicgui.widgets.protocols.TableWidgetProtocol #

Bases: ValueWidgetProtocol, SupportsReadOnly, Protocol

ValueWidget subclass intended for 2D tabular data, with row & column headers.

_mgui_bind_change_callback(callback: Callable[[Any], Any]) -> None abstractmethod #

Bind callback to value change event.

_mgui_bind_column_headers_change_callback(callback: Callable[[Any], None]) -> None abstractmethod #

Bind callback to column headers change event.

_mgui_bind_row_headers_change_callback(callback: Callable[[Any], None]) -> None abstractmethod #

Bind callback to row headers change event.

_mgui_get_cell(row: int, col: int) -> Any abstractmethod #

Get current value of the widget.

_mgui_get_column_count() -> int abstractmethod #

Get the number of columns in the table.

_mgui_get_column_headers() -> tuple abstractmethod #

Get current column headers of the widget.

_mgui_get_row_count() -> int abstractmethod #

Get the number of rows in the table.

_mgui_get_row_headers() -> tuple abstractmethod #

Get current row headers of the widget.

_mgui_remove_column(column: int) -> None abstractmethod #

Remove column at index column.

_mgui_remove_row(row: int) -> None abstractmethod #

Remove row at index row.

_mgui_set_cell(row: int, col: int, value: Any) -> None abstractmethod #

Set current value of the widget.

_mgui_set_column_count(ncols: int) -> None abstractmethod #

Set the number of columns in the table. (Create/delete as needed).

_mgui_set_column_headers(headers: Sequence) -> None abstractmethod #

Set current column headers of the widget.

_mgui_set_row_count(nrows: int) -> None abstractmethod #

Set the number of rows in the table. (Create/delete as needed).

_mgui_set_row_headers(headers: Sequence) -> None abstractmethod #

Set current row headers of the widget.

magicgui.widgets.protocols.RangedWidgetProtocol #

Bases: ValueWidgetProtocol, Protocol

Value widget that supports numbers within a provided min/max range.

_mgui_get_adaptive_step() -> bool abstractmethod #

Get adaptive step status.

_mgui_get_max() -> float abstractmethod #

Get the maximum possible value.

_mgui_get_min() -> float abstractmethod #

Get the minimum possible value.

_mgui_get_step() -> float abstractmethod #

Get the step size.

_mgui_set_adaptive_step(value: bool) -> None abstractmethod #

Set adaptive step status.

_mgui_set_max(value: float) -> None abstractmethod #

Set the maximum possible value.

_mgui_set_min(value: float) -> None abstractmethod #

Set the minimum possible value.

_mgui_set_step(value: float) -> None abstractmethod #

Set the step size.

magicgui.widgets.protocols.CategoricalWidgetProtocol #

Bases: ValueWidgetProtocol, SupportsChoices, Protocol

Categorical widget, that has a set of valid choices, and a current value.

It adds no additional methods.

magicgui.widgets.protocols.SliderWidgetProtocol #

Bases: RangedWidgetProtocol, SupportsOrientation, Protocol

Protocol for implementing a slider widget.

_mgui_get_tracking() -> bool #

If tracking is False, changed is only emitted when released.

_mgui_set_readout_visibility(visible: bool) -> None #

Set visibility of readout widget.

_mgui_set_tracking(tracking: bool) -> None #

If tracking is False, changed is only emitted when released.

magicgui.widgets.protocols.ContainerProtocol #

Bases: WidgetProtocol, SupportsOrientation, Protocol

Widget that can contain other widgets.

This generally manages a backend Layout.

_mgui_get_margins() -> tuple[int, int, int, int] abstractmethod #

Get the margins of the container.

_mgui_insert_widget(position: int, widget: Widget) -> None abstractmethod #

Insert widget at the given position in the layout.

_mgui_remove_widget(widget: Widget) -> None abstractmethod #

Remove the specified widget.

_mgui_set_margins(margins: tuple[int, int, int, int]) -> None abstractmethod #

Set the margins of the container.

magicgui.widgets.protocols.DialogProtocol #

Bases: ContainerProtocol, Protocol

Protocol for modal (blocking) containers.

_mgui_exec() -> None abstractmethod #

Show the dialog and block.

magicgui.widgets.protocols.MainWindowProtocol #

Bases: ContainerProtocol, Protocol

Application main widget.

_mgui_create_menu_item(menu_name: str, action_name: str, callback: Callable | None = None, shortcut: str | None = None) -> None abstractmethod #

Create a new menu item.

Parameters:

  • menu_name (str) –

    The name of the menu to add the item to.

  • action_name (str) –

    The name of the action to add.

  • callback (Callable | None, default: None ) –

    A callback to be called when the action is triggered, by default None.

  • shortcut (str | None, default: None ) –

    A keyboard shortcut for the action, by default None.

magicgui.widgets.protocols.SupportsChoices #

Bases: Protocol

Widget that has a set of valid choices.

_mgui_del_choice(choice_name: str) -> None abstractmethod #

Delete the provided choice_name and associated data.

_mgui_get_choice(choice_name: str) -> Any abstractmethod #

Get data for a single choice.

_mgui_get_choices() -> tuple[tuple[str, Any], ...] abstractmethod #

Get available choices.

_mgui_get_count() -> int abstractmethod #

Return number of choices.

_mgui_get_current_choice() -> str abstractmethod #

Return the text of the currently selected choice.

_mgui_set_choice(choice_name: str, data: Any) -> None abstractmethod #

Set data for choice_name, or add a new item if choice_name doesn't exist.

_mgui_set_choices(choices: Iterable[tuple[str, Any]]) -> None abstractmethod #

Set available choices.

magicgui.widgets.protocols.SupportsOrientation #

Bases: Protocol

Widget that can be reoriented.

_mgui_get_orientation() -> str abstractmethod #

Get orientation, return either 'horizontal' or 'vertical'.

_mgui_set_orientation(value: str) -> None abstractmethod #

Set orientation, value will be 'horizontal' or 'vertical'.

magicgui.widgets.protocols.SupportsText #

Bases: Protocol

Widget that have text (in addition to value)... like buttons.

_mgui_get_text() -> str abstractmethod #

Get text.

_mgui_set_text(value: str) -> None abstractmethod #

Set text.

magicgui.widgets.protocols.SupportsReadOnly #

Bases: Protocol

Widget that can be read_only.

_mgui_get_read_only() -> bool abstractmethod #

Get read_only status.

_mgui_set_read_only(value: bool) -> None abstractmethod #

Set read_only.

Application Protocol#

magicgui.widgets.protocols.BaseApplicationBackend #

Bases: ABC

Backend Application object.

Abstract class that provides an interface between backends and Application. Each backend must implement a subclass of BaseApplicationBackend, and implement all of its _mgui_xxx methods.

_mgui_get_backend_name() -> str abstractmethod #

Return the name of the backend.

_mgui_get_native_app() -> Any abstractmethod #

Return the native GUI application instance.

_mgui_process_events() -> None abstractmethod #

Process all pending GUI events.

_mgui_quit() -> None abstractmethod #

Quit the native GUI event loop.

_mgui_run() -> None abstractmethod #

Start the application.

_mgui_start_timer(interval: int = 0, on_timeout: Callable[[], None] | None = None, single: bool = False) -> None abstractmethod #

Create and start a timer.

Parameters:

  • interval (int, default: 0 ) –

    Interval between timeouts, by default 0

  • on_timeout (Optional[Callable[[], None]], default: None ) –

    Function to call when timer finishes, by default None

  • single (bool, default: False ) –

    Whether the timer should only fire once, by default False

_mgui_stop_timer() -> None abstractmethod #

Stop timer. Should check for the existence of the timer.