ctk-kit 0.2.0__tar.gz → 0.6.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- ctk_kit-0.6.0/PKG-INFO +393 -0
- ctk_kit-0.6.0/README.md +361 -0
- {ctk_kit-0.2.0 → ctk_kit-0.6.0}/ctk_kit/__init__.py +26 -6
- {ctk_kit-0.2.0 → ctk_kit-0.6.0}/ctk_kit/inputs.py +7 -4
- ctk_kit-0.6.0/ctk_kit/notify.py +606 -0
- ctk_kit-0.6.0/ctk_kit/pages.py +218 -0
- {ctk_kit-0.2.0 → ctk_kit-0.6.0}/ctk_kit/scroll_list.py +204 -5
- ctk_kit-0.6.0/ctk_kit/showcase/__init__.py +277 -0
- ctk_kit-0.6.0/ctk_kit/showcase/__main__.py +10 -0
- ctk_kit-0.6.0/ctk_kit/showcase/data.py +63 -0
- ctk_kit-0.6.0/ctk_kit/showcase/pages/__init__.py +45 -0
- ctk_kit-0.6.0/ctk_kit/showcase/pages/buttons.py +133 -0
- ctk_kit-0.6.0/ctk_kit/showcase/pages/form.py +122 -0
- ctk_kit-0.6.0/ctk_kit/showcase/pages/foundation.py +249 -0
- ctk_kit-0.6.0/ctk_kit/showcase/pages/inputs.py +223 -0
- ctk_kit-0.6.0/ctk_kit/showcase/pages/layout.py +122 -0
- ctk_kit-0.6.0/ctk_kit/showcase/pages/listing.py +174 -0
- ctk_kit-0.6.0/ctk_kit/showcase/pages/notify.py +225 -0
- ctk_kit-0.6.0/ctk_kit/showcase/pages/overview.py +108 -0
- ctk_kit-0.6.0/ctk_kit/showcase/pages/settings.py +100 -0
- ctk_kit-0.6.0/ctk_kit/showcase/pages/theme.py +155 -0
- ctk_kit-0.6.0/ctk_kit/showcase/shell.py +138 -0
- {ctk_kit-0.2.0 → ctk_kit-0.6.0}/ctk_kit/text.py +12 -5
- ctk_kit-0.6.0/ctk_kit/theme.py +280 -0
- {ctk_kit-0.2.0 → ctk_kit-0.6.0}/ctk_kit/tokens.py +4 -1
- ctk_kit-0.6.0/ctk_kit.egg-info/PKG-INFO +393 -0
- ctk_kit-0.6.0/ctk_kit.egg-info/SOURCES.txt +36 -0
- ctk_kit-0.6.0/ctk_kit.egg-info/entry_points.txt +2 -0
- {ctk_kit-0.2.0 → ctk_kit-0.6.0}/ctk_kit.egg-info/requires.txt +0 -3
- {ctk_kit-0.2.0 → ctk_kit-0.6.0}/pyproject.toml +4 -8
- ctk_kit-0.2.0/PKG-INFO +0 -209
- ctk_kit-0.2.0/README.md +0 -175
- ctk_kit-0.2.0/ctk_kit/theme.py +0 -72
- ctk_kit-0.2.0/ctk_kit.egg-info/PKG-INFO +0 -209
- ctk_kit-0.2.0/ctk_kit.egg-info/SOURCES.txt +0 -28
- ctk_kit-0.2.0/tests/test_buttons.py +0 -145
- ctk_kit-0.2.0/tests/test_dropdown.py +0 -177
- ctk_kit-0.2.0/tests/test_inputs.py +0 -126
- ctk_kit-0.2.0/tests/test_layout.py +0 -133
- ctk_kit-0.2.0/tests/test_package.py +0 -95
- ctk_kit-0.2.0/tests/test_scroll_list.py +0 -209
- ctk_kit-0.2.0/tests/test_showcase.py +0 -480
- ctk_kit-0.2.0/tests/test_text.py +0 -122
- ctk_kit-0.2.0/tests/test_theme.py +0 -86
- ctk_kit-0.2.0/tests/test_tokens.py +0 -94
- {ctk_kit-0.2.0 → ctk_kit-0.6.0}/LICENSE +0 -0
- {ctk_kit-0.2.0 → ctk_kit-0.6.0}/ctk_kit/buttons.py +0 -0
- {ctk_kit-0.2.0 → ctk_kit-0.6.0}/ctk_kit/dropdown.py +0 -0
- {ctk_kit-0.2.0 → ctk_kit-0.6.0}/ctk_kit/layout.py +0 -0
- {ctk_kit-0.2.0 → ctk_kit-0.6.0}/ctk_kit/py.typed +0 -0
- {ctk_kit-0.2.0 → ctk_kit-0.6.0}/ctk_kit.egg-info/dependency_links.txt +0 -0
- {ctk_kit-0.2.0 → ctk_kit-0.6.0}/ctk_kit.egg-info/top_level.txt +0 -0
- {ctk_kit-0.2.0 → ctk_kit-0.6.0}/setup.cfg +0 -0
ctk_kit-0.6.0/PKG-INFO
ADDED
|
@@ -0,0 +1,393 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: ctk-kit
|
|
3
|
+
Version: 0.6.0
|
|
4
|
+
Summary: 面向 CustomTkinter 的轻量界面基件:深浅色令牌、常用控件与懒加载列表
|
|
5
|
+
Author-email: 加点盐 <1431705288@qq.com>
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://gitee.com/kuangjianke/ctk-kit
|
|
8
|
+
Project-URL: Repository, https://gitee.com/kuangjianke/ctk-kit
|
|
9
|
+
Project-URL: Issues, https://gitee.com/kuangjianke/ctk-kit/issues
|
|
10
|
+
Project-URL: Changelog, https://gitee.com/kuangjianke/ctk-kit/blob/main/CHANGELOG.md
|
|
11
|
+
Project-URL: GitHub Mirror, https://github.com/DashSalter/ctk-kit
|
|
12
|
+
Keywords: customtkinter,tkinter,ui,ui-kit,theme,dark-mode,widgets
|
|
13
|
+
Classifier: Development Status :: 3 - Alpha
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.8
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
24
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
25
|
+
Classifier: Topic :: Software Development :: User Interfaces
|
|
26
|
+
Classifier: Typing :: Typed
|
|
27
|
+
Requires-Python: >=3.8
|
|
28
|
+
Description-Content-Type: text/markdown
|
|
29
|
+
License-File: LICENSE
|
|
30
|
+
Requires-Dist: customtkinter>=5.2
|
|
31
|
+
Dynamic: license-file
|
|
32
|
+
|
|
33
|
+
# ctk-kit
|
|
34
|
+
|
|
35
|
+
[](https://github.com/DashSalter/ctk-kit/actions/workflows/ci.yml)
|
|
36
|
+
[](https://pypi.org/project/ctk-kit/)
|
|
37
|
+
[](https://pypi.org/project/ctk-kit/)
|
|
38
|
+
[](LICENSE)
|
|
39
|
+
|
|
40
|
+
面向 [CustomTkinter](https://github.com/TomSchimansky/CustomTkinter) 的轻量界面基件:
|
|
41
|
+
一套深浅色设计令牌、一批常用控件,以及一个会自动分页的懒加载列表。
|
|
42
|
+
提示信息不再只能当成一行文字写进布局——`Notifier` 把它浮在窗口顶部或底部,
|
|
43
|
+
不占地方,几秒后自己消失。
|
|
44
|
+
支持 Python 3.8 – 3.14。
|
|
45
|
+
|
|
46
|
+
写它的起因很朴素——每个 customtkinter 项目都要重新调一遍颜色、圆角、按钮宽度和滚动列表的
|
|
47
|
+
分批渲染,调完还很难看齐。ctk-kit 把这些收成一层薄薄的公共件,项目之间可以直接复用。
|
|
48
|
+
|
|
49
|
+
```
|
|
50
|
+
pip install ctk-kit
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
```python
|
|
54
|
+
import customtkinter as ctk
|
|
55
|
+
from ctk_kit import apply_appearance, primary_button, page_header
|
|
56
|
+
|
|
57
|
+
apply_appearance("Dark")
|
|
58
|
+
app = ctk.CTk()
|
|
59
|
+
|
|
60
|
+
head, info = page_header(app, "全部记录")
|
|
61
|
+
head.pack(fill="x", padx=20, pady=(16, 8))
|
|
62
|
+
primary_button(app, "新建", lambda: None).pack()
|
|
63
|
+
app.mainloop()
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
看实际效果:示例随包发布,装好 ctk-kit 后可以直接跑:
|
|
67
|
+
|
|
68
|
+
```
|
|
69
|
+
pip install ctk-kit
|
|
70
|
+
ctk-kit-showcase
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
也可以从源码运行(不用安装):
|
|
74
|
+
|
|
75
|
+
```
|
|
76
|
+
git clone https://gitee.com/kuangjianke/ctk-kit
|
|
77
|
+
cd ctk-kit
|
|
78
|
+
python examples/showcase.py
|
|
79
|
+
# 等价写法
|
|
80
|
+
python -m ctk_kit.showcase
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
每个页面也能单独启动,改哪一页就只跑哪一页:
|
|
84
|
+
|
|
85
|
+
```
|
|
86
|
+
python -m ctk_kit.showcase.pages.buttons
|
|
87
|
+
python -m ctk_kit.showcase.pages.inputs
|
|
88
|
+
python -m ctk_kit.showcase.pages.notify --topmost
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
页面代码在 `ctk_kit/showcase/pages/` 下,一页一个文件;`--where` 会打印窗口矩形后退出,方便截图。
|
|
92
|
+
|
|
93
|
+
展示程序有十个页面:总览、基件、按钮、输入、布局、提示、列表、主题、表单、设置,把每个公开构建都用一遍。
|
|
94
|
+
基件页把 25 个色值连同浅/深两套十六进制值一起列出来,换主题时对着它调最直观。
|
|
95
|
+
|
|
96
|
+
## 四层结构
|
|
97
|
+
|
|
98
|
+
| 层 | 模块 | 内容 |
|
|
99
|
+
| --- | --- | --- |
|
|
100
|
+
| 令牌 | `tokens` | `COLOR_*`(全部为浅/深二元组)、`FONT_*`、`RADIUS_*`、`SPACE_*` |
|
|
101
|
+
| 主题 | `theme` | `is_dark()`、`color_of()`、`apply_appearance()`、`apply_appearance_fast()`、`set_titlebar_dark()`、`repaint_native()` |
|
|
102
|
+
| 页面 | `pages` | `PageRebuilder`:多页面窗口按需重建,切主题不卡 |
|
|
103
|
+
| 组件 | `buttons` / `inputs` / `dropdown` / `layout` / `notify` / `scroll_list` / `text` | 见下 |
|
|
104
|
+
|
|
105
|
+
## 组件
|
|
106
|
+
|
|
107
|
+
**按钮**(`buttons`)
|
|
108
|
+
|
|
109
|
+
- `primary_button(master, text, command, *, width=120, height=38, radius=9, font=FONT_BODY)`
|
|
110
|
+
- `soft_button(..., width=76, height=30, font=FONT_SMALL, border=False)` —— 次要操作
|
|
111
|
+
- `danger_button(...)` —— 删除一类不可逆操作
|
|
112
|
+
- `FlatButton(CTkButton)` / `SoftButton(FlatButton)` —— 卡片里的小按钮,宽度按文字实测
|
|
113
|
+
(内部是 `CTkButton` 子类,所以有圆角)
|
|
114
|
+
|
|
115
|
+
**输入**(`inputs`)
|
|
116
|
+
|
|
117
|
+
- `toolbar_entry(master, placeholder, *, height=40)` —— 工具条里的搜索框,聚焦时描边变主色
|
|
118
|
+
- `form_entry(master, *, show="", placeholder="", height=38, password=False)`
|
|
119
|
+
- `segmented(master, values, command=None, *, width=300, height=34, font=FONT_SMALL)`
|
|
120
|
+
—— 容器底用 `COLOR_SOFT`(比卡片深一档),不用 `COLOR_INPUT`:后者浅色值和
|
|
121
|
+
`COLOR_CARD` 都是 `#ffffff`,浅色主题下整组分段会和卡片同色、看不出边界
|
|
122
|
+
- `switch(master, command=None, *, width=44)`
|
|
123
|
+
|
|
124
|
+
**大文本**(`text`)
|
|
125
|
+
|
|
126
|
+
- `TextArea(master, *, placeholder="", height=200, readonly=False, show_counter=True, on_change=None, bg_color=None, text_color=None)`
|
|
127
|
+
—— 多行文本区:失焦时显示占位符、底部字数统计、可切换只读;读写用 `get()/set()/clear()`。
|
|
128
|
+
内部底色默认 `COLOR_INPUT`(输入框语义);当日志面板显示时传 `bg_color=COLOR_CARD` 或
|
|
129
|
+
`bg_color="transparent"`,就不会比所在卡片亮一截,`text_color` 也可单独覆盖
|
|
130
|
+
|
|
131
|
+
**下拉**(`dropdown`)
|
|
132
|
+
|
|
133
|
+
- `DropField(master, *, values_provider, command=None, placeholder="", height=36)` —— 自绘候选卡片,
|
|
134
|
+
不用 `CTkComboBox`,因为系统下拉框在深浅色之间很难统一
|
|
135
|
+
|
|
136
|
+
**布局**(`layout`)
|
|
137
|
+
|
|
138
|
+
- `page_header(master, title) -> (head, info)` —— 左标题右信息
|
|
139
|
+
- `section_title(master, text)`、`card(master)`、`divider(master)`
|
|
140
|
+
- `field_label(master, text, *, width=112)`、`hint_label(master, text)`
|
|
141
|
+
- `empty_hint(master, title, detail="")` —— 空态
|
|
142
|
+
- `scrollable(master)` / `style_scrollable(frame)` —— 统一滚动条的宽度与配色
|
|
143
|
+
|
|
144
|
+
**提示**(`notify`)
|
|
145
|
+
|
|
146
|
+
- `Notifier(master, *, duration=None, max_visible=3)` —— 浮在窗口顶部/底部的提示条
|
|
147
|
+
- `.show(message, *, title="", level="info", position="top", style="pill", duration=None, on_close=None)`
|
|
148
|
+
返回这条提示的控件;`level` 取 `"info" / "success" / "warn" / "error"`,
|
|
149
|
+
`position` 取 `"top" / "bottom"`,`style` 取 `"pill"`(一行窄条)或
|
|
150
|
+
`"card"`(带状态图标、标题和关闭按钮)
|
|
151
|
+
- `.dismiss(view)` / `.clear()` / `.count(position=None)` —— 手动关闭或数条数
|
|
152
|
+
- 默认停留:窄条 2.6 秒、卡片 4.5 秒;指针停在提示上暂停计时;`duration=0` 常驻
|
|
153
|
+
- 同一位置最多同时显示 `max_visible` 条,超出时最旧的先关掉
|
|
154
|
+
- 出现与消失有约 80ms 的淡入淡出;超限时先关最旧的再整体重排,不会跳位置
|
|
155
|
+
- 不做全局置顶:提示挂成主窗口的附属窗口(`transient`),只在主窗口之上,
|
|
156
|
+
切到别的应用或最小化主窗口时会一起下去
|
|
157
|
+
- 每条提示都是一个无边框小窗口,和下拉面板同一套做法:窗口由系统裁成圆角,
|
|
158
|
+
圆角以外不绘制,所以压在页面卡片上也不会露出一圈深色底
|
|
159
|
+
- `notify(master, message, **kwargs)` —— 按窗口缓存 `Notifier` 的便捷函数,连续调用会正常堆叠
|
|
160
|
+
|
|
161
|
+
```python
|
|
162
|
+
from ctk_kit import Notifier
|
|
163
|
+
|
|
164
|
+
tips = Notifier(app)
|
|
165
|
+
tips.show("已复制到剪贴板")
|
|
166
|
+
tips.show("云备份失败", title="网络错误", level="error", style="card", position="bottom")
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
**列表**(`scroll_list`)
|
|
170
|
+
|
|
171
|
+
- `LazyList(master, render_card, *, key_of=None, first_batch=12, load_more=8, ...)`
|
|
172
|
+
|
|
173
|
+
只创建可见的一批卡片,滚到底再补下一批;内容不足以填满视口时自动补齐。
|
|
174
|
+
卡片工厂由调用方提供,所以同一个列表能装任何东西:
|
|
175
|
+
|
|
176
|
+
```python
|
|
177
|
+
def make_card(parent, item):
|
|
178
|
+
card = ctk.CTkFrame(parent, corner_radius=12, border_width=1, border_color=COLOR_BORDER)
|
|
179
|
+
ctk.CTkLabel(card, text=item["title"], anchor="w").pack(fill="x", padx=16, pady=(14, 0))
|
|
180
|
+
return card
|
|
181
|
+
|
|
182
|
+
listing = LazyList(frame, make_card, key_of=lambda item: item["id"])
|
|
183
|
+
listing.pack(fill="both", expand=True)
|
|
184
|
+
listing.render(items)
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
数据量很大(几千条)时,传入固定卡高开启虚拟滚动:只把视口附近的卡片放上布局,
|
|
188
|
+
滚出去的卡片留在内存里复用,滚回来直接放回去,不销毁也不重建。
|
|
189
|
+
|
|
190
|
+
```python
|
|
191
|
+
listing = LazyList(frame, make_card, key_of=lambda item: item["id"], item_height=96)
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
虚拟滚动要求卡片高度固定(例如自己 `pack_propagate(False)` 并设置 `height`),
|
|
195
|
+
并把卡片间距算进 `item_height`。`item_height` 用和控件尺寸一样的逻辑单位,
|
|
196
|
+
高 DPI 缩放下由 `LazyList` 自己换算。
|
|
197
|
+
|
|
198
|
+
## 设计令牌
|
|
199
|
+
|
|
200
|
+
颜色全部是 `(浅色, 深色)` 二元组,交给 `color_of()` 按当前外观取值:
|
|
201
|
+
|
|
202
|
+
```python
|
|
203
|
+
from ctk_kit import color_of
|
|
204
|
+
from ctk_kit.tokens import COLOR_ACCENT
|
|
205
|
+
|
|
206
|
+
color_of(COLOR_ACCENT) # 深色下返回 "#2f6fed"
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
`LazyList`、`segmented` 这类控件需要跟随外观重建的,切主题后调用 `apply_appearance(mode)`,
|
|
210
|
+
再重建相关控件即可(`repaint_native()` 用于原生 tk 控件,它们的 `configure` 被 CTk 接管过)。
|
|
211
|
+
|
|
212
|
+
**切主题要重建页面**:CTk 控件的颜色写的是 `(浅色, 深色)` 二元组,按理说外观一变就会自己
|
|
213
|
+
重画,但实测在滚动容器、卡片这类层层嵌套的控件上并不总是生效;页面里又常盖着原生
|
|
214
|
+
`tk.Frame`(`bg` 在 `build` 时就定死了)。示例窗口的做法是:切换后立刻重建当前页,其余页
|
|
215
|
+
记成过期、等切过去时再重建(`show_page` 里先补建)。重建走「先建新页、再销毁旧页」——
|
|
216
|
+
页面里的 `CTkScrollableFrame` 在 `__init__` 里挂了 `bind_all`,在按钮回调里当场销毁页面,
|
|
217
|
+
事件还会派发给已销毁的控件。
|
|
218
|
+
|
|
219
|
+
**怎么让切换快**:`ctk.set_appearance_mode()` 会顺序遍历所有已注册控件一次性重绘,
|
|
220
|
+
一千多个控件要 380 ms。示例窗口先清空 `AppearanceModeTracker.callback_list` 再调用它——
|
|
221
|
+
全局外观状态照常更新,但已有控件一个都不重绘——然后只重建当前页(约 30~70 ms),
|
|
222
|
+
一次切换从 0.5 s 降到 0.15 s。拿不到那张表时自动退回官方做法,慢但不会错。
|
|
223
|
+
不要顺手把十页全建好:重建一页 30~350 ms,Tk 是单线程的,连着建会让窗口卡住一秒多。
|
|
224
|
+
|
|
225
|
+
**切主题时别让 CTk 动标题栏**:`CTk._set_appearance_mode` 在 Windows 上会顺手调
|
|
226
|
+
`_windows_set_titlebar_color`,把窗口 `withdraw()` 再 `deiconify()`(看起来像闪一层遮罩),
|
|
227
|
+
并且记下当时的焦点控件、`after(1, widget.focus)` 还回去——如果切换过程中重建了页面,
|
|
228
|
+
那个控件已经销毁,就会抛 `bad window path name`。做法是临时把
|
|
229
|
+
`CTk._deactivate_windows_window_header_manipulation` 置 `True` 再调它,标题栏颜色改用
|
|
230
|
+
`DwmSetWindowAttribute` 自己设。
|
|
231
|
+
另外重建页面后补一次 `update_idletasks()`,新页才会立刻按正确尺寸排好,
|
|
232
|
+
不然会先以占位形态显示一下再补内容。
|
|
233
|
+
|
|
234
|
+
**标题栏要自己染色**:只设 `DWMWA_USE_IMMERSIVE_DARK_MODE`(`20`/`19`)的话,颜色是
|
|
235
|
+
系统给的——浅色下约 `#f3f3f3`,和 `COLOR_BG`(`#f4f5f7`)几乎同色,看上去标题栏和内容区
|
|
236
|
+
糊成一片,只有深色下才恰好有层次。`:func:`set_titlebar_dark` 会再补三刀(Windows 11 22H2+):
|
|
237
|
+
`DWMWA_CAPTION_COLOR`(`35`)染成 `COLOR_TITLEBAR`、`DWMWA_BORDER_COLOR`(`34`)染成
|
|
238
|
+
`COLOR_BORDER`、`DWMWA_TEXT_COLOR`(`36`)染成 `COLOR_TEXT`;老系统上这几个调用返回
|
|
239
|
+
非 0,自动退回系统色。注意要等窗口 mapped 之后再调(`after(10, ...)`),否则 DWM 还没接管。
|
|
240
|
+
|
|
241
|
+
## 切主题不卡
|
|
242
|
+
|
|
243
|
+
自己写的程序也能拿到和示例窗口一样的效果——几行接入,不用管上面那些内部细节。
|
|
244
|
+
完整可运行的版本在 [`examples/fast_theme.py`](examples/fast_theme.py):
|
|
245
|
+
|
|
246
|
+
```python
|
|
247
|
+
from ctk_kit import PageRebuilder, is_dark, recolor_tree
|
|
248
|
+
from ctk_kit import tokens as T
|
|
249
|
+
|
|
250
|
+
class App(ctk.CTk):
|
|
251
|
+
def __init__(self):
|
|
252
|
+
...
|
|
253
|
+
self.pages = PageRebuilder(self.body, self._build_page, ("总览", "设置"))
|
|
254
|
+
|
|
255
|
+
def _build_page(self, name):
|
|
256
|
+
return {"总览": build_overview, "设置": build_settings}[name](self.body)
|
|
257
|
+
|
|
258
|
+
def toggle_theme(self):
|
|
259
|
+
mode = "light" if is_dark() else "dark"
|
|
260
|
+
# 钩子跑在重建当前页之前:先把外壳刷好,再到内容
|
|
261
|
+
self.pages.switch(
|
|
262
|
+
mode,
|
|
263
|
+
window=self,
|
|
264
|
+
before_rebuild=lambda: self._refresh_sidebar(),
|
|
265
|
+
)
|
|
266
|
+
|
|
267
|
+
def _refresh_sidebar(self):
|
|
268
|
+
self.sidebar.configure(fg_color=T.COLOR_SIDE)
|
|
269
|
+
recolor_tree(self.sidebar, T.COLOR_SIDE, deep=False)
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
`pages.switch()` 做了三件事:
|
|
273
|
+
|
|
274
|
+
1. 用 `apply_appearance_fast()` 更新全局配色和窗口底色,但**不让已有控件逐个重绘**
|
|
275
|
+
(省掉 380 ms);
|
|
276
|
+
2. 调 `before_rebuild()` 刷外壳——侧边栏、状态栏这类不属于任何页面的容器;
|
|
277
|
+
3. 重建用户正看着的那一页(30~350 ms),其余页面只打「过期」标记,等切换过去时
|
|
278
|
+
由 `pages.show(name)` 自动补建。
|
|
279
|
+
|
|
280
|
+
**顺序是刻意这么排的**:外壳几十毫秒就能换完,页面重建要一两百毫秒。先刷外壳,
|
|
281
|
+
眼睛先看到「窗口换了」、再看到内容慢慢铺开;反过来会让人一直盯着没反应的侧边栏。
|
|
282
|
+
|
|
283
|
+
`apply_appearance_fast(mode, window=...)` 单独用也可以:它会把窗口底色和标题栏一起刷好,
|
|
284
|
+
并且避开 CTk 那套「withdraw → deiconify → 还焦点」的标题栏处理(那正是切换时闪一下、
|
|
285
|
+
以及 `bad window path name` 的来源)。已有的控件仍然要你自己重建或重绘。
|
|
286
|
+
|
|
287
|
+
`recolor_tree(widget, bg, deep=False)` 用来刷侧边栏、状态栏这类容器:它会把直接子控件的
|
|
288
|
+
父底色改成新值,并让 CTk 控件按新外观重绘(`CTkButton` 的 `_bg_color` 是构造时从父容器
|
|
289
|
+
取死的,只改父容器会留下一圈颜色不对的方块)。`deep=False` 只走一层——CTk 控件的
|
|
290
|
+
`_set_appearance_mode` 本来就会重绘自己的画布和文字,再钻进去是白费力气(侧边栏 41 个
|
|
291
|
+
控件 46 ms → 只刷 13 个 24 ms)。容器再套一层(比如侧边栏底部的按钮组)就自己多调一次。
|
|
292
|
+
|
|
293
|
+
`PageRebuilder` 的约定只有两条:所有页面放进同一个容器,页面由 `factory(name)` 现建。
|
|
294
|
+
|
|
295
|
+
## 目录
|
|
296
|
+
|
|
297
|
+
```
|
|
298
|
+
ctk_kit/
|
|
299
|
+
├─ tokens.py 设计令牌
|
|
300
|
+
├─ theme.py 取色 / 外观切换 / 原生控件重绘
|
|
301
|
+
├─ pages.py 多页面窗口的页面管理:按需重建、切主题不卡
|
|
302
|
+
├─ buttons.py 按钮
|
|
303
|
+
├─ inputs.py 输入框 / 分段选择 / 开关
|
|
304
|
+
├─ dropdown.py 自绘下拉
|
|
305
|
+
├─ layout.py 页头、卡片、分隔线、空态、滚动容器
|
|
306
|
+
├─ notify.py 窗口顶部/底部浮层提示
|
|
307
|
+
├─ scroll_list.py 懒加载列表
|
|
308
|
+
├─ text.py 多行文本区
|
|
309
|
+
└─ showcase/
|
|
310
|
+
├─ __init__.py 主窗口 ShowcaseApp 与 ctk-kit-showcase 入口
|
|
311
|
+
├─ __main__.py `python -m ctk_kit.showcase` 入口
|
|
312
|
+
├─ data.py 页面清单、组件索引与假数据
|
|
313
|
+
├─ shell.py 公共辅助与单页启动器 run_page
|
|
314
|
+
└─ pages/ 十个页面,一页一个文件,都能 python -m 单独启动
|
|
315
|
+
├─ overview.py
|
|
316
|
+
├─ foundation.py
|
|
317
|
+
├─ buttons.py
|
|
318
|
+
├─ inputs.py
|
|
319
|
+
├─ layout.py
|
|
320
|
+
├─ notify.py
|
|
321
|
+
├─ listing.py
|
|
322
|
+
├─ theme.py
|
|
323
|
+
├─ form.py
|
|
324
|
+
└─ settings.py
|
|
325
|
+
|
|
326
|
+
examples/
|
|
327
|
+
├─ showcase.py 仓库里的快捷入口(转发到 ctk_kit.showcase:main)
|
|
328
|
+
└─ fast_theme.py 把「切主题不卡」接进自己程序的最小示例
|
|
329
|
+
```
|
|
330
|
+
|
|
331
|
+
## 验证
|
|
332
|
+
|
|
333
|
+
示例页就是验收工具:改完哪个组件,就只启动用到它的那一页看效果,例如
|
|
334
|
+
|
|
335
|
+
```
|
|
336
|
+
python -m ctk_kit.showcase.pages.buttons # 只开按钮页
|
|
337
|
+
python -m ctk_kit.showcase.pages.notify # 只开提示页
|
|
338
|
+
ctk-kit-showcase --page 设置 # 整体窗口直接打开某一页
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
没有图形环境时窗口打不开,属于预期;仓库不再维护自动化测试套件,界面改动以人工看单页为准。
|
|
342
|
+
CI(`.github/workflows/ci.yml`)只做构建与导入自检:打出 wheel、装进干净环境,
|
|
343
|
+
`import ctk_kit` 与 `import ctk_kit.showcase.pages` 成功即通过。
|
|
344
|
+
|
|
345
|
+
## 发布
|
|
346
|
+
|
|
347
|
+
版本号只写在 `pyproject.toml` 的 `version` 字段里,发布流程全自动:
|
|
348
|
+
|
|
349
|
+
1. 改 `pyproject.toml` 的 `version`(例如 `0.2.0` → `0.2.1`),同步更新 `CHANGELOG.md`;
|
|
350
|
+
2. 提交并 `git push` 到 Gitee;
|
|
351
|
+
3. 镜像自动同步到 GitHub,Actions 跑完构建后,会比较 PyPI 上的最新版本——
|
|
352
|
+
本地版本更新才发布,同版本重推不会报错。
|
|
353
|
+
|
|
354
|
+
首次发布前需要在 PyPI 的 *Publishing* 页面给 GitHub 仓库
|
|
355
|
+
`DashSalter/ctk-kit` 添加 Trusted Publisher(workflow 文件名 `ci.yml`,环境留空),
|
|
356
|
+
之后由 `pypa/gh-action-pypi-publish` 凭 OIDC 换短期令牌上传,仓库里不需要存密码。
|
|
357
|
+
|
|
358
|
+
## 已知的坑
|
|
359
|
+
|
|
360
|
+
这些都是踩过的,记下来省得再踩:
|
|
361
|
+
|
|
362
|
+
- `CTkLabel` 不支持 `border_width` / `border_color`,想加边框只能裹一层 `CTkFrame`。
|
|
363
|
+
- `CTkSegmentedButton` 同样不接受 `border_*`,传了会抛 `ValueError`。
|
|
364
|
+
- `CTkScrollbar.set()` 内部会调 `update_idletasks()`,而 `update_idletasks` 会立刻执行
|
|
365
|
+
`after_idle` 排的回调——用 `after_idle` 排分批渲染会在这个调用里递归建卡,改用 `after(1, ...)`。
|
|
366
|
+
- 滚动区域变化后,Tk 会回放一次 `yscrollcommand(0, 1)`。判断「滚到底」不能信回调参数,
|
|
367
|
+
要读 `canvas.yview()`。
|
|
368
|
+
- customtkinter 接管了 `tk.Frame.configure`,给原生控件改背景色得走
|
|
369
|
+
`widget.tk.call(widget._w, "configure", "-background", bg)`,否则会碰到已销毁的子控件。
|
|
370
|
+
- 提示条是独立的小窗口,位置按 `master` 的屏幕坐标算(相对窗口居中,不是相对屏幕);
|
|
371
|
+
想让提示只在内容区居中,就把 `master` 传成内容容器。窗口坐标用物理像素,
|
|
372
|
+
而 `geometry` 的宽高是逻辑像素,所以尺寸要再除以窗口缩放。
|
|
373
|
+
- `CTkToplevel` 只写 `geometry("+x+y")`(不给宽高)会被忽略,必须同时给尺寸,
|
|
374
|
+
否则多条提示会全部叠在同一个位置。
|
|
375
|
+
- 无边框窗口的圆角优先交给 DWM(`DwmSetWindowAttribute` 的
|
|
376
|
+
`DWMWA_WINDOW_CORNER_PREFERENCE`),系统抗锯齿,圆弧是平滑的;不行才退回
|
|
377
|
+
`CreateRoundRectRgn` + `SetWindowRgn`,后者是像素级的,圆弧一定有台阶。
|
|
378
|
+
- **每次设 DWM 圆角前都要先 `SetWindowRgn(hwnd, None, True)` 清掉旧 region**:
|
|
379
|
+
布局重排会反复走这条路,残留的 region 会把 DWM 圆角整个挡住,现象是「一会儿
|
|
380
|
+
圆角一会儿直角」。矮窗口同样适用,DWM 并没有对高度设下限。
|
|
381
|
+
- 浮层别设 `-topmost`:那样切到别的应用它还会盖在最前面。用
|
|
382
|
+
`window.transient(master)` 挂成附属窗口——只在主窗口之上,主窗口被遮挡、
|
|
383
|
+
最小化时它也跟着隐藏。
|
|
384
|
+
- 描边是「底色环 + 内容内缩 1px」画出来的,不是控件的 `border_width`——后者在
|
|
385
|
+
大圆角下画不匀;描边环的圆角半径要和系统圆角(约 8)对齐,否则四角会被裁出豁口。
|
|
386
|
+
- 别用 `-transparentcolor` 抠圆角:窗口边缘那一两像素是系统合成的,颜色不等于
|
|
387
|
+
键色,抠完会在四边留下没抠掉的一圈(尤其用深色键色时看着像黑框)。
|
|
388
|
+
- `Notifier` 的悬停暂停靠逐个子控件绑定 `<Enter>` / `<Leave>`,`CTkFrame.bind` 只接受
|
|
389
|
+
`add=True` 或 `add="+"`;自绘 canvas 上直接绑标准 Tk 事件即可。
|
|
390
|
+
|
|
391
|
+
## License
|
|
392
|
+
|
|
393
|
+
MIT
|