bootstack 0.1.0a1__py3-none-any.whl

bootstack/widgets/composites/pathentry.py

@@ -0,0 +1,223 @@
+"""Path entry field widget with file/directory chooser dialog.
+
+Provides an entry field with a button that opens a file or directory chooser
+dialog for selecting paths.
+"""
+
+from tkinter import filedialog
+from typing import Any, Literal
+
+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
+
+FileDialogType = Literal[
+    'openfilename', 'openfile', 'directory', 'openfilenames', 'openfiles',
+    'saveasfile', 'saveasfilename'
+]
+"""Type alias for file dialog types.
+
+Available dialog types:
+    - 'openfilename': Select a single existing file (returns filename)
+    - 'openfile': Select a single existing file (returns file object)
+    - 'directory': Select a directory
+    - 'openfilenames': Select multiple existing files (returns filenames)
+    - 'openfiles': Select multiple existing files (returns file objects)
+    - 'saveasfile': Select location to save a file (returns file object)
+    - 'saveasfilename': Select location to save a file (returns filename)
+"""
+
+
+class PathEntry(Field):
+    """A path entry field widget with file/directory chooser dialog button.
+
+    PathEntry extends the Field widget to provide a specialized input for file
+    and directory paths. It includes a button that opens a native file/directory
+    chooser dialog, and displays the selected path(s) in the entry field. The
+    widget supports various dialog types including single file selection, multiple
+    file selection, directory selection, and save file dialogs.
+
+    !!! note "Events"
+
+        `<<Change>>`: Fired when a path is selected from the dialog.
+          Provides `event.data` with keys: `value`, `prev_value`, `text`, `dialog_result`.
+
+        `<<Input>>`: Fired when user manually types in the entry.
+
+        `<<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 (from FieldOptions).
+        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.
+        dialog_result (Any): The raw result from the last file dialog operation.
+        dialog_button (Button): The button widget that opens the dialog.
+    """
+
+    def __init__(
+            self,
+            master: Master = None,
+            *,
+            value: str | None = None,
+            dialog: FileDialogType = "openfilename",
+            dialog_options: dict[str, Any] | None = None,
+            button_text: str = "Browse",
+            label: str = None,
+            message: str = None,
+            **kwargs: Unpack[FieldOptions]
+    ):
+        """Initialize a PathEntry widget.
+
+        Creates a path entry field with a button that opens a native file or
+        directory chooser dialog. The selected path(s) are automatically displayed
+        in the entry field. The widget supports various dialog types for different
+        use cases (single file, multiple files, directory, save file).
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+            value: Initial path value to display in the entry field. Default is None
+                (empty field). This is updated when a path is selected from the dialog.
+            dialog: Type of file dialog to open. Default is "openfilename".
+                Options:
+
+                - 'openfilename': Single file selection (returns path string)
+                - 'openfile': Single file selection (returns file object)
+                - 'directory': Directory selection
+                - 'openfilenames': Multiple file selection (returns paths)
+                - 'openfiles': Multiple file selection (returns file objects)
+                - 'saveasfile': Save file dialog (returns file object)
+                - 'saveasfilename': Save file dialog (returns path string)
+
+            dialog_options: Dictionary of options to pass to the file dialog.
+                Common options: title, initialdir, initialfile, filetypes,
+                defaultextension, multiple.
+            button_text: Text to display on the browse button. Default is "Browse".
+                Can be changed at runtime via `configure(button_text=...)`.
+            label (str): Label text to display above the entry field (from FieldOptions).
+            message (str): Message text to display below the field.
+
+        Other Parameters:
+            required (bool): If True, field cannot be empty.
+            accent (str): Accent token for the focus ring and active border.
+            allow_blank (bool): Allow empty input.
+            cursor (str): Cursor style when hovering.
+            font (str): Font for text display.
+            foreground (str): Text color.
+            initial_focus (bool): If True, widget receives focus on creation.
+            justify (str): Text alignment.
+            show_message (bool): If True, displays message area.
+            padding (str): 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.
+
+        Note:
+            When multiple files are selected (using 'openfilenames' or 'openfiles'),
+            the paths are joined with ", " (comma-space) and displayed in the entry.
+            The raw dialog result (tuple/list) is available via the `dialog_result`
+            property.
+        """
+        self._dialog = dialog
+        self._dialog_options = dialog_options
+        self._dialog_result = None
+        self._button_text = button_text
+        self._prev_value: str | None = value
+
+        super().__init__(master=master, label=label, message=message, value=value, **kwargs)
+
+        self.insert_addon(
+            Button,
+            position="before",
+            name="dialog-button",
+            text=self._button_text,
+            command=self._show_file_chooser
+        )
+
+    @property
+    def dialog_button(self):
+        """Get the dialog button widget."""
+        return self.addons.get('dialog-button')
+
+    @property
+    def dialog_result(self):
+        """Get the raw result from the last file dialog operation.
+
+        For single file selection, this returns the path string.
+        For multiple file selection, this returns a tuple/list of paths.
+        """
+        return self._dialog_result
+
+    # ------ Configuration Delegates ------
+
+    @configure_delegate('dialog')
+    def _delegate_dialog(self, value: FileDialogType = None):
+        if value is None:
+            return self._dialog
+        else:
+            self._dialog = value
+        return None
+
+    @configure_delegate('button_text')
+    def _delegate_button_text(self, value: str = None):
+        if value is None:
+            return self._button_text
+        else:
+            self._button_text = value
+            if self.dialog_button:
+                self.dialog_button['text'] = value
+        return None
+
+    @configure_delegate('dialog_options')
+    def _delegate_dialog_options(self, value: dict[str, Any] = None):
+        if value is None:
+            return self._dialog_options
+        else:
+            self._dialog_options = value
+        return None
+
+    def _show_file_chooser(self):
+        """Open the file/directory chooser dialog and update the entry."""
+        method_name = f"ask{self._dialog}"
+        dialog_func = getattr(filedialog, method_name, None)
+
+        if dialog_func is None:
+            raise ValueError(f"Invalid dialog type `{self._dialog}`")
+
+        result = dialog_func(**(self._dialog_options or {}))
+        self._dialog_result = result
+
+        # Format display text for multiple selections
+        if isinstance(result, (tuple, list)):
+            display_text = ", ".join(str(p) for p in result)
+        else:
+            display_text = result
+
+        # Only update if a selection was made (result is truthy)
+        if result:
+            prev_value = self._prev_value
+            self._prev_value = display_text
+
+            # Set the value through the field's standard mechanism
+            self.value = display_text
+
+            # Emit <<Change>> on PathEntry (the composite) with full event data
+            self.event_generate(
+                '<<Change>>',
+                data={
+                    'value': display_text,
+                    'prev_value': prev_value,
+                    'text': display_text,
+                    'dialog_result': self._dialog_result,
+                },
+                when="tail"
+            )
+

