bootstack 0.1.0a1__py3-none-any.whl

bootstack/widgets/parts/textentry_part.py

@@ -0,0 +1,344 @@
+from tkinter import Event, TclError
+from typing import Any, Callable
+
+from bootstack.core.localization import MessageCatalog, IntlFormatter
+from bootstack.widgets.primitives.entry import Entry
+from bootstack.widgets.mixins import ValidationMixin
+from bootstack.widgets.mixins.configure_mixin import configure_delegate
+
+
+class TextEntryPart(ValidationMixin, Entry):
+    """Internationalization-aware entry widget with deferred parsing and formatting.
+
+    This widget separates user input (display text) from the committed/parsed value,
+    providing a clean pattern for handling formatted data entry. Parsing and formatting
+    only occur when the user commits the value via `<FocusOut>` or `<Return>`.
+
+    !!! note "Events"
+        - `<<Input>>`: Triggered on each keystroke. `event.data = {'text': str}`
+        - `<<Change>>`: Triggered when value changes after commit. `event.data = {'value': Any, 'prev_value': Any, 'text': str}`
+        - `<Return>`: Triggered on Enter key press. `event.data = {'value': Any, 'text': str}`
+    """
+
+    def __init__(
+            self,
+            master=None,
+            *,
+            value='',
+            value_format=None,
+            initial_focus: bool = False,
+            allow_blank: bool = True,
+            **kwargs
+    ):
+        """Initialize a TextEntryPart widget with internationalization support.
+
+        Creates an entry widget that separates display text from the parsed value.
+        The widget defers parsing and formatting until the user commits the value
+        by pressing Enter or moving focus away from the widget.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+            value: Initial value to display and parse. Can be a string or any value
+                that can be formatted using value_format. Default is empty string.
+            value_format (str): ICU format pattern for parsing and formatting the value.
+                Common patterns: `'#,##0.00'` (decimal), `'¤#,##0.00'` (currency),
+                `'yyyy-MM-dd'` (date), `'#,##0.00%'` (percent).
+                If None, value is treated as plain text (no parsing/formatting).
+            initial_focus (bool): If True, widget receives focus when created.
+            allow_blank (bool): If True, empty input is parsed as None. If False, empty
+                input preserves the previous value.
+            **kwargs: Additional keyword arguments passed to the Entry base class.
+
+        Note:
+            The widget automatically subscribes to text changes and sets up
+            event handlers for `<FocusIn>`, `<FocusOut>`, and `<Return>`.
+        """
+        kwargs.setdefault('ttk_class', 'TField')
+        kwargs.setdefault('variant', 'input')
+        super().__init__(master, **kwargs)
+
+        # configuration
+        self._value_format = value_format
+        self._allow_blank = allow_blank
+        self._on_input_fid = None
+        self._fmt = IntlFormatter(locale=MessageCatalog.locale())
+
+        # set the initial display value
+        # Convert to string if it's a number
+        if isinstance(value, (int, float)):
+            initial_display = str(value)
+        else:
+            initial_display = value or self.textsignal.get() or ''
+
+        # Parse initial value if format is specified
+        if value_format is not None:
+            initial_value = self._parse_or_none(initial_display)
+        else:
+            initial_value = initial_display or ''
+
+        self._value = initial_value
+        self._prev_changed_value = initial_value
+
+        # normalize initial display if we already have a parsed value
+        if self._value is not None:
+            formatted_text = self._format_value(self._value)
+            self.textsignal.set(formatted_text)
+        else:
+            self.textsignal.set('')
+
+        # track last text emitted for CHANGE
+        self._prev_change_text = self.textsignal.get()
+
+        # subscribe to text changes
+        self._on_input_fid = self.textsignal.subscribe(self._handle_change)
+
+        # Commit on focus out / enter;
+        self.bind('<FocusIn>', self._store_prev_value, add=True)
+        self.bind('<FocusOut>', self._handle_focus_out, add=True)
+        self.bind('<Return>', self._handle_return, add=True)
+        self.winfo_toplevel().bind('<<LocaleChanged>>', self._on_locale_changed, add='+')
+
+        # set initial focus
+        if initial_focus:
+            self.focus()
+
+    def _store_prev_value(self, _: Any):
+        """Store current value on focus-in to detect changes later."""
+        self._prev_changed_value = self._value
+
+    def _handle_focus_out(self, _):
+        """Commit value and check for changes when focus leaves the widget."""
+        self.commit()
+        self._check_if_changed()
+
+    def _handle_return(self, _):
+        """Commit value and check for changes when Return key is pressed."""
+        self.commit()
+        self._check_if_changed()
+
+    def _handle_change(self, event):
+        """Emit <<Input>> event on every text change without parsing."""
+        text = self.textsignal.get()
+        if text == self._prev_change_text:
+            return
+
+        self._prev_change_text = text
+        self.event_generate('<<Input>>', data={"text": text})
+
+    def _check_if_changed(self):
+        """Emit <<Change>> event if parsed value changed since focus-in."""
+        if self._value != self._prev_changed_value:
+            data = {
+                "value": self._value,
+                "prev_value": self._prev_changed_value,
+                "text": self.textsignal.get()
+            }
+            self.event_generate('<<Change>>', data=data)
+            self._prev_changed_value = self._value
+
+    def _parse_or_none(self, s: str):
+        """Parse string using value_format, returning None on empty/invalid input."""
+        # If a non-string is passed (e.g., datetime/date), assume it's already parsed.
+        if not isinstance(s, str):
+            return s
+        s2 = (s or '').strip()
+        if not s2:
+            return None
+        try:
+            if self._value_format is None:
+                return s2
+            return self._fmt.parse(s2, self._value_format)
+        except ValueError:
+            return None
+
+    def _format_value(self, value: Any) -> str:
+        """Format a value for display using value_format.
+
+        Args:
+            value: The value to format (can be string, int, float, etc.)
+
+        Returns:
+            Formatted string representation of the value
+        """
+        if value is None:
+            return ''
+
+        # If no format specified, just convert to string
+        if self._value_format is None:
+            return str(value)
+
+        # IntlFormatter.format() expects numeric values, not strings
+        # So pass the value directly (it will be a number from parse())
+        try:
+            return self._fmt.format(value, self._value_format)
+        except (ValueError, TypeError):
+            # If formatting fails, return string representation
+            return str(value)
+
+    def on_input(self, callback: Callable) -> str:
+        """Bind to `<<Input>>`. Callback receives `event.data = {'text': str}`."""
+        return self.bind('<<Input>>', callback, add=True)
+
+    def off_input(self, bind_id: str | None = None) -> None:
+        """Unbind from `<<Input>>`."""
+        self.unbind('<<Input>>', bind_id)
+
+    def on_enter(self, callback: Callable) -> str:
+        """Bind to `<Return>`. Callback receives `event.data = {'value': Any, 'text': str}`."""
+
+        def enrich_callback(event: Event) -> None:
+            data = {"value": self._value, "text": self.textsignal.get()}
+            event.data = data
+            return callback(event)
+
+        return self.bind('<Return>', enrich_callback, add=True)
+
+    def off_enter(self, bind_id: str | None = None) -> None:
+        """Unbind from `<Return>`."""
+        self.unbind('<Return>', bind_id)
+
+    def on_changed(self, callback: Callable) -> str:
+        """Bind to `<<Change>>`. Callback receives `event.data = {'value': Any, 'prev_value': Any, 'text': str}`."""
+        return self.bind("<<Change>>", callback, add=True)
+
+    def off_changed(self, bind_id: str | None = None) -> None:
+        """Unbind from `<<Change>>`."""
+        self.unbind('<<Change>>', bind_id)
+
+    def value(self, value=None):
+        """Get or set the parsed/committed value.
+
+        Args:
+            value: If provided, sets the display text and internal value with formatting
+
+        Returns:
+            Current parsed value if no argument provided, None otherwise
+        """
+        if value is None:
+            return self._value
+        else:
+            # Store the value and format it for display
+            if isinstance(value, (int, float)):
+                value_str = str(value)
+            else:
+                value_str = str(value) if value is not None else ''
+
+            # Parse the value if format is specified
+            if self._value_format is not None and value_str:
+                self._value = self._parse_or_none(value_str)
+            else:
+                self._value = value_str if value_str else None
+
+            # Format and display
+            formatted_text = self._format_value(self._value)
+            self.textsignal.set(formatted_text)
+            return None
+
+    def text(self, value=None):
+        """Get or set the raw display text without committing.
+
+        Args:
+            value: If provided, sets the display text without parsing
+
+        Returns:
+            Current display text if no argument provided, None otherwise
+        """
+        if value is None:
+            return self.textsignal.get()
+        else:
+            self.textsignal.set(value)
+            return None
+
+    def commit(self):
+        """Parse display text, update value, and normalize display (called on FocusOut/Return)."""
+        s = self.get().strip()
+
+        # parse once
+        if s == '':
+            self._value = None if self._allow_blank else self._value
+        else:
+            try:
+                self._value = s if self._value_format is None else self._fmt.parse(s, self._value_format)
+            except ValueError:
+                # keep prior value on parse failure
+                return
+
+        # Format the value for display
+        new_text = self._format_value(self._value)
+
+        if new_text != self.textsignal.get():
+            # temporarily silence CHANGE while normalizing text
+            fid = getattr(self, '_on_input_fid', None)
+            if fid:
+                try:
+                    self.textsignal.unsubscribe(fid)
+                except TclError:
+                    pass
+            self.textsignal.set(new_text)
+            if fid:
+                self._on_input_fid = self.textsignal.subscribe(self._handle_change)
+
+    def _on_locale_changed(self, event=None):
+        """Respond to global changes in locale by updating formatter and text"""
+        self._fmt = IntlFormatter(locale=MessageCatalog.locale())
+
+        # reformat current value with new locale + same value_format
+        if self._value is not None:
+            formatted_text = self._format_value(self._value)
+            self.textsignal.set(formatted_text)
+
+    @configure_delegate('text')
+    def _delegate_text(self, value=None):
+        if value is None:
+            return self.text()
+        else:
+            return self.text(value)
+
+    @configure_delegate('value')
+    def _delegate_value(self, value=None):
+        if value is None:
+            return self.value()
+        else:
+            return self.value(value)
+
+    @configure_delegate('value_format')
+    def _delegate_value_format(self, value: str):
+        """Get or set the value format pattern and reformat display.
+
+        Can be accessed via:
+            widget.configure(value_format='#,##0.00')
+            widget['value_format'] = '#,##0.00'
+            widget.cget('value_format')
+        """
+        if value is None:
+            return self._value_format
+
+        self._value_format = value
+        # Reformat current value with new format
+        if self._value is not None:
+            formatted_text = self._format_value(self._value)
+            self.textsignal.set(formatted_text)
+
+    @configure_delegate('allow_blank')
+    def _delegate_allow_blank(self, value: bool):
+        """Get or set whether blank input is allowed.
+
+        Can be accessed via:
+            widget.configure(allow_blank=True)
+            widget['allow_blank'] = True
+            widget.cget('allow_blank')
+        """
+        if value is None:
+            return self._allow_blank
+
+        self._allow_blank = bool(value)
+
+    def destroy(self):
+        """Clean up signal subscriptions and destroy the widget."""
+        if self._on_input_fid:
+            try:
+                self.textsignal.unsubscribe(self._on_input_fid)
+            except Exception:
+                pass  # Ignore all errors during cleanup
+            self._on_input_fid = None
+        super().destroy()

