bootstack 0.1.0__py3-none-any.whl

bootstack/dialogs/_impl/__init__.py

@@ -0,0 +1,47 @@
+"""Internal dialog implementations.
+
+The Bootstrap-styled dialog building blocks behind the public dialog API. The
+curated public surface — the `alert` / `confirm` / `ask_*` verbs and the
+`Dialog` / `FormDialog` / `FontDialog` / `ColorChooserDialog` /
+`FilterDialog` classes — lives in `bootstack.dialogs`; import from there, not
+from this package.
+
+Modules here:
+
+- `message` (MessageBox/MessageDialog): info/warning/error/question prompts
+- `query` (QueryBox/QueryDialog): collect input (string, number, date, item, …)
+- `colorchooser`: color picker
+- `datedialog`: calendar date picker
+- `fontdialog`: font selection
+- `filterdialog`: multi-select filter dialog with search
+- `dialog`: the base `Dialog` / `DialogButton`
+"""
+from .colorchooser import (
+    ColorChooser,
+    ColorChooserDialog,
+)
+from .dialog import Dialog, DialogButton
+from .filterdialog import FilterDialog
+from .formdialog import FormDialog
+from .message import MessageDialog, MessageBox
+from .query import QueryDialog, QueryBox
+from .datedialog import DateDialog
+from .fontdialog import FontDialog
+
+__all__ = [
+    # Base / core dialogs
+    "Dialog",
+    "DialogButton",
+    "FilterDialog",
+    "FormDialog",
+    "MessageDialog",
+    "QueryDialog",
+    "DateDialog",
+    "FontDialog",
+    # Facades
+    "MessageBox",
+    "QueryBox",
+    # Color tools
+    "ColorChooser",
+    "ColorChooserDialog",
+]

bootstack/dialogs/_impl/colorchooser.py