bootstack/widgets/composites/radiogroup.py

@@ -0,0 +1,466 @@
+from __future__ import annotations
+
+from tkinter import StringVar
+from typing import Any, Callable, Literal, TYPE_CHECKING
+
+from typing_extensions import TypedDict, Unpack
+
+from bootstack.widgets.primitives.radiobutton import RadioButton
+from bootstack.widgets.primitives.label import Label
+from bootstack.widgets.mixins.configure_mixin import configure_delegate
+from bootstack.widgets.primitives import Frame
+from bootstack.widgets.types import Master
+
+if TYPE_CHECKING:
+    from bootstack.core.signals import Signal
+    import tkinter as tk
+
+
+class RadioGroupKwargs(TypedDict, total=False):
+    variable: Any
+    signal: Signal[Any]
+    value: str
+    orient: Literal['horizontal', 'vertical']
+    accent: str
+    text: str
+    labelanchor: Literal['n', 's', 'e', 'w', 'ne', 'nw', 'se', 'sw']
+    state: Literal['normal', 'disabled']
+    show_border: bool
+    surface: str
+    style_options: dict[str, Any]
+    # Frame options
+    padding: Any
+    width: int
+    height: int
+
+
+class RadioGroup(Frame):
+    """A group of radio buttons with automatic state tracking and optional label.
+
+    The RadioGroup widget provides a convenient way to create groups of radio
+    buttons with automatic state management. It supports both horizontal and
+    vertical orientations, and can display an optional label in various positions.
+
+    Attributes:
+        variable (Variable): The underlying tk.Variable for the selected value.
+        signal (Signal): Signal for reactive programming and change subscriptions.
+    """
+
+    def __init__(self, master: Master = None, **kwargs: Unpack[RadioGroupKwargs]):
+        """Initialize the RadioGroup.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+
+        Other Parameters:
+            orient (str): Layout orientation - 'horizontal' (default) or 'vertical'.
+            accent (str): Accent token for styling (e.g., 'primary', 'success', 'danger').
+                Defaults to 'primary'.
+            bootstyle (str): DEPRECATED - Use `accent` instead.
+            text (str): Optional label text to display.
+            labelanchor (str): Label position - 'n' (top, default), 's' (bottom),
+                'e' (right), 'w' (left), or combinations like 'nw', 'ne', etc.
+            variable (Variable): Optional tk.StringVar for controlling the selected value.
+            signal (Signal): Optional Signal instance for reactive programming.
+            value (str): Initial selected value.
+            state (str): Initial state for all buttons - 'normal' (default) or 'disabled'.
+            show_border (bool): If True, draws a border around the group.
+            surface (str): Optional surface token; otherwise inherited.
+            style_options (dict): Additional style options passed to child buttons.
+            padding (int | tuple): Frame padding. Defaults to 1.
+            width (int): Requested width in pixels.
+            height (int): Requested height in pixels.
+        """
+        # Extract RadioGroup-specific options before super().__init__
+        self._orientation = kwargs.pop('orient', 'horizontal')
+        # Support both 'accent' and legacy 'bootstyle'
+        self._accent = kwargs.pop('accent', None) or kwargs.pop('bootstyle', 'primary')
+        self._labeltext = kwargs.pop('text', None)
+        self._labelanchor = kwargs.pop('labelanchor', 'n')
+        self._state = kwargs.pop('state', 'normal')
+
+        # Handle signal/variable/value
+        initial_value = kwargs.pop('value', None)
+        style_options = kwargs.pop('style_options', {})
+
+        # Initialize internal state
+        self._buttons: dict[str, RadioButton] = {}
+        self._label: Label | None = None
+        self._button_container: Frame | None = None
+
+        # Extract signal/variable before Frame init
+        signal_value = kwargs.pop('signal', None)
+        variable_value = kwargs.pop('variable', None)
+
+        # Handle padding default
+        if 'padding' not in kwargs:
+            kwargs['padding'] = 1
+
+        # Call super().__init__() - just Frame now
+        super().__init__(master, style_options=style_options, **kwargs)
+
+        # Handle variable/signal setup manually
+        if signal_value is not None:
+            # Signal provided - extract its variable
+            self._signal = signal_value
+            self._variable = signal_value.var
+        elif variable_value is not None:
+            # Variable provided - wrap in Signal
+            from bootstack.core.signals import Signal
+            self._variable = variable_value
+            self._signal = Signal.from_variable(variable_value)
+            # Set initial value if provided
+            if initial_value is not None:
+                self._variable.set(initial_value)
+        else:
+            # Neither provided - create internal variable
+            from bootstack.core.signals import Signal
+            internal_var = StringVar(value=initial_value or '')
+            self._variable = internal_var
+            self._signal = Signal.from_variable(internal_var)
+
+        # Build the UI
+        self._build_ui()
+
+    def _build_ui(self):
+        """Construct the widget layout."""
+        # Create button container
+        self._button_container = Frame(self)
+
+        # Create label if text provided
+        if self._labeltext:
+            self._label = Label(self, text=self._labeltext)
+
+        # Position based on labelanchor
+        self._update_layout()
+
+    def _update_layout(self):
+        """Update grid layout based on labelanchor."""
+        # Clear existing layout
+        for widget in self.winfo_children():
+            widget.grid_forget()
+
+        # Determine anchor direction from labelanchor
+        # n/s = top/bottom, e/w = right/left
+        anchor = self._labelanchor.lower()
+
+        # Normalize compound anchors to primary direction
+        # Priority: n > s > w > e (vertical placement preferred over horizontal)
+        if 'n' in anchor:
+            primary = 'n'
+        elif 's' in anchor:
+            primary = 's'
+        elif 'w' in anchor:
+            primary = 'w'
+        elif 'e' in anchor:
+            primary = 'e'
+        else:
+            # Default to north
+            primary = 'n'
+
+        # Layout based on primary anchor
+        if primary == 'n':
+            # Label on top
+            if self._label:
+                self._label.grid(row=0, column=0, sticky='w', pady=(0, 4))
+            self._button_container.grid(row=1, column=0, sticky='ew')
+            self.grid_columnconfigure(0, weight=1)
+        elif primary == 's':
+            # Label on bottom
+            self._button_container.grid(row=0, column=0, sticky='ew')
+            if self._label:
+                self._label.grid(row=1, column=0, sticky='w', pady=(4, 0))
+            self.grid_columnconfigure(0, weight=1)
+        elif primary == 'w':
+            # Label on left
+            if self._label:
+                self._label.grid(row=0, column=0, sticky='w', padx=(0, 8))
+            self._button_container.grid(row=0, column=1, sticky='ew')
+            self.grid_columnconfigure(1, weight=1)
+        else:  # 'e'
+            # Label on right
+            self._button_container.grid(row=0, column=0, sticky='ew')
+            if self._label:
+                self._label.grid(row=0, column=1, sticky='w', padx=(8, 0))
+            self.grid_columnconfigure(0, weight=1)
+
+    @property
+    def variable(self) -> 'tk.Variable':
+        """Get the underlying tk.Variable."""
+        return self._variable
+
+    @variable.setter
+    def variable(self, value: 'tk.Variable') -> None:
+        """Set the variable."""
+        from bootstack.core.signals import Signal
+        self._variable = value
+        self._signal = Signal.from_variable(value)
+        # Update all buttons to use new variable
+        for button in self._buttons.values():
+            button.configure(variable=value)
+
+    @property
+    def signal(self) -> 'Signal[Any]':
+        """Get the signal."""
+        return self._signal
+
+    @signal.setter
+    def signal(self, value: 'Signal[Any]') -> None:
+        """Set the signal."""
+        self._signal = value
+        self._variable = value.var
+        # Update all buttons to use new variable
+        for button in self._buttons.values():
+            button.configure(variable=value.var)
+
+    def add(self, text: str = None, value: Any = None, key: str | None = None, **kwargs: Any) -> RadioButton:
+        """Add a radio button to the group.
+
+        Args:
+            text: Text to display on the button.
+            value: Value this button represents (required).
+            key: Unique identifier. Defaults to value.
+            **kwargs: Additional arguments passed to RadioButton.
+
+        Returns:
+            The created RadioButton widget.
+
+        Raises:
+            ValueError: If value is None or if a button with the same key already exists.
+        """
+        if value is None:
+            raise ValueError("The 'value' argument is required.")
+
+        key = key or value
+        if key in self._buttons:
+            raise ValueError(f"A button with the key '{key}' already exists.")
+
+        btn_kwargs = kwargs.copy()
+        # Use accent for button styling
+        if 'accent' not in btn_kwargs and 'bootstyle' not in btn_kwargs:
+            btn_kwargs['accent'] = self._accent
+        # Apply current state if not explicitly provided
+        if 'state' not in btn_kwargs:
+            btn_kwargs['state'] = self._state
+
+        button = RadioButton(
+            self._button_container,
+            text=text,
+            value=value,
+            variable=self.variable,
+            **btn_kwargs
+        )
+
+        if self._orientation == 'horizontal':
+            button.pack(side='left', padx=2)
+        else:  # vertical
+            button.pack(side='top', anchor='w', pady=2)
+
+        self._buttons[key] = button
+        return button
+
+    def get(self) -> str:
+        """Return the currently selected value."""
+        return self.variable.get()
+
+    def set(self, value: str) -> None:
+        """Set the selected value.
+
+        Args:
+            value: The value to select (must match a button's value).
+
+        Raises:
+            TypeError: If value is not a string.
+            ValueError: If value doesn't exist in the group.
+        """
+        if not isinstance(value, str):
+            raise TypeError(f"RadioGroup requires a string value, got {type(value).__name__}")
+
+        # Allow empty string (deselection)
+        if value and value not in self._buttons:
+            valid_values = list(self._buttons.keys())
+            raise ValueError(
+                f"Value '{value}' not found in group. "
+                f"Valid values: {valid_values}"
+            )
+
+        self.variable.set(value)
+
+    @property
+    def value(self) -> str:
+        """Get or set the selected value."""
+        return self.get()
+
+    @value.setter
+    def value(self, value: str) -> None:
+        self.set(value)
+
+    def remove(self, key: str):
+        """Remove a button by its key.
+
+        Args:
+            key: The key of the button to remove.
+
+        Raises:
+            KeyError: If no button with the given key exists.
+        """
+        if key not in self._buttons:
+            raise KeyError(f"No button with key '{key}'")
+        button = self._buttons.pop(key)
+        button.destroy()
+
+    def items(self) -> tuple[RadioButton, ...]:
+        """Get all button widgets in the group.
+
+        Returns:
+            A tuple of all RadioButton instances in the group.
+        """
+        return tuple(self._buttons.values())
+
+    def item(self, key: str) -> RadioButton:
+        """Get a button by its key.
+
+        Args:
+            key: The key of the button to retrieve.
+
+        Returns:
+            The RadioButton instance.
+
+        Raises:
+            KeyError: If no button with the given key exists.
+        """
+        if key not in self._buttons:
+            raise KeyError(f"No button with key '{key}'")
+        return self._buttons[key]
+
+    def configure_item(self, key: str, option: str = None, **kwargs: Any):
+        """Configure a specific button by its key.
+
+        Args:
+            key: The key of the button to configure.
+            option: If provided, return the value of this option.
+            **kwargs: Configuration options to apply to the button.
+
+        Returns:
+            If option is provided, returns the value of that option.
+        """
+        button = self.item(key)
+        if option is not None:
+            return button.cget(option)
+        button.configure(**kwargs)
+
+    def on_changed(self, callback: Callable) -> Any:
+        """Subscribe to value changes. Callback receives `new_value: str` directly."""
+        return self._signal.subscribe(callback)
+
+    def off_changed(self, bind_id: Any) -> None:
+        """Unsubscribe from value changes."""
+        self._signal.unsubscribe(bind_id)
+
+    @configure_delegate('accent')
+    def _delegate_accent(self, value=None):
+        """Get or set the accent. Updates all buttons when changed."""
+        if value is None:
+            return self._accent
+
+        self._accent = value
+        # Update all buttons with new accent
+        for button in self._buttons.values():
+            button.configure(accent=value)
+
+    @configure_delegate('orient')
+    def _delegate_orient(self, value=None):
+        """Get or set orientation ('horizontal' or 'vertical'). Repacks buttons when changed."""
+        if value is None:
+            return self._orientation
+
+        if value not in ('horizontal', 'vertical'):
+            raise ValueError("orient must be 'horizontal' or 'vertical'")
+
+        self._orientation = value
+
+        # Repack all buttons in new orientation
+        for button in self._buttons.values():
+            button.pack_forget()
+            if self._orientation == 'horizontal':
+                button.pack(side='left', padx=2)
+            else:
+                button.pack(side='top', anchor='w', pady=2)
+
+    @configure_delegate('labelanchor')
+    def _delegate_labelanchor(self, value=None):
+        """Get or set label anchor position. Updates layout when changed."""
+        if value is None:
+            return self._labelanchor
+
+        valid_anchors = ('n', 's', 'e', 'w', 'ne', 'nw', 'se', 'sw')
+        if value not in valid_anchors:
+            raise ValueError(f"labelanchor must be one of {valid_anchors}")
+
+        self._labelanchor = value
+        self._update_layout()
+
+    @configure_delegate('text')
+    def _delegate_text(self, value=None):
+        """Get or set label text. Creates or removes label as needed."""
+        if value is None:
+            return self._labeltext if self._labeltext else ''
+
+        self._labeltext = value
+        if value and not self._label:
+            # Create label if it doesn't exist
+            self._label = Label(self, text=value)
+            self._update_layout()
+        elif self._label:
+            if value:
+                self._label.configure(text=value)
+            else:
+                # Remove label if text is empty
+                self._label.destroy()
+                self._label = None
+                self._update_layout()
+
+    @configure_delegate('value')
+    def _delegate_value(self, value=None):
+        """Get or set the selected value."""
+        if value is None:
+            return self.get()
+        self.set(value)
+
+    @configure_delegate('state')
+    def _delegate_state(self, value=None):
+        """Get or set state for all buttons ('normal' or 'disabled')."""
+        if value is None:
+            return self._state
+
+        if value not in ('normal', 'disabled'):
+            raise ValueError("state must be 'normal' or 'disabled'")
+
+        self._state = value
+        # Update all buttons with new state
+        for button in self._buttons.values():
+            button.configure(state=value)
+
+    def keys(self) -> tuple[str, ...]:
+        """Get all button keys.
+
+        Returns:
+            A tuple of all button keys in the group.
+        """
+        return tuple(self._buttons.keys())
+
+    def values(self) -> tuple[str, ...]:
+        """Get all possible values.
+
+        Returns:
+            A tuple of all values that can be selected.
+        """
+        return tuple(self._buttons.keys())
+
+    def __len__(self) -> int:
+        """Return the number of buttons in the group."""
+        return len(self._buttons)
+
+    def __contains__(self, key: str) -> bool:
+        """Check if a button with the given key exists in the group."""
+        return key in self._buttons