bootstack/widgets/primitives/__init__.py

@@ -0,0 +1,55 @@
+"""Primitive bootstack widgets."""
+
+from .badge import Badge
+from .button import Button
+from .card import Card
+from .checkbutton import CheckButton
+from .checktoggle import CheckToggle
+from .combobox import Combobox
+from .entry import Entry
+from .frame import Frame
+from .gridframe import GridFrame
+from .label import Label
+from .labelframe import LabelFrame
+from .menubutton import MenuButton
+from .notebook import Notebook
+from .packframe import PackFrame
+from .panedwindow import PanedWindow
+from .progressbar import Progressbar
+from .radiobutton import RadioButton
+from .radiotoggle import RadioToggle
+from .scale import Scale
+from .scrollbar import Scrollbar
+from .separator import Separator
+from .sizegrip import SizeGrip
+from .spinbox import Spinbox
+from .switch import Switch
+from .treeview import TreeView
+
+__all__ = [
+    "Badge",
+    "Button",
+    "Card",
+    "CheckButton",
+    "CheckToggle",
+    "Combobox",
+    "Entry",
+    "Frame",
+    "GridFrame",
+    "Label",
+    "LabelFrame",
+    "MenuButton",
+    "Notebook",
+    "PackFrame",
+    "PanedWindow",
+    "Progressbar",
+    "RadioButton",
+    "RadioToggle",
+    "Scale",
+    "Scrollbar",
+    "Separator",
+    "SizeGrip",
+    "Spinbox",
+    "Switch",
+    "TreeView",
+]

