bootstack 0.1.0a1__py3-none-any.whl

bootstack/widgets/composites/tabs/tabview.py

@@ -0,0 +1,352 @@
+"""TabView widget - a tabbed container combining Tabs with PageStack."""
+from __future__ import annotations
+
+__all__ = ['TabView']
+
+import tkinter as tk
+from typing import Callable, Literal, Union
+
+from bootstack.widgets.primitives.frame import Frame
+from bootstack.widgets.composites.tabs.tabs import Tabs
+from bootstack.widgets.composites.tabs.tabitem import TabItem
+from bootstack.widgets.composites.pagestack import PageStack
+from bootstack.widgets.types import Master
+
+
+class TabView(Frame):
+    """A tabbed container that combines Tabs with a PageStack.
+
+    TabView provides a complete tabbed interface where each tab corresponds
+    to a page in the page stack. Selecting a tab navigates to the associated
+    page.
+
+    !!! note "Events"
+        - `<<TabSelect>>`: Fired when a tab is selected.
+        - `<<TabClose>>`: Fired when a tab's close button is clicked.
+        - `<<TabAdd>>`: Fired when the add button is clicked (if enable_adding=True).
+        - `<<PageChange>>`: Fired when the page changes (from PageStack).
+    """
+
+    def __init__(
+        self,
+        master: Master = None,
+        orient: Literal['horizontal', 'vertical'] = 'horizontal',
+        variant: Literal['pill', 'bar'] = 'bar',
+        show_divider: bool = None,
+        compound: Literal['left', 'right', 'top', 'bottom', 'center', 'none'] = 'left',
+        tab_width: Union[None, int, Literal['stretch']] = None,
+        tab_padding: tuple = (12, 8),
+        tab_anchor: str = None,
+        enable_closing: Union[bool, Literal['hover']] = False,
+        enable_adding: bool = False,
+        accent: str = None,
+        **kwargs
+    ):
+        """Create a TabView widget.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+            orient: Orientation of the tab bar. 'horizontal' places tabs above
+                the content, 'vertical' places tabs to the left. Default is 'horizontal'.
+            variant: Visual style variant ('pill' or 'bar').
+            show_divider: Whether to show a divider between tabs and content.
+            compound: How to position icon relative to text in tabs.
+            tab_width: Width of tabs (None, integer, or 'stretch').
+            tab_padding: Padding for all tabs as (horizontal, vertical).
+            tab_anchor: Anchor for tab text/icon alignment. If None, defaults
+                to 'w' for vertical orientation, 'center' for horizontal.
+            enable_closing: Default close button visibility for all tabs.
+                True=always visible, False=hidden, 'hover'=visible on hover.
+                Can be overridden per-tab via `closable` in add().
+            enable_adding: If True, shows an "add" button that fires `<<TabAdd>>`.
+            accent: Accent token for styling.
+            **kwargs: Additional arguments passed to Frame.
+        """
+        super().__init__(master, **kwargs)
+
+        self._orient = orient
+        self._variant = variant
+        self._accent = accent
+
+        # Create internal variable for tab selection
+        self._tab_variable = tk.StringVar()
+
+        # Create tabs container
+        self._tabs = Tabs(
+            self,
+            orient=orient,
+            variant=variant,
+            show_divider=show_divider,
+            compound=compound,
+            tab_width=tab_width,
+            tab_padding=tab_padding,
+            tab_anchor=tab_anchor,
+            enable_closing=enable_closing,
+            enable_adding=enable_adding,
+            variable=self._tab_variable,
+            accent=accent,
+        )
+
+        # Create page stack
+        self._page_stack = PageStack(self)
+
+        # Layout based on orientation
+        if orient == 'horizontal':
+            self._tabs.pack(side='top', fill='x')
+            self._page_stack.pack(side='top', fill='both', expand=True)
+        else:
+            self._tabs.pack(side='left', fill='y')
+            self._page_stack.pack(side='left', fill='both', expand=True)
+
+        # Bind variable trace to navigate pages
+        self._trace_id = self._tab_variable.trace_add('write', self._on_tab_selected)
+
+        # Track tabs by key for removal
+        self._tab_map: dict[str, TabItem] = {}
+
+        # Clean up trace on destroy
+        self.bind('<Destroy>', self._on_destroy, add='+')
+
+    def _on_destroy(self, event=None):
+        """Clean up variable trace when widget is destroyed."""
+        if event.widget is not self:
+            return
+        if self._trace_id is not None:
+            try:
+                self._tab_variable.trace_remove('write', self._trace_id)
+            except Exception:
+                pass
+            self._trace_id = None
+
+    def _on_tab_selected(self, *args):
+        """Handle tab selection to navigate page stack."""
+        key = self._tab_variable.get()
+        if key and key in self._tab_map:
+            # Only navigate if not already on this page
+            current = self._page_stack.current()
+            if current is None or current[0] != key:
+                self._page_stack.navigate(key)
+
+    def add(
+        self,
+        key: str,
+        text: str = "",
+        icon: str | dict = None,
+        page: tk.Widget = None,
+        closable: Union[bool, Literal['hover'], None] = None,
+        close_command: Callable = None,
+        command: Callable = None,
+        **kwargs
+    ) -> tk.Widget:
+        """Add a tab and its associated page.
+
+        Args:
+            key: Unique identifier for the tab/page.
+            text: Text to display on the tab.
+            icon: Icon to display on the tab.
+            page: The page widget. If None, creates a Frame.
+            closable: Close button visibility (True, False, 'hover', or None).
+                If None, uses the widget's `enable_closing` setting.
+            close_command: Callback when close button is clicked.
+                If not provided and closable is enabled, removes the tab/page.
+            command: Callback when tab is selected.
+            **kwargs: Additional arguments passed to page Frame (if created).
+
+        Returns:
+            The page widget.
+        """
+        # Determine effective closable value
+        effective_closable = closable if closable is not None else self._tabs._enable_closing
+
+        # Create close command wrapper if closable but no command provided
+        if effective_closable and close_command is None:
+            close_command = lambda k=key: self.remove(k)
+
+        # Add tab
+        tab = self._tabs.add(
+            text=text,
+            icon=icon,
+            value=key,
+            closable=closable,
+            close_command=close_command,
+            command=command,
+        )
+        self._tab_map[key] = tab
+
+        # Add page
+        page_widget = self._page_stack.add(key, page, **kwargs)
+
+        # If this is the first tab, select it
+        if len(self._tab_map) == 1:
+            self._tab_variable.set(key)
+
+        return page_widget
+
+    def remove(self, key: str) -> None:
+        """Remove a tab and its associated page.
+
+        Args:
+            key: The identifier of the tab/page to remove.
+        """
+        # Remove tab
+        if key in self._tab_map:
+            tab = self._tab_map.pop(key)
+            self._tabs.remove(tab)
+            tab.destroy()
+
+        # Remove page
+        self._page_stack.remove(key)
+
+        # If the removed tab was selected, select another
+        if self._tab_variable.get() == key:
+            if self._tab_map:
+                # Select the first available tab
+                first_key = next(iter(self._tab_map))
+                self._tab_variable.set(first_key)
+            else:
+                self._tab_variable.set('')
+
+    def select(self, key: str) -> None:
+        """Select a tab by its key.
+
+        Args:
+            key: The identifier of the tab to select.
+        """
+        if key in self._tab_map:
+            self._tab_variable.set(key)
+
+    def navigate(self, key: str, data: dict = None) -> None:
+        """Navigate to a tab/page with optional data.
+
+        Args:
+            key: The identifier of the tab/page to navigate to.
+            data: Optional data to pass to the page.
+        """
+        if key in self._tab_map:
+            self._tab_variable.set(key)
+            if data:
+                self._page_stack.navigate(key, data=data)
+
+    @property
+    def tabs_widget(self) -> Tabs:
+        """Get the internal Tabs widget."""
+        return self._tabs
+
+    @property
+    def page_stack_widget(self) -> PageStack:
+        """Get the internal PageStack widget."""
+        return self._page_stack
+
+    @property
+    def current(self) -> str | None:
+        """Get the currently selected tab key."""
+        key = self._tab_variable.get()
+        return key if key else None
+
+    def page(self, key: str) -> tk.Widget:
+        """Get a page widget by its key.
+
+        Args:
+            key: The identifier of the page.
+
+        Returns:
+            The page widget.
+
+        Raises:
+            KeyError: If no page with the given key exists.
+        """
+        return self._page_stack.item(key)
+
+    def pages(self) -> tuple[tk.Widget, ...]:
+        """Get all page widgets.
+
+        Returns:
+            A tuple of all page widgets.
+        """
+        return self._page_stack.items()
+
+    def page_keys(self) -> tuple[str, ...]:
+        """Get all page keys.
+
+        Returns:
+            A tuple of all page keys.
+        """
+        return self._page_stack.keys()
+
+    def tab(self, key: str) -> TabItem:
+        """Get a tab widget by its key.
+
+        Args:
+            key: The identifier of the tab.
+
+        Returns:
+            The TabItem widget.
+
+        Raises:
+            KeyError: If no tab with the given key exists.
+        """
+        if key not in self._tab_map:
+            raise KeyError(f"No tab with key '{key}'")
+        return self._tab_map[key]
+
+    def tabs(self) -> tuple[TabItem, ...]:
+        """Get all tab widgets.
+
+        Returns:
+            A tuple of all TabItem widgets.
+        """
+        return tuple(self._tab_map.values())
+
+    def tab_keys(self) -> tuple[str, ...]:
+        """Get all tab keys.
+
+        Returns:
+            A tuple of all tab keys.
+        """
+        return tuple(self._tab_map.keys())
+
+    def configure_tab(self, key: str, option: str = None, **kwargs):
+        """Configure a specific tab by its key.
+
+        Args:
+            key: The key of the tab to configure.
+            option: If provided, return the value of this option.
+            **kwargs: Configuration options to apply to the tab.
+
+        Returns:
+            If option is provided, returns the value of that option.
+        """
+        tab = self.tab(key)
+        if option is not None:
+            return tab.cget(option)
+        tab.configure(**kwargs)
+
+    def on_page_changed(self, callback: Callable) -> str:
+        """Bind to `<<PageChange>>` event.
+
+        Args:
+            callback: Function to call when page changes.
+
+        Returns:
+            Binding identifier.
+        """
+        return self._page_stack.on_page_changed(callback)
+
+    def off_page_changed(self, bind_id: str | None = None) -> None:
+        """Unbind from `<<PageChange>>` event."""
+        self._page_stack.off_page_changed(bind_id)
+
+    def on_tab_added(self, callback: Callable) -> str:
+        """Bind to `<<TabAdd>>` event (when add button is clicked).
+
+        Args:
+            callback: Function to call when add button is clicked.
+
+        Returns:
+            Binding identifier for use with off_tab_added().
+        """
+        return self._tabs.on_tab_added(callback)
+
+    def off_tab_added(self, bind_id: str | None = None) -> None:
+        """Unbind from `<<TabAdd>>` event."""
+        self._tabs.off_tab_added(bind_id)

