feat: add request_values convenience, shows modal dialog to request values (#416)

* feat: add show_values_dialog

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix test

* add docstring

* prevent dialog show in tests

* fix test

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: tlambert03

examples/values_dialog.py

@@ -0,0 +1,8 @@
+from magicgui.widgets import request_values
+
+vals = request_values(
+    age=int,
+    name=dict(annotation=str, label="Enter your name:"),
+    title="Hi, who are you?",
+)
+print(repr(vals))

magicgui/backends/_qtpy/__init__.py

@@ -5,6 +5,7 @@
     Container,
     DateEdit,
     DateTimeEdit,
+    Dialog,
     EmptyWidget,
     FloatSlider,
     FloatSpinBox,
@@ -34,6 +35,7 @@
     "Container",
     "DateEdit",
     "DateTimeEdit",
+    "Dialog",
     "EmptyWidget",
     "FloatSlider",
     "FloatSpinBox",

magicgui/backends/_qtpy/widgets.py

@@ -1025,6 +1025,52 @@ def _mgui_get_value(self):
             return self._qwidget.time().toPyTime()
 
 
+class Dialog(QBaseWidget, _protocols.ContainerProtocol):
+    def __init__(self, layout="vertical", **k):
+        QBaseWidget.__init__(self, QtW.QDialog)
+        if layout == "horizontal":
+            self._layout: QtW.QBoxLayout = QtW.QHBoxLayout()
+        else:
+            self._layout = QtW.QVBoxLayout()
+        self._qwidget.setLayout(self._layout)
+        self._layout.setSizeConstraint(QtW.QLayout.SizeConstraint.SetMinAndMaxSize)
+
+        button_box = QtW.QDialogButtonBox(
+            QtW.QDialogButtonBox.StandardButton.Ok
+            | QtW.QDialogButtonBox.StandardButton.Cancel,
+            Qt.Orientation.Horizontal,
+            self._qwidget,
+        )
+        button_box.accepted.connect(self._qwidget.accept)
+        button_box.rejected.connect(self._qwidget.reject)
+        self._layout.addWidget(button_box)
+
+    def _mgui_insert_widget(self, position: int, widget: Widget):
+        self._layout.insertWidget(position, widget.native)
+
+    def _mgui_remove_widget(self, widget: Widget):
+        self._layout.removeWidget(widget.native)
+        widget.native.setParent(None)
+
+    def _mgui_get_margins(self) -> tuple[int, int, int, int]:
+        m = self._layout.contentsMargins()
+        return m.left(), m.top(), m.right(), m.bottom()
+
+    def _mgui_set_margins(self, margins: tuple[int, int, int, int]) -> None:
+        self._layout.setContentsMargins(*margins)
+
+    def _mgui_set_orientation(self, value) -> None:
+        """Set orientation, value will be 'horizontal' or 'vertical'."""
+        raise NotImplementedError("Setting orientation not supported for dialogs.")
+
+    def _mgui_get_orientation(self) -> str:
+        """Set orientation, return either 'horizontal' or 'vertical'."""
+        return "horizontal" if isinstance(self, QtW.QHBoxLayout) else "vertical"
+
+    def _mgui_exec(self) -> Any:
+        return self._qwidget.exec_()
+
+
 QFILE_DIALOG_MODES = {
     FileDialogMode.EXISTING_FILE: QtW.QFileDialog.getOpenFileName,
     FileDialogMode.EXISTING_FILES: QtW.QFileDialog.getOpenFileNames,

magicgui/widgets/__init__.py

@@ -18,6 +18,7 @@
     Container,
     DateEdit,
     DateTimeEdit,
+    Dialog,
     EmptyWidget,
     FileEdit,
     FloatSlider,
@@ -41,7 +42,7 @@
     TimeEdit,
     TupleEdit,
 )
-from ._dialogs import show_file_dialog
+from ._dialogs import request_values, show_file_dialog
 from ._function_gui import FunctionGui, MainFunctionGui
 from ._image import Image
 from ._table import Table
@@ -71,6 +72,7 @@
     "create_widget",
     "DateEdit",
     "DateTimeEdit",
+    "Dialog",
     "EmptyWidget",
     "FileEdit",
     "FloatSlider",
@@ -99,6 +101,7 @@
     "TupleEdit",
     "Widget",
     "show_file_dialog",
+    "request_values",
 ]
 
 del partial

magicgui/widgets/_bases/container_widget.py

@@ -285,6 +285,12 @@ def labels(self, value: bool):
 
     NO_VALUE = "NO_VALUE"
 
+    def asdict(self) -> dict[str, Any]:
+        """Return state of widget as dict."""
+        return {
+            w.name: getattr(w, "value", None) for w in self if w.name and not w.gui_only
+        }
+
     @debounce
     def _dump(self, path):
         """Dump the state of the widget to `path`."""