bootstack/widgets/primitives/badge.py

@@ -0,0 +1,44 @@
+from typing_extensions import Unpack
+from bootstack.widgets.primitives.label import Label, LabelKwargs
+from bootstack.widgets.types import Master
+
+
+class Badge(Label):
+    """bootstack wrapper for `ttk.Label` that renders with a badge style."""
+
+    def __init__(self, master: Master = None, **kwargs: Unpack[LabelKwargs]):
+        """Create a themed bootstack Badge.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+
+        Other Parameters:
+            text (str): Text to display on the badge.
+            image (PhotoImage): Image to display.
+            icon (str | dict): Theme-aware icon spec handled by the style system.
+            icon_only (bool): If True, removes the additional padding reserved for label text.
+            compound (str): Placement of the image relative to text.
+            anchor (str): Alignment of the badge content within its area.
+            justify (str): How to justify multiple lines of text.
+            localize (bool | Literal['auto']): Determines the widget's localization mode.
+            value_format (str | dict): Format specification for the badge value.
+            padding (int | tuple): Extra space around the badge content.
+            width (int): Width of the badge in characters.
+            wraplength (int): Maximum width before wrapping text.
+            font (str | Font): Font for the badge text.
+            foreground (str): Text color.
+            background (str): Background color.
+            relief (str): Border style.
+            state (str): Widget state.
+            takefocus (bool): Whether the widget participates in focus traversal.
+            style (str): Explicit ttk style name (overrides accent/variant).
+            accent (str): Accent token for styling, e.g. 'primary', 'success', 'danger'.
+            variant (str): Shape of badge. 'pill' or 'square' (default).
+            surface (str): Optional surface token; otherwise inherited.
+            style_options (dict): Optional dict forwarded to the style builder.
+        """
+        kwargs.setdefault('ttk_class', 'TBadge')
+        kwargs.setdefault('anchor', 'center')
+        kwargs.setdefault('font', '-size 8')
+        kwargs.setdefault('variant', 'square')
+        super().__init__(master=master, **kwargs)