bootstack/widgets/composites/textentry.py

@@ -0,0 +1,90 @@
+from typing import Any
+
+from typing_extensions import Unpack
+
+from bootstack.widgets.composites.field import Field, FieldOptions
+from bootstack.widgets.types import Master
+
+
+class TextEntry(Field):
+    """A text entry field widget with label, validation, and formatting support.
+
+    TextEntry is a composite widget that combines a label, text entry input, and
+    message area into a single component. It provides internationalization-aware
+    text input with deferred parsing, validation support, and visual feedback.
+
+    The widget separates user input (display text) from the committed/parsed value,
+    only parsing and formatting when the user commits via `<FocusOut>` or `<Return>`.
+
+    !!! note "Events"
+
+        - `<<Input>>`: Triggered on each keystroke.
+          Provides `event.data` with keys: `text`.
+
+        - `<<Change>>`: Triggered when value changes after commit.
+          Provides `event.data` with keys: `value`, `prev_value`, `text`.
+
+        - `<<Valid>>`: Triggered when validation passes.
+          Provides `event.data` with keys: `value`, `is_valid` (True), `message`.
+
+        - `<<Invalid>>`: Triggered when validation fails.
+          Provides `event.data` with keys: `value`, `is_valid` (False), `message`.
+
+        - `<<Validate>>`: Triggered after any validation.
+          Provides `event.data` with keys: `value`, `is_valid` (bool), `message`.
+
+    Attributes:
+        entry_widget (TextEntryPart): The underlying text entry widget.
+        label_widget (Label): The label widget above the entry.
+        message_widget (Label): The message label widget below the entry.
+        addons (dict[str, Widget]): Dictionary of inserted addon widgets by name.
+        variable (Variable): Tkinter Variable linked to entry text.
+        signal (Signal): Signal object for reactive updates.
+    """
+
+    def __init__(
+            self, master: Master = None, value: Any = None, label: str = None, message: str = None,
+            **kwargs: Unpack[FieldOptions]):
+        """Initialize a TextEntry widget.
+
+        Creates a composite text entry field with optional label, validation,
+        and formatting support. The widget includes a label area, entry input,
+        and message area for displaying hints or validation errors.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+            value: Initial value to display. Default is None.
+            label: Optional label text to display above the entry field.
+                If required=True, an asterisk (*) is automatically appended.
+            message: Optional message text to display below the entry field.
+                This is replaced by validation error messages when validation fails.
+
+        Other Parameters:
+            allow_blank (bool): Allow empty input. Default is True.
+            color (str): Color token for the focus ring and active border.
+            bootstyle (str): DEPRECATED - Use `color` instead.
+            cursor (str): Cursor style when hovering.
+            value_format (str): ICU format pattern for parsing/formatting.
+            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. Default is True.
+            padding: Padding around entry widget.
+            show (str): Character to mask input (e.g., '*' for passwords).
+            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.
+            required (bool): If True, field cannot be empty. Adds 'required'
+                validation rule and appends '*' to label.
+            xscrollcommand: Callback for horizontal scrolling.
+
+        Note:
+            The widget automatically sets up event handlers for focus, validation,
+            and value commits. Use on_input(), on_changed(), on_valid(), and
+            on_invalid() methods to bind callbacks to widget events.
+        """
+        super().__init__(master, value=value, label=label, message=message, **kwargs)
+

