bootstack 0.1.0__py3-none-any.whl

bootstack/_runtime/base_window.py

@@ -0,0 +1,945 @@
+"""Base window functionality shared between App (Tk) and Toplevel.
+
+This module provides the BaseWindow mixin class that encapsulates common
+window management functionality used by both the main App and Toplevel classes.
+This eliminates code duplication and ensures consistent behavior across all
+window types.
+
+Standard widget APIs (events, scheduling, clipboard, geometry managers, winfo) are documented under capabilities and are
+ available through normal Tk/Ttk inheritance.”
+
+The BaseWindow mixin provides:
+- Window manager (wm) pass-throughs with modern docstrings
+- Window configuration (size, position, constraints)
+- Alpha transparency handling (platform-aware)
+- Icon management
+- Positioning utilities
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import tkinter
+import warnings
+from typing import Literal, Optional, Tuple, Callable, Any, List
+
+from bootstack.i18n import MessageCatalog
+from bootstack._runtime.window_utilities import AnchorPoint, WindowPositioning, WindowSizing
+
+
+def on_visibility_alpha(event: tkinter.Event) -> None:
+    """Set Window or Toplevel alpha value on Visibility (X11).
+
+    X11 requires alpha to be set after the window is visible, so we bind
+    to the <Visibility> event and set alpha then, unbinding after first use.
+
+    Args:
+        event: The visibility event containing the widget.
+    """
+    widget = event.widget
+    if hasattr(widget, 'alpha') and hasattr(widget, 'alpha_bind'):
+        if widget.alpha_bind:
+            widget.unbind(widget.alpha_bind)
+        widget.attributes("-alpha", widget.alpha)
+
+
+class BaseWindow:
+    """Base window behavior shared by bootstack windows.
+
+    This class is intended to be used as a mixin alongside `tkinter.Tk` or
+    `tkinter.Toplevel`, for example:
+
+        class App(BaseWindow, tkinter.Tk): ...
+        class Window(BaseWindow, tkinter.Toplevel): ...
+
+    The methods below are thin pass-throughs to Tk's window manager ("wm")
+    functionality, primarily to provide modern, consistent docstrings and a
+    curated, documented API surface.
+    """
+
+    _title_message_id: str | None = None
+
+    # -------------------------------------------------------------------------
+    # Setup methods (bootstack-specific)
+    # -------------------------------------------------------------------------
+
+    def _setup_window(
+            self,
+            title: str = "bootstack",
+            size: Optional[tuple[int, int]] = None,
+            position: Optional[tuple[int, int]] = None,
+            minsize: Optional[tuple[int, int]] = None,
+            maxsize: Optional[tuple[int, int]] = None,
+            resizable: Optional[tuple[bool, bool]] = None,
+            transient: Optional[tkinter.Misc] = None,
+            overrideredirect: bool = False,
+            alpha: float = 1.0,
+            window_style: Optional[str] = None,
+            center_on_parent: Optional[tkinter.Misc] = None,
+            center_on_screen: bool = False,
+    ) -> None:
+        """Configure common window properties.
+
+        This method should be called during window initialization to set up
+        standard window properties. It handles platform differences automatically.
+        The window is temporarily hidden during setup so that sizing and
+        positioning are applied before it is shown.
+
+        Args:
+            title: Window title shown in titlebar.
+            size: Optional (width, height) in pixels.
+            position: Optional (x, y) position on screen.
+            minsize: Optional (width, height) minimum window size.
+            maxsize: Optional (width, height) maximum window size.
+            resizable: Optional (width, height) resizable flags.
+            transient: Optional master window for transient behavior.
+            overrideredirect: If True, removes window decorations.
+            alpha: Transparency level (0.0 to 1.0). Platform-aware.
+            window_style: Windows-only pywinstyles effect. Options include
+                'mica', 'acrylic', 'aero', 'transparent', 'win7', etc.
+                If None, uses AppSettings.window_style (defaults to 'mica').
+            center_on_parent: If provided, center window over this parent widget
+                after layout. Ignored when `position` is also given.
+            center_on_screen: If True, center window on screen after layout.
+                Ignored when `position` or `center_on_parent` is also given.
+
+        Note:
+            The window must already be initialized (tkinter.Tk.__init__ or
+            tkinter.Toplevel.__init__ called) before calling this method.
+        """
+        # Get window_style from AppSettings if not explicitly provided
+        if window_style is None:
+            try:
+                from bootstack._runtime.app import get_app_settings
+                window_style = get_app_settings().window_style
+            except (ImportError, RuntimeError):
+                # No app registered yet, use default
+                window_style = 'mica'
+
+        # Store window style for later application
+        self._window_style = window_style
+        # Hide window until we finish applying geometry/resizing to avoid flicker
+        self.withdraw()
+
+        # Store window system for platform-specific behavior
+        if not hasattr(self, 'winsys'):
+            self.winsys = self.tk.call('tk', 'windowingsystem')
+
+        # Basic configuration - localize title automatically
+        self.title(title)
+
+        # Bind locale changes
+        self.winfo_toplevel().bind("<<LocaleChanged>>", self._handle_locale_changed)
+
+        # Geometry
+        if size is not None:
+            width, height = size
+            self.geometry(f"{width}x{height}")
+
+        if position is not None:
+            xpos, ypos = position
+            self.geometry(f"+{xpos}+{ypos}")
+
+        # Size constraints
+        if minsize is not None:
+            width, height = minsize
+            self.minsize(width, height)
+
+        if maxsize is not None:
+            width, height = maxsize
+            self.maxsize(width, height)
+
+        if resizable is not None:
+            width, height = resizable
+            self.resizable(width, height)
+
+        # Window attributes
+        if transient is not None:
+            self.transient(transient)
+
+        if overrideredirect:
+            # Skip overrideredirect on macOS - causes click handling issues and crashes
+            if self.winsys != 'aqua':
+                self.overrideredirect(1)
+
+        # Alpha transparency (platform-aware)
+        self._setup_alpha(alpha)
+
+        # Centering (only when no explicit position given)
+        if position is None:
+            self.update_idletasks()
+            if center_on_parent is not None:
+                x, y = WindowPositioning.center_on_parent(self, center_on_parent)
+                x, y = WindowPositioning.ensure_on_screen(self, x, y)
+                self.geometry(f'+{x}+{y}')
+            elif center_on_screen:
+                x, y = WindowPositioning.center_on_screen(self)
+                x, y = WindowPositioning.ensure_on_screen(self, x, y)
+                self.geometry(f'+{x}+{y}')
+
+    def _apply_window_style(self) -> None:
+        """Apply pywinstyles effect on Windows.
+
+        Uses the window_style set during initialization. Only applies on Windows
+        and only if the style hasn't already been applied.
+        """
+        if getattr(self, '_window_style_applied', False):
+            return
+        window_style = getattr(self, '_window_style', 'mica')
+        if window_style is None:
+            return
+        if not hasattr(self, 'winsys') or self.winsys != 'win32':
+            return
+        try:
+            import pywinstyles
+            pywinstyles.apply_style(self, window_style)
+            self._window_style_applied = True
+            self.after(0, self._update_chrome_color)
+            self.bind('<<ThemeChanged>>', self._schedule_chrome_update, add='+')
+        except Exception:
+            pass
+
+    def _schedule_chrome_update(self, _event=None) -> None:
+        """Coalesce chrome re-tinting on theme change.
+
+        The toplevel receives `<<ThemeChanged>>` ~1400x per theme rebuild (once
+        per ttk style reconfigure). Cancel any pending update and schedule a
+        single one so the (DWM) chrome repaint runs once, not hundreds of times.
+        """
+        pending = getattr(self, '_chrome_update_after', None)
+        if pending is not None:
+            try:
+                self.after_cancel(pending)
+            except Exception:
+                pass
+        self._chrome_update_after = self.after(0, self._update_chrome_color)
+
+    def _update_chrome_color(self) -> None:
+        if getattr(self, '_updating_chrome', False):
+            return
+        self._updating_chrome = True
+        try:
+            import pywinstyles
+            from bootstack.style.style import get_theme_provider
+            color = get_theme_provider().colors['chrome']
+            # The DWM header/border calls are expensive (~100ms each); skip them
+            # when the chrome color is unchanged (redundant theme events, or a
+            # theme switch that keeps the same chrome).
+            if getattr(self, '_chrome_color_applied', None) != color:
+                self._chrome_color_applied = color
+                pywinstyles.change_header_color(self, color)
+                # Match the window border to the chrome too, so it honors the
+                # theme (otherwise Windows leaves a light border in dark mode).
+                pywinstyles.change_border_color(self, color)
+        except Exception:
+            pass
+        finally:
+            self._updating_chrome = False
+
+    def _setup_alpha(self, alpha: float) -> None:
+        """Configure window alpha transparency in a platform-aware manner.
+
+        Handles platform differences in alpha transparency support:
+        - X11: Requires setting alpha after window is visible
+        - Windows/macOS: Can set alpha immediately
+
+        Args:
+            alpha: Transparency level (0.0 = fully transparent, 1.0 = opaque).
+
+        Note:
+            On X11, this binds to <Visibility> event to set alpha after
+            the window becomes visible. The binding is automatically
+            removed after first use.
+        """
+        if alpha is not None and alpha != 1.0:
+            if self.winsys == 'x11':
+                # X11 requires alpha to be set after window is visible
+                self.alpha = alpha
+                self.alpha_bind = self.bind("<Visibility>", on_visibility_alpha, '+')
+            else:
+                # Windows and macOS can set alpha immediately
+                self.attributes("-alpha", alpha)
+
+    def _setup_icon(self, iconphoto: Optional[str], default_icon_enabled: bool = True) -> None:
+        """Configure window icon from file path or use default.
+
+        Sets up the window icon, with support for:
+        - Custom icon from file path or PhotoImage object
+        - Default bootstack.png from package assets (when iconphoto is None and default_icon_enabled=True)
+        - No icon (when iconphoto is None and default_icon_enabled=False)
+
+        Args:
+            iconphoto: Path to icon image file, PhotoImage object, or None for default/no icon.
+            default_icon_enabled: Whether to use default icon when iconphoto is None.
+
+        Note:
+            The icon is stored in self._icon to prevent garbage collection (for PhotoImage icons).
+            On failure to load custom icon, falls back to default icon if enabled.
+        """
+        if iconphoto is None:
+            if default_icon_enabled:
+                try:
+                    from pathlib import Path
+                    import bootstack
+                    assets = Path(bootstack.__file__).parent / 'assets'
+                    if sys.platform == 'win32':
+                        self.wm_iconbitmap(str(assets / 'bootstack.ico'))
+                    else:
+                        self._icon = tkinter.PhotoImage(file=str(assets / 'bootstack.png'), master=self)
+                        self.iconphoto(True, self._icon)
+                except (ImportError, FileNotFoundError, tkinter.TclError, Exception):
+                    pass
+            return
+
+        # User provided a custom icon — a path string or a photo-image object
+        # (Tk's PhotoImage or Pillow's ImageTk.PhotoImage, both accepted by
+        # iconphoto()).
+        try:
+            if isinstance(iconphoto, (str, os.PathLike)):
+                path = str(iconphoto)
+                if path.lower().endswith('.ico'):
+                    self.wm_iconbitmap(path)
+                else:
+                    self._icon = tkinter.PhotoImage(file=path, master=self)
+                    self.iconphoto(True, self._icon)
+            else:
+                self._icon = iconphoto
+                self.iconphoto(True, self._icon)
+        except (tkinter.TclError, Exception) as e:
+            print(f'Failed to load icon: {iconphoto} - {e}')
+            if default_icon_enabled:
+                try:
+                    from pathlib import Path
+                    import bootstack
+                    assets = Path(bootstack.__file__).parent / 'assets'
+                    if sys.platform == 'win32':
+                        self.wm_iconbitmap(str(assets / 'bootstack.ico'))
+                    else:
+                        self._icon = tkinter.PhotoImage(file=str(assets / 'bootstack.png'), master=self)
+                        self.iconphoto(True, self._icon)
+                except (ImportError, FileNotFoundError, tkinter.TclError, Exception):
+                    pass
+
+    def _handle_locale_changed(self, *_):
+        """Handle locale change events by updating the localized title."""
+        if self._title_message_id:
+            self.title(self._title_message_id)
+
+    # -------------------------------------------------------------------------
+    # Close handler chain
+    # -------------------------------------------------------------------------
+
+    def _init_close_handlers(self) -> None:
+        """Initialize the close handler list and register the dispatch function.
+
+        Idempotent — safe to call multiple times.
+        """
+        if not hasattr(self, '_close_handlers'):
+            self._close_handlers: List[Callable[[], bool | None]] = []
+            self.protocol("WM_DELETE_WINDOW", self._close_dispatch)
+
+    def _close_dispatch(self) -> None:
+        """WM_DELETE_WINDOW handler that runs registered close handlers.
+
+        Runs each handler in registration order. If any returns `False` the
+        close is vetoed and the window stays open. If all pass (return `None`
+        or `True`), `_do_close()` is called to perform the actual close.
+        """
+        for handler in list(getattr(self, '_close_handlers', [])):
+            try:
+                result = handler()
+            except Exception:
+                result = None
+            if result is False:
+                return
+        self._do_close()
+
+    def _do_close(self) -> None:
+        """Perform the default close action.
+
+        Subclasses may override this to change what happens after all handlers
+        pass. The default is `self.destroy()`.
+        """
+        try:
+            self.destroy()
+        except tkinter.TclError:
+            pass
+
+    def close(self) -> None:
+        """Close the window programmatically, bypassing the close handlers.
+
+        This is the uniform close contract every top-level window honors. It
+        performs the default close action directly (`_do_close()`), so the
+        veto handlers registered with `add_close_handler()` — which guard the
+        user clicking the window's close button — are not run. The application
+        root overrides this to quit its event loop instead.
+        """
+        self._do_close()
+
+    def add_close_handler(self, callback: Callable[[], bool | None]) -> None:
+        """Register a callback invoked when the window's close button is clicked.
+
+        Handlers are called in registration order. Return `False` from a
+        handler to veto the close; return `None` or `True` to allow it.
+        All handlers that pass are run before the window closes.
+
+        Args:
+            callback: Called with no arguments when close is requested.
+                Return `False` to cancel the close, `None` or `True` to proceed.
+        """
+        self._init_close_handlers()
+        self._close_handlers.append(callback)
+
+    def remove_close_handler(self, callback: Callable[[], bool | None]) -> None:
+        """Remove a previously registered close handler.
+
+        Args:
+            callback: The handler to remove. No-op if not found.
+        """
+        if hasattr(self, '_close_handlers'):
+            try:
+                self._close_handlers.remove(callback)
+            except ValueError:
+                pass
+
+    # -------------------------------------------------------------------------
+    # Window manager (wm) — pass-throughs with modern docstrings
+    # -------------------------------------------------------------------------
+
+    def show(self) -> None:
+        """Show the window after it has been fully initialized.
+
+        This forces a geometry/layout pass before mapping the window, which is
+        useful if you have performed setup that affects sizing.
+        """
+        # Apply Windows window style while still withdrawn to prevent flash.
+        # The update() flushes input/IO events so pywinstyles can attach to a
+        # fully realized HWND on Windows; on Aqua it can hang indefinitely
+        # processing children's pending events (see Dialog._position_dialog
+        # for the same pattern), so gate it on the platform that needs it.
+        self.update_idletasks()
+        self._apply_window_style()
+        if getattr(self, 'winsys', None) == 'win32':
+            self.update()
+
+        # Reveal-after-settle: some content can only realize its final size once
+        # the window is mapped (e.g. a ScrollView's canvas filling its viewport).
+        # Map the window invisibly, let it settle, then reveal it — so it never
+        # visibly shifts into place on open. Restores any prior alpha.
+        try:
+            prev_alpha = self.attributes('-alpha')
+        except tkinter.TclError:
+            prev_alpha = None
+        if prev_alpha is not None:
+            try:
+                self.attributes('-alpha', 0.0)
+            except tkinter.TclError:
+                prev_alpha = None
+
+        try:
+            self.deiconify()
+            self.update_idletasks()
+            if getattr(self, 'winsys', None) == 'win32':
+                self.update()
+        finally:
+            # Always restore visibility — if settling raised (e.g. a pending
+            # callback in update()), the window must not stay stuck at alpha 0.
+            if prev_alpha is not None:
+                try:
+                    self.attributes('-alpha', prev_alpha)
+                except tkinter.TclError:
+                    pass
+
+    def title(self, value: str | None = None) -> str:
+        """Get or set the window title.
+
+        If you localize UI text (e.g., via a message catalog), the title is
+        automatically translated using the MessageCatalog.
+
+        Args:
+            value: The new title text. If None, return the current title.
+
+        Returns:
+            The current title string (getter) or the title string after setting.
+        """
+        if value is None:
+            return super().title()
+        self._title_message_id = value
+        return super().title(MessageCatalog.translate(self._title_message_id))
+
+    def geometry(self, new_geometry: str | None = None) -> str:
+        """Get or set the window geometry.
+
+        Geometry strings use the standard Tk format:
+
+        - "{width}x{height}" (size only)
+        - "+{x}+{y}" (position only)
+        - "{width}x{height}+{x}+{y}" (size + position)
+
+        Args:
+            new_geometry: The geometry string to apply. If None, return the
+                current geometry string.
+
+        Returns:
+            The current geometry string (getter) or the geometry after setting.
+        """
+        return super().geometry(new_geometry)
+
+    def state(self, newstate: str | None = None) -> str:
+        """Get or set the window manager state.
+
+        Common states include:
+
+        - "normal": displayed normally
+        - "iconic": minimized (iconified)
+        - "withdrawn": hidden (not shown)
+        - "zoomed": maximized (platform/window-manager dependent)
+
+        Args:
+            newstate: State to apply. If None, return the current state.
+
+        Returns:
+            The current state string.
+        """
+        return super().state(newstate)
+
+    def attributes(self, *args: Any) -> Any:
+        """Get or set platform-specific window attributes.
+
+        This method forwards to Tk's "wm attributes" command. Common attributes:
+
+        - "-alpha" (float 0.0-1.0): transparency
+        - "-fullscreen" (bool): fullscreen mode
+        - "-topmost" (bool): keep window above others
+
+        The exact supported attributes vary by platform/window manager.
+
+        Args:
+            *args: Arguments accepted by Tk's `wm attributes`. Common forms are:
+                - (name,) to query a single attribute
+                - (name, value) to set an attribute
+                - () to query all supported attributes (platform dependent)
+
+        Returns:
+            The queried attribute value(s), or an implementation-dependent
+            result when setting.
+        """
+        return super().attributes(*args)
+
+    def iconify(self) -> None:
+        """Minimize (iconify) the window."""
+        return super().iconify()
+
+    def deiconify(self) -> None:
+        """Show a minimized or withdrawn window.
+
+        This restores a window that has been hidden with `withdraw()` or
+        minimized with `iconify()`.
+        """
+        return super().deiconify()
+
+    def withdraw(self) -> None:
+        """Hide the window without destroying it.
+
+        A withdrawn window is unmapped and typically removed from
+        taskbar/window lists. Use `deiconify()` to show it again.
+        """
+        return super().withdraw()
+
+    def resizable(self, width: bool | None = None, height: bool | None = None) -> tuple[int, int] | None:
+        """Get or set whether the user can resize the window.
+
+        Args:
+            width: If provided, enable/disable horizontal resizing.
+            height: If provided, enable/disable vertical resizing.
+
+        Returns:
+            When called as a getter (both args None), returns `(width_flag, height_flag)`
+            where each flag is 0/1. When called as a setter, Tk returns None.
+        """
+        return super().resizable(width, height)
+
+    def minsize(self, width: int | None = None, height: int | None = None) -> tuple[int, int] | None:
+        """Get or set the minimum window size in pixels.
+
+        Args:
+            width: Minimum width in pixels. If None, act as a getter.
+            height: Minimum height in pixels. If None, act as a getter.
+
+        Returns:
+            When called as a getter (both args None), returns `(width, height)`.
+            When called as a setter, Tk returns None.
+        """
+        return super().minsize(width, height)
+
+    def maxsize(self, width: int | None = None, height: int | None = None) -> tuple[int, int] | None:
+        """Get or set the maximum window size in pixels.
+
+        Args:
+            width: Maximum width in pixels. If None, act as a getter.
+            height: Maximum height in pixels. If None, act as a getter.
+
+        Returns:
+            When called as a getter (both args None), returns `(width, height)`.
+            When called as a setter, Tk returns None.
+        """
+        return super().maxsize(width, height)
+
+    def transient(self, master: tkinter.Misc | None = None) -> tkinter.Misc | None:
+        """Get or set the transient parent (window relationship).
+
+        Transient windows typically stay on top of their parent and may be
+        omitted from the taskbar. This is commonly used for dialogs.
+
+        Args:
+            master: The parent window. If None, return the current transient parent.
+
+        Returns:
+            The current transient parent (getter) or the provided master (setter),
+            depending on Tk/platform behavior.
+        """
+        return super().transient(master)
+
+    def protocol(self, name: str, func: Callable[[], Any] | None = None) -> Any:
+        """Get or set a window manager protocol handler.
+
+        The most common protocol is "WM_DELETE_WINDOW" (close button).
+
+        Args:
+            name: Protocol name.
+            func: Handler to register. If None, return the current handler (if any).
+
+        Returns:
+            The current handler when queried, or an implementation-dependent result
+            when setting.
+        """
+        return super().protocol(name, func)
+
+    def overrideredirect(self, boolean: bool | None = None) -> bool | None:
+        """Get or set override-redirect mode.
+
+        When enabled, the window manager typically does not decorate or manage
+        the window (no title bar/borders). Useful for popups/menus; use with care.
+
+        Note:
+            On macOS (Aqua), overrideredirect is disabled due to Tk/Cocoa issues
+            with click handling and event processing that can cause crashes.
+
+        Args:
+            boolean: True to enable override-redirect, False to disable. If None,
+                return the current value.
+
+        Returns:
+            The current override-redirect value when queried, or None when set.
+        """
+        # Skip overrideredirect on macOS - causes click handling issues and crashes
+        if boolean and hasattr(self, 'winsys') and self.winsys == 'aqua':
+            return None
+        return super().overrideredirect(boolean)
+
+    # -------------------------------------------------------------------------
+    # Convenience wrappers: intent-based names for common tasks
+    # -------------------------------------------------------------------------
+
+    def on_close(self, handler: Callable[[], bool | None]) -> None:
+        """Register a handler for the window close button.
+
+        Equivalent to `add_close_handler(handler)`. Handlers are called in
+        registration order; return `False` to veto the close.
+
+        Args:
+            handler: Called with no arguments when close is requested.
+                Return `False` to cancel, `None` or `True` to proceed.
+        """
+        self.add_close_handler(handler)
+
+    def hide(self) -> None:
+        """Hide the window (alias for `withdraw()`)."""
+        self.withdraw()
+
+    def minimize(self) -> None:
+        """Minimize the window (alias for `iconify()`)."""
+        self.iconify()
+
+    def maximize(self) -> None:
+        """Maximize the window where supported.
+
+        Tk uses `state("zoomed")` to request maximized windows on some platforms.
+        On unsupported window managers this may raise `tkinter.TclError`.
+        """
+        try:
+            self.state("zoomed")
+        except tkinter.TclError:
+            pass
+
+    def set_topmost(self, value: bool = True) -> None:
+        """Enable/disable always-on-top behavior where supported.
+
+        Args:
+            value: True to keep the window above others; False to disable.
+        """
+        try:
+            self.attributes("-topmost", bool(value))
+        except tkinter.TclError:
+            pass
+
+    # Backward compatibility alias
+    keep_on_top = set_topmost
+
+    def set_fullscreen(self, value: bool = True) -> None:
+        """Enable/disable fullscreen where supported.
+
+        Args:
+            value: True to enter fullscreen; False to exit.
+        """
+        try:
+            self.attributes("-fullscreen", bool(value))
+        except tkinter.TclError:
+            pass
+
+    def set_alpha(self, value: float) -> None:
+        """Set window opacity where supported.
+
+        Args:
+            value: Opacity from 0.0 (transparent) to 1.0 (opaque).
+        """
+        try:
+            self.attributes("-alpha", float(value))
+        except tkinter.TclError:
+            pass
+
+    # -------------------------------------------------------------------------
+    # Positioning utilities
+    # -------------------------------------------------------------------------
+
+    def place_center(self) -> None:
+        """Position the window in the center of the screen.
+
+        Centers the window on the primary display. For multi-monitor setups,
+        this typically centers on the monitor containing the mouse pointer.
+
+        The window geometry is updated immediately.
+
+        Examples:
+            >>> app = App()
+            >>> app.place_center()
+            >>> app.mainloop()
+        """
+        x, y = WindowPositioning.center_on_screen(self)
+        x, y = WindowPositioning.ensure_on_screen(self, x, y)
+        self.geometry(f'+{x}+{y}')
+
+    def place_center_on(self, parent: tkinter.Misc) -> None:
+        """Position the window centered on a parent widget or window.
+
+        Centers this window on the specified parent widget or window.
+        Commonly used for dialogs to center them on their parent window.
+
+        Args:
+            parent: The parent widget or window to center on.
+
+        Examples:
+            >>> parent = App()
+            >>> dialog = Toplevel()
+            >>> dialog.place_center_on(parent)
+        """
+        x, y = WindowPositioning.center_on_parent(self, parent)
+        x, y = WindowPositioning.ensure_on_screen(self, x, y)
+        self.geometry(f'+{x}+{y}')
+
+    def place_at(self, x: int, y: int, ensure_visible: bool = True) -> None:
+        """Position the window at specific screen coordinates.
+
+        Places the window at the given (x, y) coordinates, optionally
+        adjusting the position to ensure the window remains fully visible
+        on screen.
+
+        Args:
+            x: X coordinate on screen (in pixels from left edge).
+            y: Y coordinate on screen (in pixels from top edge).
+            ensure_visible: If True, adjusts coordinates to keep window on screen.
+
+        Examples:
+            >>> window = App()
+            >>> window.place_at(100, 100)
+        """
+        if ensure_visible:
+            x, y = WindowPositioning.ensure_on_screen(self, x, y)
+        self.geometry(f'+{x}+{y}')
+
+    def place_anchor(
+            self,
+            anchor_to: tkinter.Misc,
+            anchor_point: AnchorPoint = 'sw',
+            window_point: AnchorPoint = 'nw',
+            offset: Tuple[int, int] = (0, 0),
+            ensure_visible: bool = True
+    ) -> None:
+        """Position window relative to another widget using anchor points.
+
+        Uses tkinter's standard anchor naming (n, s, e, w, ne, nw, se, sw, center).
+        This is useful for dropdowns, tooltips, context menus, and popovers.
+
+        Args:
+            anchor_to: The widget to anchor this window to.
+            anchor_point: Which point on the anchor widget to use (default 'sw').
+            window_point: Which point on this window to align (default 'nw').
+            offset: Additional (x, y) offset in pixels.
+            ensure_visible: If True, adjusts position to keep window on screen.
+
+        Examples:
+            >>> # Show dialog below button
+            >>> dialog = Toplevel()
+            >>> dialog.place_anchor(
+            ...     anchor_to=button,
+            ...     anchor_point='sw',  # button's bottom-left
+            ...     window_point='nw',  # dialog's top-left
+            ...     offset=(0, 5)
+            ... )
+        """
+        WindowPositioning.position_with_anchor(
+            window=self,
+            anchor_to=anchor_to,
+            anchor_point=anchor_point,
+            window_point=window_point,
+            offset=offset,
+            ensure_visible=ensure_visible
+        )
+
+    def place_dropdown(
+            self,
+            trigger_widget: tkinter.Misc,
+            prefer_below: bool = True,
+            align: Literal['left', 'right', 'center'] = 'left',
+            offset: Tuple[int, int] = (0, 2),
+            ensure_visible: bool = True,
+            auto_flip: bool = True
+    ) -> None:
+        """Position window as a dropdown relative to a trigger widget.
+
+        Smart positioning that automatically flips above/below based on
+        available space. Perfect for combobox dropdowns, autocomplete
+        suggestions, and dropdown menus.
+
+        Args:
+            trigger_widget: The widget that triggers the dropdown.
+            prefer_below: If True, tries to show below trigger; else tries above.
+            align: Horizontal alignment ('left', 'right', or 'center').
+            offset: Additional (x, y) offset in pixels.
+            ensure_visible: If True, adjusts position to keep window on screen.
+            auto_flip: If True, automatically flips above/below if no room.
+
+        Examples:
+            >>> # Dropdown menu below button
+            >>> menu = Toplevel()
+            >>> menu.place_dropdown(
+            ...     trigger_widget=button,
+            ...     prefer_below=True,
+            ...     align='left'
+            ... )
+        """
+        WindowPositioning.position_dropdown(
+            window=self,
+            trigger_widget=trigger_widget,
+            prefer_below=prefer_below,
+            align=align,
+            offset=offset,
+            ensure_visible=ensure_visible,
+            auto_flip=auto_flip
+        )
+
+    def place_cursor(
+            self,
+            offset: Tuple[int, int] = (5, 5),
+            ensure_visible: bool = True
+    ) -> None:
+        """Position window at the current mouse cursor location.
+
+        Useful for context menus, tooltips that follow the cursor, or
+        click-to-show dialogs.
+
+        Args:
+            offset: Additional (x, y) offset from cursor in pixels.
+            ensure_visible: If True, adjusts position to keep window on screen.
+
+        Examples:
+            >>> # Show context menu at cursor
+            >>> menu = Toplevel()
+            >>> menu.place_cursor(offset=(2, 2))
+        """
+        WindowPositioning.position_at_cursor(
+            window=self,
+            offset=offset,
+            ensure_visible=ensure_visible
+        )
+
+    # Backward compatibility aliases
+    def place_window_center(self) -> None:
+        """Alias for place_center(). Deprecated, use place_center() instead."""
+        self.place_center()
+
+    position_center = place_center  # Additional alias for compatibility
+
+    # -------------------------------------------------------------------------
+    # Sizing utilities
+    # -------------------------------------------------------------------------
+
+    def set_default_size(
+            self,
+            width_ratio: float = 0.6,
+            height_ratio: float = 0.7,
+            min_width: int = 400,
+            min_height: int = 300,
+            max_width: Optional[int] = None,
+            max_height: Optional[int] = None
+    ) -> None:
+        """Set window size as a percentage of screen size.
+
+        Calculates and applies a window size based on screen dimensions,
+        constrained by minimum and optional maximum sizes. Useful for
+        creating responsive windows that adapt to different screen sizes.
+
+        Args:
+            width_ratio: Proportion of screen width (0.0 to 1.0).
+            height_ratio: Proportion of screen height (0.0 to 1.0).
+            min_width: Minimum window width in pixels.
+            min_height: Minimum window height in pixels.
+            max_width: Optional maximum window width in pixels.
+            max_height: Optional maximum window height in pixels.
+
+        Examples:
+            >>> window = App()
+            >>> window.set_default_size(width_ratio=0.8, height_ratio=0.8)
+            >>> # Window will be 80% of screen size
+        """
+        width, height = WindowSizing.get_default_size(
+            self, width_ratio, height_ratio,
+            min_width, min_height, max_width, max_height
+        )
+        self.geometry(f"{width}x{height}")
+
+    def apply_size_constraints(
+            self,
+            minsize: Optional[tuple[int, int]] = None,
+            maxsize: Optional[tuple[int, int]] = None,
+            resizable: Optional[tuple[bool, bool]] = None
+    ) -> None:
+        """Apply multiple size constraints at once.
+
+        Convenience method to set minsize, maxsize, and resizable in one call.
+
+        Args:
+            minsize: Optional (width, height) minimum size.
+            maxsize: Optional (width, height) maximum size.
+            resizable: Optional (width, height) resizable flags.
+
+        Examples:
+            >>> window = App()
+            >>> window.apply_size_constraints(
+            ...     minsize=(400, 300),
+            ...     resizable=(True, False)  # Width resizable, height fixed
+            ... )
+        """
+        WindowSizing.apply_size_constraints(self, minsize, maxsize, resizable)
+