bootstack 0.1.0a1__py3-none-any.whl

bootstack/style/builders/treeview.py

@@ -0,0 +1,269 @@
+"""Treeview widget style builders.
+
+This module contains style builders for ttk.Treeview widget and variants.
+
+TODO there is a strange bug that causes the treeview to request more size when the custom border element is used.
+"""
+import tkinter as tk
+from tkinter import font
+
+from ttkbootstrap_icons_bs import BootstrapIcon
+from bootstack.style.bootstyle_builder_ttk import BootstyleBuilderTTk
+from bootstack.style.element import Element, ElementImage
+from bootstack.style.utility import create_transparent_image, recolor_element_image
+from bootstack.style.builders.utils import normalize_button_density
+
+
+def _tk_version_at_least(major: int, minor: int, patch: int) -> bool:
+    """Check if the current Tk version is at least the specified version.
+
+    This is used to work around a regression in Tk 8.6.13+ where user1/user2
+    states don't work properly with custom image elements for treeview indicators.
+    See: https://core.tcl-lang.org/tk/timeline?r=rfe-d632d28ba4
+    """
+    try:
+        version_str = tk._default_root.tk.call('info', 'patchlevel')
+        parts = version_str.split('.')
+        current = (int(parts[0]), int(parts[1]), int(parts[2]))
+        return current >= (major, minor, patch)
+    except Exception:
+        # If we can't determine version, assume newer Tk (safer fallback)
+        return True
+
+
+def _treeview_font(density: str) -> str:
+    """Get font token based on density."""
+    return 'caption' if density == 'compact' else 'body'
+
+
+def _treeview_row_height(density: str) -> float:
+    """Get row height multiplier based on density."""
+    return 1.6 if density == 'compact' else 1.75
+
+
+def _treeview_indicator_size(density: str) -> int:
+    """Get indicator size based on density."""
+    return 10 if density == 'compact' else 12
+
+
+def _treeview_icon_size(density: str) -> int:
+    """Get custom icon size based on density."""
+    return 12 if density == 'compact' else 16
+
+
+def _treeview_item_padding(density: str) -> tuple[int, int]:
+    """Get item padding based on density."""
+    return (4, 0) if density == 'compact' else (6, 0)
+
+
+def _treeview_heading_padding(density: str) -> tuple[int, int]:
+    """Get heading padding based on density."""
+    return (4, 4) if density == 'compact' else (8, 10)
+
+
+def _treeview_cell_padding(density: str) -> tuple[int, int]:
+    """Get cell padding based on density."""
+    return (2, 0) if density == 'compact' else (6, 0)
+
+
+@BootstyleBuilderTTk.register_builder('default', 'Treeview')
+@BootstyleBuilderTTk.register_builder('tree', 'Treeview')
+def build_tree_style(b: BootstyleBuilderTTk, ttk_style: str, **options):
+    """
+    Create treeview style.
+
+    Available options via `style_options`:
+        * border_color
+        * show_border
+        * open_icon
+        * close_icon
+        * select_background
+        * header_background
+        * density ('default' or 'compact')
+    """
+    surface_token = options.get('surface', 'content')
+    density = normalize_button_density(options.get('density', 'default'))
+    surface = b.color(surface_token)
+
+    if options.get('show_border', True):
+        if options.get('border_color'):
+            border_color = b.color(options.get('border_color'))
+        else:
+            border_color = b.border(surface)
+    else:
+        border_color = surface
+
+    if options.get('header_background'):
+        heading_color = b.color(options.get('header_background'))
+        heading_hover = b.active(heading_color)
+    else:
+        heading_color = b.elevate(surface, 3)
+        heading_hover = b.active(heading_color)
+
+    on_heading = b.on_color(heading_color)
+    on_surface = b.on_color(surface)
+    on_surface_disabled = b.disabled('text', surface)
+    hover = b.active(surface)
+
+    select_background_token = options.get('select_background', 'primary')
+    select_background = b.color(select_background_token)
+    select_hover = b.active(select_background)
+    on_select = b.on_color(select_background)
+
+    # Density-based sizing
+    body_font = _treeview_font(density)
+    row_multiplier = _treeview_row_height(density)
+    indicator_size = _treeview_indicator_size(density)
+    item_padding = _treeview_item_padding(density)
+    heading_padding = _treeview_heading_padding(density)
+    cell_padding = _treeview_cell_padding(density)
+
+    # Calculate row height - use TkDefaultFont for metrics when using font spec
+    metrics_font = 'TkDefaultFont' if body_font.startswith('-') else body_font
+    f = font.nametofont(metrics_font)
+    row_height = int(f.metrics()['linespace'] * row_multiplier)
+
+    # Tk 8.6.13+ has a regression where user1/user2 states don't work with
+    # custom image elements for treeview indicators. Use native indicator on
+    # newer Tk versions until TIP #719 lands with proper open/leaf states.
+    # See: https://core.tcl-lang.org/tk/timeline?r=rfe-d632d28ba4
+    use_native_indicator = _tk_version_at_least(8, 6, 13)
+
+    if use_native_indicator:
+        # Use native Treeitem.indicator with custom foreground colors
+        # The native indicator uses triangles that rotate based on open/closed state
+        # Create a spacer element to add space between indicator and text
+        spacer_width = 8 if density == 'compact' else 8
+        spacer = create_transparent_image(b.scale(spacer_width), 1)
+        b.create_style_element_image(
+            ElementImage(f'{ttk_style}.spacer', spacer, sticky='', width=b.scale(spacer_width))
+        )
+
+        b.create_style_layout(
+            f'{ttk_style}.Item',
+            Element('Treeitem.padding').children(
+                [
+                    Element('Treeitem.indicator', side='left', sticky=''),
+                    Element(f'{ttk_style}.spacer', side='left', sticky=''),
+                    Element('Treeitem.image', side='left', sticky=''),
+                    Element('Treeitem.text', side='left', sticky='w')
+                ])
+        )
+
+        indicator_margins = (0, 0, 0, 2) if density == 'compact' else (0, 0, 0, 2)
+        b.configure_style(
+            f'{ttk_style}.Item',
+            padding=b.scale(item_padding),
+            foreground=on_surface,
+            indicatorsize=b.scale(indicator_size),
+            indicatormargins=b.scale(indicator_margins)
+        )
+        b.map_style(
+            f'{ttk_style}.Item',
+            foreground=[
+                ('selected', on_select),
+                ('', on_surface)
+            ]
+        )
+    else:
+        # Use custom image indicator with user1/user2 states (works on Tk < 8.6.13)
+        open_icon = options.get('open_icon', 'chevron-right')
+        closed_icon = options.get('close_icon', 'chevron-down')
+        icon_size = b.scale(_treeview_icon_size(density))
+
+        expand_icon_normal = BootstrapIcon(open_icon, icon_size, on_surface).image
+        expand_icon_selected = BootstrapIcon(open_icon, icon_size, on_select).image
+        collapse_icon_normal = BootstrapIcon(closed_icon, icon_size, on_surface).image
+        collapse_icon_selected = BootstrapIcon(closed_icon, icon_size, on_select).image
+        leaf = create_transparent_image(icon_size, icon_size)
+
+        indicator_height = 12 if density == 'compact' else 14
+        b.create_style_element_image(
+            ElementImage(
+                f'{ttk_style}.indicator', expand_icon_normal,
+                sticky='w', height=b.scale(indicator_height), width=b.scale(icon_size + 10)).state_specs(
+                [
+                    ('user2', leaf),
+                    ('user1 selected', collapse_icon_selected),
+                    ('user1', collapse_icon_normal),
+                    ('!user1 selected', expand_icon_selected),
+                ])
+        )
+
+        b.create_style_layout(
+            f'{ttk_style}.Item',
+            Element('Treeitem.padding').children(
+                [
+                    Element(f'{ttk_style}.indicator', side='left', sticky=''),
+                    Element('Treeitem.image', side='left', sticky=''),
+                    Element('Treeitem.text', side='left', sticky='w')
+                ])
+        )
+
+        b.configure_style(f'{ttk_style}.Item', padding=b.scale(item_padding))
+
+    # customize the tree field
+    border_img = recolor_element_image('border', surface, border_color, surface, surface)
+
+    b.create_style_element_image(
+        ElementImage(
+            f'{ttk_style}.field', border_img.image, sticky='nsew',
+            border=border_img.meta.border, padding=border_img.meta.border,
+            width=0, height=0
+        )
+    )
+
+    b.create_style_layout(
+        ttk_style, Element(f'{ttk_style}.field', sticky="nsew").children(
+            [
+                Element('Treeview.padding', sticky="nsew").children(
+                    [
+                        Element('Treeview.treearea', sticky="nsew")
+                    ]),
+            ]))
+
+    # configure header
+    heading_font = 'caption' if density == 'compact' else 'label'
+    b.configure_style(
+        f'{ttk_style}.Heading',
+        font=heading_font,
+        background=heading_color,
+        foreground=on_heading,
+        padding=b.scale(heading_padding)
+    )
+    b.map_style(
+        f'{ttk_style}.Heading',
+        foreground=[('disabled', on_surface_disabled), ('', on_heading)],
+        background=[('active !disabled', heading_hover), ('', heading_color)]
+    )
+
+    # configure tree body
+    b.configure_style(
+        ttk_style,
+        font=body_font,
+        background=surface,
+        fieldbackground=surface,
+        foreground=on_surface,
+        borderwidth=0,
+        padding=0,
+        rowheight=row_height,
+        relief='flat'
+    )
+
+    b.map_style(
+        ttk_style,
+        background=[
+            ('active !disabled', hover),
+            ('selected active !disabled', select_hover),
+            ('selected !disabled', select_background)
+            # do not set fallback or it will override tag formats
+        ],
+        foreground=[
+            ('disabled', on_surface_disabled),
+            ('selected !disabled', on_select)
+            # do not set fallback or it will override tag formats
+        ]
+    )
+
+    # configure cell
+    b.configure_style(f"{ttk_style}.Cell", font=body_font, padding=b.scale(cell_padding))