bootstack/widgets/primitives/button.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from tkinter import ttk
+from typing import Any, Callable, Literal, Optional, TypedDict, TYPE_CHECKING
+from typing_extensions import Unpack
+
+from bootstack.core.mixins.ttk_state import TtkStateMixin
+from bootstack.core.mixins.widget import WidgetCapabilitiesMixin
+from bootstack.widgets.internal.wrapper_base import TTKWrapperBase
+from bootstack.widgets.mixins import IconMixin, TextSignalMixin, LocalizationMixin
+from bootstack.widgets.types import Master
+
+if TYPE_CHECKING:
+    from bootstack.core.signals import Signal
+
+
+class ButtonKwargs(TypedDict, total=False):
+    # Standard ttk.Button options
+    text: Any
+    command: Optional[Callable[[], Any]]
+    image: Any
+    icon: Any
+    icon_only: bool
+    anchor: str
+    compound: Literal['text', 'image', 'top', 'bottom', 'left', 'right', 'center', 'none'] | str
+    padding: Any
+    width: int
+    underline: int
+    state: Literal['normal', 'active', 'disabled', 'readonly'] | str
+    takefocus: Any
+    localize: bool | Literal['auto']
+    style: str
+    class_: str
+    cursor: str
+    default: Any
+    name: str
+    textvariable: Any
+    textsignal: Signal[str]
+
+    # bootstack-specific extensions
+    bootstyle: str  # DEPRECATED: Use accent and variant instead
+    accent: str
+    density: Literal['default', 'compact']
+    variant: str
+    surface: str
+    style_options: dict[str, Any]
+
+
+class Button(LocalizationMixin, TextSignalMixin, IconMixin, TTKWrapperBase, WidgetCapabilitiesMixin, TtkStateMixin, ttk.Button):
+    """TTK Bootstrap Button
+
+    bootstack wrapper for `ttk.Button` with bootstyle and icon support.
+    """
+    _ttk_base = ttk.Button
+
+    def __init__(self, master: Master = None, **kwargs: Unpack[ButtonKwargs]) -> None:
+        """Create a themed bootstack Button.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+
+        Other Parameters:
+            text (str): Text to display on the button.
+            textvariable (Variable): Tk variable linked to the button text.
+            textsignal (Signal[str]): Reactive Signal linked to the button text (auto-synced with textvariable).
+            command (Callable): Callable invoked when the button is pressed.
+            image (PhotoImage): Image to display on the button.
+            icon (str | dict): Optional icon spec integrated via the style system.
+            icon_only (bool): If true, removes the extra padding reserved for the text labels.
+            compound (str): Placement of the image relative to text (e.g., 'left').
+            padding (int | tuple): Extra space around the button content.
+            anchor (str): Determines how the content is aligned in the container. Combination of 'n', 's', 'e', 'w', or 'center' (default).
+            localize (bool | Literal['auto']): Determines the widgets localization mode.
+            width (int): Width of the button in characters.
+            underline (int): Index of the character to underline in `text`.
+            state (str): Widget state (e.g., 'normal', 'disabled').
+            takefocus (bool): Whether the widget accepts focus during traversal.
+            style (str): Explicit ttk style name to apply (overrides accent/variant).
+            accent (str): Accent token for styling, e.g. 'primary', 'danger', 'success'.
+            variant (str): Style variant, e.g. 'solid', 'outline', 'link', 'text'. Defaults to 'solid'.
+            density (str): The vertical and horizontal compactness of widget content, e.g. 'default', 'compact'.
+            bootstyle (str): DEPRECATED - Use `accent` and `variant` instead.
+            surface (str): Optional surface token to use for this button; if not provided, surface color is inherited from the parent.
+            style_options (dict): Optional dict forwarded to the style builder.
+        """
+        if 'bootstyle' not in kwargs:
+            kwargs.setdefault('variant', 'solid')
+        kwargs.update(style_options=self._capture_style_options(['icon_only', 'icon', 'anchor', 'density'], kwargs))
+        super().__init__(master, **kwargs)

