ctk-kit 0.1.0__py3-none-any.whl

ctk_kit/__init__.py

@@ -0,0 +1,88 @@
+"""ctk-kit —— 面向 CustomTkinter 的轻量界面基件。
+
+分三层：
+
+- ``tokens``  设计令牌：颜色（深浅两套）、字体、圆角、间距
+- ``theme``   取色与外观切换工具，以及原生 tk 控件的重绘
+- 组件        ``buttons`` / ``inputs`` / ``dropdown`` / ``layout`` / ``scroll_list``
+
+安装::
+
+    pip install ctk-kit
+
+最小示例::
+
+    import customtkinter as ctk
+    from ctk_kit import primary_button, card, page_header
+
+    app = ctk.CTk()
+    header, info = page_header(app, "备份")
+    box = card(app)
+    primary_button(box, "立即备份", command=lambda: print("go")).pack(padx=16, pady=16)
+    app.mainloop()
+
+全组件展示（示例脚本，见仓库 examples/）::
+
+    python examples/showcase.py
+
+仓库: https://gitee.com/kuangjianke/ctk-kit
+镜像: https://github.com/DashSalter/ctk-kit
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from . import tokens, theme
+from .buttons import (
+    FlatButton,
+    SoftButton,
+    danger_button,
+    primary_button,
+    soft_button,
+)
+from .dropdown import DropField
+from .inputs import form_entry, segmented, switch, toolbar_entry
+from .layout import (
+    card,
+    divider,
+    empty_hint,
+    field_label,
+    hint_label,
+    page_header,
+    scrollable,
+    section_title,
+    style_scrollable,
+)
+from .scroll_list import LazyList
+from .theme import apply_appearance, color_of, is_dark, repaint_native
+
+__all__ = [
+    "DropField",
+    "FlatButton",
+    "LazyList",
+    "SoftButton",
+    "__version__",
+    "apply_appearance",
+    "card",
+    "color_of",
+    "danger_button",
+    "divider",
+    "empty_hint",
+    "field_label",
+    "form_entry",
+    "hint_label",
+    "is_dark",
+    "page_header",
+    "primary_button",
+    "repaint_native",
+    "scrollable",
+    "section_title",
+    "segmented",
+    "soft_button",
+    "style_scrollable",
+    "switch",
+    "theme",
+    "tokens",
+    "toolbar_entry",
+]

ctk_kit/buttons.py

@@ -0,0 +1,233 @@
+"""按钮：主按钮、次要按钮、危险按钮，以及卡片里用的微型按钮。
+
+尺寸约定：
+- 主按钮      38 高、圆角 9  —— 保存、搜索这一层的动作
+- 次要按钮    30 高、圆角 8  —— 取消、刷新、选择目录
+- 微型按钮    由文字宽度算出来 —— 卡片里的「复制 / 显示 / 详情」
+
+所有按钮工厂只返回 ``ctk.CTkButton``，不负责 ``pack`` / ``grid``，摆位交给调用方。
+"""
+
+from __future__ import annotations
+
+import tkinter as tk
+import tkinter.font as tkfont
+from typing import Callable, Dict, Optional
+
+import customtkinter as ctk
+
+from . import tokens as T
+from .theme import ColorToken, color_of
+
+# 无参回调；CTk 的 command 就是这么调的，不会传入事件对象。
+Command = Optional[Callable[[], None]]
+
+# 同一套字体反复测量很浪费，按字体规格缓存度量对象。
+# 注意：度量对象绑定在某个 Tk 解释器上，解释器销毁后需要清空（测试里有 fixture）。
+_MEASURERS: Dict[tuple, tkfont.Font] = {}
+
+
+def _measurer(font_spec: T.FontSpec) -> tkfont.Font:
+    """返回 ``font_spec`` 对应的 ``tkfont.Font`` 度量对象，并按规格缓存。
+
+    参数:
+        font_spec: ``(字族, 字号)`` 或 ``(字族, 字号, "bold")``。
+
+    返回:
+        可用于 ``measure()`` / ``metrics()`` 的字体对象；相同规格返回同一实例。
+    """
+    key = tuple(font_spec)
+    cached = _MEASURERS.get(key)
+    if cached is None:
+        cached = tkfont.Font(font=font_spec)
+        _MEASURERS[key] = cached
+    return cached
+
+
+def primary_button(
+    master: tk.Misc,
+    text: str,
+    command: Command = None,
+    *,
+    width: int = 120,
+    height: int = 38,
+    radius: int = T.RADIUS_SMALL + 1,
+    font: T.FontSpec = T.FONT_BODY,
+) -> ctk.CTkButton:
+    """强调色主按钮（保存 / 搜索 / 立即备份）。
+
+    参数:
+        master: 父容器。
+        text: 按钮文字。
+        command: 点击回调，不接收参数。
+        width: 宽度（像素），默认 120。
+        height: 高度（像素），默认 38。
+        radius: 圆角半径，默认 9。
+        font: 字体规格，默认 :data:`tokens.FONT_BODY`。
+
+    返回:
+        尚未摆位的 ``CTkButton``。
+    """
+    return ctk.CTkButton(
+        master,
+        text=text,
+        width=width,
+        height=height,
+        corner_radius=radius,
+        font=font,
+        fg_color=T.COLOR_ACCENT,
+        hover_color=T.COLOR_ACCENT_HOVER,
+        text_color=T.COLOR_ACCENT_TEXT,
+        command=command,
+    )
+
+
+def soft_button(
+    master: tk.Misc,
+    text: str,
+    command: Command = None,
+    *,
+    width: int = 76,
+    height: int = 30,
+    font: T.FontSpec = T.FONT_SMALL,
+    border: bool = False,
+) -> ctk.CTkButton:
+    """浅底次要按钮。
+
+    ``border=True`` 时加一圈细边，适合「取消 / 清除」这类不该抢视线的动作。
+
+    参数:
+        master: 父容器。
+        text: 按钮文字。
+        command: 点击回调，不接收参数。
+        width: 宽度（像素），默认 76。
+        height: 高度（像素），默认 30；高度超过 30 时圆角自动加 1。
+        font: 字体规格，默认 :data:`tokens.FONT_SMALL`。
+        border: 是否显示 1px 边框。
+
+    返回:
+        尚未摆位的 ``CTkButton``。
+    """
+    return ctk.CTkButton(
+        master,
+        text=text,
+        width=width,
+        height=height,
+        corner_radius=T.RADIUS_SMALL if height <= 30 else T.RADIUS_SMALL + 1,
+        font=font,
+        fg_color=T.COLOR_SOFT,
+        hover_color=T.COLOR_SOFT_HOVER,
+        text_color=T.COLOR_TEXT,
+        border_width=1 if border else 0,
+        border_color=T.COLOR_BORDER if border else T.COLOR_SOFT,
+        command=command,
+    )
+
+
+def danger_button(
+    master: tk.Misc,
+    text: str,
+    command: Command = None,
+    *,
+    width: int = 76,
+    height: int = 30,
+    font: T.FontSpec = T.FONT_SMALL,
+) -> ctk.CTkButton:
+    """危险动作（删除 / 清空全部）：淡红底 + 红字，比纯红按钮安静。
+
+    参数:
+        master: 父容器。
+        text: 按钮文字。
+        command: 点击回调，不接收参数。
+        width: 宽度（像素），默认 76。
+        height: 高度（像素），默认 30。
+        font: 字体规格，默认 :data:`tokens.FONT_SMALL`。
+
+    返回:
+        尚未摆位的 ``CTkButton``。
+    """
+    return ctk.CTkButton(
+        master,
+        text=text,
+        width=width,
+        height=height,
+        corner_radius=T.RADIUS_SMALL,
+        font=font,
+        fg_color=T.COLOR_DANGER_SOFT,
+        hover_color=T.COLOR_DANGER_SOFT_HOVER,
+        text_color=T.COLOR_DANGER,
+        command=command,
+    )
+
+
+class FlatButton(ctk.CTkButton):
+    """卡片里的小号圆角按钮（复制 / 显示 / 详情）。
+
+    宽度按文字实测宽度算出来，既不浪费横向空间，也不会把文字挤掉。
+    颜色默认取当前外观下的浅色/深色单值（经 :func:`theme.color_of`），
+    所以深浅色切换后需要重新创建才能刷新。
+    """
+
+    def __init__(
+        self,
+        master: tk.Misc,
+        text: str,
+        command: Command = None,
+        *,
+        bg: Optional[ColorToken] = None,
+        hover: Optional[ColorToken] = None,
+        fg: Optional[ColorToken] = None,
+        font: T.FontSpec = T.FONT_TINY,
+        padx: int = 10,
+        pady: int = 3,
+        radius: int = T.RADIUS_SMALL,
+    ) -> None:
+        """创建按文字宽度自适应的微型按钮。
+
+        参数:
+            master: 父容器。
+            text: 按钮文字；宽度由它决定。
+            command: 点击回调，不接收参数。
+            bg: 底色，默认 ``tokens.COLOR_SOFT``。
+            hover: 悬停底色，默认 ``tokens.COLOR_SOFT_HOVER``。
+            fg: 文字颜色，默认 ``tokens.COLOR_TEXT``。
+            font: 字体规格，默认 :data:`tokens.FONT_TINY`。
+            padx: 文字左右各留的空白（像素），默认 10。
+            pady: 文字上下各留的空白（像素），默认 3。
+            radius: 圆角半径，默认 :data:`tokens.RADIUS_SMALL`。
+        """
+        measure = _measurer(font)
+        super().__init__(
+            master,
+            text=text,
+            command=command,
+            width=measure.measure(text) + padx * 2,
+            height=measure.metrics("linespace") + pady * 2,
+            corner_radius=radius,
+            font=font,
+            fg_color=bg if bg is not None else color_of(T.COLOR_SOFT),
+            hover_color=hover if hover is not None else color_of(T.COLOR_SOFT_HOVER),
+            text_color=fg if fg is not None else color_of(T.COLOR_TEXT),
+        )
+
+
+class SoftButton(FlatButton):
+    """更安静的小按钮：灰字、更小的内边距（复制 / 显示 / 收起）。"""
+
+    def __init__(self, master: tk.Misc, text: str, command: Command = None) -> None:
+        """创建灰字小按钮。
+
+        参数:
+            master: 父容器。
+            text: 按钮文字。
+            command: 点击回调，不接收参数。
+        """
+        super().__init__(
+            master,
+            text,
+            command,
+            fg=color_of(T.COLOR_MUTED),
+            padx=8,
+            pady=2,
+            radius=T.RADIUS_SMALL - 2,
+        )

ctk_kit/dropdown.py

@@ -0,0 +1,264 @@
+"""下拉输入框：输入框 + 右侧箭头，候选用 UI Kit 自己的卡片弹出。
+
+不用 CTkComboBox：它底层是 tkinter.Menu（Windows 原生菜单），带粗白边、
+直角和系统字体，和这套深色卡片的观感对不上。
+
+箭头用字体里的实心三角字符，不做任何自绘——既不会有锯齿，也不会在输入框
+内部留下色块。
+"""
+
+from __future__ import annotations
+
+import contextlib
+import sys
+import tkinter as tk
+from typing import Callable, Optional, Sequence
+
+import customtkinter as ctk
+
+from . import tokens as T
+
+_ARROW_CLOSED = "▼"
+_ARROW_OPEN = "▲"
+
+
+class DropField(ctk.CTkFrame):
+    """输入框 + 下拉箭头，整体是一个带描边的圆角框。
+
+    用法与输入框接近：``get()`` / ``set(value)``；选中候选后会回调
+    ``command(value)``。候选由 ``values_provider()`` 提供，每次展开都会重新
+    调用，所以数据源可以在外部随意变化。
+    """
+
+    def __init__(
+        self,
+        master: tk.Misc,
+        *,
+        values_provider: Callable[[], Sequence[str]],
+        command: Optional[Callable[[str], None]] = None,
+        placeholder: str = "",
+        height: int = 36,
+    ) -> None:
+        """创建下拉输入框。
+
+        参数:
+            master: 父容器。
+            values_provider: 返回候选列表的函数，每次展开下拉都会调用一次。
+            command: 选中候选后的回调，参数是被选中的字符串。
+            placeholder: 输入框为空时的灰色占位文字。
+            height: 整体高度（像素），默认 36。
+        """
+        super().__init__(
+            master,
+            fg_color=T.COLOR_INPUT,
+            border_width=1,
+            border_color=T.COLOR_BORDER,
+            corner_radius=T.RADIUS_SMALL,
+            height=height,
+        )
+        self.pack_propagate(False)
+        self._values_provider: Callable[[], Sequence[str]] = values_provider
+        self._command: Optional[Callable[[str], None]] = command
+        self._popup: Optional[ctk.CTkToplevel] = None
+        self._root_bind_id: Optional[str] = None
+        self._focus_bind_id: Optional[str] = None
+
+        self.entry: ctk.CTkEntry = ctk.CTkEntry(
+            self,
+            fg_color="transparent",
+            border_width=0,
+            corner_radius=0,
+            height=height - 2,
+            font=T.FONT_BODY,
+            text_color=T.COLOR_TEXT,
+            placeholder_text=placeholder,
+            placeholder_text_color=T.COLOR_FAINT,
+        )
+        self.entry.pack(side="left", fill="both", expand=True, padx=(12, 0), pady=1)
+
+        self.arrow: ctk.CTkLabel = ctk.CTkLabel(
+            self,
+            text=_ARROW_CLOSED,
+            width=34,
+            height=26,
+            font=(T.FONT_NAME, 11),
+            text_color=T.COLOR_MUTED,
+            fg_color="transparent",
+            corner_radius=5,
+            anchor="center",
+        )
+        self.arrow.pack(side="right", padx=(0, 4), pady=1)
+        self.arrow.configure(cursor="hand2")
+        self.arrow.bind("<Button-1>", lambda _event: self.open_menu())
+        self.arrow.bind("<Enter>", lambda _event: self._set_hover(True))
+        self.arrow.bind("<Leave>", lambda _event: self._set_hover(False))
+
+    def _set_hover(self, hover: bool) -> None:
+        """箭头悬停态：文字与底色一起变。"""
+        self.arrow.configure(
+            text_color=T.COLOR_TEXT if hover else T.COLOR_MUTED,
+            fg_color=T.COLOR_HOVER_FAINT if hover else "transparent",
+        )
+
+    # --- 读写 ---
+    def get(self) -> str:
+        """当前输入框里的文字。"""
+        return self.entry.get()
+
+    def set(self, value: str) -> None:
+        """直接写入一个值（不触发 ``command``）。"""
+        self.entry.delete(0, "end")
+        self.entry.insert(0, value)
+
+    # --- 下拉面板 ---
+    def open_menu(self) -> None:
+        """展开候选面板；已经展开时再次调用会收起。"""
+        if self._popup is not None and self._popup.winfo_exists():
+            self._close_menu()
+            return
+
+        values = list(self._values_provider() or [])
+        if not values:
+            return
+
+        popup = ctk.CTkToplevel(self)
+        popup.withdraw()
+        popup.overrideredirect(True)
+        popup.attributes("-topmost", True)
+        popup.configure(fg_color=T.COLOR_CARD)
+
+        body = ctk.CTkFrame(
+            popup,
+            fg_color=T.COLOR_CARD,
+            corner_radius=0,
+            border_width=1,
+            border_color=T.COLOR_BORDER,
+        )
+        body.pack(fill="both", expand=True)
+
+        for value in values:
+            ctk.CTkButton(
+                body,
+                text=value,
+                anchor="w",
+                height=32,
+                corner_radius=T.RADIUS_SMALL,
+                fg_color="transparent",
+                hover_color=T.COLOR_SOFT_HOVER,
+                text_color=T.COLOR_TEXT,
+                font=T.FONT_SMALL,
+                command=lambda v=value: self._pick(v),
+            ).pack(fill="x", padx=5, pady=1)
+
+        popup.update_idletasks()
+        # 宽高按逻辑像素缩放，位置参数直接是物理像素
+        scaling = self.winfo_toplevel()._get_window_scaling()
+        width = max(self.winfo_width(), int(320 * scaling)) / scaling
+        height = (popup.winfo_reqheight() + 2) / scaling
+        popup.geometry(
+            f"{int(width)}x{int(height)}+"
+            f"{self.winfo_rootx()}+{self.winfo_rooty() + self.winfo_height() + 2}"
+        )
+        popup.deiconify()
+        popup.bind("<Escape>", self._close_menu)
+        self._round_window_corners(popup)
+
+        self._popup = popup
+        self.arrow.configure(text=_ARROW_OPEN)
+        # 点击面板以外的地方收起：绑在顶层窗口上（子控件的点击也会冒泡到顶层）
+        self._root_bind_id = self.winfo_toplevel().bind(
+            "<Button-1>", self._maybe_close_menu, add="+"
+        )
+        # 焦点离开本应用（切到别的程序）时也收起，避免面板一直浮在最上面
+        self._focus_bind_id = self.winfo_toplevel().bind(
+            "<FocusOut>", self._on_root_focus_out, add="+"
+        )
+
+    def _on_root_focus_out(self, _event: Optional[tk.Event] = None) -> None:
+        """顶层窗口失焦后稍等再检查焦点，避免刚点面板就被收起。"""
+        self.after(100, self._check_focus)
+
+    def _check_focus(self) -> None:
+        """焦点既不在面板、也不在本窗口时收起面板。"""
+        if self._popup is None:
+            return
+        try:
+            focused = self.focus_get()
+        except Exception:
+            focused = None
+        if focused is not None:
+            widget_name = str(focused)
+            if widget_name.startswith(str(self._popup)) or widget_name.startswith(
+                str(self.winfo_toplevel())
+            ):
+                return
+        self._close_menu()
+
+    def _round_window_corners(self, popup: ctk.CTkToplevel) -> None:
+        """把窗口本身裁成圆角。
+
+        tk 的窗口永远是直角，靠透明键色抠角又会留下一圈抗锯齿杂边，
+        这里直接用 Windows 的 SetWindowRgn 把窗口区域切掉，四角干净没有残色。
+        非 Windows 平台什么都不做。
+        """
+        if sys.platform != "win32":
+            return
+        with contextlib.suppress(Exception):
+            import ctypes
+
+            popup.update_idletasks()
+            hwnd = ctypes.windll.user32.GetParent(popup.winfo_id()) or popup.winfo_id()
+            scaling = self.winfo_toplevel()._get_window_scaling()
+            radius = int(T.RADIUS_MEDIUM * 2 * scaling)
+            width = popup.winfo_width()
+            height = popup.winfo_height()
+            region = ctypes.windll.gdi32.CreateRoundRectRgn(
+                0, 0, width + 1, height + 1, radius, radius
+            )
+            ctypes.windll.user32.SetWindowRgn(hwnd, region, True)
+
+    def _maybe_close_menu(self, event: tk.Event) -> None:
+        """顶层窗口上的点击：点在面板外就收起。"""
+        popup = self._popup
+        if popup is None or not popup.winfo_exists():
+            return
+        if (
+            popup.winfo_rootx()
+            <= event.x_root
+            <= popup.winfo_rootx() + popup.winfo_width()
+            and popup.winfo_rooty()
+            <= event.y_root
+            <= popup.winfo_rooty() + popup.winfo_height()
+        ):
+            return
+        self._close_menu()
+
+    def _pick(self, value: str) -> None:
+        """选中候选：写入值、收起面板、回调。"""
+        self.set(value)
+        self._close_menu()
+        if self._command is not None:
+            self._command(value)
+
+    def _close_menu(self, _event: Optional[tk.Event] = None) -> None:
+        """收起面板并清理绑定；重复调用安全。"""
+        if self._root_bind_id is not None:
+            with contextlib.suppress(Exception):
+                self.winfo_toplevel().unbind("<Button-1>", self._root_bind_id)
+            self._root_bind_id = None
+        if self._focus_bind_id is not None:
+            with contextlib.suppress(Exception):
+                self.winfo_toplevel().unbind("<FocusOut>", self._focus_bind_id)
+            self._focus_bind_id = None
+        with contextlib.suppress(Exception):
+            self.arrow.configure(text=_ARROW_CLOSED)
+        if self._popup is not None:
+            with contextlib.suppress(Exception):
+                if self._popup.winfo_exists():
+                    self._popup.destroy()
+            self._popup = None
+
+    def destroy(self) -> None:
+        """销毁前先收起面板，避免浮窗残留。"""
+        self._close_menu()
+        super().destroy()