bootstack/style/builders/utils.py

@@ -0,0 +1,404 @@
+"""Utility functions for style builders.
+
+This module provides common utilities used across builder functions,
+including accent extraction, variant parsing, and style name manipulation.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Optional
+
+from bootstack.style.element import Element
+
+if TYPE_CHECKING:
+    from bootstack.style.bootstyle_builder_ttk import BootstyleBuilderTTk
+
+# Standard bootstack color tokens
+COLORS = {
+    'primary', 'secondary', 'success', 'info',
+    'warning', 'danger', 'light', 'dark', 'blue'
+}
+
+
+def extract_accent_from_style(ttk_style: str, default: str = 'primary') -> str:
+    """Extract accent token from TTK style name.
+
+    Args:
+        ttk_style: Full TTK style name (e.g., "custom_abc.success.Outline.TButton")
+        default: Default accent if none found
+
+    Returns:
+        Accent token name (e.g., "success")
+
+    Examples:
+        >>> extract_accent_from_style("success.Outline.TButton")
+        'success'
+        >>> extract_accent_from_style("custom_abc.danger.TLabel")
+        'danger'
+        >>> extract_accent_from_style("TButton")
+        'primary'
+    """
+    # Remove custom prefix if present
+    parts = ttk_style.split('.')
+    if parts and parts[0].startswith('custom_'):
+        parts = parts[1:]
+
+    # Find accent in parts
+    for part in parts:
+        if part.lower() in COLORS:
+            return part.lower()
+
+    return default
+
+
+def extract_variant_from_style(ttk_style: str) -> Optional[str]:
+    """Extract variant name from TTK style name.
+
+    Args:
+        ttk_style: Full TTK style name (e.g., "success.Outline.TButton")
+
+    Returns:
+        Variant name (lowercase) or None
+
+    Examples:
+        >>> extract_variant_from_style("success.Outline.TButton")
+        'outline'
+        >>> extract_variant_from_style("primary.TLabel") is None
+        True
+    """
+    parts = ttk_style.split('.')
+
+    # Remove custom prefix if present
+    if parts and parts[0].startswith('custom_'):
+        parts = parts[1:]
+
+    # Find variant (not accent, not widget class)
+    for part in parts:
+        part_lower = part.lower()
+        if part_lower not in COLORS and not part.startswith('T'):
+            return part_lower
+
+    return None
+
+
+def extract_widget_class_from_style(ttk_style: str) -> Optional[str]:
+    """Extract widget class from TTK style name.
+
+    Args:
+        ttk_style: Full TTK style name (e.g., "success.Outline.TButton")
+
+    Returns:
+        Widget class name or None
+
+    Examples:
+        >>> extract_widget_class_from_style("success.Outline.TButton")
+        'TButton'
+        >>> extract_widget_class_from_style("primary.TLabel")
+        'TLabel'
+    """
+    parts = ttk_style.split('.')
+
+    # Find widget class (starts with 'T')
+    for part in parts:
+        if part.startswith('T'):
+            return part
+
+    return None
+
+
+def parse_style_components(ttk_style: str) -> dict:
+    """Parse TTK style name into all components.
+
+    Args:
+        ttk_style: Full TTK style name
+
+    Returns:
+        Dictionary with parsed components:
+        {
+            'custom_prefix': 'custom_abc123' or None,
+            'accent': 'success' or default,
+            'variant': 'outline' or None,
+            'widget_class': 'TButton'
+        }
+
+    Examples:
+        >>> parse_style_components("custom_abc.success.Outline.TButton")
+        {'custom_prefix': 'custom_abc', 'accent': 'success', 'variant': 'outline', 'widget_class': 'TButton'}
+        >>> parse_style_components("danger.TLabel")
+        {'custom_prefix': None, 'accent': 'danger', 'variant': None, 'widget_class': 'TLabel'}
+    """
+    parts = ttk_style.split('.')
+
+    # Check for custom prefix
+    custom_prefix = None
+    if parts and parts[0].startswith('custom_'):
+        custom_prefix = parts[0]
+
+    return {
+        'custom_prefix': custom_prefix,
+        'accent': extract_accent_from_style(ttk_style),
+        'variant': extract_variant_from_style(ttk_style),
+        'widget_class': extract_widget_class_from_style(ttk_style),
+    }
+
+
+# Button utilities
+# These utilities are used by button style builders and can be reused by other widgets.
+
+# Valid button densities: 'default' (normal) and 'compact' (smaller/tighter)
+BUTTON_DENSITIES = {'default', 'compact'}
+
+
+def normalize_button_density(density: str) -> str:
+    """Normalize button density to valid values ('default' or 'compact').
+
+    Args:
+        density: The requested button density.
+
+    Returns:
+        'compact' for compact buttons, 'default' for all other densities.
+    """
+    return 'compact' if density == 'compact' else 'default'
+
+
+def button_layout(ttk_style: str) -> Element:
+    """Create the standard button element layout.
+
+    Args:
+        ttk_style: The TTK style name prefix for the button.
+
+    Returns:
+        Element tree representing the button layout.
+    """
+    return Element(f"{ttk_style}.Button.border", sticky="nsew").children(
+        [
+            Element("Button.padding", sticky="nsew").children(
+                [
+                    Element("Button.label", sticky="nsew")
+                ])
+        ])
+
+
+def toolbutton_layout(ttk_style: str) -> Element:
+    """Create the standard toolbutton element layout.
+
+    Args:
+        ttk_style: The TTK style name prefix for the toolbutton.
+
+    Returns:
+        Element tree representing the toolbutton layout.
+    """
+    return Element(f"{ttk_style}.border", sticky="nsew").children(
+        [
+            Element("Toolbutton.padding", sticky="nsew").children(
+                [
+                    Element("Toolbutton.label", sticky="nsew")
+                ])
+        ])
+
+
+def icon_size(icon_only: bool, density: str) -> int:
+    """Determine icon size based on button density and icon_only flag.
+
+    Args:
+        icon_only: Whether the button displays only an icon (no text).
+        density: The button density ('default' or 'compact').
+
+    Returns:
+        The icon size in pixels.
+    """
+    from tkinter import font
+
+    if icon_only:
+        return 23 if density != 'compact' else 18
+
+    # Get icon size from font ascent for proper alignment with text
+    # Different buffers compensate for y_bias effect per density
+    font_name = 'caption' if density == 'compact' else 'body'
+    f = font.nametofont(font_name)
+    buffer = 4 if density == 'compact' else 3
+    return f.metrics()['ascent'] + buffer
+
+
+def button_font(density: str) -> str:
+    """Get the font token for a button based on its density.
+
+    Args:
+        density: The button density ('default' or 'compact').
+
+    Returns:
+        The font token name.
+    """
+    return 'caption' if density == 'compact' else 'body'
+
+
+def button_padding(b: BootstyleBuilderTTk, icon_only: bool, density: Any) -> int | tuple[int, ...]:
+    """Calculate button padding based on options.
+
+    Args:
+        b: The bootstyle builder instance.
+        icon_only: Whether the button displays only an icon.
+        density: The button density ('default' or 'compact').
+
+    Returns:
+        Padding value (0 for icon_only, scaled tuple otherwise).
+    """
+    if icon_only:
+        return b.scale((2, 3, 2, 3)) if density == 'compact' else 0
+    if density == 'compact':
+        # (left, top, right, bottom) - extra top padding to center text
+        return b.scale((6, 5, 6, 3))
+    return b.scale((8, 0))
+
+
+def apply_icon_mapping(
+        b: BootstyleBuilderTTk,
+        options: dict,
+        state_spec: dict,
+        default_size: int | None = None
+) -> dict:
+    """Apply icon mapping to a state specification dictionary.
+
+    Args:
+        b: The bootstyle builder instance.
+        options: Style options dictionary containing 'icon' and 'icon_only' keys.
+        state_spec: The state specification dictionary to update.
+        default_size: Default icon size, or None to use normalize_icon_spec defaults.
+
+    Returns:
+        Updated state_spec with icon mappings applied.
+    """
+    icon = options.get('icon')
+    if icon is None:
+        return state_spec
+
+    if default_size is None:
+        icon = b.normalize_icon_spec(icon)
+    else:
+        icon = b.normalize_icon_spec(icon, default_size)
+
+    state_spec['image'] = b.map_stateful_icons(icon, state_spec['foreground'])
+    # Set compound to 'left' so text is visible alongside the icon
+    icon_only = options.get('icon_only', False)
+    if not icon_only:
+        state_spec['compound'] = 'left'
+    return state_spec
+
+
+# Entry/Field utilities
+# These utilities are used by entry-type style builders (Entry, Combobox, Spinbox, Field).
+
+def entry_font(density: str) -> str:
+    """Get the font for an entry widget based on its density.
+
+    Args:
+        density: The entry density ('default' or 'compact').
+
+    Returns:
+        The Tk font name.
+    """
+    from bootstack.style.typography import get_font
+    font_token = 'caption' if density == 'compact' else 'body'
+    return str(get_font(font_token))
+
+
+def entry_padding(b: BootstyleBuilderTTk, density: str) -> tuple:
+    """Get entry padding based on density.
+
+    Args:
+        b: The bootstyle builder instance.
+        density: The entry density ('default' or 'compact').
+
+    Returns:
+        Scaled padding tuple (horizontal, vertical).
+    """
+    if density == 'compact':
+        return b.scale((6, 0))
+    return b.scale((6, 0))
+
+def field_height(b: BootstyleBuilderTTk, density: str) -> int:
+    """Get entry element height based on density.
+
+    Args:
+        b: The bootstyle builder instance.
+        density: The entry density ('default' or 'compact').
+
+    Returns:
+        Scaled height in pixels.
+    """
+    return b.scale(26) if density == 'compact' else b.scale(33)
+
+def entry_height(b: BootstyleBuilderTTk, density: str) -> int:
+    """Get entry element height based on density.
+
+    Args:
+        b: The bootstyle builder instance.
+        density: The entry density ('default' or 'compact').
+
+    Returns:
+        Scaled height in pixels.
+    """
+    return b.scale(25) if density == 'compact' else b.scale(31)
+
+
+def entry_icon_size(b: BootstyleBuilderTTk, density: str) -> int:
+    """Get icon size for entry widgets (chevrons, spinner arrows).
+
+    Args:
+        b: The bootstyle builder instance.
+        density: The entry density ('default' or 'compact').
+
+    Returns:
+        Scaled icon size in pixels.
+    """
+    return b.scale(12) if density == 'compact' else b.scale(14)
+
+
+def entry_image_key(base: str, density: str) -> str:
+    """Get density-aware manifest key for entry elements.
+
+    Args:
+        base: Base key name (e.g., 'input', 'input_before', 'input_after').
+        density: The entry density ('default' or 'compact').
+
+    Returns:
+        Full manifest key with density suffix (e.g., 'input_default', 'input_compact').
+    """
+    return f'{base}_{density}'
+
+
+def spinner_arrow_height(b: BootstyleBuilderTTk, density: str) -> int:
+    """Get height for spinner arrow elements based on density.
+
+    Args:
+        b: The bootstyle builder instance.
+        density: The entry density ('default' or 'compact').
+
+    Returns:
+        Scaled arrow height in pixels.
+    """
+    return b.scale(10) if density == 'compact' else b.scale(13)
+
+
+def spinner_arrow_width(b: BootstyleBuilderTTk) -> int:
+    """Get width for spinner arrow elements.
+
+    Args:
+        b: The bootstyle builder instance.
+
+    Returns:
+        Scaled arrow width in pixels.
+    """
+    return b.scale(16)
+
+
+def chevron_width(b: BootstyleBuilderTTk) -> int:
+    """Get width for combobox chevron element.
+
+    Args:
+        b: The bootstyle builder instance.
+
+    Returns:
+        Scaled chevron width in pixels.
+    """
+    return b.scale(16)

bootstack/style/builders_tk/__init__.py

@@ -0,0 +1,16 @@
+"""Tk (legacy tkinter) widget builders for bootstack.
+
+Importing this package registers default builder functions for common Tk
+widgets using the BootstyleBuilderTk registry. Builders receive the actual
+widget instance, plus theme/color utilities via the builder object.
+"""
+
+from __future__ import annotations
+
+# Import defaults to trigger registration
+from . import defaults  # noqa: F401
+
+__all__ = [
+    'defaults',
+]
+