@@ -336,3 +342,16 @@ def create_menu_item(
         ``menu_name`` will be created if it does not already exist.
         """
         self._widget._mgui_create_menu_item(menu_name, item_name, callback, shortcut)
+
+
+class DialogWidget(ContainerWidget):
+    """Modal Container."""
+
+    _widget: _protocols.DialogProtocol
+
+    def exec(self) -> bool:
+        """Show the dialog, and block.
+
+        Return True if the dialog was accepted, False if rejected.
+        """
+        return bool(self._widget._mgui_exec())

magicgui/widgets/_concrete.py

@@ -19,6 +19,7 @@
 from magicgui.application import use_app
 from magicgui.types import FileDialogMode, PathLike, WidgetOptions
 from magicgui.widgets import _protocols
+from magicgui.widgets._bases.container_widget import DialogWidget
 from magicgui.widgets._bases.mixins import _OrientationMixin, _ReadOnlyMixin
 
 from ._bases import (
@@ -414,6 +415,11 @@ class Container(ContainerWidget):
     """A Widget to contain other widgets."""
 
 
+@backend_widget
+class Dialog(DialogWidget):
+    """A modal container."""
+
+
 @backend_widget
 class MainWindow(MainWindowWidget):
     """A Widget to contain other widgets."""

magicgui/widgets/_dialogs.py

@@ -1,6 +1,9 @@
-from typing import Optional, Union
+from typing import Any, Dict, Hashable, Iterable, Mapping, Optional, Tuple, Type, Union
 
 from magicgui.types import FileDialogMode
+from magicgui.widgets._bases.create_widget import create_widget
+
+from ._concrete import Dialog
 
 
 def show_file_dialog(
@@ -41,3 +44,69 @@ def show_file_dialog(
     app = use_app()
     assert app.native
     return app.get_obj("show_file_dialog")(mode, caption, start_path, filter, parent)
+
+
+def request_values(
+    values: Union[Mapping, Iterable[Tuple[Hashable, Any]]] = (),
+    *,
+    title: str = "",
+    **kwargs: Union[Type, Dict]
+) -> Optional[Dict[str, Any]]:
+    """Show a dialog with a set of values and request the user to enter them.
+
+    Dialog is modal and immediately blocks execution until user closes it.
+    If the dialog is accepted, the values are returned as a dictionary, otherwise
+    returns `None`.
+
+    See also the docstring of :func:`magicgui.widgets.create_widget` for more
+    information.
+
+    Parameters
+    ----------
+    values : Union[Mapping, Iterable[Tuple[Hashable, Any]]], optional
+        A mapping of name to arguments to create_widget.  Values can be a dict, in which
+        case they are kwargs to `create_widget`, or a single value, in which case it is
+        interpreted as the `annotation` in `create_widget`, by default ()
+    title : str
+        An optional label to put at the top., by default ""
+    **kwargs : Union[Type, Dict]
+        Additional keyword arguments are used as name -> annotation arguments to
+        `create_widget`.
+
+    Returns
+    -------
+    Optional[Dict[str, Any]]
+        Dictionary of values if accepted, or `None` if canceled.
+
+    Examples
+    --------
+    >>> from magicgui.widgets import request_values
+
+    >>> request_values(age=int, name=str, title="Hi! Who are you?")
+
+    >>> request_values(
+    ...     age=dict(value=40),
+    ...     name=dict(annotation=str, label="Enter your name:"),
+    ...     title="Hi! Who are you?"
+    ... )
+
+    >>> request_values(
+    ...     values={'age': int, 'name': str},
+    ...     title="Hi! Who are you?"
+    ... )
+    """
+    widgets = []
+    if title:
+        from . import Label
+
+        widgets.append(Label(value=title))
+
+    for key, val in dict(values, **kwargs).items():
+        kwargs = val if isinstance(val, dict) else dict(annotation=val)
+        kwargs.setdefault("name", key)
+        widgets.append(create_widget(**kwargs))  # type: ignore
+
+    d = Dialog(widgets=widgets)
+    if d.exec():
+        return d.asdict()
+    return None

magicgui/widgets/_function_gui.py

@@ -335,12 +335,6 @@ def __repr__(self) -> str:
         """Return string representation of instance."""
         return f"<{type(self).__name__} {self._callable_name}{self.__signature__}>"
 
-    def asdict(self) -> dict[str, Any]:
-        """Return state of widget as dict."""
-        return {
-            w.name: getattr(w, "value", None) for w in self if w.name and not w.gui_only
-        }
-
     def update(
         self,
         mapping: Mapping | Iterable[tuple[str, Any]] | None = None,

magicgui/widgets/_protocols.py

@@ -461,6 +461,15 @@ def _mgui_set_margins(self, margins: tuple[int, int, int, int]) -> None:
         raise NotImplementedError()
 
 
+class DialogProtocol(ContainerProtocol, Protocol):
+    """Protocol for modal (blocking) containers."""
+
+    @abstractmethod
+    def _mgui_exec(self):
+        """Show the dialog and block."""
+        raise NotImplementedError()
+
+
 class MainWindowProtocol(ContainerProtocol, Protocol):
     """Application main widget."""
 

tests/test_docs.py

@@ -40,11 +40,18 @@ def test_doc_code_cells(fname, globalns=globals()):
 @pytest.mark.parametrize(
     "fname", [f for f in glob("examples/*.py") if "napari" not in f]
 )
-def test_examples(fname):
+def test_examples(fname, monkeypatch):
     """Make sure that all code cells in documentation perform as expected."""
     if "table.py" in fname and os.name == "nt" and sys.version_info < (3, 8):
         pytest.mark.skip()
         return
+    if "values_dialog" in str(fname):
+        from magicgui.backends._qtpy.widgets import QtW  # type: ignore
+
+        try:
+            monkeypatch.setattr(QtW.QDialog, "exec", lambda s: None)
+        except AttributeError:
+            monkeypatch.setattr(QtW.QDialog, "exec_", lambda s: None)
     app = use_app()
     app.start_timer(50 if "table" in str(fname) else 5, app.quit)
     try:

tests/test_widgets.py

@@ -23,6 +23,7 @@
             "FunctionGui",
             "MainFunctionGui",
             "show_file_dialog",
+            "request_values",
         )
     ],
 )