bootstack 0.1.0__py3-none-any.whl

bootstack/dialogs/_impl/formdialog.py

@@ -0,0 +1,564 @@
+"""FormDialog - A dialog that embeds a Form widget for data entry.
+
+This module provides FormDialog, which combines the Dialog and Form widgets
+to create modal or non-modal dialogs for structured data entry.
+"""
+
+from __future__ import annotations
+
+from tkinter import Widget
+from typing import Any, Callable, Iterable, Literal, Mapping, Optional, Sequence, Tuple, Union, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from bootstack.widgets._impl.composites.form import FormItem
+
+from bootstack.dialogs._impl.dialog import Dialog, DialogButton, ButtonSpec
+from bootstack.widgets._impl.primitives.frame import Frame
+from bootstack.widgets.types import Master
+from bootstack.constants import DEFAULT_MIN_COL_WIDTH as FORM_MIN_COL_WIDTH
+from bootstack._runtime.window_utilities import AnchorPoint
+
+
+class FormDialog:
+    """A dialog window that embeds a Form widget for structured data entry.
+
+    FormDialog combines the Dialog and Form widgets to create modal or non-modal
+    dialogs for data entry with automatic field generation or explicit layouts.
+
+    Attributes:
+        result: After closing — the entered form data (dict) for a submit
+            button (ok/submit/save), the button's own result value for a custom
+            action button (e.g. "delete"), or None if cancelled.
+        form: The embedded Form widget instance, accessible for advanced usage.
+
+    Args:
+        parent: Parent widget. If None, uses the default root window.
+        title: Dialog window title. Defaults to "Form".
+        data: Initial data backing the form. Keys become field names.
+        items: Optional explicit form definition using FieldItem/GroupItem/TabsItem.
+            If not provided, fields are inferred from data keys and types.
+        col_count: Number of columns for form layout. Defaults to 1.
+        min_col_width: Minimum width for each column in pixels. Defaults to the
+            shared form default.
+        on_data_change: Optional callback invoked when any field value changes.
+            Receives the updated data dict as parameter.
+        width: Requested width for the form. Defaults to None (auto-size).
+        height: Requested height for the form. Defaults to None (auto-size).
+        scrollable: Deprecated; FormDialog manages scrolling internally.
+        scrollview_options: Additional options passed to ScrollView when scrollable is True.
+        buttons: Footer buttons. Can be DialogButton instances, dicts, or strings.
+            If not provided, defaults to Cancel and OK buttons.
+            First button appears rightmost (Bootstrap convention).
+        minsize: Minimum dialog window size as (width, height).
+            If None, automatically calculated based on col_count * min_col_width + padding.
+            If provided, ensures width is at least the calculated minimum to prevent
+            horizontal scrolling. Defaults to None (auto-calculate).
+        maxsize: Maximum dialog window size as (width, height). Defaults to None.
+        resizable: Allow window resizing as (width, height) bools. Defaults to (True, True).
+        alert: If True, plays system alert sound on show. Defaults to False.
+        mode: Dialog interaction mode ("modal" or "popover"). Defaults to "modal".
+    """
+
+    def __init__(
+        self,
+        parent: Master = None,
+        *,
+        title: str = "Form",
+        data: dict[str, Any] | None = None,
+        items: Sequence[FormItem | Mapping[str, Any]] | None = None,
+        col_count: int = 1,
+        min_col_width: int | None = None,
+        on_data_change: Callable[[dict[str, Any]], Any] | None = None,
+        on_close: Callable[[], Any] | None = None,
+        width: int | None = None,
+        height: int | None = None,
+        scrollable: bool = True,
+        scrollview_options: dict[str, Any] | None = None,
+        buttons: Iterable[ButtonSpec | str] | None = None,
+        minsize: tuple[int, int] | None = None,
+        maxsize: tuple[int, int] | None = None,
+        resizable: tuple[bool, bool] | bool | None = False,
+        alert: bool = False,
+        mode: Literal['modal', 'popover'] = "modal",
+    ):
+        """Initialize a FormDialog that wraps a Form inside a Dialog.
+
+        Args:
+            parent: Parent widget. Defaults to the default root window.
+            title: Dialog window title.
+            data: Initial data backing the form; keys become field names.
+            items: Optional explicit form layout (FieldItem/GroupItem/TabsItem or mappings).
+            col_count: Number of columns for the form layout.
+            min_col_width: Minimum width per column; defaults to the shared form default.
+            on_data_change: Callback invoked when any field value changes.
+            width: Explicit form width; if None, size naturally.
+            height: Explicit form height; if None, size naturally.
+            scrollable: Whether the form content should be scrollable.
+            scrollview_options: Extra options passed to the ScrollView when scrollable.
+            buttons: Dialog footer buttons (DialogButton, mapping, or string).
+            minsize: Minimum dialog window size (width, height).
+            maxsize: Maximum dialog window size (width, height).
+            resizable: Bool or (width, height) tuple to allow window resizing.
+            alert: Whether to play the system alert sound when shown.
+            mode: Dialog interaction mode, "modal" or "popover".
+        """
+        self._data = data or {}
+        self._items = items
+        self._col_count = col_count
+        # Use the shared form default when not provided to keep layouts consistent
+        self._min_col_width = min_col_width if min_col_width is not None else FORM_MIN_COL_WIDTH
+        self._on_data_change = on_data_change
+        self._width = width
+        self._height = height
+        self._scrollable = scrollable  # deprecated; kept for compatibility with callers
+
+        # Use better default scrollview options - auto-hide when content fits
+        default_scrollview_options = {
+            # Keep the scrollbar visible to avoid width jumps when it appears/disappears
+            'scrollbar_visibility': 'always',
+            'autohide_delay': 1000,
+        }
+        if scrollview_options:
+            default_scrollview_options.update(scrollview_options)
+        self._scrollview_options = default_scrollview_options
+
+        # Normalize buttons and wrap command callbacks
+        self._buttons = self._normalize_buttons(buttons)
+        self._wrap_button_commands()
+
+        # Store minsize for later adjustment
+        self._user_minsize = minsize
+        self._user_maxsize = maxsize
+
+        # Normalize resizable flag: bool applies to both axes
+        if isinstance(resizable, bool):
+            resizable = (resizable, resizable)
+
+        # Create the dialog with form as content
+        # We'll set the proper minsize after measuring the actual form
+        self._dialog = Dialog(
+            title=title,
+            content_builder=self._build_form_content,
+            _raw_content=True,
+            buttons=self._buttons,
+            min_size=minsize,
+            max_size=maxsize,
+            resizable=resizable,
+            alert=alert,
+            mode=mode,
+            on_close=on_close,
+            parent=parent,
+        )
+
+        self.form: Any = None  # Form widget, imported lazily to avoid circular import
+        self.result: Any = None
+        self._initial_layout_done = False
+        self._scrollview = None
+        self._window_id = None
+
+    def show(
+            self,
+            *,
+            position: Optional[Tuple[int, int]] = None,
+            modal: Optional[bool] = None,
+            anchor_to: Optional[Union[Widget, Literal["screen", "cursor", "parent"]]] = None,
+            anchor_point: AnchorPoint = 'center',
+            window_point: AnchorPoint = 'center',
+            offset: Tuple[int, int] = (0, 0),
+            auto_flip: Union[bool, Literal['vertical', 'horizontal']] = False
+    ):
+        """Show the form dialog and populate `result` when closed.
+
+        Args:
+            position: Optional (x, y) coordinates to position the dialog.
+                If provided, takes precedence over anchor-based positioning.
+            modal: Override the mode's default modality.
+                - If None, uses mode:
+                    - "modal": grab_set + wait_window
+                    - "popover": no grab, but wait_window
+            anchor_to: Positioning target. Can be:
+                - Widget: Anchor to a specific widget
+                - "screen": Anchor to screen edges/corners
+                - "cursor": Anchor to mouse cursor location
+                - "parent": Anchor to parent window (same as widget)
+                - None: Centers on parent (default)
+            anchor_point: Point on the anchor target (n, s, e, w, ne, nw, se, sw, center).
+                Default 'center'.
+            window_point: Point on the dialog window (n, s, e, w, ne, nw, se, sw, center).
+                Default 'center'.
+            offset: Additional (x, y) offset in pixels from the anchor position.
+            auto_flip: Smart positioning to keep window on screen.
+                - False: No flipping (default)
+                - True: Flip both vertically and horizontally as needed
+                - 'vertical': Only flip up/down
+                - 'horizontal': Only flip left/right
+        """
+        # Allow initial layout priming each time the dialog is shown
+        self._initial_layout_done = False
+
+        self._dialog.show(
+            position=position,
+            modal=modal,
+            anchor_to=anchor_to,
+            anchor_point=anchor_point,
+            window_point=window_point,
+            offset=offset,
+            auto_flip=auto_flip
+        )
+
+        # Transfer the result from dialog to FormDialog.
+        self.result = self._resolve_result(self._dialog.result)
+
+    # Submit-style button results that mean "return the entered form data".
+    _DATA_RESULTS = frozenset({"ok", "submit", "save"})
+
+    def _resolve_result(self, dialog_result: Any) -> Any:
+        """Map the closing button's dialog result to the FormDialog result.
+
+        A data-submit button (ok / submit / save) yields the entered form data;
+        a custom action button (e.g. a `'delete'` result) yields its own result
+        value so callers can tell the action apart from the data. A cancel /
+        unset result (`None`) yields `None`.
+        """
+        if dialog_result is None:
+            return None
+        if isinstance(dialog_result, str) and dialog_result.lower() in self._DATA_RESULTS:
+            return self.form.data if self.form else None
+        # A non-cancel button with no explicit result already carries the form
+        # data (set in `_wrap_button_commands`); anything else is an action token.
+        return dialog_result
+
+
+    def _build_form_content(self, parent):
+        """Builder callback that creates the Form widget inside the dialog."""
+        # Import Form here to avoid circular import
+        from bootstack.widgets._impl.composites.form import Form
+        from bootstack.widgets._impl.composites.scrollview import ScrollView
+
+        # Configure parent to allow stretching
+        parent.columnconfigure(0, weight=1)
+        parent.rowconfigure(0, weight=1)
+
+        container = parent
+        if self._scrollable:
+            self._scrollview = ScrollView(parent, scroll_direction='vertical', **self._scrollview_options)
+            self._scrollview.grid(row=0, column=0, sticky="nsew")
+            self._scrollview.enable_scrolling()
+            # add a padding frame inside the scrollview so the form has margins
+            padding_frame = Frame(self._scrollview, padding=10)
+            padding_frame.columnconfigure(0, weight=1)
+            padding_frame.rowconfigure(0, weight=1)
+            self._scrollview.add(padding_frame, anchor='nw')
+            self._window_id = self._scrollview._window_id
+            self._scrollview.bind('<Configure>', self._on_scrollview_configure, add="+")
+            # Keep canvas window width in sync with viewport on every resize
+            self._scrollview.canvas.bind("<Configure>", self._on_canvas_configure, add="+")
+            container = padding_frame
+        else:
+            self._scrollview = None
+
+        # Create the form without its own scrolling; scrolling is managed by the dialog
+        self.form = Form(
+            container,
+            data=self._data,
+            items=self._items,
+            col_count=self._col_count,
+            min_col_width=self._min_col_width,
+            on_data_change=self._on_data_change,
+            width=None,  # Let form size naturally
+            height=None if self._scrollable else self._height,
+            buttons=None,
+        )
+
+        # Add the form to the scrollview container or grid directly
+        if self._scrollview:
+            self.form.grid(row=0, column=0, sticky="nsew")
+        else:
+            self.form.grid(row=0, column=0, sticky="nsew", padx=10, pady=10)
+
+        # Ensure initial layout runs right after build (for scrollable dialogs)
+        self._schedule_initial_layout()
+
+        # Measure the actual content width after rendering
+        measured_width = self._col_count * self._min_col_width
+        if self._items:
+            nested_width = self._calculate_required_width()
+            measured_width = max(measured_width, nested_width)
+
+        if self._width:
+            measured_width = self._width
+
+        # Calculate dialog size: content + padding (10x2) + dialog chrome (~40)
+        dialog_width = measured_width + 60
+
+        _MIN_HEIGHT = 150
+        _MAX_HEIGHT = 800
+
+        min_height = _MIN_HEIGHT
+        if self._user_minsize:
+            user_width, user_height = self._user_minsize
+            dialog_width = max(user_width, dialog_width)
+            min_height = max(user_height, _MIN_HEIGHT)
+
+        # Store the intended content width for pre-show sizing of the scrollview
+        self._desired_canvas_width = measured_width
+
+        if self._dialog.toplevel:
+            # Seed width and minimum height, then measure natural content height
+            self._dialog.toplevel.minsize(dialog_width, min_height)
+            self._dialog.toplevel.geometry(f"{dialog_width}x{min_height}")
+            self._dialog.toplevel.update_idletasks()
+
+            if self._height:
+                dialog_height = min(self._height + 100, _MAX_HEIGHT)
+            else:
+                natural = self._dialog.toplevel.winfo_reqheight()
+                dialog_height = min(max(natural, min_height), _MAX_HEIGHT)
+
+            self._dialog.toplevel.geometry(f"{dialog_width}x{dialog_height}")
+            self._dialog.toplevel.update_idletasks()
+
+    def _schedule_initial_layout(self):
+        """Run layout fixups immediately before showing the window."""
+        if not self._scrollable:
+            return
+        if self._dialog and self._dialog.toplevel:
+            # Make sure all pending geometry work is processed while withdrawn.
+            # update_idletasks alone flushes layout/redraw; full update() also
+            # pumps input/IO events, which can hang on Aqua when the form
+            # contains heavy widgets (same pattern as the Dialog/BaseWindow
+            # pre-deiconify hang). Gate update() to win32 only.
+            top = self._dialog.toplevel
+            top.update_idletasks()
+            if getattr(top, 'winsys', None) == 'win32':
+                top.update()
+        # Run once synchronously so sizing is applied before deiconify
+        self._fire_initial_configure(blocking=True)
+
+    def _fire_initial_configure(self, _event=None, attempts: int = 5, blocking: bool = False):
+        """Trigger scrollview/layout config once after geometry stabilizes."""
+        if self._initial_layout_done:
+            return
+        if not (self._scrollable and self._scrollview and self.form):
+            return
+
+        canvas = self._scrollview.canvas
+        canvas_width = 0
+
+        # When blocking, loop a few times to give Tk a chance to size the canvas
+        loops = attempts if blocking else 1
+        for _ in range(max(1, loops)):
+            if self._dialog and self._dialog.toplevel:
+                self._dialog.toplevel.update_idletasks()
+            self._scrollview.update_idletasks()
+            canvas_width = canvas.winfo_width()
+            if canvas_width > 1:
+                break
+
+        fallback_width = max(
+            getattr(self, "_desired_canvas_width", 0),
+            self.form.winfo_reqwidth() if self.form else 0,
+            self._col_count * self._min_col_width,
+        )
+        if canvas_width <= 1:
+            canvas_width = fallback_width
+
+        # Apply width and manually call handlers
+        if self._window_id:
+            canvas.itemconfigure(self._window_id, width=canvas_width)
+        self._on_scrollview_configure(None)
+        try:
+            self._scrollview._on_frame_configure(None)
+        except Exception:
+            pass
+
+        # Ensure scrolling bindings are active after layout adjustments
+        try:
+            if getattr(self._scrollview, "_scrolling_enabled", False):
+                self._scrollview.refresh_bindings()
+            else:
+                self._scrollview.enable_scrolling()
+        except Exception:
+            pass
+
+        # Generate configure to mirror user-driven resize
+        try:
+            canvas.event_generate("<Configure>")
+        except Exception:
+            pass
+
+    def _on_scrollview_configure(self, _event=None):
+        """Keep scrollview content width in sync with the viewport."""
+        if self._scrollview and self._window_id:
+            canvas_width = self._scrollview.canvas.winfo_width()
+            if canvas_width > 1:
+                self._scrollview.canvas.itemconfigure(self._window_id, width=canvas_width)
+
+    def _on_canvas_configure(self, event=None):
+        """Keep the embedded form window width aligned to the canvas viewport."""
+        if not (self._scrollview and self._window_id):
+            return
+        width = event.width if event and hasattr(event, "width") else self._scrollview.canvas.winfo_width()
+        if width <= 1:
+            return
+        self._scrollview.canvas.itemconfigure(self._window_id, width=width)
+        try:
+            self._scrollview._on_frame_configure(None)
+        except Exception:
+            pass
+
+    def _calculate_required_width(self) -> int:
+        """Calculate the required minimum width for the dialog based on form structure."""
+        try:
+
+            # Start by finding the maximum width requirement
+            max_content_width = self._find_max_content_width(self._items, self._col_count, self._min_col_width)
+
+            # Add all the padding layers:
+            # 1. Form widget padding (grid padx=10 on each side) = 20px
+            # 2. Dialog content frame borders = 10px
+            # 3. Window chrome and safety margin = 30px
+            total_width = max_content_width + 60
+
+            return total_width
+        except:
+            # Fallback to basic calculation
+            return (self._col_count * self._min_col_width) + 60
+
+    def _find_max_content_width(self, items, parent_col_count: int, parent_min_col_width: int) -> int:
+        """Find the maximum content width needed, accounting for nested structures."""
+        if not items:
+            # No items, use parent layout
+            # Each column needs: min_col_width + padx (6 on each side = 12)
+            return (parent_col_count * (parent_min_col_width + 12))
+
+        max_width = 0
+
+        # Calculate width for current level
+        current_width = parent_col_count * (parent_min_col_width + 12)
+        max_width = max(max_width, current_width)
+
+        # Check all items for nested layouts
+        try:
+            from bootstack.widgets._impl.composites.form import GroupItem, TabsItem
+
+            for item in items:
+                if isinstance(item, dict):
+                    item_type = item.get('type', 'field')
+                    if item_type == 'group':
+                        nested_col_count = item.get('col_count', parent_col_count)
+                        nested_min_col_width = item.get('min_col_width', self._min_col_width)
+                        nested_items = item.get('items', [])
+
+                        # GroupItem content width
+                        group_content = self._find_max_content_width(nested_items, nested_col_count, nested_min_col_width)
+                        # Add LabelFrame padding (8px each side) and borders (~4px) = 24px total
+                        group_total = group_content + 24
+                        max_width = max(max_width, group_total)
+
+                    elif item_type == 'tabs':
+                        tabs = item.get('tabs', [])
+                        for tab in tabs:
+                            if isinstance(tab, dict):
+                                tab_items = tab.get('items', [])
+                                tab_width = self._find_max_content_width(tab_items, parent_col_count, parent_min_col_width)
+                                max_width = max(max_width, tab_width + 20)
+
+                elif isinstance(item, GroupItem):
+                    nested_col_count = item.col_count if item.col_count else parent_col_count
+                    nested_min_col_width = item.min_col_width if item.min_col_width else self._min_col_width
+
+                    # GroupItem content width
+                    group_content = self._find_max_content_width(item.items, nested_col_count, nested_min_col_width)
+                    # Add LabelFrame padding
+                    group_total = group_content + 24
+                    max_width = max(max_width, group_total)
+
+                elif isinstance(item, TabsItem):
+                    for tab in item.tabs:
+                        tab_items = tab.items if hasattr(tab, 'items') else []
+                        tab_width = self._find_max_content_width(tab_items, parent_col_count, parent_min_col_width)
+                        max_width = max(max_width, tab_width + 20)
+        except:
+            pass
+
+        return max_width
+
+    def _wrap_button_commands(self):
+        """Wrap button command callbacks to pass FormDialog instead of Dialog."""
+        for button in self._buttons:
+            # For non-cancel buttons, handle validation and closing manually
+            if button.role != "cancel":
+                button.closes = False
+            if button.command:
+                original_command = button.command
+                def wrapped_command(dlg, cmd=original_command, btn=button):
+                    # Validate form before running custom command
+                    if self.form and btn.role != "cancel":
+                        if not self.form.validate():
+                            return
+                    result = cmd(self)  # Pass FormDialog, not Dialog
+                    if result is False:
+                        return
+                    # Set result and close manually when not cancelled
+                    if self._dialog:
+                        self._dialog.result = btn.result if btn.result is not None else (self.form.data if self.form else None)
+                        if btn.closes is False and self._dialog.toplevel:
+                            self._dialog.toplevel.destroy()
+                    return result
+                button.command = wrapped_command
+            else:
+                # No custom command: inject validation and close behavior for non-cancel buttons
+                def auto_command(dlg=None, btn=button):
+                    if btn.role == "cancel":
+                        # Cancel button: leave result as None, dialog closes via default behavior
+                        return
+                    if self.form:
+                        if not self.form.validate():
+                            return
+                    if self._dialog:
+                        self._dialog.result = btn.result if btn.result is not None else (self.form.data if self.form else None)
+                        if btn.closes is False and self._dialog.toplevel:
+                            self._dialog.toplevel.destroy()
+                button.command = auto_command
+
+    def _normalize_buttons(self, buttons: Iterable[ButtonSpec | str] | None) -> list[DialogButton]:
+        """Normalize button specifications, providing defaults if none given."""
+        if buttons is None:
+            # Default buttons: Cancel and OK
+            return [
+                DialogButton(text="button.cancel", role="cancel", result=None),
+                DialogButton(text="button.ok", role="primary", result="ok", default=True),
+            ]
+
+        normalized: list[DialogButton] = []
+        for btn in buttons:
+            if isinstance(btn, DialogButton):
+                normalized.append(btn)
+            elif isinstance(btn, str):
+                # Simple string becomes a button
+                btn_lower = btn.lower()
+                if btn_lower == "cancel":
+                    role = "cancel"
+                    result = None
+                elif btn_lower in ("ok", "submit", "save"):
+                    role = "primary"
+                    result = btn_lower
+                else:
+                    role = "primary" if not normalized else "secondary"
+                    result = None
+                normalized.append(DialogButton(text=btn, role=role, result=result))
+            elif isinstance(btn, Mapping):
+                normalized.append(DialogButton(**btn))
+            else:
+                raise TypeError(f"Invalid button type: {type(btn)}")
+
+        return normalized
+
+    @property
+    def toplevel(self):
+        """Read-only access to the underlying toplevel window."""
+        return self._dialog.toplevel if self._dialog else None
+
+
+__all__ = ["FormDialog"]