ctk-kit 0.2.0__tar.gz → 0.3.0__tar.gz

{ctk_kit-0.2.0 → ctk_kit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctk-kit
-Version: 0.2.0
+Version: 0.3.0
 Summary: 面向 CustomTkinter 的轻量界面基件：深浅色令牌、常用控件与懒加载列表
 Author-email: 加点盐 <1431705288@qq.com>
 License: MIT
@@ -63,12 +63,21 @@ primary_button(app, "新建", lambda: None).pack()
 app.mainloop()
 ```
 
-看实际效果：
+看实际效果：示例随包发布，装好 ctk-kit 后可以直接跑：
+
+```
+pip install ctk-kit
+ctk-kit-showcase
+```
+
+也可以从源码运行（不用安装）：
 
 ```
 git clone https://gitee.com/kuangjianke/ctk-kit
 cd ctk-kit
 python examples/showcase.py
+# 等价写法
+python -m ctk_kit.showcase
 ```
 
 展示程序有九个页面：总览、基件、按钮、输入、布局、列表、主题、表单、设置，把每个公开构建都用一遍。
@@ -101,8 +110,10 @@ python examples/showcase.py
 
 **大文本**（`text`）
 
-- `TextArea(master, *, placeholder="", height=200, readonly=False, show_counter=True, on_change=None)`
-  —— 多行文本区：失焦时显示占位符、底部字数统计、可切换只读；读写用 `get()/set()/clear()`
+- `TextArea(master, *, placeholder="", height=200, readonly=False, show_counter=True, on_change=None, bg_color=None, text_color=None)`
+  —— 多行文本区：失焦时显示占位符、底部字数统计、可切换只读；读写用 `get()/set()/clear()`。
+  内部底色默认 `COLOR_INPUT`（输入框语义）；当日志面板显示时传 `bg_color=COLOR_CARD` 或
+  `bg_color="transparent"`，就不会比所在卡片亮一截，`text_color` 也可单独覆盖
 
 **下拉**（`dropdown`）
 
@@ -135,6 +146,17 @@ python examples/showcase.py
   listing.render(items)
   ```
 
+  数据量很大（几千条）时，传入固定卡高开启虚拟滚动：只把视口附近的卡片放上布局，
+  滚出去的卡片留在内存里复用，滚回来直接放回去，不销毁也不重建。
+
+  ```python
+  listing = LazyList(frame, make_card, key_of=lambda item: item["id"], item_height=96)
+  ```
+
+  虚拟滚动要求卡片高度固定（例如自己 `pack_propagate(False)` 并设置 `height`），
+  并把卡片间距算进 `item_height`。`item_height` 用和控件尺寸一样的逻辑单位，
+  高 DPI 缩放下由 `LazyList` 自己换算。
+
 ## 设计令牌
 
 颜色全部是 `(浅色, 深色)` 二元组，交给 `color_of()` 按当前外观取值：
@@ -159,10 +181,12 @@ ctk_kit/
 ├─ inputs.py       输入框 / 分段选择 / 开关
 ├─ dropdown.py     自绘下拉
 ├─ layout.py       页头、卡片、分隔线、空态、滚动容器
-└─ scroll_list.py  懒加载列表
+├─ scroll_list.py  懒加载列表
+├─ text.py         多行文本区
+└─ showcase.py     全组件展示（随包发布，`ctk-kit-showcase`）
 
 examples/
-└─ showcase.py     全组件展示（九个页面，也可当模板改）
+└─ showcase.py     仓库里的快捷入口（转发到 ctk_kit.showcase:main）
 ```
 
 ## 测试
@@ -173,7 +197,7 @@ pytest
 ```
 
 测试跑在真实 Tk 窗口里（窗口全透明，不会在屏幕上闪），覆盖令牌、主题、按钮、输入框、
-下拉、布局、懒加载列表，以及 `examples/showcase.py` 的九个示例页；没有图形环境时相关用例自动 skip。
+下拉、布局、懒加载列表、大文本区，以及 `ctk_kit/showcase.py` 的九个示例页；没有图形环境时相关用例自动 skip。
 
 CI 在 GitHub Actions 上跑 Python 3.8 – 3.14 全矩阵（`.github/workflows/ci.yml`），
 无头环境下用 Xvfb 提供虚拟屏幕；`CI` 环境变量存在时如果建不出窗口会直接失败，而不是静默跳过。

{ctk_kit-0.2.0 → ctk_kit-0.3.0}/README.md

@@ -29,12 +29,21 @@ primary_button(app, "新建", lambda: None).pack()
 app.mainloop()
 ```
 
-看实际效果：
+看实际效果：示例随包发布，装好 ctk-kit 后可以直接跑：
+
+```
+pip install ctk-kit
+ctk-kit-showcase
+```
+
+也可以从源码运行（不用安装）：
 
 ```
 git clone https://gitee.com/kuangjianke/ctk-kit
 cd ctk-kit
 python examples/showcase.py
+# 等价写法
+python -m ctk_kit.showcase
 ```
 
 展示程序有九个页面：总览、基件、按钮、输入、布局、列表、主题、表单、设置，把每个公开构建都用一遍。
@@ -67,8 +76,10 @@ python examples/showcase.py
 
 **大文本**（`text`）
 
-- `TextArea(master, *, placeholder="", height=200, readonly=False, show_counter=True, on_change=None)`
-  —— 多行文本区：失焦时显示占位符、底部字数统计、可切换只读；读写用 `get()/set()/clear()`
+- `TextArea(master, *, placeholder="", height=200, readonly=False, show_counter=True, on_change=None, bg_color=None, text_color=None)`
+  —— 多行文本区：失焦时显示占位符、底部字数统计、可切换只读；读写用 `get()/set()/clear()`。
+  内部底色默认 `COLOR_INPUT`（输入框语义）；当日志面板显示时传 `bg_color=COLOR_CARD` 或
+  `bg_color="transparent"`，就不会比所在卡片亮一截，`text_color` 也可单独覆盖
 
 **下拉**（`dropdown`）
 
@@ -101,6 +112,17 @@ python examples/showcase.py
   listing.render(items)
   ```
 
+  数据量很大（几千条）时，传入固定卡高开启虚拟滚动：只把视口附近的卡片放上布局，
+  滚出去的卡片留在内存里复用，滚回来直接放回去，不销毁也不重建。
+
+  ```python
+  listing = LazyList(frame, make_card, key_of=lambda item: item["id"], item_height=96)
+  ```
+
+  虚拟滚动要求卡片高度固定（例如自己 `pack_propagate(False)` 并设置 `height`），
+  并把卡片间距算进 `item_height`。`item_height` 用和控件尺寸一样的逻辑单位，
+  高 DPI 缩放下由 `LazyList` 自己换算。
+
 ## 设计令牌
 
 颜色全部是 `(浅色, 深色)` 二元组，交给 `color_of()` 按当前外观取值：
@@ -125,10 +147,12 @@ ctk_kit/
 ├─ inputs.py       输入框 / 分段选择 / 开关
 ├─ dropdown.py     自绘下拉
 ├─ layout.py       页头、卡片、分隔线、空态、滚动容器
-└─ scroll_list.py  懒加载列表
+├─ scroll_list.py  懒加载列表
+├─ text.py         多行文本区
+└─ showcase.py     全组件展示（随包发布，`ctk-kit-showcase`）
 
 examples/
-└─ showcase.py     全组件展示（九个页面，也可当模板改）
+└─ showcase.py     仓库里的快捷入口（转发到 ctk_kit.showcase:main）
 ```
 
 ## 测试
@@ -139,7 +163,7 @@ pytest
 ```
 
 测试跑在真实 Tk 窗口里（窗口全透明，不会在屏幕上闪），覆盖令牌、主题、按钮、输入框、
-下拉、布局、懒加载列表，以及 `examples/showcase.py` 的九个示例页；没有图形环境时相关用例自动 skip。
+下拉、布局、懒加载列表、大文本区，以及 `ctk_kit/showcase.py` 的九个示例页；没有图形环境时相关用例自动 skip。
 
 CI 在 GitHub Actions 上跑 Python 3.8 – 3.14 全矩阵（`.github/workflows/ci.yml`），
 无头环境下用 Xvfb 提供虚拟屏幕；`CI` 环境变量存在时如果建不出窗口会直接失败，而不是静默跳过。

{ctk_kit-0.2.0 → ctk_kit-0.3.0}/ctk_kit/__init__.py

@@ -21,9 +21,12 @@
     primary_button(box, "立即备份", command=lambda: print("go")).pack(padx=16, pady=16)
     app.mainloop()
 
-全组件展示（示例脚本，见仓库 examples/）::
+全组件展示（随包发布，装好后直接运行）::
 
-    python examples/showcase.py
+    ctk-kit-showcase
+    python -m ctk_kit.showcase
+
+从源码运行时等价写法：``python examples/showcase.py``。
 
 仓库: https://gitee.com/kuangjianke/ctk-kit
 镜像: https://github.com/DashSalter/ctk-kit
@@ -31,7 +34,7 @@
 
 from __future__ import annotations
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 from . import tokens, theme
 from .buttons import (

{ctk_kit-0.2.0 → ctk_kit-0.3.0}/ctk_kit/scroll_list.py

@@ -52,6 +52,11 @@ class LazyList(tk.Frame):
         load_threshold: 可滚动区滚到多少比例触发追加，默认 0.92。
         gap: 卡片上下的外边距，默认 ``(0, 10)``。
         padx: 卡片左右留白（给滚动条让位），默认 ``(0, 8)``。
+        item_height: 固定卡片高度（含 ``gap``）。给定时开启虚拟滚动：只把
+            视口附近的卡片放上布局，滚出视口的卡片保留在内存里复用，滚回来
+            直接重新放上去，不销毁、不重建。适合几千条数据的列表；要求
+            ``render_card`` 返回的卡片高度固定（例如自己 ``pack_propagate(False)``
+            并设置 ``height``），否则卡片会互相叠压。
     """
 
     def __init__(
@@ -66,6 +71,7 @@ class LazyList(tk.Frame):
         load_threshold: float = 0.92,
         gap: tuple[int, int] = (0, 10),
         padx: tuple[int, int] = (0, 8),
+        item_height: Optional[int] = None,
     ) -> None:
         super().__init__(master, bg=color_of(T.COLOR_BG), highlightthickness=0)
         self.render_card: RenderCard = render_card
@@ -76,6 +82,9 @@ class LazyList(tk.Frame):
         self.load_threshold: float = load_threshold
         self.gap: tuple[int, int] = gap
         self.padx: tuple[int, int] = padx
+        #: 固定卡片高度（含间距）。给定时开启虚拟滚动：只把视口附近的卡片
+        #: 放上布局，滚过去的卡片留在内存里复用，不销毁，回滚时直接放回来。
+        self.item_height: Optional[int] = item_height
 
         self._items: list[Any] = []
         self._shown: int = 0
@@ -85,6 +94,10 @@ class LazyList(tk.Frame):
         self._signature: Optional[tuple] = None
         self._empty_box: Optional[tk.Frame] = None
         self._scrollbar_visible: Optional[bool] = None
+        #: 虚拟模式：索引 -> 已建卡片（卡片不销毁，只在视口外 place_forget）。
+        self._built: dict[int, tk.Misc] = {}
+        self._range: Optional[tuple[int, int]] = None
+        self._resize_job: Optional[str] = None
 
         self.grid_rowconfigure(0, weight=1)
         self.grid_columnconfigure(0, weight=1)
@@ -157,6 +170,12 @@ class LazyList(tk.Frame):
             self._empty_box = box
             return
 
+        if self.item_height is not None:
+            self._layout_virtual()
+            self._suppress = False
+            self.after(1, self._refresh_scroll)
+            return
+
         self._append(self.first_batch)
         self._suppress = False
         # 滚动条位置留到下一帧再算：set() 会同步布局，放在这里会拖慢首帧
@@ -189,14 +208,45 @@ class LazyList(tk.Frame):
 
     @property
     def cards(self) -> list[tk.Misc]:
-        """当前已建出的卡片控件（副本，改动它不会影响列表）。"""
+        """当前已建出的卡片控件（副本，改动它不会影响列表）。
+
+        虚拟模式下返回所有建过的卡片（含视口外未布局的），按索引排序。
+        """
+        if self.item_height is not None:
+            return [self._built[index] for index in sorted(self._built)]
         return list(self.inner.winfo_children())
 
     def flush(self) -> None:
-        """一次性补齐所有卡片（测试、导出时用）。"""
+        """一次性补齐所有卡片（测试、导出时用）。
+
+        虚拟模式下只建卡、不改变视口，所以耗时也只和卡片总数有关。
+        """
+        if self.item_height is not None:
+            for index in range(len(self._items)):
+                self._ensure_card(index)
+            self._sync_window(force=True)
+            return
         self._cancel_load()
         self._append(len(self._items) - self._shown)
 
+    def reset(self) -> None:
+        """回到首屏：只保留 ``first_batch`` 张卡并把滚动位置归零。
+
+        适合页面被隐藏时调用。已展开几百张卡时，控件数量会让重新显示
+        或窗口缩放明显变慢；缩回首屏后重排成本就回到常数级。
+
+        虚拟模式下卡片本来就只布局视口附近，所以这里只把滚动位置归零，
+        已建卡片全部保留复用，不会重建。
+        """
+        if not self._items:
+            return
+        if self.item_height is not None:
+            self.canvas.yview_moveto(0)
+            self._sync_window(force=True)
+            return
+        self._signature = None
+        self.render(self._items, force=True)
+
     def scroll_units(self, steps: int) -> None:
         """按「行」滚动；steps>0 向下，steps<0 向上。
 
@@ -225,6 +275,7 @@ class LazyList(tk.Frame):
     def destroy(self) -> None:
         """停止滚轮绑定后销毁。"""
         self._alive = False
+        self._cancel_resize()
         super().destroy()
 
     # ------------------------------------------------------------------ #
@@ -256,8 +307,11 @@ class LazyList(tk.Frame):
 
     def _sync_scrollbar(self) -> None:
         """内容装得下时把滑块涂成背景色（布局宽度不变）。"""
-        box = self.canvas.bbox("all")
-        content = (box[3] - box[1]) if box else 0
+        if self.item_height is not None:
+            content = len(self._items) * self.item_height * self._card_scale()
+        else:
+            box = self.canvas.bbox("all")
+            content = (box[3] - box[1]) if box else 0
         visible = content > self.canvas.winfo_height() + 1
         if visible == self._scrollbar_visible:
             return
@@ -275,6 +329,8 @@ class LazyList(tk.Frame):
         放在定时器里：Tk 要跑完一次事件循环才会更新内层 Frame 的尺寸，
         这时 bbox 才是准的。
         """
+        if self.item_height is not None:
+            return
         if self._shown >= len(self._items):
             return
         box = self.canvas.bbox("all")
@@ -294,6 +350,10 @@ class LazyList(tk.Frame):
         if self._suppress:
             return
         self.scrollbar.set(first, last)
+        if self.item_height is not None:
+            self._sync_scrollbar()
+            self._sync_window(float(first), float(last))
+            return
         if self._loading or self._shown >= len(self._items):
             return
         # 不信回调参数：scrollregion 刚变时会回放一次 (0, 1)
@@ -314,12 +374,23 @@ class LazyList(tk.Frame):
             self.after_cancel(self._load_job)
             self._load_job = None
 
+    def _cancel_resize(self) -> None:
+        """取消还没触发的窗口尺寸同步任务。"""
+        if self._resize_job is not None:
+            self.after_cancel(self._resize_job)
+            self._resize_job = None
+
     def _clear_cards(self) -> None:
         """清空内层卡片并复位滚动位置。"""
         self._loading = False
         self._cancel_load()
+        self._cancel_resize()
+        self._built.clear()
+        self._range = None
         for child in self.inner.winfo_children():
             child.destroy()
+        if self.item_height is not None:
+            self.inner.configure(height=0)
         self._empty_box = None
         self.canvas.yview_moveto(0)
         self._sync_scrollregion()
@@ -334,9 +405,101 @@ class LazyList(tk.Frame):
 
     def _sync_scrollregion(self, _event: Optional[tk.Event] = None) -> None:
         """把 canvas 的可滚动区域更新为内容包围盒。"""
+        if self.item_height is not None and self._items:
+            # 虚拟模式的内容高度是算出来的，不依赖当前放上布局的卡片
+            height = self.item_height * len(self._items) * self._card_scale()
+            self.canvas.configure(
+                scrollregion=(0, 0, self.canvas.winfo_width(), height)
+            )
+            return
         self.canvas.configure(scrollregion=self.canvas.bbox("all"))
 
     def _on_canvas_resize(self, event: tk.Event) -> None:
         """canvas 宽度变化时让内层 Frame 跟着变宽。"""
         self.canvas.itemconfigure(self._window, width=event.width)
-        self.after(1, self._sync_scrollbar)
+        if self.item_height is None:
+            self.after(1, self._sync_scrollbar)
+            return
+        # 拖动窗口时 Configure 会连发很多次，合并成一次，避免反复排版
+        if self._resize_job is not None:
+            self.after_cancel(self._resize_job)
+        self._resize_job = self.after(60, self._after_resize)
+
+    def _after_resize(self) -> None:
+        """窗口尺寸稳定后补一次滚动条与视口同步。"""
+        self._resize_job = None
+        self._sync_scrollbar()
+        if self.item_height is not None:
+            self._sync_window()
+
+    # ------------------------------------------------------------------ #
+    #  虚拟滚动
+    def _card_scale(self) -> float:
+        """卡片 place 时 CTk 会按窗口缩放放大坐标，这里取同一个系数。"""
+        try:
+            scale = float(ctk.ScalingTracker.get_widget_scaling(self))
+        except Exception:
+            scale = 1.0
+        return scale if scale > 0 else 1.0
+
+    def _layout_virtual(self) -> None:
+        """按固定卡片高度把内层撑到总高，然后只铺视口附近的卡片。"""
+        height = self.item_height or 0
+        total = len(self._items) * height * self._card_scale()
+        self.inner.configure(height=total)
+        self.canvas.itemconfigure(self._window, width=self.canvas.winfo_width())
+        self.canvas.configure(
+            scrollregion=(0, 0, self.canvas.winfo_width(), total)
+        )
+        self._sync_window(force=True)
+
+    def _ensure_card(self, index: int) -> tk.Misc:
+        """按索引取卡：建过的直接复用，没建过的才调 ``render_card``。"""
+        card = self._built.get(index)
+        if card is None:
+            card = self.render_card(self.inner, self._items[index])
+            self._built[index] = card
+        return card
+
+    def _sync_window(
+        self, first: Optional[float] = None, last: Optional[float] = None, force: bool = False
+    ) -> None:
+        """把视口附近的卡片放上布局，滚出视口的收起（保留对象不销毁）。
+
+        ``first`` / ``last`` 由 yscrollcommand 回调直接给出；不传时读
+        ``canvas.yview()``。滚动过程中回调参数比再读一次更接近真实位置。
+        """
+        height = self.item_height
+        if height is None:
+            return
+        count = len(self._items)
+        if count == 0:
+            return
+        # 内层是普通 tk.Frame，高度按物理像素算；卡片 place 的坐标是逻辑值，
+        # CTk 会再乘一次缩放，所以总高要乘缩放系数，否则滚动位置会错位。
+        scale = self._card_scale()
+        total = count * height * scale
+        step = height * scale
+        if int(self.inner.cget("height")) != total:
+            # 任何地方把内层改小时都拉回总高，否则滚动条比例会错
+            self.inner.configure(height=total)
+            self.canvas.configure(
+                scrollregion=(0, 0, self.canvas.winfo_width(), total)
+            )
+        if first is None or last is None:
+            current = self.canvas.yview()
+            first, last = float(current[0]), float(current[1])
+        # 缓冲几张，快速滚动或拖动滚动条时不会露出空白
+        start = max(0, int(first * total // step) - 3)
+        end = min(count, int(last * total // step) + 4)
+        if not force and (start, end) == self._range:
+            return
+        self._range = (start, end)
+        for index in range(start, end):
+            card = self._ensure_card(index)
+            # CTk 控件禁止在 place() 里传 width/height，卡片高度由
+            # render_card 自己固定；这里只负责纵向定位和铺满宽度。
+            card.place(x=self.padx[0], y=index * height + self.gap[0], relwidth=1)
+        for index, card in list(self._built.items()):
+            if index < start or index >= end:
+                card.place_forget()