bootstack/widgets/primitives/card.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from typing import Any, TypedDict
+
+from typing_extensions import Unpack
+
+from bootstack.widgets.primitives.frame import Frame
+from bootstack.widgets.types import Master
+
+
+class CardKwargs(TypedDict, total=False):
+    # Standard ttk.Frame options
+    padding: Any
+    width: int
+    height: int
+    style: str
+    cursor: str
+    name: str
+    takefocus: bool
+    class_: str
+
+    # bootstack-specific extensions
+    accent: str
+    variant: str
+    surface: str
+    show_border: bool
+    style_options: dict[str, Any]
+    bootstyle: str  # DEPRECATED: Use accent and variant instead
+
+
+class Card(Frame):
+    """A convenience wrapper for Frame with card styling.
+
+    Card is a Frame with `surface='card'` and `show_border=True` by default,
+    providing an elevated container with a visible border for grouping content.
+
+    Example:
+        ```python
+        card = ttk.Card(app, padding=20)
+        ttk.Label(card, text="Card content").pack()
+        ```
+    """
+
+    def __init__(self, master: Master = None, **kwargs: Unpack[CardKwargs]) -> None:
+        """Create a themed Card container.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+
+        Other Parameters:
+            padding (int | tuple): Extra padding inside the card. Default 16.
+            width (int): Requested width in pixels.
+            height (int): Requested height in pixels.
+            takefocus (bool): Widget accepts focus during keyboard traversal.
+            style (str): Explicit ttk style name (overrides accent/variant).
+            accent (str): Accent/color token for the card. Default 'card'.
+            variant (str): Style variant (if applicable).
+            surface (str): Surface token for the parent background.
+            show_border (bool): Draw a border around the card. Default True.
+            style_options (dict): Optional dict forwarded to the style builder.
+        """
+        if 'bootstyle' not in kwargs:
+            kwargs.setdefault('accent', 'card')
+        kwargs.setdefault('show_border', True)
+        kwargs.setdefault('padding', 16)
+        super().__init__(master, **kwargs)