Add initial documentation about widget communication #721

Czaki · 2025-05-25T17:37:12Z

References and relevant issues

Description

This PR adds documentation about possible way to communicate or share state between widgets.

psobolewskiPhD · 2025-05-25T20:50:04Z

docs/plugins/advanced_topics/widget_communication.md

+## Widget name 
+
+When widget is added to the viewer as plugin contribution (by using a menu or `add_plugin_dock_widget`), it is assigned a name.
+The name is created by concatenating the widget name and the plugin name in brackets, like this: `"widget_name (plugin_name)"`.


Suggested change

The name is created by concatenating the widget name and the plugin name in brackets, like this: `"widget_name (plugin_name)"`.

The name is created by concatenating the widget `display_name` from the plugin manifest and the plugin name in parenthesis, like this: `"Widget name (plugin_name)"`. Note: this is the same name that is shown in the napari menus and the title bar of the widget.

I was confused by the underscore, thinking it could be the Python name.

psobolewskiPhD · 2025-05-25T21:22:09Z

docs/plugins/advanced_topics/widget_communication.md

+### Warnings 
+
+Many plugins use the `viewer.window._dock_widgets` attribute to access `QtViewerDockWidget` widgets.
+It is an internal API and may stop working on any release 


Suggested change

### Warnings

Many plugins use the `viewer.window._dock_widgets` attribute to access `QtViewerDockWidget` widgets.

It is an internal API and may stop working on any release

```{important}

We don't recommend using the `viewer.window._dock_widgets` attribute to access `QtViewerDockWidget` widgets. This is a private, internal API and may stop working on any release. Please use the above described public API instead.

```

How about making this an admonition?

psobolewskiPhD

Really like this! Thank you for writing this up!
I made some small-ish suggestions.

willingc

Thanks @Czaki for adding this helpful documentation. I made a few suggestions for clarity.

willingc · 2025-05-27T22:33:24Z

docs/plugins/advanced_topics/widget_communication.md

@@ -0,0 +1,146 @@
+(widget-communication)=
+
+# Accessing docked widgets


Move to level ## and make title # Widget communication

willingc · 2025-05-27T22:39:07Z

docs/plugins/advanced_topics/widget_communication.md

+
+# Accessing docked widgets
+
+Sometimes more complex workflows require access to other docked widgets, sometimes from other plugins, created by other developers.


Suggested change

Sometimes more complex workflows require access to other docked widgets, sometimes from other plugins, created by other developers.

Sometimes complex workflows require access to other docked widgets, information from other plugins, which may be created by other developers.

willingc · 2025-05-27T22:44:01Z

docs/plugins/advanced_topics/widget_communication.md

+## Accessing plugin widgets `viewer.window.add_plugin_dock_widget`
+
+If a plugin widget is already docked in the viewer, 
+calling the `add_plugin_dock_widget` method will return the existing widget instance.
+
+This is the most convenient way to access a plugin widget that is required by your plugin.
+Because if the widget is absent, it will be created and added to the viewer.


Suggested change

## Accessing plugin widgets `viewer.window.add_plugin_dock_widget`

If a plugin widget is already docked in the viewer,

calling the `add_plugin_dock_widget` method will return the existing widget instance.

This is the most convenient way to access a plugin widget that is required by your plugin.

Because if the widget is absent, it will be created and added to the viewer.

## Access another plugin widget with `viewer.window.add_plugin_dock_widget`

If a desired plugin widget is already docked in the viewer,

calling the `add_plugin_dock_widget` method will return the existing widget instance.

If the desired widget is absent, it will be created and added to the viewer.

`add_plugin_dock_widget` is the most convenient way to access a plugin widget that is required by your plugin.

willingc · 2025-05-27T22:48:06Z

docs/plugins/advanced_topics/widget_communication.md

+## Accessing widget by name `viewer.window.get_dock_widget`
+
+If you need to access a widget, but without creating it, you can use the `get_dock_widget` method.
+The `get_dock_widget` method allows you to retrieve a docked widget by its name.
+
+This method returns the `QtViewerDockWidget` associated with the widget, or `None` if the widget is not found.
+
+To access the original widget, you can use the `inner_widget` method of the `QtViewerDockWidget`.
+
+This method allows accessing non-plugin widgets added to viewer using the `add_dock_widget` method.
+
+
+*The `get_dock_widget` and `inner_widget` were added in napari 0.6.2.*


Suggested change

## Accessing widget by name `viewer.window.get_dock_widget`

If you need to access a widget, but without creating it, you can use the `get_dock_widget` method.

The `get_dock_widget` method allows you to retrieve a docked widget by its name.

This method returns the `QtViewerDockWidget` associated with the widget, or `None` if the widget is not found.

To access the original widget, you can use the `inner_widget` method of the `QtViewerDockWidget`.

This method allows accessing non-plugin widgets added to viewer using the `add_dock_widget` method.

*The `get_dock_widget` and `inner_widget` were added in napari 0.6.2.*

## Access a widget by name with `viewer.window.get_dock_widget`

If access a target widget, but without creating it, use the `get_dock_widget` method.

The `get_dock_widget` method returns a docked widget by its name.

