bootstack 0.2.3__tar.gz → 0.3.0__tar.gz

{bootstack-0.2.3/src/bootstack.egg-info → bootstack-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bootstack
-Version: 0.2.3
+Version: 0.3.0
 Summary: Build desktop GUI apps in pure Python and ship them as a standalone executable — built on Tk, no Tkinter boilerplate.
 Author-email: Israel Dryer <israel.dryer@gmail.com>
 License-Expression: MIT

{bootstack-0.2.3 → bootstack-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "bootstack"
-version = "0.2.3"
+version = "0.3.0"
 description = "Build desktop GUI apps in pure Python and ship them as a standalone executable — built on Tk, no Tkinter boilerplate."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -114,7 +114,7 @@ where = ["src"]
 ]
 
 [tool.bumpversion]
-current_version = "0.2.3"
+current_version = "0.3.0"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)((?P<pre>a|b|rc)(?P<pre_n>\\d+))?"
 serialize = [
     "{major}.{minor}.{patch}{pre}{pre_n}",

bootstack-0.3.0/src/bootstack/_core/capture.py

@@ -0,0 +1,449 @@
+"""Screen-region capture backing the public `widget.capture()`.
+
+A capture reads pixels from the display, so the region has to be visible:
+the widget must be on screen, and anything drawn over it is captured along
+with it. There is no offscreen rendering path — the toolkit does not offer
+one — which is why the public method requires a visible widget.
+
+Capture uses Pillow's `ImageGrab`, falling back to a desktop screenshot tool
+on Linux sessions where `ImageGrab` is unavailable (Wayland, or a Pillow
+built without XCB support).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+import tkinter
+from pathlib import Path
+
+from PIL import Image, ImageGrab
+
+from bootstack.errors import BootstackError
+
+try:
+    from screeninfo import get_monitors
+    HAS_SCREENINFO = True
+except ImportError:
+    HAS_SCREENINFO = False
+
+# Platforms whose capture backend ships with the operating system. There is
+# nothing to install and nothing to fall back to, so a failure here is a real
+# failure rather than a missing-backend one.
+_BUILTIN_BACKEND_PLATFORMS = ("win32", "darwin")
+
+# How long to pause between event-loop turns while settling. Short enough to
+# stay responsive to the repaint we are waiting for, long enough not to spin.
+_SETTLE_TICK = 0.01
+
+# Formats that store plain color and nothing else. A capture bound for one of
+# these is converted first, because saving an image that carries transparency
+# — or a color palette — as JPEG fails outright.
+_NO_ALPHA_FORMATS = {".jpg", ".jpeg", ".pdf", ".bmp"}
+
+# Image modes those formats accept as they are.
+_PLAIN_COLOR_MODES = ("RGB", "L")
+
+# Tried in order, first one installed wins.
+_SUBPROCESS_BACKENDS = (
+    ("grim", ["grim", "{out}"]),                                    # wlroots, Sway
+    ("gnome-screenshot", ["gnome-screenshot", "-f", "{out}"]),
+    # `-f` asks for the full screen. Without it spectacle repeats whatever
+    # capture mode it was last used with, which is remembered in its own
+    # config — so the same call photographs the desktop on one machine and a
+    # single window on the next.
+    ("spectacle", ["spectacle", "-b", "-n", "-f", "-o", "{out}"]),  # KDE
+    ("import", ["import", "-window", "root", "{out}"]),             # ImageMagick
+)
+
+# Platforms where cutting the region has to stay `ImageGrab`'s job, because it
+# needs detail this module does not have. Windows crops against the origin its
+# own grab reports, which cannot be reconstructed from a rectangle alone; macOS
+# asks `screencapture` for the region and rescales the answer, which is what
+# keeps the result aligned on a Retina display. Cutting the region here would
+# discard both.
+#
+# This says which code owns the crop, not that the crop is checked — neither of
+# those is. Windows pads a region reaching past the grabbed desktop with black,
+# and macOS stretches a region the system clamped. Extending the bounds check to
+# them is a separate change, and one no box available here can verify.
+#
+# Everywhere else — Linux — `ImageGrab` grabs the whole desktop and crops it
+# with no check that it covers the region, padding the difference with black
+# and raising nothing. That is the failure `_crop_desktop` refuses, so there
+# the region is cut here rather than by the library.
+_LIBRARY_REGION_PLATFORMS = ("win32", "darwin")
+_LIBRARY_HANDLES_REGION = sys.platform in _LIBRARY_REGION_PLATFORMS
+
+
+def widget_region(tk_widget, inset: int = 0) -> tuple[int, int, int, int]:
+    """Return a widget's on-screen rectangle as `(left, top, right, bottom)`.
+
+    Coordinates span the whole virtual desktop, so a widget on a monitor
+    placed to the left of, or above, the primary one has a negative origin.
+
+    Args:
+        tk_widget: The toolkit widget to measure.
+        inset: Pixels to trim from every edge. Zero or more.
+    """
+    if inset < 0:
+        raise BootstackError(
+            f"inset={inset} is negative. An inset trims pixels from every "
+            f"edge, so it cannot reach past the widget onto its neighbors."
+        )
+    x, y = tk_widget.winfo_rootx(), tk_widget.winfo_rooty()
+    width, height = tk_widget.winfo_width(), tk_widget.winfo_height()
+    left, top = x + inset, y + inset
+    right, bottom = x + width - inset, y + height - inset
+    if right <= left or bottom <= top:
+        raise BootstackError(
+            f"inset={inset} trims away the whole capture — the widget is only "
+            f"{width}x{height} pixels."
+        )
+    return (left, top, right, bottom)
+
+
+def still_exists(tk_widget) -> bool:
+    """Whether a widget is still alive, without leaking a toolkit error.
+
+    `winfo_exists()` reports 0 for a destroyed child but RAISES for a destroyed
+    root — the toolkit has no interpreter left to ask by then. Both mean the
+    same thing to a caller, so both answer False here.
+    """
+    try:
+        return bool(tk_widget.winfo_exists())
+    except tkinter.TclError:
+        return False
+
+
+def clipped_out_of_view(tk_widget) -> bool:
+    """Whether a widget's rectangle has left its own window entirely.
+
+    A widget scrolled out of a viewport stays MAPPED — the toolkit reports
+    `winfo_ismapped()` and `winfo_viewable()` as 1 for a row that is nowhere
+    near the visible area — while `winfo_rooty()` keeps reporting where the row
+    would be if the window were tall enough to show it. Measured: a row in a
+    scrolled list reported y=273 for a window spanning 390 to 630.
+
+    Capturing that rectangle photographs whatever else is on screen there and
+    saves it without complaint, which is the one outcome this module exists to
+    prevent. Only a rectangle that has left the window completely is refused;
+    a row half out of view still captures, matching the rule that a capture
+    shows what the screen shows.
+    """
+    top = tk_widget.winfo_toplevel()
+    if tk_widget is top:
+        return False
+
+    left, top_y = tk_widget.winfo_rootx(), tk_widget.winfo_rooty()
+    right = left + tk_widget.winfo_width()
+    bottom = top_y + tk_widget.winfo_height()
+
+    win_left, win_top = top.winfo_rootx(), top.winfo_rooty()
+    win_right = win_left + top.winfo_width()
+    win_bottom = win_top + top.winfo_height()
+
+    return not (
+        left < win_right and right > win_left
+        and top_y < win_bottom and bottom > win_top
+    )
+
+
+@contextlib.contextmanager
+def raised(tk_widget):
+    """Hold a widget's window at the front for the duration of a capture.
+
+    A capture reads whatever is on the display, so a window sitting over the
+    target is captured instead of it — silently, and with a plausible-looking
+    image to show for it. Raising the window first is what makes the result
+    mean what the caller asked for.
+
+    The previous always-on-top setting is restored on the way out, and left
+    alone entirely if it was already set, so a window the application
+    deliberately pinned on top does not get un-pinned by taking a picture.
+    """
+    top = tk_widget.winfo_toplevel()
+    try:
+        top.lift()
+    except tkinter.TclError:
+        pass
+
+    # None means "left alone" — either the setting could not be read, or the
+    # window manager does not support it. Some Linux window managers do not,
+    # and a capture must not fail just because it cannot pin a window.
+    was_topmost = None
+    try:
+        was_topmost = bool(top.attributes("-topmost"))
+        if not was_topmost:
+            top.attributes("-topmost", True)
+    except tkinter.TclError:
+        was_topmost = None
+
+    try:
+        yield
+    finally:
+        # Restore only what this function actually changed.
+        if was_topmost is False:
+            try:
+                top.attributes("-topmost", False)
+            except tkinter.TclError:
+                pass
+
+
+def settle(tk_widget, seconds: float) -> None:
+    """Let pending redraws finish before the pixels are read.
+
+    Waits `seconds` while the event loop turns, so the desktop can repaint
+    the area behind any window that has just closed — a save dialog, most
+    commonly.
+
+    The wait has to dispatch events. Flushing our own drawing is not enough:
+    the area a closing window uncovers is repainted by the desktop, and on
+    macOS that repaint does not happen at all unless the loop is turning. A
+    capture taken without it photographs the dialog that was just dismissed
+    rather than the widget underneath.
+
+    Dispatching brings its own problem, which is why the window is held busy
+    for the duration. Turning the loop runs everything queued, including a
+    second click on the button that started the capture: that click would
+    re-enter the caller's handler, opening a second save dialog on top of the
+    first and starting an overlapping capture, none of which the person
+    clicking asked for. `tk busy` routes that click to a blocking window
+    instead.
+
+    ⚠ THE HOLD IS BEST-EFFORT, AND ON macOS IT DOES NOTHING. Aqua reports the
+    hold as successful and never maps the window it created: `tk busy status`
+    returns 1 while the busy window sits at `winfo_ismapped() == 0`, and Tk's
+    own hit test at the button's position still resolves to the button. So a
+    real click re-enters the handler there — confirmed by hand, since a
+    synthesized click cannot test this. Measured on Tk 8.6.17 in plain
+    tkinter, so it is the toolkit rather than anything above it. X11 and Win32
+    map the window and are expected to honor it;
+    `development/probe_429_busy_during_settle.py` reports which a given box
+    does.
+
+    The wait dispatches either way. A correct picture is worth more than a
+    stray click: without dispatching, the capture reads pixels that are simply
+    wrong, and that is the failure this function exists to prevent.
+
+    Args:
+        tk_widget: Any widget; its root window is the one flushed.
+        seconds: How long to wait for. Zero flushes without waiting.
+    """
+    root = tk_widget._root()
+    root.update_idletasks()
+    with _input_blocked(tk_widget):
+        deadline = time.perf_counter() + max(seconds, 0.0)
+        while time.perf_counter() < deadline:
+            root.update()
+            # Yield the processor rather than spinning on update() alone.
+            time.sleep(_SETTLE_TICK)
+        # Once more after the wait, so anything the pause allowed to arrive
+        # is drawn before the pixels are read.
+        root.update()
+    root.update_idletasks()
+
+
+@contextlib.contextmanager
+def _input_blocked(tk_widget):
+    """Route input away from a window while the event loop is being turned.
+
+    Yields either way: a window that cannot be held busy is still captured,
+    just without the protection from a stray click.
+
+    ⚠ Yielding `True` means the hold was ACCEPTED, not that input is actually
+    blocked — macOS accepts it and does not map the busy window. See `settle`.
+
+    ⚠ The target may already be DEAD by the time this runs — settling flushes
+    pending drawing first, and idle work queued before the capture can destroy
+    it. Asking a destroyed widget for its toplevel raises a raw `TclError`,
+    which would escape a method documented to raise `BootstackError` and
+    pre-empt the guard that reports the closure properly. So the lookup is
+    guarded too, not just the `tk busy` calls.
+    """
+    top = None
+    held = False
+    try:
+        top = tk_widget.winfo_toplevel()
+        top.tk.call("tk", "busy", "hold", top._w)
+        held = True
+    except tkinter.TclError:
+        held = False
+    try:
+        yield held
+    finally:
+        if held and top is not None:
+            try:
+                top.tk.call("tk", "busy", "forget", top._w)
+            except tkinter.TclError:
+                pass
+
+
+def capture_region(bbox: tuple[int, int, int, int], path) -> Path:
+    """Grab one screen region and write it to `path`, returning the path."""
+    return save(grab(bbox), path)
+
+
+def grab(bbox: tuple[int, int, int, int] | None = None) -> Image.Image:
+    """Grab a screen region, or the whole primary display when `bbox` is None."""
+    try:
+        if _LIBRARY_HANDLES_REGION:
+            # `all_screens` widens the grab to the whole virtual desktop.
+            # Without it, a region on a monitor left of or above the primary
+            # one is cropped out of a primary-only grab and comes back
+            # silently BLACK — no exception raised and nothing to debug.
+            return ImageGrab.grab(bbox=bbox, all_screens=bbox is not None)
+        # Grab the whole desktop and cut the region out below, under the
+        # bounds check. This platform grabs everything and crops either way,
+        # so what changes is where the crop happens, not how much is read.
+        image = ImageGrab.grab()
+    except (OSError, NotImplementedError) as exc:
+        # Diagnosis happens only AFTER a failed grab, never before one, so
+        # nothing here can reject a capture that would have worked.
+        #
+        # The catch is deliberately wide because the failures it has to cover
+        # are: no ImageGrab on this build at all, and a grab that ran and came
+        # back with nothing usable. Those need opposite answers, and the
+        # exception type cannot tell them apart — Pillow reports a region no
+        # display covers as `UnidentifiedImageError`, which IS an `OSError`.
+        if bbox is not None and _covered_by_a_display(bbox) is False:
+            raise BootstackError(
+                f"The area being captured — ({bbox[0]}, {bbox[1]}) to "
+                f"({bbox[2]}, {bbox[3]}) — is not on any display, so there are "
+                f"no pixels to read. A window moved off the edge of the screen, "
+                f"or a widget scrolled out of view, is the usual cause."
+            ) from exc
+
+        if sys.platform in _BUILTIN_BACKEND_PLATFORMS:
+            # Falling through to the subprocess chain here would end in advice
+            # to install Linux screenshot tools on a machine that already has a
+            # working backend — wrong on its face and no help in fixing this.
+            raise BootstackError(
+                f"The screen capture failed — {exc}. The window may have been "
+                f"hidden or moved while the picture was being taken."
+            ) from exc
+
+        # Wayland, or a Pillow built without XCB.
+        return _grab_via_subprocess(bbox)
+    # Outside the `except` on purpose: a region the grab missed is a capture
+    # failure to report, not a reason to try another backend.
+    return _crop_desktop(image, bbox) if bbox else image
+
+
+def _covered_by_a_display(bbox: tuple[int, int, int, int]) -> bool | None:
+    """Whether any monitor covers part of `bbox`.
+
+    Returns None when the question cannot be answered — no `screeninfo`, or it
+    could not read the display layout — so a caller can tell "definitely not on
+    a display" apart from "could not tell", and only act on the former.
+
+    Partial overlap counts as covered. A window hanging off the bottom edge of
+    the screen captures perfectly well; only a region no monitor touches at all
+    has nothing to read.
+    """
+    if not HAS_SCREENINFO:
+        return None
+
+    left, top, right, bottom = bbox
+    try:
+        monitors = get_monitors()
+    except Exception:  # noqa: BLE001 - a diagnostic must not raise its own error
+        return None
+    if not monitors:
+        return None
+
+    return any(
+        left < m.x + m.width and right > m.x
+        and top < m.y + m.height and bottom > m.y
+        for m in monitors
+    )
+
+
+def save(image: Image.Image, path) -> Path:
+    """Write an image to `path`, taking the format from its extension."""
+    path = Path(path)
+    # Decided by the target format rather than one source mode: a desktop
+    # screenshot tool can hand back a palette or grayscale-with-alpha image,
+    # and those fail on the same formats RGBA does.
+    if (
+        path.suffix.lower() in _NO_ALPHA_FORMATS
+        and image.mode not in _PLAIN_COLOR_MODES
+    ):
+        image = image.convert("RGB")
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        image.save(path)
+    except (OSError, ValueError, KeyError) as exc:
+        raise BootstackError(
+            f"Could not save the capture to '{path}' — {exc}. The file "
+            f"extension selects the format; '.png', '.jpg', and '.pdf' are "
+            f"the usual choices."
+        ) from exc
+    return path
+
+
+def _grab_via_subprocess(
+    bbox: tuple[int, int, int, int] | None = None,
+) -> Image.Image:
+    """Capture through a desktop screenshot tool, for Linux without ImageGrab."""
+    for name, argv in _SUBPROCESS_BACKENDS:
+        if not shutil.which(name):
+            continue
+        # A unique name per call — a fixed one collides when two captures
+        # overlap, and the loser silently reads the other's pixels.
+        handle, tmp_name = tempfile.mkstemp(
+            prefix="bootstack-capture-", suffix=".png"
+        )
+        os.close(handle)
+        tmp = Path(tmp_name)
+        try:
+            subprocess.run(
+                [arg.format(out=tmp) for arg in argv],
+                check=True,
+                capture_output=True,
+                timeout=30,
+            )
+            with Image.open(tmp) as opened:
+                opened.load()
+                image = opened.copy()
+        except (subprocess.SubprocessError, OSError):
+            continue
+        finally:
+            tmp.unlink(missing_ok=True)
+        return _crop_desktop(image, bbox) if bbox else image
+
+    raise BootstackError(
+        "No screen capture backend is available. Install a Pillow build with "
+        "XCB support, or one of: grim, gnome-screenshot, spectacle, import."
+    )
+
+
+def _crop_desktop(
+    image: Image.Image, bbox: tuple[int, int, int, int]
+) -> Image.Image:
+    """Cut a region out of a whole-desktop grab, refusing a region it misses.
+
+    A whole-desktop grab returns an image measured from whatever its source
+    treats as the origin, while the region is measured across the whole virtual
+    desktop. Those agree on an ordinary single-monitor session and can disagree
+    otherwise — most often when the window sits on a monitor the grab did not
+    cover. Cropping past the edge of an image pads the result with black rather
+    than failing, so the caller would get a plausible-looking all-black picture
+    and no way to tell why. Raising is the better answer.
+    """
+    left, top, right, bottom = bbox
+    if left < 0 or top < 0 or right > image.width or bottom > image.height:
+        raise BootstackError(
+            f"The screen capture returned a {image.width}x{image.height} "
+            f"picture, which does not cover the area being captured — "
+            f"({left}, {top}) to ({right}, {bottom}). Either the window is "
+            f"hanging off the edge of the screen, or it is on a display the "
+            f"capture did not reach. Moving it fully onto the main display "
+            f"resolves both."
+        )
+    return image.crop(bbox)

{bootstack-0.2.3 → bootstack-0.3.0}/src/bootstack/dialogs/__init__.py

@@ -436,7 +436,12 @@ class FormDialog:
         on_close: Callback fired when the dialog closes by any means.
         width: Explicit form width in pixels.
         height: Explicit form height in pixels.
-        buttons: Footer button specs. Defaults to Cancel + OK.
+        buttons: Footer button specs. Defaults to Cancel + OK. A button's
+            `result=` decides whether it submits the form: `'ok'`, `'submit'`
+            and `'save'` return the entered data, and so does a button with no
+            `result=` at all. Give an action button — a Delete, say — a result
+            token of its own, and it runs without the form having to validate
+            and hands that token back instead of the data.
         min_size: Minimum dialog window size `(width, height)`.
         max_size: Maximum dialog window size `(width, height)`.
         resizable: Allow window resizing. Default `False`.

{bootstack-0.2.3 → bootstack-0.3.0}/src/bootstack/dialogs/_impl/datedialog.py

@@ -260,7 +260,6 @@ class DateDialog:
                     text="button.ok",
                     role="primary",
                     default=True,
-                    closes=False,
                     command=lambda dlg: self._on_confirm_range(),
                 ),
             ]
@@ -318,22 +317,39 @@ class DateDialog:
 
         self._confirm(selected)
 
-    def _on_confirm_range(self) -> None:
+    def _on_confirm_range(self) -> bool:
         """Confirm the selected range when OK is clicked.
 
-        No-op (dialog stays open) until both endpoints are selected.
+        Refuses the press — leaving the dialog open — until both endpoints are
+        selected. The OK button hands that answer back to `Dialog`, which owns
+        the close.
+
+        Unlike `_confirm`, this releases no grab of its own. It does not need
+        to: `Dialog` destroys the toplevel, and Tk releases a grab held by a
+        window when that window is destroyed (measured — see
+        `development/probe_437_review2_fixes.py`). `_confirm` keeps its
+        `grab_release()` because it destroys the window itself, where the call
+        is at least self-documenting.
         """
         if not self._picker:
-            return
+            return False
         start, end = self._picker.get_range()
         if start is None or end is None:
-            return
-        self._confirm((start, end))
+            return False
+        self._record((start, end))
+        return True
 
-    def _confirm(self, result: date | Tuple[date, date]) -> None:
-        """Record the result, emit, and close the dialog."""
+    def _record(self, result: date | Tuple[date, date]) -> None:
+        """Record the result and notify listeners, without closing."""
         self._dialog.result = result
         self._emit_result(result, confirmed=True)
+
+    def _confirm(self, result: date | Tuple[date, date]) -> None:
+        """Record the result, emit, and close the dialog.
+
+        Used by the commit-on-select path, which has no button behind it.
+        """
+        self._record(result)
         if self._dialog.toplevel:
             top = self._dialog.toplevel
             try:

{bootstack-0.2.3 → bootstack-0.3.0}/src/bootstack/dialogs/_impl/dialog.py

@@ -84,14 +84,15 @@ class DialogButton:
     result: Any | None = None  # value assigned to dialog.result
     """Value assigned to `dialog.result` when clicked."""
 
-    closes: bool = True  # close dialog after click
-    """Whether the button closes the dialog when clicked."""
-
     default: bool = False  # default button (Enter)
     """Whether this is the default button (focused, triggered by Enter)."""
 
-    command: Callable[[Dialog], None] | None = None
-    """Callback invoked when clicked."""
+    command: Callable[[Dialog], Any] | None = None
+    """Callback invoked when clicked. Returning `False` refuses the press — no
+    result is recorded, and a dialog stays open — which is how a button rejects
+    the input it was given. Any other return value, including `None`, accepts
+    it. The same applies wherever these specifications are used, including the
+    button row of a `Form`."""
 
     accent: AccentToken | str | None = None
     """Accent token for styling (e.g. `'primary'`, `'danger'`)."""
@@ -501,11 +502,21 @@ class Dialog:
 
             def make_command(s: DialogButton):
                 def cmd():
-                    if s.command:
-                        s.command(self)
+                    # A command returning False refuses the press: the dialog
+                    # neither records a result nor closes. Without this, a
+                    # command that declines to act (a form failing validation,
+                    # say) still stamps its button's result, and that value
+                    # outlives the press — a later cancel cannot clear it,
+                    # because a cancel button's own result is None and the write
+                    # below is skipped for None.
+                    if s.command and s.command(self) is False:
+                        return
                     if s.result is not None:
                         self.result = s.result
-                    if s.closes and self._toplevel:
+                    # `winfo_exists` rather than a bare truth test: a command is
+                    # free to close the dialog itself, and destroying an already
+                    # destroyed toplevel raises.
+                    if self._toplevel and self._toplevel.winfo_exists():
                         self._toplevel.destroy()
 
                 return cmd
@@ -531,7 +542,41 @@ class Dialog:
 
         if default_button is not None:
             default_button.focus_set()
-            self._toplevel.bind("<Return>", lambda e, b=default_button: b.invoke())
+            top = self._toplevel
+
+            def press_default(event: Any, b: Any = default_button) -> None:
+                """Press the default button, unless a button already has.
+
+                This binding lives on the toplevel, so it runs for every key
+                press anywhere in the dialog. A press delivered to a button has
+                already invoked that button by the time the bindtag walk
+                reaches here — buttons carry a class binding for Return and
+                KP_Enter — so firing again would either invoke the same button
+                twice or, with focus on some OTHER button, run the default
+                button's command on top of the one the user actually pressed.
+                Standing down is also what makes keyboard traversal mean
+                something: Enter presses the button you tabbed to.
+
+                A DISABLED button is the exception: its class binding runs but
+                `invoke` does nothing, so nothing has answered the key and the
+                default button should still get it. Standing down there would
+                leave the keyboard dead for the whole dialog — which is what a
+                content button that greys itself out on click would cause.
+
+                The remaining case is the one this binding exists for — focus
+                in an entry, as in `QueryDialog`, where nothing else would
+                answer the key.
+                """
+                pressed = event.widget
+                if "TButton" in pressed.bindtags() and not pressed.instate(["disabled"]):
+                    return
+                b.invoke()
+
+            # The keypad Enter key reports `KP_Enter`, a separate keysym from
+            # `Return` on Windows, X11 and Aqua alike, so it needs its own
+            # binding to reach the default button from an input field.
+            for key in ("<Return>", "<KP_Enter>"):
+                self._toplevel.bind(key, press_default)
 
         if cancel_button is not None:
             self._toplevel.bind("<Escape>", lambda e, b=cancel_button: b.invoke())
@@ -636,11 +681,11 @@ class Dialog:
     def _style_for_role(self, role: ButtonRole) -> tuple[str | None, str | None]:
         """Return (accent, variant) tuple for a button role."""
         if role == "primary":
-            return ("primary", None)
+            return "primary", None
         if role == "secondary":
-            return ("default", None)
+            return "default", None
         if role == "danger":
-            return ("danger", None)
+            return "danger", None
         if role == "cancel":
-            return ("default", "outline")
-        return ("default", None)
+            return "default", "outline"
+        return "default", None