bootstack/widgets/composites/timeentry.py

@@ -0,0 +1,189 @@
+"""Time entry field widget with dropdown list of time intervals.
+
+Provides a specialized entry field for time input with a searchable dropdown
+list of time values at specified intervals.
+"""
+
+import datetime
+from typing import Union
+
+from typing_extensions import Unpack
+
+from bootstack.runtime.app import get_app_settings
+from bootstack.core.localization import IntlFormatter
+from bootstack.widgets.composites.field import FieldOptions
+from bootstack.widgets.composites.selectbox import SelectBox
+from bootstack.widgets.types import Master
+
+
+class TimeEntry(SelectBox):
+    """Time entry field with dropdown list of time intervals.
+
+    TimeEntry extends SelectBox to provide specialized time input with
+    locale-aware formatting and a searchable dropdown of time intervals.
+    The widget supports various time format presets and custom time patterns.
+
+    !!! note "Events"
+
+        - `<<Change>>`: Fired when time value changes after commit.
+        - `<<Input>>`: Fired on each keystroke.
+        - `<<Valid>>`: Fired when validation passes.
+        - `<<Invalid>>`: Fired when validation fails.
+
+    Attributes:
+        entry_widget (TextEntryPart): The underlying text entry widget.
+        label_widget (Label): The label widget above the entry.
+        message_widget (Label): The message label widget below the entry.
+        addons (dict[str, Widget]): Dictionary of inserted addon widgets by name.
+        variable (Variable): Tkinter Variable linked to entry text.
+        signal (Signal): Signal object for reactive updates.
+    """
+
+    def __init__(
+            self,
+            master: Master = None,
+            value: Union[datetime.time, str] = None,
+            value_format: str = 'shortTime',
+            interval: int = 30,
+            min_time: Union[datetime.time, str] = None,
+            max_time: Union[datetime.time, str] = None,
+            label: str = None,
+            message: str = None,
+            **kwargs: Unpack[FieldOptions]
+    ):
+        """Initialize a TimeEntry widget.
+
+        Creates a time entry field with locale-aware formatting and a searchable
+        dropdown of time intervals. The widget accepts time input as time objects
+        or strings, and formats them according to the specified value_format pattern.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+            value: Initial time value to display. Can be a time object or string.
+                Default is current time.
+            value_format: Time format pattern for parsing and displaying times.
+                Default is "shortTime" (e.g., "3:30 PM"). Common formats:
+                "shortTime" (3:30 PM), "longTime" (3:30:45 PM PST),
+                "mediumTime" (3:30:45 PM), "HH:mm" (15:30), "h:mm a" (3:30 PM).
+            interval: Time interval in minutes for dropdown items (e.g., 15, 30, 60).
+                Default is 30 minutes.
+            min_time: Minimum time value for the dropdown list. Can be a time object
+                or string (e.g., "09:00" or "9:00 AM"). Default is midnight (00:00).
+            max_time: Maximum time value for the dropdown list. Can be a time object
+                or string (e.g., "17:00" or "5:00 PM"). Default is 11:59 PM (23:59).
+            label: Optional label text to display above the entry field.
+                If required=True, an asterisk (*) is automatically appended.
+            message: Optional message text to display below the entry field.
+                Used for hints or help text. Replaced by validation errors when
+                validation fails.
+
+        Other Parameters:
+            locale (str): Locale identifier for time formatting (e.g., 'en_US').
+            required (bool): If True, field cannot be empty.
+            color (str): Color token for the focus ring and active border.
+            bootstyle (str): DEPRECATED - Use `color` instead.
+            allow_blank (bool): Allow empty input.
+            width (int): Width in characters.
+            textvariable (Variable): Tkinter Variable to link with text.
+            textsignal (Signal): Signal object for reactive updates.
+
+        Note:
+            The widget uses IntlFormatter for locale-aware time formatting.
+            The dropdown is searchable - type to filter time values.
+            Custom time values can be entered directly in the field.
+        """
+        self._interval = interval
+        self._value_format = value_format
+        self._locale = kwargs.get('locale') or get_app_settings().locale
+
+        # Parse and store time range
+        self._min_time = self._parse_time(min_time) if min_time else datetime.time(0, 0)
+        self._max_time = self._parse_time(max_time) if max_time else datetime.time(23, 59)
+
+        # Default to current time if not provided
+        if value is None:
+            value = datetime.datetime.now().time()
+
+        # Generate time intervals for dropdown
+        items = self._generate_time_intervals()
+
+        # Initialize SelectBox with time-specific configuration
+        super().__init__(
+            master=master,
+            value=value,
+            value_format=value_format,
+            items=items,
+            allow_custom_values=True,
+            enable_search=True,
+            dropdown_button_icon='clock',
+            message=message,
+            label=label,
+            **kwargs
+        )
+
+    def _parse_time(self, time_value: Union[datetime.time, str]) -> datetime.time:
+        """Parse time value from various input formats.
+
+        Args:
+            time_value: Time value as time object or string
+
+        Returns:
+            Parsed time object, or midnight (00:00) if parsing fails
+        """
+        if isinstance(time_value, datetime.time):
+            return time_value
+
+        if isinstance(time_value, str):
+            # Try 24-hour format (HH:MM)
+            try:
+                dt = datetime.datetime.strptime(time_value, '%H:%M')
+                return dt.time()
+            except ValueError:
+                pass
+
+            # Try 12-hour format (h:MM AM/PM)
+            try:
+                dt = datetime.datetime.strptime(time_value, '%I:%M %p')
+                return dt.time()
+            except ValueError:
+                pass
+
+        # Fallback to midnight
+        return datetime.time(0, 0)
+
+    def _generate_time_intervals(self) -> list[str]:
+        """Generate list of formatted time strings at specified intervals.
+
+        Creates a list of time values from min_time to max_time at the specified
+        interval, formatted according to value_format. Uses IntlFormatter for
+        consistent locale-aware formatting with Field.
+
+        Returns:
+            List of formatted time strings
+        """
+        times = []
+        formatter = IntlFormatter(locale=self._locale)
+
+        # Convert time objects to datetime for iteration
+        current = datetime.datetime.combine(datetime.date.today(), self._min_time)
+        end = datetime.datetime.combine(datetime.date.today(), self._max_time)
+
+        # Handle midnight crossing (e.g., min_time=22:00, max_time=02:00)
+        if end < current:
+            end += datetime.timedelta(days=1)
+
+        # Generate intervals
+        while current <= end:
+            # Format using IntlFormatter (consistent with TextEntryPart)
+            # Note: Pass datetime (not time) as IntlFormatter expects it for Babel
+            try:
+                formatted_time = formatter.format(current, self._value_format)
+            except (ValueError, TypeError):
+                # Fallback to 24-hour format if formatting fails
+                formatted_time = current.strftime('%H:%M')
+
+            times.append(formatted_time)
+            current += datetime.timedelta(minutes=self._interval)
+
+        return times
+