bootstack 0.1.0__py3-none-any.whl

bootstack/style/builders/toolbutton.py

@@ -0,0 +1,275 @@
+"""Toolbutton widget style builders.
+
+This module contains style builders for ttk.Checkbutton and Radiobutton toolbutton variants.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from bootstack.style.style_builder_ttk import StyleBuilderTtk
+from bootstack.style.element import ElementImage
+from bootstack.style.utility import recolor_element_image
+from bootstack.style.builders.utils import (
+    apply_icon_mapping,
+    button_font,
+    button_padding,
+    icon_size,
+    normalize_button_density,
+    toolbutton_layout,
+)
+
+
+# The active styles are intentionally limited on toolbuttons to improve interaction
+# and limit the number of images created for each style.
+
+
+@StyleBuilderTtk.register_builder('default', 'Toolbutton')
+@StyleBuilderTtk.register_builder('solid', 'Toolbutton')
+def build_solid_toolbutton_style(b: StyleBuilderTtk, ttk_style: str, accent: Optional[str] = None, **options):
+    """
+    Configure the solid toolbutton style.
+
+    Style options include:
+        * anchor
+        * icon
+        * icon_only
+        * density
+    """
+    accent = b.default(accent)
+    anchor = options.get('anchor', 'center')
+    surface_token = options.get('surface', 'content')
+    density = options.get('density', 'default')
+    surface = b.color(surface_token)
+    accent_color = b.elevate(surface, 1) if accent is None else b.color(accent)
+    icon_only = options.get('icon_only', False)
+    image_key = f'button_{normalize_button_density(density)}'
+
+    bg_normal = b.elevate(surface, 1)
+
+    # background colors
+    bg_active = b.active(accent_color)
+    bg_selected = accent_color if accent is not None else b.elevate(surface, 2)
+    bg_disabled = b.disabled()
+
+    # foreground colors
+    fg_normal = b.muted_foreground(bg_normal)
+    fg_selected = b.on_color(bg_selected)
+    fg_disabled = b.disabled('text', bg_disabled)
+
+    # border colors
+    bd_normal = b.border(bg_normal)
+    bd_active = b.border(bg_active)
+    bd_selected = b.border(bg_selected)
+    bd_disabled = b.border(bg_disabled)
+
+    # focus
+    accent_focus = b.focus(accent_color)
+    focus_ring = b.focus_ring(accent_focus, surface)
+
+    normal_img = recolor_element_image(image_key, bg_normal, bd_normal, surface, surface)
+    normal_focus_img = recolor_element_image(image_key, bg_normal, bd_normal, focus_ring, surface)
+    active_img = recolor_element_image(image_key, bg_active, bd_active, surface, surface)
+    selected_img = recolor_element_image(image_key, bg_selected, bd_selected, surface, surface)
+    selected_focus_img = recolor_element_image(image_key, bg_selected, bd_selected, focus_ring, surface)
+    disabled_img = recolor_element_image(image_key, bg_disabled, bd_disabled, surface, surface)
+
+    b.create_style_element_image(
+        ElementImage(
+            f'{ttk_style}.border', normal_img.image, sticky="nsew",
+            border=normal_img.meta.border, padding=normal_img.meta.border
+        ).state_specs([
+            ('disabled', disabled_img.image),
+            ('background pressed focus selected', selected_focus_img.image),
+            ('background focus selected', selected_focus_img.image),
+            ('selected', selected_img.image),
+            ('background focus !selected', normal_focus_img.image),
+            ('background active !focus', active_img.image),
+            ('', normal_img.image)
+        ]))
+
+    b.create_style_layout(ttk_style, toolbutton_layout(ttk_style))
+
+    b.configure_style(
+        ttk_style,
+        background=surface,
+        foreground=fg_normal,
+        stipple="gray12",
+        relief='flat',
+        padding=button_padding(b, icon_only, density),
+        anchor=anchor,
+        font=button_font(density)
+    )
+
+    state_spec = dict(
+        foreground=[
+            ('disabled', fg_disabled),
+            ('selected', fg_selected),
+            ('', fg_normal)
+        ]
+    )
+    state_spec = apply_icon_mapping(b, options, state_spec, icon_size(icon_only, density))
+    b.map_style(ttk_style, **state_spec)
+
+
+@StyleBuilderTtk.register_builder('outline', 'Toolbutton')
+def build_outline_toolbutton_style(b: StyleBuilderTtk, ttk_style: str, accent: Optional[str] = None, **options):
+    """
+    Configure the outline toolbutton style.
+
+    Style options include:
+        * anchor
+        * icon
+        * icon_only
+        * density
+    """
+    accent = b.default(accent)
+    anchor = options.get('anchor', 'center')
+    surface_token = options.get('surface', 'content')
+    density = options.get('density', 'default')
+    icon_only = options.get('icon_only', False)
+    image_key = f'button_{normalize_button_density(density)}'
+
+    surface = b.color(surface_token)
+    accent_color = b.elevate(surface, 1) if accent is None else b.color(accent)
+
+    # background colors
+    bg_normal = surface
+    bg_selected = accent_color
+    bg_disabled = b.disabled()
+
+    # foreground colors
+    fg_normal = b.on_color(bg_normal) if accent is None else accent_color
+    fg_selected = b.on_color(bg_selected)
+    fg_disabled = b.disabled('text', bg_disabled)
+
+    # border colors
+    bd_normal = b.border(bg_normal) if accent is None else accent_color
+    bd_selected = b.border(bg_selected)
+    bd_disabled = b.border(bg_disabled)
+
+    # focus
+    accent_focus = b.focus(accent_color)
+    focus_ring = b.focus_ring(accent_focus, surface)
+
+    normal_img = recolor_element_image(image_key, surface, bd_normal, surface, surface)
+    normal_focus_img = recolor_element_image(image_key, surface, bd_normal, focus_ring, surface)
+    selected_img = recolor_element_image(image_key, bg_selected, bd_selected, surface, surface)
+    selected_focus_img = recolor_element_image(image_key, bg_selected, bd_selected, focus_ring, surface)
+    disabled_img = recolor_element_image(image_key, bg_disabled, bd_disabled, surface, surface)
+
+    b.create_style_element_image(
+        ElementImage(
+            f'{ttk_style}.border', normal_img.image, sticky="nsew",
+            border=normal_img.meta.border, padding=normal_img.meta.border
+        ).state_specs([
+            ('disabled', disabled_img.image),
+            ('background pressed selected focus', selected_focus_img.image),
+            ('pressed', selected_img.image),
+            ('background selected focus', selected_focus_img.image),
+            ('selected', selected_img.image),
+            ('background focus !selected', normal_focus_img.image),
+            ('', normal_img.image)
+        ]))
+
+    b.create_style_layout(ttk_style, toolbutton_layout(ttk_style))
+
+    b.configure_style(
+        ttk_style,
+        background=surface,
+        foreground=fg_normal,
+        stipple="gray12",
+        relief='flat',
+        padding=button_padding(b, icon_only, density),
+        anchor=anchor,
+        font=button_font(density)
+    )
+
+    state_spec = dict(
+        foreground=[
+            ('disabled', fg_disabled),
+            ('selected !disabled', fg_selected),
+            ('pressed !disabled', fg_selected),
+            ('', fg_normal)
+        ]
+    )
+    state_spec = apply_icon_mapping(b, options, state_spec, icon_size(icon_only, density))
+    b.map_style(ttk_style, **state_spec)
+
+
+@StyleBuilderTtk.register_builder('ghost', 'Toolbutton')
+def build_ghost_toolbutton_style(b: StyleBuilderTtk, ttk_style: str, accent: Optional[str] = None, **options):
+    """
+    Configure the ghost toolbutton style.
+
+    Style options include:
+        * anchor
+        * icon
+        * icon_only
+        * density
+    """
+    accent = b.default(accent)
+    anchor = options.get('anchor', 'center')
+    surface_token = options.get('surface', 'content')
+    density = options.get('density', 'default')
+    icon_only = options.get('icon_only', False)
+    image_key = f'button_{normalize_button_density(density)}'
+
+    surface = b.color(surface_token)
+    accent_color = b.elevate(surface, 1) if accent is None else b.color(accent)
+
+    # background colors
+    bg_normal = surface
+    bg_selected = b.elevate(surface, 2) if accent is None else b.subtle(accent, surface)
+    bg_disabled = b.disabled()
+
+    # foreground colors
+    fg_normal = b.muted_foreground(bg_normal)
+    fg_selected = b.on_color(bg_selected) if accent is None else b.color(accent)
+    fg_disabled = b.disabled('text', bg_disabled)
+
+    # focus
+    accent_focus = b.focus(accent_color)
+    focus_ring = b.focus_ring(accent_focus, surface)
+
+    normal_img = recolor_element_image(image_key, bg_normal, bg_normal, surface, surface)
+    normal_focus_img = recolor_element_image(image_key, bg_normal, accent_color, focus_ring, surface)
+    selected_img = recolor_element_image(image_key, bg_selected, bg_selected, surface, surface)
+    selected_focus_img = recolor_element_image(image_key, bg_selected, accent_focus, focus_ring, surface)
+    disabled_img = recolor_element_image(image_key, bg_disabled, bg_disabled, surface, surface)
+
+    b.create_style_element_image(
+        ElementImage(
+            f'{ttk_style}.border', normal_img.image, sticky="nsew",
+            border=normal_img.meta.border, padding=normal_img.meta.border
+        ).state_specs([
+            ('disabled', disabled_img.image),
+            ('background pressed selected focus', selected_focus_img.image),
+            ('background selected focus', selected_focus_img.image),
+            ('selected', selected_img.image),
+            ('background focus !selected', normal_focus_img.image),
+            ('', normal_img.image)
+        ]))
+
+    b.create_style_layout(ttk_style, toolbutton_layout(ttk_style))
+
+    b.configure_style(
+        ttk_style,
+        background=surface,
+        foreground=fg_normal,
+        stipple="gray12",
+        relief='flat',
+        padding=button_padding(b, icon_only, density),
+        anchor=anchor,
+        font=button_font(density)
+    )
+
+    state_spec = dict(
+        foreground=[
+            ('disabled', fg_disabled),
+            ('selected', fg_selected),
+            ('', fg_normal)
+        ]
+    )
+    state_spec = apply_icon_mapping(b, options, state_spec, icon_size(icon_only, density))
+    b.map_style(ttk_style, **state_spec)

bootstack/style/builders/tooltip.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from bootstack.style.style_builder_ttk import StyleBuilderTtk
+from bootstack.style.element import Element
+
+
+@StyleBuilderTtk.register_builder('tooltip', 'TFrame')
+def build_tooltip_frame(b: StyleBuilderTtk, ttk_style: str, accent: str = None, **options):
+    surface_token = options.get('surface') or accent or "background"
+    if accent:
+        background = b.color(accent)
+    else:
+        background = b.color(surface_token)
+
+    border_color = b.border(background)
+
+    b.create_style_layout(ttk_style, Element(f'{ttk_style}.Frame.border', sticky="nsew"))
+
+    b.configure_style(
+        ttk_style,
+        background=background,
+        border_color=border_color,
+        darkcolor=background,
+        lightcolor=background,
+        relief='flat',
+        )

bootstack/style/builders/treeview.py

@@ -0,0 +1,193 @@
+"""Treeview widget style builders."""
+import tkinter as tk
+from tkinter import font
+
+from bootstack._core.images import _ImageService
+from bootstack.style.style_builder_ttk import StyleBuilderTtk
+from bootstack.style.element import Element, ElementImage
+from bootstack.style.utility import create_transparent_image
+from bootstack.style.builders.utils import normalize_button_density, _snap_even
+
+
+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)
+
+
+@StyleBuilderTtk.register_builder('default', 'Treeview')
+@StyleBuilderTtk.register_builder('tree', 'Treeview')
+def build_tree_style(b: StyleBuilderTtk, 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: str = options.get('surface', 'content')
+    border_token: str = options.get('border_color', surface_token)
+    header_bg_token: str | None = options.get('header_background')
+    show_border = options.get('show_border', True)
+    density = normalize_button_density(options.get('density', 'default'))
+    surface = b.color(surface_token)
+
+    if show_border:
+        if border_token is not None:
+            border_color = b.color(border_token)
+        else:
+            border_color = b.border(surface)
+    else:
+        border_color = surface
+
+    if header_bg_token is not None:
+        heading_color = b.color(header_bg_token)
+        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')
+    # Subtle accent wash so striping shows through and text/icons keep one color.
+    select_background = b.subtle(select_background_token)
+    select_hover = b.active(select_background)
+    on_select = on_surface  # selected rows keep normal text on the soft wash
+
+    # Density-based sizing
+    body_font = _treeview_font(density)
+    row_multiplier = _treeview_row_height(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)
+
+    # Transparent gap between the leading icon (checkbox / group chevron) and the
+    # text, so a group label doesn't butt up against its chevron. Harmless for
+    # rows whose icon slot has no adjacent text (e.g. checkbox-only cells).
+    gap_width = 8 if density == 'compact' else 10
+    gap = create_transparent_image(b.scale(gap_width), 1)
+    b.create_style_element_image(
+        ElementImage(f'{ttk_style}.iconspacer', gap, sticky='', width=b.scale(gap_width))
+    )
+
+    b.create_style_layout(
+        f'{ttk_style}.Item',
+        Element('Treeitem.padding').children(
+            [
+                Element('Treeitem.image', side='left', sticky=''),
+                Element(f'{ttk_style}.iconspacer', side='left', sticky=''),
+                Element('Treeitem.text', side='left', sticky='w')
+            ])
+    )
+
+    b.configure_style(f'{ttk_style}.Item', padding=b.scale(item_padding))
+
+    # 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
+    show_border = options.get('show_border', True)
+    b.configure_style(
+        ttk_style,
+        font=body_font,
+        background=surface,
+        fieldbackground=surface,
+        foreground=on_surface,
+        borderwidth=1 if show_border else 0,
+        bordercolor=border_color,
+        darkcolor=surface,
+        lightcolor=surface,
+        padding=0,
+        rowheight=row_height,
+        relief='solid' if show_border else '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))