This method returns the `QtViewerDockWidget` associated with the widget, or `None` if the widget is not found or does not exist.

To access the target widget, you can use the `inner_widget` method of the `QtViewerDockWidget`.

This method allows accessing non-plugin widgets added to viewer using the `add_dock_widget` method.

*The `get_dock_widget` and `inner_widget` were added in napari 0.6.2.*

willingc · 2025-05-27T22:49:36Z

docs/plugins/advanced_topics/widget_communication.md

+
+### Warnings 
+
+Many plugins use the `viewer.window._dock_widgets` attribute to access `QtViewerDockWidget` widgets.


Suggested change

Many plugins use the `viewer.window._dock_widgets` attribute to access `QtViewerDockWidget` widgets.

Many plugins use the private `viewer.window._dock_widgets` attribute to access `QtViewerDockWidget` widgets.

willingc · 2025-05-27T22:51:47Z

docs/plugins/advanced_topics/widget_communication.md

+
+## Shared state between widgets
+
+If you need for multiple widgets to share the state, you can use a shared global object.


Suggested change

If you need for multiple widgets to share the state, you can use a shared global object.

If you need for multiple widgets to share state, you can use a shared global object.

willingc · 2025-05-27T22:53:24Z

docs/plugins/advanced_topics/widget_communication.md

+    return GLOBAL_STATE[viewer]
+```
+
+To store state between sessions, you can enhance the `get_global_state` to load state from drive or database.


Suggested change

To store state between sessions, you can enhance the `get_global_state` to load state from drive or database.

To store state between sessions, you can enhance the `get_global_state` to load state from persistent storage, such as a drive or database.

willingc · 2025-05-27T22:54:18Z

docs/plugins/advanced_topics/widget_communication.md

+
+
+def save_global_state(event):
+    """Save the global state to a file."""    # Serialize the state to a file


Suggested change

"""Save the global state to a file.""" # Serialize the state to a file

"""Save the global state by serializing it to a file."""

Add initial documentation about widget communication

88d835d

Czaki added this to the 0.6.2 milestone May 25, 2025

Czaki added the documentation Improvements or additions to documentation label May 25, 2025

github-actions bot assigned Czaki May 25, 2025

psobolewskiPhD reviewed May 25, 2025

View reviewed changes

psobolewskiPhD approved these changes May 25, 2025

View reviewed changes

willingc approved these changes May 27, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add initial documentation about widget communication #721

Add initial documentation about widget communication #721

Uh oh!

Czaki commented May 25, 2025

Uh oh!

psobolewskiPhD May 25, 2025 •

edited

Loading

Uh oh!

psobolewskiPhD May 25, 2025

Uh oh!

psobolewskiPhD left a comment

Uh oh!

willingc left a comment

Uh oh!

willingc May 27, 2025

Uh oh!

willingc May 27, 2025

Uh oh!

willingc May 27, 2025

Uh oh!

willingc May 27, 2025

Uh oh!

willingc May 27, 2025

Uh oh!

willingc May 27, 2025

Uh oh!

willingc May 27, 2025

Uh oh!

willingc May 27, 2025

Uh oh!

Uh oh!

	The name is created by concatenating the widget name and the plugin name in brackets, like this: `"widget_name (plugin_name)"`.
	The name is created by concatenating the widget `display_name` from the plugin manifest and the plugin name in parenthesis, like this: `"Widget name (plugin_name)"`. Note: this is the same name that is shown in the napari menus and the title bar of the widget.

		@@ -0,0 +1,146 @@
		(widget-communication)=

		# Accessing docked widgets


		# Accessing docked widgets

		Sometimes more complex workflows require access to other docked widgets, sometimes from other plugins, created by other developers.

	Sometimes more complex workflows require access to other docked widgets, sometimes from other plugins, created by other developers.
	Sometimes complex workflows require access to other docked widgets, information from other plugins, which may be created by other developers.


		### Warnings

		Many plugins use the `viewer.window._dock_widgets` attribute to access `QtViewerDockWidget` widgets.

	Many plugins use the `viewer.window._dock_widgets` attribute to access `QtViewerDockWidget` widgets.
	Many plugins use the private `viewer.window._dock_widgets` attribute to access `QtViewerDockWidget` widgets.


		## Shared state between widgets

		If you need for multiple widgets to share the state, you can use a shared global object.

	To store state between sessions, you can enhance the `get_global_state` to load state from drive or database.
	To store state between sessions, you can enhance the `get_global_state` to load state from persistent storage, such as a drive or database.



		def save_global_state(event):
		"""Save the global state to a file.""" # Serialize the state to a file

	"""Save the global state to a file.""" # Serialize the state to a file
	"""Save the global state by serializing it to a file."""

Add initial documentation about widget communication #721

Are you sure you want to change the base?

Add initial documentation about widget communication #721

Uh oh!

Conversation

Czaki commented May 25, 2025

References and relevant issues

Description

Uh oh!

psobolewskiPhD May 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

psobolewskiPhD left a comment

Choose a reason for hiding this comment

Uh oh!

willingc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

psobolewskiPhD May 25, 2025 •

edited

Loading