@@ -0,0 +1,588 @@
+"""Color chooser widget for bootstack dialogs.
+
+This module provides a comprehensive color selection widget with multiple
+selection methods including RGB sliders, HSL controls, standard color palette,
+and hex input.
+"""
+import tkinter
+from collections import namedtuple
+from tkinter import Canvas, IntVar, StringVar
+from types import SimpleNamespace
+from typing import Any, Callable, List, NamedTuple, Optional, Tuple
+
+from PIL import ImageColor
+
+from bootstack.constants import *
+from bootstack._core import colorutils
+from bootstack._core.colorutils import HEX, HSL, HUE, LUM, RGB, SAT
+from bootstack.dialogs._impl.dialog import Dialog
+from bootstack.i18n import MessageCatalog
+from bootstack._runtime import utility
+from bootstack.style.style import get_style, get_theme_color
+from bootstack.widgets._impl.composites.tabs.tabview import TabView
+from bootstack.widgets._impl.primitives import Button, Entry, Frame, Label, Spinbox
+
+# Theme-color families shown on the "Themed" tab, in display order. Each is a
+# semantic color the active theme exposes as a full light-to-dark band; `gray`
+# is the neutral ramp for surface/text picks. (`secondary` is intentionally
+# omitted — it is a flat token with no band.)
+THEMED_FAMILIES: Tuple[str, ...] = (
+    "primary", "success", "info", "warning", "danger", "gray",
+)
+# Band stops sampled per family, light to dark — rendered as one gradient row.
+THEMED_SHADES: Tuple[int, ...] = (
+    50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950,
+)
+
+ttk = SimpleNamespace(
+    Button=Button,
+    Canvas=Canvas,
+    Entry=Entry,
+    Frame=Frame,
+    IntVar=IntVar,
+    Label=Label,
+    Spinbox=Spinbox,
+    StringVar=StringVar,
+    use_style=get_style,
+)
+
+ColorValues = namedtuple('ColorValues', 'h s l r g b hex')
+
+
+class ColorChoice(NamedTuple):
+    """A color selected from `ColorChooserDialog` or `ask_color`."""
+
+    rgb: Tuple[int, int, int]
+    """The color as an `(r, g, b)` tuple, each component 0–255."""
+    hsl: Tuple[int, int, int]
+    """The color as an `(h, s, l)` tuple — hue 0–360, saturation and luminance 0–100."""
+    hex: str
+    """The color as a lowercase hex string, e.g. `'#ff0000'`."""
+
+
+class ColorChooser(ttk.Frame):
+    """Color chooser widget — hue/saturation spectrum with luminance slider."""
+
+    def __init__(
+            self, master: Optional[tkinter.Misc], initial_color: Optional[str] = None,
+            padding: Optional[int] = None) -> None:
+        """Create a color chooser widget.
+
+        Shows a hue/saturation spectrum with a luminance slider, RGB/HSL/hex
+        numeric inputs, and a live color preview.
+
+        Args:
+            master: Parent widget.
+            initial_color: Initial color string; defaults to theme background.
+            padding: Padding around the chooser.
+        """
+        super().__init__(master, padding=padding)
+        self.tframe = ttk.Frame(self, padding=5)
+        self.tframe.pack(fill=X)
+        self.bframe = ttk.Frame(self, padding=(5, 0, 5, 5))
+        self.bframe.pack(fill=X)
+
+        self.notebook = TabView(self.tframe)
+        self.notebook.pack(fill=BOTH)
+
+        self.style = ttk.use_style()
+        self.colors = self.style.colors
+        fallback_bg = (
+                          self.colors.get("bg")
+                          if isinstance(self.colors, dict)
+                          else getattr(self.colors, "bg", None)
+                      ) or "#ffffff"
+        self.initial_color = initial_color or fallback_bg
+
+        # color variables
+        r, g, b = ImageColor.getrgb(self.initial_color)
+        h, s, l = colorutils.color_to_hsl((r, g, b), RGB)
+        hx = colorutils.color_to_hex((r, g, b), RGB)
+
+        self.hue = ttk.IntVar(value=h)
+        self.sat = ttk.IntVar(value=s)
+        self.lum = ttk.IntVar(value=l)
+        self.red = ttk.IntVar(value=r)
+        self.grn = ttk.IntVar(value=g)
+        self.blu = ttk.IntVar(value=b)
+        self.hex = ttk.StringVar(value=hx)
+
+        # widget sizes (adjusted by widget scaling)
+        self.spectrum_height = utility.scale_size(self, 240)
+        self.spectrum_width = utility.scale_size(self, 530)
+        self.spectrum_point = utility.scale_size(self, 12)
+
+        # build widgets — the themed swatches and the spectrum each get a tab
+        # (themed first); the luminance scale, preview, and numeric inputs stay
+        # shared below both tabs (so switching tabs doesn't shift the layout).
+        themed_page = self.notebook.add('themed', text='color.themed')
+        self.themed_swatches = self.create_swatches(themed_page)
+        self.themed_swatches.pack(fill=BOTH, expand=YES)
+
+        custom_page = self.notebook.add('custom', text='color.custom')
+        self.color_spectrum = self.create_spectrum(custom_page)
+        self.color_spectrum.pack(fill=X, side=TOP)
+
+        self.luminance_scale = self.create_luminance_scale(self.tframe)
+        self.luminance_scale.pack(fill=X)
+
+        preview_frame = self.create_preview(self.bframe)
+        preview_frame.pack(side=LEFT, fill=BOTH, expand=YES, padx=(0, 5))
+        self.color_entries = self.create_value_inputs(self.bframe)
+        self.color_entries.pack(side=RIGHT)
+
+        self.create_spectrum_indicator()
+        self.create_luminance_indicator()
+
+    def create_spectrum(self, master: tkinter.Misc) -> ttk.Canvas:
+        """Create the color spectrum canvas"""
+        # canvas and point dimensions
+        width = self.spectrum_width
+        height = self.spectrum_height
+        xf = yf = self.spectrum_point
+
+        # create canvas widget and binding
+        canvas = ttk.Canvas(master, width=width, height=height, cursor='tcross')
+        canvas.bind("<B1-Motion>", self.on_spectrum_interaction, add="+")
+        canvas.bind("<Button-1>", self.on_spectrum_interaction, add="+")
+
+        # add color points
+        for x, colorx in enumerate(range(0, width, xf)):
+            for y, colory in enumerate(range(0, height, yf)):
+                values = self.color_from_coords(colorx, colory)
+                fill = values.hex
+                bbox = [x * xf, y * yf, (x * xf) + xf, (y * yf) + yf]
+                canvas.create_rectangle(*bbox, fill=fill, width=0)
+        return canvas
+
+    def create_spectrum_indicator(self) -> None:
+        """Create a square indicator that displays in the position of
+        the selected color"""
+        s = utility.scale_size(self, 10)
+        width = utility.scale_size(self, 2)
+        values = self.get_variables()
+        x1, y1 = self.coords_from_color(values.hex)
+        tag = ['spectrum-indicator']
+        self.color_spectrum.create_rectangle(
+            x1, y1, x1 + s, y1 + s, width=width, tags=[tag])
+        self.color_spectrum.tag_lower('spectrum-indicator')
+
+    # widget builder methods
+    def create_swatches(self, master: tkinter.Misc) -> ttk.Frame:
+        """Create a grid of the active theme's color bands.
+
+        Each row is one semantic color family rendered as a light-to-dark
+        gradient of its band stops; clicking any swatch loads that exact
+        on-theme color into the chooser.
+        """
+        gap = utility.scale_size(self, 1)
+        n_cols = len(THEMED_SHADES)
+        n_rows = len(THEMED_FAMILIES)
+
+        # Distribute leftover pixels so the grid sums to EXACTLY the spectrum
+        # width/height — otherwise integer rounding leaves the themed page a few
+        # pixels off and switching tabs shifts the layout.
+        avail_w = self.spectrum_width - gap * (n_cols - 1)
+        base_w, extra_w = divmod(avail_w, n_cols)
+        col_widths = [base_w + (1 if j < extra_w else 0) for j in range(n_cols)]
+        avail_h = self.spectrum_height - gap * (n_rows - 1)
+        base_h, extra_h = divmod(avail_h, n_rows)
+
+        container = ttk.Frame(master)
+        for i, family in enumerate(THEMED_FAMILIES):
+            row_height = base_h + (1 if i < extra_h else 0)
+            row_frame = ttk.Frame(container)
+            for j, shade in enumerate(THEMED_SHADES):
+                token = f"{family}[{shade}]"
+                hexcolor = get_theme_color(token)
+                swatch = ttk.Frame(
+                    row_frame,
+                    surface=token,
+                    width=col_widths[j],
+                    height=row_height,
+                )
+                swatch.bind(
+                    '<Button-1>',
+                    lambda _e, hx=hexcolor: self.on_press_swatch(hx),
+                    add="+",
+                )
+                # Left-pad only, so the inter-swatch gap is exactly `gap` (a
+                # symmetric padx would double it and widen the page).
+                swatch.pack(side=LEFT, padx=(gap if j > 0 else 0, 0))
+            row_frame.pack(fill=X, pady=(gap if i > 0 else 0, 0))
+        return container
+
+    def create_preview(self, master: tkinter.Misc) -> ttk.Frame:
+        """Create the preview swatches for the original and new colors."""
+        container = ttk.Frame(master)
+        constrast_fg = colorutils.contrast_color(color=self.initial_color, model='hex')
+
+        # Each swatch is a single ttk.Label: unlike most ttk widgets, Label
+        # honors the background/foreground instance options directly, so the label
+        # itself is the color fill with its caption on top — no native tk widget
+        # and no autostyle coupling, and live updates stay an O(1) configure().
+        old = ttk.Label(
+            container,
+            text=MessageCatalog.translate("color.current"),
+            background=self.initial_color,
+            foreground=constrast_fg,
+            anchor=NW,
+            width=7,
+            padding=6,
+        )
+        old.pack(side=LEFT, fill=BOTH, expand=YES, padx=(0, 2))
+
+        self.preview = ttk.Label(
+            container,
+            text=MessageCatalog.translate("color.new"),
+            background=self.initial_color,
+            foreground=constrast_fg,
+            anchor=NW,
+            width=7,
+            padding=6,
+        )
+        self.preview.pack(side=LEFT, fill=BOTH, expand=YES, padx=(2, 0))
+
+        return container
+
+    def create_value_inputs(self, master: tkinter.Misc) -> ttk.Frame:
+        """Create color value input widgets"""
+        container = ttk.Frame(master)
+        for x in range(4):
+            container.columnconfigure(x, weight=1)
+
+        # value labels - use semantic keys with built-in localization
+        lbl_cnf = {'master': container, 'anchor': E}
+        ttk.Label(**lbl_cnf, text='color.hue:').grid(row=0, column=0, sticky=E)
+        ttk.Label(**lbl_cnf, text='color.sat:').grid(row=1, column=0, sticky=E)
+        ttk.Label(**lbl_cnf, text='color.lum:').grid(row=2, column=0, sticky=E)
+        ttk.Label(**lbl_cnf, text='color.hex:').grid(row=3, column=0, sticky=E)
+        ttk.Label(**lbl_cnf, text='color.red:').grid(row=0, column=2, sticky=E)
+        ttk.Label(**lbl_cnf, text='color.green:').grid(row=1, column=2, sticky=E)
+        ttk.Label(**lbl_cnf, text='color.blue:').grid(row=2, column=2, sticky=E)
+
+        # value spinners and entry widgets
+        rgb_cnf = {'master': container, 'from_': 0, 'to': 255, 'width': 3}
+        sl_cnf = {'master': container, 'from_': 0, 'to': 100, 'width': 3}
+        hue_cnf = {'master': container, 'from_': 0, 'to': 360, 'width': 3}
+        sb_hue = ttk.Spinbox(**hue_cnf, textvariable=self.hue)
+        sb_hue.grid(row=0, column=1, padx=4, pady=2, sticky=EW)
+        sb_sat = ttk.Spinbox(**sl_cnf, textvariable=self.sat)
+        sb_sat.grid(row=1, column=1, padx=4, pady=2, sticky=EW)
+        sb_lum = ttk.Spinbox(**sl_cnf, textvariable=self.lum)
+        sb_lum.grid(row=2, column=1, padx=4, pady=2, sticky=EW)
+        sb_red = ttk.Spinbox(**rgb_cnf, textvariable=self.red)
+        sb_red.grid(row=0, column=3, padx=4, pady=2, sticky=EW)
+        sb_grn = ttk.Spinbox(**rgb_cnf, textvariable=self.grn)
+        sb_grn.grid(row=1, column=3, padx=4, pady=2, sticky=EW)
+        sb_blu = ttk.Spinbox(**rgb_cnf, textvariable=self.blu)
+        sb_blu.grid(row=2, column=3, padx=4, pady=2, sticky=EW)
+        ent_hex = ttk.Entry(container, textvariable=self.hex)
+        ent_hex.grid(row=3, column=1, padx=4, columnspan=3, pady=2, sticky=EW)
+
+        # event binding for updating colors on value change
+        for sb in [sb_hue, sb_sat, sb_lum]:
+            for sequence in ['<<Increment>>', '<<Decrement>>', '<Return>', '<KP_Enter>']:
+                sb.bind(
+                    sequence=sequence,
+                    func=lambda _, w=sb: self.on_entry_value_change(w, HSL),
+                    add="+"
+                )
+        for sb in [sb_red, sb_grn, sb_blu]:
+            for sequence in ['<<Increment>>', '<<Decrement>>', '<Return>', '<KP_Enter>']:
+                sb.bind(
+                    sequence=sequence,
+                    func=lambda _, w=sb: self.on_entry_value_change(w, RGB),
+                    add="+"
+                )
+        for sequence in ['<Return>', '<KP_Enter>']:
+            ent_hex.bind(
+                sequence=sequence,
+                func=lambda _, w=ent_hex: self.on_entry_value_change(w, HEX),
+                add="+"
+            )
+
+        return container
+
+    def create_luminance_scale(self, master: tkinter.Misc) -> ttk.Canvas:
+        """Create the color luminance canvas"""
+        # widget dimensions
+        height = xf = self.spectrum_point
+        width = self.spectrum_width
+
+        values = self.get_variables()
+        canvas = ttk.Canvas(master, height=height, width=width)
+
+        # add color points to scale
+        for x, l in enumerate(range(0, width, xf)):
+            lum = l / width * LUM
+            fill = colorutils.update_hsl_value(
+                color=values.hex,
+                lum=lum,
+                inmodel='hex',
+                outmodel='hex'
+            )
+            bbox = [x * xf, 0, (x * xf) + xf, height]
+            tag = f'color{x}'
+            canvas.create_rectangle(*bbox, fill=fill, width=0, tags=[tag])
+            canvas.bind("<B1-Motion>", self.on_luminance_interaction, add="+")
+            canvas.bind("<Button-1>", self.on_luminance_interaction, add="+")
+        return canvas
+
+    def create_luminance_indicator(self) -> None:
+        """Create an indicator that displays in the position of the
+        luminance value"""
+        lum = 50
+        x1 = int(lum / LUM * self.spectrum_width) - \
+             ((self.spectrum_point - 2) // 2)
+        y1 = 0
+        x2 = x1 + self.spectrum_point
+        y2 = self.spectrum_point - 3
+        tag = 'luminance-indicator'
+        bbox = [x1, y1, x2, y2]
+        self.luminance_scale.create_rectangle(
+            *bbox, fill='white', outline='black', tags=[tag])
+        self.luminance_scale.tag_lower(tag)
+
+    def coords_from_color(self, hexcolor: str) -> Tuple[float, float]:
+        """Get the coordinates on the color spectrum from the color value"""
+        h, s, _ = colorutils.color_to_hsl(hexcolor)
+        x = (h / HUE) * self.spectrum_width
+        y = (1 - (s / SAT)) * self.spectrum_height
+        return x, y
+
+    def color_from_coords(self, x: int, y: int):
+        """Get the color value from the mouse position in the color spectrum"""
+        HEIGHT = self.spectrum_height
+        WIDTH = self.spectrum_width
+        h = int(min(HUE, max(0, (HUE / WIDTH) * x)))
+        s = int(min(SAT, max(0, SAT - ((SAT / HEIGHT) * y))))
+        l = 50
+        hx = colorutils.color_to_hex([h, s, l], 'hsl')
+        r, g, b = colorutils.color_to_rgb(hx)
+        return ColorValues(h, s, l, r, g, b, hx)
+
+    def set_variables(self, h: int, s: int, l: int, r: int, g: int, b: int, hx: str) -> None:
+        """Update the color value variables"""
+        self.hue.set(h)
+        self.sat.set(s)
+        self.lum.set(l)
+        self.red.set(r)
+        self.grn.set(g)
+        self.blu.set(b)
+        self.hex.set(hx)
+
+    def get_variables(self):
+        """Get the values of all color models and return a tuple of color values"""
+        h = self.hue.get()
+        s = self.sat.get()
+        l = self.lum.get()
+        r = self.red.get()
+        g = self.grn.get()
+        b = self.blu.get()
+        hx = self.hex.get()
+        return ColorValues(h, s, l, r, g, b, hx)
+
+    def update_preview(self) -> None:
+        """Update the color in the preview frame"""
+        hx = self.hex.get()
+        fg = colorutils.contrast_color(color=hx, model='hex')
+        self.preview.configure(background=hx, foreground=fg)
+
+    def update_luminance_scale(self) -> None:
+        """Update the luminance scale with the change in hue and saturation"""
+        values = self.get_variables()
+        width = self.spectrum_width
+        xf = self.spectrum_point
+        for x, l in enumerate(range(0, width, xf)):
+            lum = l / width * LUM
+            fill = colorutils.update_hsl_value(
+                color=values.hex,
+                lum=lum,
+                inmodel='hex',
+                outmodel='hex'
+            )
+            tag = f'color{x}'
+            self.luminance_scale.itemconfig(tag, fill=fill)
+
+    def update_luminance_indicator(self) -> None:
+        """Update the position of the luminance indicator"""
+        lum = self.lum.get()
+        x = int(lum / LUM * self.spectrum_width) - \
+            ((self.spectrum_point - 2) // 2)
+        self.luminance_scale.moveto('luminance-indicator', x, 0)
+        self.luminance_scale.tag_raise('luminance-indicator')
+
+    def update_spectrum_indicator(self) -> None:
+        """Move the spectrum indicator to a new location"""
+        values = self.get_variables()
+        x, y = self.coords_from_color(values.hex)
+        self.color_spectrum.moveto('spectrum-indicator', x, y)
+        self.color_spectrum.tag_raise('spectrum-indicator')
+        color = colorutils.contrast_color(values.hex, 'hex')
+        self.color_spectrum.itemconfig('spectrum-indicator', outline=color)
+
+    # color events
+    def sync_color_values(self, model) -> None:
+        """Sync all color model variables when one changes."""
+        values = self.get_variables()
+        if model == HEX:
+            hx = values.hex
+            r, g, b = colorutils.color_to_rgb(hx)
+            h, s, l = colorutils.color_to_hsl(hx)
+        elif model == RGB:
+            r, g, b = values.r, values.g, values.b
+            h, s, l = colorutils.color_to_hsl([r, g, b], 'rgb')
+            hx = colorutils.color_to_hex([r, g, b])
+        elif model == HSL:
+            h, s, l = values.h, values.s, values.l
+            r, g, b = colorutils.color_to_rgb([h, s, l], 'hsl')
+            hx = colorutils.color_to_hex([h, s, l], 'hsl')
+        self.set_variables(h, s, l, r, g, b, hx)
+        self.update_preview()
+        self.update_luminance_indicator()
+
+    def on_entry_value_change(self, widget: ttk.Spinbox, model: Any) -> None:
+        """Update widget colors when a color value input changes"""
+        is_valid = widget.validate()
+        if is_valid:
+            self.sync_color_values(model)
+            self.update_luminance_scale()
+            self.update_spectrum_indicator()
+
+    def on_press_swatch(self, hexcolor: str) -> None:
+        """Update widget colors when a themed swatch is clicked."""
+        self.hex.set(hexcolor)
+        self.sync_color_values(HEX)
+        self.update_luminance_scale()
+        self.update_spectrum_indicator()
+
+    def on_spectrum_interaction(self, event: tkinter.Event) -> None:
+        """Update widget colors when the color spectrum canvas is pressed"""
+        values = self.color_from_coords(event.x, event.y)
+        self.hue.set(values.h)
+        self.sat.set(values.s)
+        self.lum.set(values.l)
+        self.sync_color_values(HSL)
+        self.update_luminance_scale()
+        self.update_spectrum_indicator()
+
+    def on_luminance_interaction(self, event: tkinter.Event) -> None:
+        """Update widget colors when the luminance scale is pressed"""
+        l = max(0, min(LUM, int((event.x / self.spectrum_width) * LUM)))
+        self.lum.set(l)
+        self.sync_color_values(HSL)
+
+
+class ColorChooserDialog:
+    """Dialog wrapper for the ColorChooser widget.
+
+    Args:
+        master: Parent widget used for positioning and event binding.
+        title: Dialog window title (localized).
+        initial_color: Initial color shown in the chooser; defaults to theme background.
+    """
+
+    def __init__(
+            self,
+            master: Optional[tkinter.Misc] = None,
+            title: str = "color.chooser",
+            initial_color: Optional[str] = None,
+    ) -> None:
+        self._master = master
+        self._title = title
+        self._initial_color = initial_color
+        self.result: Optional[ColorChoice] = None
+        self._emitted_result = False
+
+        self._dialog = Dialog(
+            parent=master,
+            title=self._title,
+            content_builder=self._build_content,
+            _raw_content=True,
+            footer_builder=self._build_footer,
+        )
+        self._chooser: Optional[ColorChooser] = None
+
+    # builders -----------------------------------------------------------------
+    def _build_content(self, master: tkinter.Widget) -> None:
+        self._chooser = ColorChooser(master, self._initial_color)
+        self._chooser.pack(fill=BOTH, expand=YES)
+
+    def _build_footer(self, master: tkinter.Widget) -> None:
+        ok = ttk.Button(
+            master,
+            accent='primary',
+            text='button.ok',
+            command=self._on_ok,
+        )
+        ok.pack(side=RIGHT)
+
+        cancel = ttk.Button(
+            master,
+            accent='default',
+            text='button.cancel',
+            command=self._on_cancel,
+        )
+        cancel.pack(side=RIGHT)
+
+    # callbacks ----------------------------------------------------------------
+    def _on_ok(self) -> None:
+        if self._chooser:
+            values = self._chooser.get_variables()
+            self.result = ColorChoice(
+                rgb=(values.r, values.g, values.b),
+                hsl=(values.h, values.s, values.l),
+                hex=values.hex
+            )
+        self._emit_result(confirmed=True)
+        if self._dialog.toplevel:
+            self._dialog.toplevel.after_idle(self._dialog.toplevel.destroy)
+
+    def _on_cancel(self) -> None:
+        self.result = None
+        self._emit_result(confirmed=False)
+        if self._dialog.toplevel:
+            self._dialog.toplevel.after_idle(self._dialog.toplevel.destroy)
+
+    # API ----------------------------------------------------------------------
+    def show(self, position: Optional[Tuple[int, int]] = None, modal: bool = True) -> None:
+        """Display the dialog."""
+        self.result = None
+        self._emitted_result = False
+        self._dialog.show(position=position, modal=modal)
+        if not self._emitted_result:
+            self._emit_result(confirmed=self.result is not None)
+
+    def on_dialog_result(self, callback: Callable[[Any], None]) -> Optional[str]:
+        """Bind a callback fired when the dialog produces a result."""
+        target = self._master or self._dialog.toplevel
+        if target is None:
+            return None
+
+        def handler(event):
+            callback(getattr(event, "data", None))
+
+        return target.bind("<<DialogResult>>", handler, add="+")
+
+    def off_dialog_result(self, funcid: str) -> None:
+        """Unbind a previously bound dialog result callback."""
+        target = self._master or self._dialog.toplevel
+        if target is None:
+            return
+        target.unbind("<<DialogResult>>", funcid)
+
+    # helpers ------------------------------------------------------------------
+    def _emit_result(self, confirmed: bool) -> None:
+        payload = {"result": self.result, "confirmed": confirmed}
+        target = self._master or self._dialog.toplevel
+        if not target:
+            return
+        try:
+            target.event_generate("<<DialogResult>>", data=payload)
+        except Exception:
+            try:
+                target.event_generate("<<DialogResult>>")
+            except Exception:
+                pass
+        self._emitted_result = True