bootstack 0.1.0a1__py3-none-any.whl

bootstack/widgets/composites/dateentry.py

@@ -0,0 +1,261 @@
+"""Date entry field widget with calendar picker button.
+
+Provides a specialized entry field for date input with locale-aware formatting
+and an optional calendar picker button.
+"""
+
+from datetime import date, datetime
+from typing import TYPE_CHECKING
+
+from typing_extensions import Unpack
+
+from bootstack.widgets.primitives.button import Button
+from bootstack.widgets.composites.field import Field, FieldOptions
+from bootstack.widgets.mixins import configure_delegate
+from bootstack.widgets.types import Master
+
+if TYPE_CHECKING:
+    from bootstack.dialogs.datedialog import DateDialog
+
+
+class DateEntry(Field):
+    """A date entry field widget with calendar picker button.
+
+    DateEntry extends the Field widget to provide specialized date input with
+    locale-aware formatting and an optional calendar picker button. The widget
+    supports various date format presets and custom ICU date format patterns,
+    and can accept input as strings, date objects, or datetime objects.
+
+    The available date format presets are: `longDate` (January 15, 2025),
+    `shortDate` (1/15/25), `monthAndDate` (January 15), `monthAndYear`
+    (January 2025), `quarterAndYear` (Q1 2025), `day` (15), `dayOfWeek`
+    (Wednesday), `month` (January), `quarter` (Q1), `year` (2025),
+    `longTime` (3:30:45 PM PST), `shortTime` (3:30 PM), `longDateLongTime`,
+    `shortDateShortTime`, or any custom ICU date format pattern (e.g., "yyyy-MM-dd").
+
+    !!! note "Events"
+
+        - `<<Change>>`: Fired when date value changes after commit.
+        - `<<Input>>`: Fired on each keystroke.
+        - `<<Valid>>`: Fired when validation passes.
+        - `<<Invalid>>`: Fired when validation fails.
+
+        The calendar picker button uses a DateDialog. The button can be hidden
+        using `show_picker_button=False`.
+
+    Attributes:
+        entry_widget (TextEntryPart): Access to the underlying TextEntryPart widget.
+        label_widget (Label): Access to the label widget.
+        message_widget (Label): Access to the message label widget.
+        addons (dict): Dictionary of inserted addon widgets.
+        variable (Variable): Tkinter Variable linked to entry text.
+        signal (Signal): Signal object for reactive updates.
+        date_picker_button (Button): The calendar picker button widget.
+    """
+
+    def __init__(
+            self,
+            master: Master = None,
+            value: str | date | datetime = None,
+            value_format: str = "longDate",
+            label: str = None,
+            message: str = None,
+            show_picker_button=True,
+            picker_title: str = "Select new date",
+            picker_first_weekday: int = 6,
+            **kwargs: Unpack[FieldOptions]
+    ):
+        """Initialize a DateEntry widget.
+
+        Creates a date entry field with locale-aware formatting and an optional
+        calendar picker button. The widget accepts date input as strings, date
+        objects, or datetime objects, and formats them according to the specified
+        value_format pattern.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+            value (str | date | datetime): Initial date value to display. Can be a
+                date object, datetime object, or string representation.
+            value_format (str): Date format pattern to use for parsing and displaying
+                dates. See class docstring for complete list of presets.
+            label (str): Optional label text to display above the entry field.
+                If required=True, an asterisk (*) is automatically appended.
+            message (str): Optional message text to display below the entry field.
+                Used for hints or help text. Replaced by validation errors when
+                validation fails.
+            show_picker_button (bool): If True, displays the calendar picker button
+                to the right of the entry. If False, hides the button.
+            picker_title (str): Title text for the calendar picker dialog.
+            picker_first_weekday (int): First day of the week to display in the
+                calendar picker. 0=Monday, 6=Sunday.
+
+        Other Parameters:
+            locale (str): Locale identifier for date formatting (e.g., 'en_US').
+            required (bool): If True, field cannot be empty.
+            bootstyle (str): The accent color of the focus ring and active border.
+            allow_blank (bool): Allow empty input.
+            cursor (str): Cursor style when hovering.
+            exportselection (bool): Export selection to clipboard.
+            font (str): Font for text display.
+            foreground (str): Text color.
+            initial_focus (bool): If True, widget receives focus on creation.
+            justify (str): Text alignment ('left', 'center', 'right').
+            show_message (bool): If True, displays message area.
+            padding (int | tuple): Padding around entry widget.
+            takefocus (bool): If True, widget accepts Tab focus.
+            textvariable (Variable): Tkinter Variable to link with text.
+            textsignal (Signal): Signal object for reactive updates.
+            width (int): Width in characters.
+            xscrollcommand (Callable): Callback for horizontal scrolling.
+
+        Note:
+            The widget uses the IntlFormatter for locale-aware date formatting.
+            The value is parsed and formatted automatically when the user commits
+            input (on FocusOut or Return key). Invalid date strings that cannot
+            be parsed will revert to the previous valid value.
+        """
+        kwargs.setdefault('bootstyle', 'primary')
+        super().__init__(master=master, value=value, value_format=value_format, label=label, message=message, **kwargs)
+
+        # configuration
+        self._show_picker_button = show_picker_button
+        self._picker_title = picker_title
+        self._picker_first_weekday = picker_first_weekday
+
+        self._button_pack = {}
+
+        self.insert_addon(
+            Button,
+            position="after",
+            name="date-picker",
+            icon="calendar-week",
+            icon_only=True,
+            command=self._show_date_picker
+        )
+
+        self._delegate_show_picker_button(self._show_picker_button)
+
+    @property
+    def date_picker_button(self):
+        """Get the calendar picker button widget."""
+        return self.addons.get('date-picker')
+
+    @configure_delegate('show_picker_button')
+    def _delegate_show_picker_button(self, value: bool = None):
+        """Get or set the visibility of the calendar picker button."""
+        if value is None:
+            return self._show_picker_button
+        else:
+            if value:
+                if not self.date_picker_button.winfo_ismapped():
+                    self.date_picker_button.pack(**self._button_pack)
+            else:
+                self._button_pack = self.date_picker_button.pack_info()
+                self.date_picker_button.pack_forget()
+        return None
+
+    def _show_date_picker(self):
+        """Open the calendar picker dialog.
+
+        Opens a DateDialog seeded with the current value (if valid), updates
+        the entry when a date is picked, and leaves the field unchanged on
+        cancel.
+        """
+        from bootstack.dialogs.datedialog import DateDialog
+
+        # Prevent multiple dialogs: reuse existing if still open
+        existing = getattr(self, "_active_date_dialog", None)
+        top = getattr(getattr(existing, "_dialog", None), "toplevel", None) if existing else None
+        try:
+            exists = bool(top and top.winfo_exists())
+        except Exception:
+            exists = False
+
+        if exists:
+            try:
+                top.lift()
+                top.focus_force()
+            except Exception:
+                pass
+            return
+        self._active_date_dialog = None
+
+        current_value = self.value
+        if isinstance(current_value, datetime):
+            current_value = current_value.date()
+        if not isinstance(current_value, date):
+            current_value = date.today()
+
+        position = self._picker_position()
+
+        dialog = DateDialog(
+            master=self.winfo_toplevel(),
+            title=self._picker_title,
+            first_weekday=self._picker_first_weekday,
+            initial_date=current_value,
+            accent=self._accent,
+            hide_window_chrome=True,
+            close_on_click_outside=False,  # Disabled to avoid interference with button clicks
+        )
+
+        self._active_date_dialog = dialog
+
+        def _on_result(payload):
+            if isinstance(payload, dict):
+                result = payload.get('result')
+                self.value = result
+            else:
+                self.value = payload
+
+        dialog.on_result(lambda x: _on_result(x))
+        dialog.show(position=position)
+
+        top = getattr(getattr(dialog, "_dialog", None), "toplevel", None)
+        cleared = False
+        try:
+            if top and top.winfo_exists():
+                def _clear(_=None):
+                    self._active_date_dialog = None
+                top.bind("<Destroy>", _clear, add="+")
+                cleared = True
+        except Exception:
+            cleared = False
+        if not cleared:
+            self._active_date_dialog = None
+
+        # Fallback: ensure value is applied after modal dialog closes.
+        selected = dialog.result
+        if isinstance(selected, datetime):
+            selected = selected.date()
+        if isinstance(selected, date):
+            self.value = selected
+
+        # Return focus to the entry after dialog closes
+        # Note: focus_force() is needed on Windows after override-redirect dialogs
+        try:
+            self._entry.focus_force()
+        except Exception:
+            pass
+
+    def _picker_position(self):
+        """Choose a dialog position beneath the entry mirroring SelectBox spacing."""
+        try:
+            # Position relative to the inner field widget, not the whole container
+            # This ensures proper positioning even when message label is visible
+            field_widget = self._field
+            field_widget.update_idletasks()
+            x = field_widget.winfo_rootx() + 4
+            y = field_widget.winfo_rooty() + field_widget.winfo_height() + 2
+            return x, y
+        except Exception:
+            pass
+
+        try:
+            top = self.winfo_toplevel()
+            top.update_idletasks()
+            x = top.winfo_rootx() + top.winfo_width() // 2
+            y = top.winfo_rooty() + top.winfo_height() // 2
+            return x, y
+        except Exception:
+            return None
+

bootstack/widgets/composites/dropdownbutton.py

@@ -0,0 +1,190 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Literal, Optional, TYPE_CHECKING, TypedDict
+
+from typing_extensions import Unpack
+
+from bootstack.widgets.composites.contextmenu import ContextMenu, ContextMenuItem
+from bootstack.widgets.primitives.menubutton import MenuButton
+from bootstack.widgets.mixins import configure_delegate
+from bootstack.widgets.types import Master
+
+if TYPE_CHECKING:
+    from bootstack.core.signals import Signal
+
+
+class DropdownButtonKwargs(TypedDict, total=False):
+    command: Optional[Callable[[], Any]]
+    image: Any
+    icon: Any
+    icon_only: bool
+    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
+    style: str
+    class_: str
+    cursor: str
+    default: Any
+    name: str
+    textvariable: Any
+    textsignal: Signal[str]
+    bootstyle: str  # DEPRECATED: Use accent and variant instead
+    accent: str
+    density: Literal['default', 'compact']
+    variant: str
+    surface: str
+    style_options: dict[str, Any]
+    popdown_options: dict[str, Any]
+    show_dropdown_button: bool
+    dropdown_button_icon: str | dict
+
+
+class DropdownButton(MenuButton):
+
+    def __init__(
+            self,
+            master: Master = None,
+            text: Any = None,
+            items: list[ContextMenuItem] = None,
+            **kwargs: Unpack[DropdownButtonKwargs],
+    ):
+        """Create a dropdown button backed by a ContextMenu.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+            text (str): Label text for the button.
+            items (list): Initial list of ContextMenuItem entries.
+
+        Other Parameters:
+            command (Callable): Callback when the button is activated.
+            image (PhotoImage): Tk image to display.
+            icon (str | dict): Bootstyle icon spec for the button content.
+            icon_only (bool): Whether to reserve label padding when showing only an icon.
+            compound (str): Placement of image relative to text.
+            padding (int | tuple): Extra padding around the button content.
+            density (str): The vertical and horizontal compactness of widget content, e.g. 'default', 'compact'.
+            width (int): Width of the button.
+            underline (int): Index of underlined character in text.
+            state (str): Widget state ('normal', 'active', 'disabled', 'readonly').
+            takefocus (bool): Participation in focus traversal.
+            style (str): Explicit ttk style name.
+            textvariable (Variable): Existing Tk variable for the label text.
+            textsignal (Signal[str]): Signal bound to the textvariable.
+            accent (str): Accent token for styling (e.g., 'primary', 'danger').
+            variant (str): Style variant (e.g., 'outline', 'ghost').
+            bootstyle (str): DEPRECATED - Use `accent` and `variant` instead.
+            surface (str): Surface token for style.
+            style_options (dict): Dict forwarded to the menubutton style builder.
+            popdown_options (dict): Dict forwarded to ContextMenu (e.g., anchor, attach, offset).
+            show_dropdown_button (bool): Show/hide the chevron.
+            dropdown_button_icon (str | dict): Icon name for the chevron.
+        """
+        style_options = kwargs.pop('style_options', {})
+        style_options.update(
+            self._capture_style_options(
+                options=['icon', 'icon_only', 'density', 'show_dropdown_button', 'dropdown_button_icon'],
+                source=kwargs
+            )
+        )
+        kwargs['style_options'] = style_options
+        self._item_click_callback = None
+        self._items = items if items else []
+        self._popdown_options = kwargs.pop('popdown_options', {})
+
+        # Store the textvariable if provided, or create a new one
+        super().__init__(master, text=text, **kwargs)
+
+        # Create menu items that update the shared variable
+        self._context_menu = self._build_context_menu()
+
+        # Bind menu display to button events
+        self.bind('<Button-1>', lambda _: self.show_menu(), add="+")
+        self.bind('<Return>', lambda _: self.show_menu(), add="+")
+        self.bind('<KP_Enter>', lambda _: self.show_menu(), add="+")
+
+        # passthrough methods
+        self.on_item_click = self._context_menu.on_item_click
+        self.add_radiobutton = self._context_menu.add_radiobutton
+        self.add_command = self._context_menu.add_command
+        self.add_checkbutton = self._context_menu.add_checkbutton
+        self.add_separator = self._context_menu.add_separator
+        self.add_item = self._context_menu.add_item
+        self.add_items = self._context_menu.add_items
+        self.insert_item = self._context_menu.insert_item
+        self.remove_item = self._context_menu.remove_item
+        self.move_item = self._context_menu.move_item
+        self.configure_item = self._context_menu.configure_item
+        self.items = self._context_menu.items
+
+    def on_item_click(self, callback: Callable) -> None:
+        """Set item click callback. Callback receives `item_info = {'type': str, 'text': str, 'value': Any}`."""
+        self._item_click_callback = callback
+        self._context_menu.on_item_click(callback)
+
+    def off_item_click(self) -> None:
+        """Remove the item click callback."""
+        self._item_click_callback = None
+        self._context_menu.on_item_click(None)
+
+    def _build_context_menu(self):
+        """Construct the ContextMenu with current items and options."""
+        # Offset compensates for the focus-ring affordance baked into the
+        # button image so the dropdown's left edge aligns with the visible
+        # button border. Same treatment as OptionMenu.
+        from bootstack.style.bootstyle_builder_base import BootstyleBuilderBase
+        offset_x = BootstyleBuilderBase.scale_from_source(10)
+        density = self.configure_style_options('density') or 'default'
+        options = {
+            "anchor": "nw",
+            "attach": "sw",
+            "offset": (offset_x, 0),
+            "density": density,
+        }
+        options.update(self._popdown_options)
+        # DropdownButton manages its own activation (left-click, Return/
+        # KP_Enter via show_menu), so opt out of ContextMenu's auto-trigger.
+        cm = ContextMenu(self, target=self, items=self._items, trigger=None, **options)
+        if self._item_click_callback:
+            self.on_item_click(self._item_click_callback)
+        return cm
+
+    @property
+    def context_menu(self):
+        """Returns the context menu widget"""
+        return self._context_menu
+
+    def show_menu(self):
+        """Show the dropdown menu unless disabled or readonly."""
+        if not self.instate(("!disabled", "!readonly")):
+            return
+        self._context_menu.show()
+
+    @configure_delegate('popdown_options')
+    def _delegate_popdown_options(self, value=None):
+        if value is None:
+            return self._popdown_options
+        else:
+            self._popdown_options = value
+            return self.context_menu.configure(**value)
+
+    @configure_delegate('show_dropdown_button')
+    def _delegate_show_dropdown_button(self, value=None):
+        """Get or set visibility of the dropdown chevron."""
+        if value is None:
+            return self.configure_style_options('show_dropdown_button')
+        else:
+            self.configure_style_options(show_dropdown_button=value)
+            return self.rebuild_style()
+
+    @configure_delegate('dropdown_button_icon')
+    def _delegate_dropdown_button_icon(self, value=None):
+        """Get or set the dropdown chevron icon name."""
+        if value is None:
+            return self.configure_style_options('dropdown_button_icon')
+        else:
+            self.configure_style_options(dropdown_button_icon=value)
+            return self.rebuild_style()
+