ctk-kit 0.9.1__tar.gz → 0.9.2__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.9.2/PKG-INFO +615 -0
- ctk_kit-0.9.2/README.md +580 -0
- ctk_kit-0.9.2/ctk_kit/__init__.py +247 -0
- ctk_kit-0.9.2/ctk_kit/branding.py +149 -0
- {ctk_kit-0.9.1 → ctk_kit-0.9.2}/ctk_kit/buttons.py +45 -9
- ctk_kit-0.9.2/ctk_kit/choices.py +297 -0
- ctk_kit-0.9.2/ctk_kit/code_panel.py +111 -0
- {ctk_kit-0.9.1 → ctk_kit-0.9.2}/ctk_kit/collapse.py +4 -1
- ctk_kit-0.9.2/ctk_kit/context_menu.py +817 -0
- ctk_kit-0.9.2/ctk_kit/dialog.py +489 -0
- {ctk_kit-0.9.1 → ctk_kit-0.9.2}/ctk_kit/dropdown.py +126 -18
- {ctk_kit-0.9.1 → ctk_kit-0.9.2}/ctk_kit/files.py +22 -6
- ctk_kit-0.9.2/ctk_kit/fonts.py +44 -0
- ctk_kit-0.9.2/ctk_kit/frames.py +33 -0
- {ctk_kit-0.9.1 → ctk_kit-0.9.2}/ctk_kit/image_view.py +24 -14
- ctk_kit-0.9.2/ctk_kit/images.py +53 -0
- ctk_kit-0.9.2/ctk_kit/inputs.py +878 -0
- ctk_kit-0.9.2/ctk_kit/layout.py +385 -0
- ctk_kit-0.9.2/ctk_kit/misc.py +495 -0
- {ctk_kit-0.9.1 → ctk_kit-0.9.2}/ctk_kit/notify.py +60 -33
- ctk_kit-0.9.2/ctk_kit/page.py +39 -0
- {ctk_kit-0.9.1 → ctk_kit-0.9.2}/ctk_kit/pages.py +65 -4
- {ctk_kit-0.9.1 → ctk_kit-0.9.2}/ctk_kit/scroll_list.py +1 -0
- ctk_kit-0.9.2/ctk_kit/scrolling.py +68 -0
- ctk_kit-0.9.2/ctk_kit/select.py +1379 -0
- ctk_kit-0.9.2/ctk_kit/sidebar.py +591 -0
- {ctk_kit-0.9.1 → ctk_kit-0.9.2}/ctk_kit/table.py +69 -17
- {ctk_kit-0.9.1 → ctk_kit-0.9.2}/ctk_kit/text.py +76 -3
- {ctk_kit-0.9.1 → ctk_kit-0.9.2}/ctk_kit/tokens.py +4 -0
- ctk_kit-0.9.2/ctk_kit/window.py +215 -0
- ctk_kit-0.9.2/ctk_kit.egg-info/PKG-INFO +615 -0
- ctk_kit-0.9.2/ctk_kit.egg-info/SOURCES.txt +38 -0
- {ctk_kit-0.9.1 → ctk_kit-0.9.2}/ctk_kit.egg-info/requires.txt +1 -3
- {ctk_kit-0.9.1 → ctk_kit-0.9.2}/pyproject.toml +6 -7
- ctk_kit-0.9.1/PKG-INFO +0 -343
- ctk_kit-0.9.1/README.md +0 -307
- ctk_kit-0.9.1/ctk_kit/__init__.py +0 -153
- ctk_kit-0.9.1/ctk_kit/context_menu.py +0 -423
- ctk_kit-0.9.1/ctk_kit/inputs.py +0 -465
- ctk_kit-0.9.1/ctk_kit/layout.py +0 -217
- ctk_kit-0.9.1/ctk_kit/showcase/__init__.py +0 -362
- ctk_kit-0.9.1/ctk_kit/showcase/__main__.py +0 -10
- ctk_kit-0.9.1/ctk_kit/showcase/data.py +0 -82
- ctk_kit-0.9.1/ctk_kit/showcase/pages/__init__.py +0 -49
- ctk_kit-0.9.1/ctk_kit/showcase/pages/buttons.py +0 -191
- ctk_kit-0.9.1/ctk_kit/showcase/pages/choices.py +0 -260
- ctk_kit-0.9.1/ctk_kit/showcase/pages/collapse.py +0 -247
- ctk_kit-0.9.1/ctk_kit/showcase/pages/form.py +0 -122
- ctk_kit-0.9.1/ctk_kit/showcase/pages/foundation.py +0 -249
- ctk_kit-0.9.1/ctk_kit/showcase/pages/image.py +0 -177
- ctk_kit-0.9.1/ctk_kit/showcase/pages/inputs.py +0 -326
- ctk_kit-0.9.1/ctk_kit/showcase/pages/listing.py +0 -174
- ctk_kit-0.9.1/ctk_kit/showcase/pages/menu.py +0 -190
- ctk_kit-0.9.1/ctk_kit/showcase/pages/notify.py +0 -222
- ctk_kit-0.9.1/ctk_kit/showcase/pages/overview.py +0 -108
- ctk_kit-0.9.1/ctk_kit/showcase/pages/settings.py +0 -100
- ctk_kit-0.9.1/ctk_kit/showcase/pages/table.py +0 -123
- ctk_kit-0.9.1/ctk_kit/showcase/pages/theme.py +0 -155
- ctk_kit-0.9.1/ctk_kit/showcase/shell.py +0 -176
- ctk_kit-0.9.1/ctk_kit.egg-info/PKG-INFO +0 -343
- ctk_kit-0.9.1/ctk_kit.egg-info/SOURCES.txt +0 -45
- ctk_kit-0.9.1/ctk_kit.egg-info/entry_points.txt +0 -2
- {ctk_kit-0.9.1 → ctk_kit-0.9.2}/LICENSE +0 -0
- {ctk_kit-0.9.1 → ctk_kit-0.9.2}/ctk_kit/py.typed +0 -0
- {ctk_kit-0.9.1 → ctk_kit-0.9.2}/ctk_kit/theme.py +0 -0
- {ctk_kit-0.9.1 → ctk_kit-0.9.2}/ctk_kit.egg-info/dependency_links.txt +0 -0
- {ctk_kit-0.9.1 → ctk_kit-0.9.2}/ctk_kit.egg-info/top_level.txt +0 -0
- {ctk_kit-0.9.1 → ctk_kit-0.9.2}/setup.cfg +0 -0
ctk_kit-0.9.2/PKG-INFO
ADDED
|
@@ -0,0 +1,615 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: ctk-kit
|
|
3
|
+
Version: 0.9.2
|
|
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
|
+
Requires-Dist: pillow>=9
|
|
32
|
+
Provides-Extra: dnd
|
|
33
|
+
Requires-Dist: tkinterdnd2>=0.3; extra == "dnd"
|
|
34
|
+
Dynamic: license-file
|
|
35
|
+
|
|
36
|
+
# ctk-kit
|
|
37
|
+
|
|
38
|
+
[](https://github.com/DashSalter/ctk-kit/actions/workflows/ci.yml)
|
|
39
|
+
[](https://pypi.org/project/ctk-kit/)
|
|
40
|
+
[](https://pypi.org/project/ctk-kit/)
|
|
41
|
+
[](LICENSE)
|
|
42
|
+
|
|
43
|
+
面向 [CustomTkinter](https://github.com/TomSchimansky/CustomTkinter) 的界面基件:
|
|
44
|
+
一套深浅色设计令牌和一批开箱即用的控件。支持 Python 3.8 – 3.14。
|
|
45
|
+
|
|
46
|
+
CustomTkinter 的公开接口(`CTk`、`CTkButton`、`CTkImage` 等)也全部从 `ctk_kit`
|
|
47
|
+
转出;根窗口 `App` 还多收标题、尺寸、外观这些构造参数。建窗口和摆控件都只
|
|
48
|
+
import 这一个包就够了。
|
|
49
|
+
|
|
50
|
+
## 安装
|
|
51
|
+
|
|
52
|
+
```
|
|
53
|
+
pip install ctk-kit
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
`pip` 会一并装上 Pillow:勾选/单选指示符、`Spinner` 箭头、`Progress` /
|
|
57
|
+
`RingProgress` 的圆角与圆弧都靠它做抗锯齿绘制,`ImageViewer` 也需要它。
|
|
58
|
+
|
|
59
|
+
## 快速开始
|
|
60
|
+
|
|
61
|
+
```python
|
|
62
|
+
from ctk_kit import App, Card, PageHeader, PrimaryButton
|
|
63
|
+
|
|
64
|
+
app = App(title="全部记录", size=(880, 560), min_size=(640, 400), appearance="dark")
|
|
65
|
+
|
|
66
|
+
header = PageHeader(app, "全部记录")
|
|
67
|
+
header.info.configure(text="共 12 条")
|
|
68
|
+
header.pack(fill="x", padx=20, pady=(16, 8))
|
|
69
|
+
|
|
70
|
+
box = Card(app)
|
|
71
|
+
box.pack(fill="x", padx=20)
|
|
72
|
+
PrimaryButton(box, "新建", lambda: app.notify("已保存")).pack(padx=16, pady=16)
|
|
73
|
+
|
|
74
|
+
app.mainloop()
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
想看全部控件的实际效果,运行仓库里的示例窗口:
|
|
78
|
+
|
|
79
|
+
```
|
|
80
|
+
python examples/basics/window.py
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
### 原生窗口与控件
|
|
84
|
+
|
|
85
|
+
customtkinter 的公开接口全部从 `ctk_kit` 转出,应用代码不用再 `import customtkinter`:
|
|
86
|
+
|
|
87
|
+
```python
|
|
88
|
+
from ctk_kit import App, CTkButton, CTkFrame
|
|
89
|
+
|
|
90
|
+
app = App(title="备份", size=(880, 560), min_size=(640, 400))
|
|
91
|
+
bar = CTkFrame(app)
|
|
92
|
+
CTkButton(bar, text="保存").pack()
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
`App` 是 `CTk` 的便捷子类,构造时多收这几个参数:
|
|
96
|
+
|
|
97
|
+
- `title="..."`:窗口标题,等价于 `app.title(...)`
|
|
98
|
+
- `size=(宽, 高)`:初始尺寸,等价于 `app.geometry("宽x高")`
|
|
99
|
+
- `min_size=(宽, 高)`:最小尺寸,等价于 `app.minsize(...)`
|
|
100
|
+
- `appearance="light" | "dark" | "system"`:建窗前设置外观
|
|
101
|
+
- `theme="blue" | "dark-blue" | "green" | 主题文件路径`:建窗前设置配色主题
|
|
102
|
+
- `center=True`:窗口建好后居中
|
|
103
|
+
- `notifier=True`:自动建好提示层 `self.notifier`,可以直接 `app.notify(...)`
|
|
104
|
+
- `icon=True`:窗口图标(标题栏左上角 + 任务栏),默认用内置 logo;
|
|
105
|
+
传 `False` 不设,传字符串则用自定义的 `.ico` / `.png`
|
|
106
|
+
|
|
107
|
+
窗口标题栏颜色也会自动跟随外观(Windows 11 22H2+ 真正上色),不需要再手动调
|
|
108
|
+
`set_titlebar_dark`。
|
|
109
|
+
|
|
110
|
+
### 内置 logo
|
|
111
|
+
|
|
112
|
+
仓库里带一张 logo,放在 `ctk_kit/logo/`,`App` 默认就挂上:
|
|
113
|
+
|
|
114
|
+
| 文件 | 用途 |
|
|
115
|
+
| --- | --- |
|
|
116
|
+
| `logo.png` | 1024 主图,透明背景 |
|
|
117
|
+
| `logo-16.png` … `logo-256.png` | 预渲染的小图,运行时不用再缩放 |
|
|
118
|
+
| `logo.ico` | 多尺寸 Windows 图标 |
|
|
119
|
+
| `logo-source.jpg` | 原始手绘图,留档用 |
|
|
120
|
+
|
|
121
|
+
```python
|
|
122
|
+
from ctk_kit import ICON_PATH, LOGO_PATH, load_logo, set_window_icon
|
|
123
|
+
|
|
124
|
+
set_window_icon(some_toplevel) # 给别的窗口也挂上
|
|
125
|
+
photo = load_logo(96) # 拿一张 PhotoImage 放到 canvas / label
|
|
126
|
+
print(LOGO_PATH, ICON_PATH) # 需要原图路径时
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
`ImageViewer` 的空状态默认画这张 logo:没设置图片时中间显示图标,下面一行
|
|
130
|
+
「还没有图片」。不想要图标就 `ImageViewer(frame, empty_image=False)`,回到纯文字。
|
|
131
|
+
|
|
132
|
+
`CTk` 本身仍然原样导出,需要完全原生的入口时直接用它。
|
|
133
|
+
|
|
134
|
+
- 窗口:`CTk`、`CTkToplevel`、`CTkInputDialog`
|
|
135
|
+
- 容器:`CTkFrame`、`CTkScrollableFrame`、`CTkTabview`
|
|
136
|
+
- 基础控件:`CTkLabel` `CTkButton` `CTkEntry` `CTkTextbox` `CTkCheckBox`
|
|
137
|
+
`CTkRadioButton` `CTkSwitch` `CTkSlider` `CTkProgressBar` `CTkComboBox`
|
|
138
|
+
`CTkOptionMenu` `CTkSegmentedButton` `CTkScrollbar`
|
|
139
|
+
- 字体、图片与绘制基类:`CTkFont` `CTkImage` `CTkCanvas` `CTkBaseClass`
|
|
140
|
+
- 外观:`set_appearance_mode(mode)` / `get_appearance_mode()` / `set_default_color_theme(name)`
|
|
141
|
+
|
|
142
|
+
除 `App`、`CTkEntry`、`CTkButton` 和 `Frame` 外,这些就是 customtkinter 自己的类,
|
|
143
|
+
参数、行为、回调完全一致,类型标注和 IDE 跳转照常。`App` 是加标题、尺寸等构造参数的
|
|
144
|
+
便捷子类;`CTkEntry` 是默认套用库输入框样式的子类——填充底、1px 描边、圆角、placeholder
|
|
145
|
+
灰字都从 `tokens` 取,并默认带「复制 / 粘贴 / 剪切 / 清空」右键菜单(`menu=False` 关掉);`CTkButton` 是默认套用库按钮样式的子类——正文微软雅黑、
|
|
146
|
+
38 高、9 圆角、浅灰底深色字;`Frame` 是默认 `fg_color="transparent"` 的布局容器。
|
|
147
|
+
它们的参数都与原生同名类相同,显式传同名参数即可覆盖。
|
|
148
|
+
`CTkImage` 和 customtkinter 里一样需要 Pillow,但只在真正创建图片对象时才会用到。
|
|
149
|
+
|
|
150
|
+
和本库 `apply_appearance` 的分工:`set_appearance_mode` 是 CTk 原生语义,
|
|
151
|
+
`"system"` 表示跟随系统;`apply_appearance` 是本库的封装,只认小写 `"light"`,
|
|
152
|
+
其余取值(含 `"system"`)一律按深色处理。
|
|
153
|
+
|
|
154
|
+
## 组件
|
|
155
|
+
|
|
156
|
+
全部从 `ctk_kit` 顶层导入:
|
|
157
|
+
|
|
158
|
+
| 模块 | 提供 | 备注 |
|
|
159
|
+
| --- | --- | --- |
|
|
160
|
+
| `buttons` | `PrimaryButton` `SecondaryButton` `DangerButton` `FlatButton` `SoftButton` | |
|
|
161
|
+
| `inputs` | `ToolbarEntry` `FormEntry` `Segmented` `Switch` `Checkbox` `radio_group` `Slider` `ProgressBar` `Spinner` `bind_focus_border` | |
|
|
162
|
+
| `choices` | `Check` `Radio` | 勾选 / 单选的指示符,Pillow 抗锯齿绘制 |
|
|
163
|
+
| `text` | `TextArea` | |
|
|
164
|
+
| `dropdown` | `DropField` | 单选下拉 |
|
|
165
|
+
| `select` | `TagSelectField` `TreeSelectField` | 多选标签 / 层级树,面板行为与 `DropField` 一致 |
|
|
166
|
+
| `layout` | `Card` `PageHeader` `SectionTitle` `divider` `vertical_divider` `FieldLabel` `HintLabel` `empty_hint` `Scrollable` `style_scrollable` `style_scrollbar` | `Card.body` 拿内容容器 |
|
|
167
|
+
| `misc` | `Progress` `RingProgress` | 进度条 / 圆环:连续、分格、条纹、不确定态、刻度 |
|
|
168
|
+
| `notify` | `Notifier` `notify` | |
|
|
169
|
+
| `dialog` | `Dialog` `alert` `confirm` `prompt` | 模态,无边框圆角卡片 |
|
|
170
|
+
| `scroll_list` | `LazyList` | |
|
|
171
|
+
| `context_menu` | `ContextMenu` `attach_menu` `attach_edit_menu` | 输入框默认带菜单 |
|
|
172
|
+
| `collapse` | `Collapsible` | 可折叠面板 |
|
|
173
|
+
| `code_panel` | `CodePanel` | 卡片底部的「查看实现」折叠代码块;`set_code` 换代码 |
|
|
174
|
+
| `files` | `PathField` `DropZone` `pick_path` `has_dnd` | 拖放需要 `tkinterdnd2` |
|
|
175
|
+
| `frames` | `Frame` | 默认透明底的布局容器 |
|
|
176
|
+
| `table` | `Table` | `set_rows` / `add_row` / `remove_row` |
|
|
177
|
+
| `image_view` | `ImageViewer` | 依赖 Pillow(已在必需依赖里) |
|
|
178
|
+
| `pages` | `PageRebuilder` | 多页面窗口;`add_page` / `remove_page`,页面可写 `on_show` / `on_hide` |
|
|
179
|
+
| `page` | `PageBase` | 页面基类:注入 `app`,子类建议实现 `bind_events`,可选 `on_show` / `on_hide` |
|
|
180
|
+
| `sidebar` | `SidebarNav` | 侧边栏 + 页面管理,`add_page` / `remove_page`,见下 |
|
|
181
|
+
| `theme` / `tokens` | `apply_appearance` `color_of` 等 | 外观与设计令牌 |
|
|
182
|
+
| `customtkinter` | `CTk` `App` `CTkButton` `CTkFrame` `CTkImage` `CTkFont` `set_appearance_mode` 等 | 原生类原样转出;`App` / `CTkEntry` / `CTkButton` / `Frame` 是带库默认样式或默认参数的子类,见上 |
|
|
183
|
+
|
|
184
|
+
### 按钮(`buttons`)
|
|
185
|
+
|
|
186
|
+
- `PrimaryButton(master, text, command, *, width=120, height=38, radius=9, font=FONT_BODY)`
|
|
187
|
+
主操作,实心主色
|
|
188
|
+
- `SecondaryButton(master, text, command, *, width=76, height=30, font=FONT_SMALL, border=False)`
|
|
189
|
+
次要操作,灰底;`border=True` 时加 1px 描边
|
|
190
|
+
- `DangerButton(master, text, command, *, width=76, height=30, font=FONT_SMALL)`
|
|
191
|
+
删除一类不可逆操作,红底
|
|
192
|
+
- `FlatButton(master, text, command, *, bg=None, hover=None, fg=None, font=FONT_TINY, padx=10, pady=3, radius=8)`
|
|
193
|
+
卡片里的小按钮,宽度按文字实测
|
|
194
|
+
- `bg` / `hover` / `fg` 分别覆盖底色、悬停色、文字色(默认都从令牌取)
|
|
195
|
+
- `SoftButton(master, text, command)` —— `FlatButton` 的灰底版
|
|
196
|
+
|
|
197
|
+
这些工厂返回的都是 `CTkButton`,`command` 收一个无参回调。
|
|
198
|
+
|
|
199
|
+
### 输入(`inputs`)
|
|
200
|
+
|
|
201
|
+
- `ToolbarEntry(master, placeholder, *, height=40, menu=True)`
|
|
202
|
+
工具条里的搜索框,填充底 + 1px 描边
|
|
203
|
+
- `FormEntry(master, *, show="", placeholder="", height=38, password=False, menu=True)`
|
|
204
|
+
表单里的输入框;`show="•"` 或 `password=True` 走密文
|
|
205
|
+
- 上面两个输入框、以及 `ctk_kit.CTkEntry` 本身都支持
|
|
206
|
+
`set(text)` / `append(text)` / `clear()`(覆盖、追加、清空)
|
|
207
|
+
- 输入框默认带「复制 / 粘贴 / 剪切 / 清空」右键菜单,`menu=False` 关掉,
|
|
208
|
+
`menu=[(文字, 函数), ...]` 换成自己的项;想基于默认项扩展用 `attach_edit_menu`,
|
|
209
|
+
见「右键菜单」一节
|
|
210
|
+
- `Segmented(master, values, command=None, *, width=300, height=34, font=FONT_SMALL)`
|
|
211
|
+
分段选择;`command` 收选中的文字
|
|
212
|
+
- `Switch(master, command=None, *, text="", width=44)`
|
|
213
|
+
开关,`text` 留空就只显示轨道;`command` 收开关状态。轨道和圆球是 Pillow
|
|
214
|
+
4 倍超采样画的图,边缘没有锯齿;圆球色是 `COLOR_BUTTON_KNOB`,悬停色是
|
|
215
|
+
`COLOR_BUTTON_KNOB_HOVER`(都在 `tokens` 里改)
|
|
216
|
+
- `Checkbox(master, text="", command=None, *, width=20, height=20)`
|
|
217
|
+
勾选框,选中后填主色打勾
|
|
218
|
+
- `radio_group(master, values, command=None, *, variable=None, gap=8)` → `(容器, StringVar)`
|
|
219
|
+
一组互斥单选;`gap` 是行距,`variable` 可以传自己的 `StringVar` 进去
|
|
220
|
+
- `Slider(master, command=None, *, from_=0.0, to=100.0, steps=0, width=220)`
|
|
221
|
+
滑块,`command` 收 `float`;`steps>0` 时只能停在等分点
|
|
222
|
+
- `ProgressBar(master, *, value=0.0, width=220, height=6)`
|
|
223
|
+
细进度条,`value` 收 0~1
|
|
224
|
+
- `Progress(master, *, value=0.0, width=240, height=8, steps=0, show_text=False,
|
|
225
|
+
striped=False, color=None, track=None, radius=None, handle=False, on_change=None)`
|
|
226
|
+
进度条的完整版,比 `ProgressBar` 多几种形态
|
|
227
|
+
- `steps>0` 时分格显示,达标的格子点亮
|
|
228
|
+
- `show_text=True` 时右侧显示百分比
|
|
229
|
+
- `striped=True` 时已完成部分画成 45° 斜条纹
|
|
230
|
+
- `radius=0` 换成直角端点;`height=2~4` 就是细线样式
|
|
231
|
+
- `handle=True` 在进度端画一个圆点把手,拖着就能改值,`on_change` 收 0~1 - `start_indeterminate()` / `stop_indeterminate()`:不确定态,一段色块来回滚
|
|
232
|
+
- `color` / `track` 可单独换已完成色和轨道色
|
|
233
|
+
- `RingProgress(master, *, value=0.0, size=140, thickness=10, show_text=True,
|
|
234
|
+
ticks=0, color=None, track=None, ring=True, tick_len=6)`
|
|
235
|
+
圆环进度
|
|
236
|
+
- `ticks>0` 时环外画一圈刻度,走过的刻度用主色;`ticks` 就是刻度密度
|
|
237
|
+
- `ring=False` 只画刻度、不画圆环本体(纯刻度圈)
|
|
238
|
+
- `tick_len` 控制每根刻度多长,默认 6
|
|
239
|
+
- 有刻度时圆环自动往里收,不会和刻度重叠
|
|
240
|
+
- 整块尺寸由 `size` 固定,不随容器拉伸
|
|
241
|
+
- `Spinner(master, *, from_=0, to=100, increment=1, values=None, value=None,
|
|
242
|
+
command=None, placeholder="", height=36, width=160, as_int=True)`
|
|
243
|
+
带上下箭头的步进输入框
|
|
244
|
+
- 数字模式:`from_` / `to` / `increment`,到边界停住;`as_int=False` 时 `get()` 收 `float`
|
|
245
|
+
- 列表模式:传 `values=["小", "中", "大"]`,上下箭头在列表里前后移动,同样停在首尾
|
|
246
|
+
- 也可以直接改数字后回车,会夹回区间里;`set()` 写入不触发 `command`
|
|
247
|
+
- 箭头是 canvas 画的两个小三角,不依赖字体符号
|
|
248
|
+
- `bind_focus_border(widget, *, source=None, idle_color=None, width=2, on_width=None)`
|
|
249
|
+
给任意控件绑「聚焦才出现描边」的样式;`source` 是真正接焦点事件的子控件,
|
|
250
|
+
`idle_color` 是不聚焦时的描边色,`on_width(width)` 在每次切换时回调
|
|
251
|
+
|
|
252
|
+
### 多行文本(`text`)
|
|
253
|
+
|
|
254
|
+
- `TextArea(master, *, placeholder="", height=200, readonly=False, show_counter=True, on_change=None, bg_color=None, text_color=None, menu=True)`
|
|
255
|
+
- `placeholder` 失焦时显示
|
|
256
|
+
- `show_counter=True` 在底部右侧显示字数
|
|
257
|
+
- `readonly=True` 只读
|
|
258
|
+
- `on_change(text)` 每次内容变化回调
|
|
259
|
+
- `bg_color` 默认 `COLOR_INPUT`;当日志面板用,传 `COLOR_CARD` 或 `"transparent"`
|
|
260
|
+
- `text_color` 单独覆盖文字色
|
|
261
|
+
- `menu` 含义同输入框:默认带右键菜单,`False` 关掉
|
|
262
|
+
- 方法:`get()` / `set(text)` / `clear()` / `append(text)` / `insert(text, at="end")`;
|
|
263
|
+
插入和追加会自动刷新字数并触发 `on_change`,只读时也能写入(写完仍保持只读)
|
|
264
|
+
|
|
265
|
+
### 下拉(`dropdown` / `select`)
|
|
266
|
+
|
|
267
|
+
- `DropField(master, *, values_provider, command=None, placeholder="", height=36, disabled=None)`
|
|
268
|
+
- `values_provider()` 每次展开时调用,返回候选文字列表
|
|
269
|
+
- `command` 收选中的文字
|
|
270
|
+
- 面板贴输入框展开;下方放不下会自动翻到上方,候选超过 8 项时面板内部滚动
|
|
271
|
+
- 移动窗口时面板立刻跟随;缩放窗口时左边不动、右边界推过来就把面板裁窄,停手后归位
|
|
272
|
+
- 页面滚动会改变控件位置但不产生顶层事件,由 60 ms 一次的位置比对补上;控件滚出可视区就自动收起
|
|
273
|
+
- 窗口变窄时面板跟着收窄,窄到放不下就直接收起,不会伸出窗口
|
|
274
|
+
- 方法:`get()` / `set(value)` / `clear()`(`set` 不触发 `command`)
|
|
275
|
+
- `TagSelectField(master, *, values_provider, command=None, placeholder="", height=36, values=None, disabled=None)`
|
|
276
|
+
多选标签:选中的值变成青色标签排进框里,点标签本身即可删掉
|
|
277
|
+
- 值不重复;已选中的项再点一次是取消选中
|
|
278
|
+
- 没有输入框:点标签区空白或右侧箭头展开候选;标签多了横向滚动(滚轮可滚,停在标签上也能滚)
|
|
279
|
+
- `command` 收到当前全部标签的列表;面板点选后不关,方便连续多选
|
|
280
|
+
- 方法:`get()` → `list` / `set(values)` / `clear()` / `open_menu()`
|
|
281
|
+
- `TreeSelectField(master, *, values_provider, command=None, placeholder="", height=36, value="", disabled=None)`
|
|
282
|
+
层级树:`values_provider()` 返回嵌套的 `("分组", ["子项", ...])` 元组,字符串等于叶子
|
|
283
|
+
- 分组节点只能展开 / 收起,右侧 `▶` / `▼` 跟着变;分组本身不可选中
|
|
284
|
+
- 子项逐级缩进;展开 / 收起只增删受影响的那几行、不重建整个列表,再重算面板高度与翻转
|
|
285
|
+
- 只有叶子能选,选中后写进输入框、收起面板并回调 `command(value)`
|
|
286
|
+
- 方法:`get()` / `set(value)` / `open_menu()`
|
|
287
|
+
- 三个下拉都支持禁用个别候选项,接口一样:
|
|
288
|
+
- `disable(value)` / `enable(value)` / `is_disabled(value) -> bool`
|
|
289
|
+
- `get_disabled() -> list` / `set_disabled(values)` / `clear_disabled()`
|
|
290
|
+
- 也可以构造时传 `disabled=[...]`;面板开着时改会立刻刷新
|
|
291
|
+
- 禁用的项在列表里置灰、点了不响应;多选里如果它已经在标签中,`disable()` 会顺手移除
|
|
292
|
+
- `Stepper(master, *, values=None, from_=0, to=100, increment=1, value=None,
|
|
293
|
+
command=None, width=170, height=36, suffix="%", decimals=0)`
|
|
294
|
+
紧凑步进器:`[ − ] 当前值 ▾ [ + ]`
|
|
295
|
+
- 左右两个按钮加减一步,点中间展开候选
|
|
296
|
+
- `values` 给一组备选,或 `from_` / `to` / `increment` 走数值范围
|
|
297
|
+
- `suffix` 拼在数值后面,`decimals` 控制显示几位小数
|
|
298
|
+
- `get()` / `set(value)`;`command` 每次变化后收到当前值
|
|
299
|
+
|
|
300
|
+
### 布局(`layout`)
|
|
301
|
+
|
|
302
|
+
- `PageHeader(master, title)` → `PageHeader`:左标题右信息,右侧标签用 `header.info` 访问(也兼容 `head, info = PageHeader(...)` 解包)
|
|
303
|
+
- `SectionTitle(master, text)`:分区标题
|
|
304
|
+
- `Card(master, *, title="")`:圆角卡片;传 `title` 时在卡片上方放标题(标题在卡片外,卡片要用 pack 放置)
|
|
305
|
+
- `divider(master, *, pady=(12, 0), text="", dashed=False, color=None)`:分隔线
|
|
306
|
+
- `text` 给了就从左边起排一行字,右边接实线;`dashed=True` 画虚线
|
|
307
|
+
- `color` 可单独指定线色(默认 `COLOR_BORDER`)
|
|
308
|
+
- `vertical_divider(master, *, height=20, padx=(0, 0), color=None)`:1px 宽竖线,
|
|
309
|
+
用来隔开同一行里的几块内容
|
|
310
|
+
- `FieldLabel(master, text, *, width=112)`:表单左侧字段名
|
|
311
|
+
- `HintLabel(master, text)`:灰色说明文字
|
|
312
|
+
- `empty_hint(master, title, detail="")`:空态
|
|
313
|
+
- `Scrollable(master, **kwargs)`:透明底、滚动条已统一样式的滚动容器(参数同 `CTkScrollableFrame`)
|
|
314
|
+
- `style_scrollable(frame)` / `style_scrollbar(bar)`:把已有滚动控件的宽度与配色统一
|
|
315
|
+
|
|
316
|
+
### 浮层提示(`notify`)
|
|
317
|
+
|
|
318
|
+
`App` 自带提示层,不用手动建 `Notifier`:
|
|
319
|
+
|
|
320
|
+
```python
|
|
321
|
+
app.notify("已复制到剪贴板", level="success")
|
|
322
|
+
app.notify("云备份失败", title="网络错误", level="error", style="card", position="bottom")
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
- `Notifier(master, *, duration=None, max_visible=3)`
|
|
326
|
+
- `.show(message, *, title="", level="info", position="top", style="pill", duration=None, on_close=None)`
|
|
327
|
+
- `level`:`"info"` / `"success"` / `"warn"` / `"error"`
|
|
328
|
+
- `position`:`"top"` / `"bottom"`
|
|
329
|
+
- `style`:`"pill"`(一行窄条)或 `"card"`(带图标、标题和关闭按钮)
|
|
330
|
+
- `duration`:停留秒数;`0` 常驻;不传用默认(窄条 2.6 秒、卡片 4.5 秒)
|
|
331
|
+
- `on_close()`:提示消失后回调
|
|
332
|
+
- 返回这条提示的控件,可以传给 `.dismiss()` 手动关掉
|
|
333
|
+
- `.dismiss(view)` 关掉某一条;`.clear()` 全关;`.count(position=None)` 数条数
|
|
334
|
+
- 同一位置最多 `max_visible` 条,超出时最旧的先关
|
|
335
|
+
- `notify(master, message, **kwargs)`:按窗口缓存 `Notifier` 的便捷函数,参数同 `show()`;
|
|
336
|
+
传入 `App` 时会直接复用它的 `self.notifier`,不会建出第二个提示层
|
|
337
|
+
- 不需要提示的窗口可以 `App(notifier=False)`,此时没有 `self.notifier`
|
|
338
|
+
|
|
339
|
+
```python
|
|
340
|
+
from ctk_kit import App
|
|
341
|
+
|
|
342
|
+
app = App(title="备份", size=(880, 560))
|
|
343
|
+
app.notify("已复制到剪贴板", level="success")
|
|
344
|
+
app.notifier.show("云备份失败", title="网络错误", level="error", style="card")
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
### 对话框(`dialog`)
|
|
348
|
+
|
|
349
|
+
模态面板,和上面非阻塞的提示浮层(`notify`)分工不同:`alert` / `confirm` /
|
|
350
|
+
`prompt` 会停在那里等用户操作,直到点按钮或按 Esc 才返回。
|
|
351
|
+
|
|
352
|
+
没有系统标题栏,弹出就是一块圆角卡片。弹出期间主窗口**可以拖**,对话框跟着走;
|
|
353
|
+
但客户区点不了、滚轮也滚不动(`grab_set` + 在父窗口上拦 `<MouseWheel>`——
|
|
354
|
+
CTk 的滚动走 `bind_all`,光靠 grab 拦不住)。位置会夹在屏幕内——父窗口拖到
|
|
355
|
+
屏幕外时,对话框仍然可见、能点。
|
|
356
|
+
|
|
357
|
+
```python
|
|
358
|
+
from ctk_kit import alert, confirm, prompt
|
|
359
|
+
|
|
360
|
+
alert(app, "已保存到 D:/backup", title="完成", level="success")
|
|
361
|
+
|
|
362
|
+
if confirm(app, "删除这份备份?", title="删除备份", level="warn", danger=True, ok="删除"):
|
|
363
|
+
...
|
|
364
|
+
|
|
365
|
+
name = prompt(app, "给备份起个名字", title="重命名", value="backup-01")
|
|
366
|
+
if name is None:
|
|
367
|
+
... # 用户按了取消
|
|
368
|
+
```
|
|
369
|
+
|
|
370
|
+
- `alert(master, message, *, title="", level="info", ok="知道了", detail="")`:只有一个按钮,返回 `None`
|
|
371
|
+
- `confirm(master, message, *, title="", level="warn", ok="确定", cancel="取消", detail="", danger=False)`
|
|
372
|
+
- 返回 `True` / `False`;点取消、按 Esc、直接关窗都是 `False`
|
|
373
|
+
- `danger=True` 让确认按钮变危险色
|
|
374
|
+
- `prompt(master, message, *, title="", value="", ok="确定", cancel="取消", detail="")`
|
|
375
|
+
- 返回输入的字符串;取消或 Esc 返回 `None`;输入框里按回车等同确定
|
|
376
|
+
- 初始值放在 `value` 里
|
|
377
|
+
- `Dialog(master, *, title="", message="", detail="", level="info", buttons=None, prompt=None, danger=False, width=392)`
|
|
378
|
+
- 需要自己排版时用:`buttons=[(文字, 返回值), ...]`,最后一个按钮是主按钮(排最右)
|
|
379
|
+
- `.show()` 阻塞到用户操作,返回被点按钮的 `value`;Esc / 关窗返回 `None`
|
|
380
|
+
- `prompt` 传字符串就多显示一个输入框,确认时返回输入的文字(注意与
|
|
381
|
+
`prompt()` 函数同名,这里只是初始值)
|
|
382
|
+
- `level` 只影响左上角图标的颜色:`"info"` / `"success"` / `"warn"` / `"error"`
|
|
383
|
+
- `detail` 在正文下面补一行灰色小字;`width` 固定宽度,高度跟着内容走
|
|
384
|
+
- 对话框是一次性的:`show()` 结束就销毁,别拿同一个实例再调一次
|
|
385
|
+
- 对话框本身没有标题栏、不能拖;位置由父窗口决定。无边框窗口也没有右上角的
|
|
386
|
+
关闭按钮,退出靠按钮、Esc 或 Alt+F4。
|
|
387
|
+
|
|
388
|
+
示例窗的「弹窗」页(`examples/basics/dialog_page.py`)把四种级别的信息框、
|
|
389
|
+
普通 / 危险确认、输入框和自定义三按钮都摆了一遍。
|
|
390
|
+
|
|
391
|
+
### 懒加载列表(`scroll_list`)
|
|
392
|
+
|
|
393
|
+
- `LazyList(master, render_card, *, key_of=None, first_batch=12, load_more=8, load_delay_ms=90, load_threshold=0.92, gap=(0, 10), padx=(0, 8), item_height=None)`
|
|
394
|
+
- `render_card(parent, item)` 返回一张卡片(同步、必须立刻建成)
|
|
395
|
+
- `key_of(item)` 返回唯一键,用于复用已有卡片
|
|
396
|
+
- `first_batch` 首屏建多少张;`load_more` 每次补多少张
|
|
397
|
+
- `load_threshold` 滚到还剩多少比例时补下一批
|
|
398
|
+
- `gap` 卡片纵距;`padx` 左右内缩
|
|
399
|
+
- `item_height` 传了才开启虚拟滚动(卡片高度必须固定),适合几千条数据
|
|
400
|
+
- 方法:`render(items, *, empty_title="这里还没有内容", empty_detail="", force=False)`
|
|
401
|
+
|
|
402
|
+
```python
|
|
403
|
+
listing = LazyList(frame, make_card, key_of=lambda item: item["id"])
|
|
404
|
+
listing.pack(fill="both", expand=True)
|
|
405
|
+
listing.render(items)
|
|
406
|
+
```
|
|
407
|
+
|
|
408
|
+
### 右键菜单(`context_menu`)
|
|
409
|
+
|
|
410
|
+
- `attach_menu(widget, items=None, *, width=132, event="<Button-3>", deep=False)` → `ContextMenu`
|
|
411
|
+
- `items` 每项是 `(文字, 函数)`
|
|
412
|
+
- 函数接一个参数时,拿到的就是被右键的那个控件;额外传参用 `lambda btn: fn(btn, ...)`
|
|
413
|
+
- `text` 为空的项渲染成分隔线
|
|
414
|
+
- `deep=True` 时连容器里的子控件一起挂上:给卡片、面板这类容器用,右键落在里面的
|
|
415
|
+
文字上也会弹出(默认只绑容器自身和它露在外面的那层 canvas)
|
|
416
|
+
- `ContextMenu(master, *, width=132, font=FONT_SMALL)`
|
|
417
|
+
- `.add_command(文字, 回调, *, enabled=None)`(返回自身)、`.add_separator()`、`.clear()`
|
|
418
|
+
- `.has_command(文字)` 判断在不在;`.remove_command(文字)` 删掉第一项(顺手清掉孤立的分隔线);
|
|
419
|
+
`.rename_command(文字, 新文字)` 换显示文字、保留回调——三个都返回自身,可以链式写
|
|
420
|
+
- `enabled` 传布尔或「收控件、返回布尔」的函数,弹出时按控件状态决定是否置灰
|
|
421
|
+
- `.show(x, y, source=None)` / `.close()` / `.visible`
|
|
422
|
+
- 同一个应用里同时只会有一个菜单:右键另一个控件时,上一个会自动收起来
|
|
423
|
+
- `source` 是回调第一个参数拿到的控件
|
|
424
|
+
- `attach_edit_menu(widget, items=None, *, preset=True, width=132, reset=False)` → `ContextMenu`
|
|
425
|
+
- 输入框的「复制 / 粘贴 / 剪切 / 清空」预设,`CTkEntry` / `FormEntry` / `ToolbarEntry` /
|
|
426
|
+
`TextArea` / `DropField` 默认已经挂好,一般不用自己调
|
|
427
|
+
- 项跟着状态走:没选中时「剪切 / 复制」灰、剪贴板空时「粘贴」灰、框空时「清空」灰
|
|
428
|
+
- 返回菜单对象,可以继续 `add_separator()` / `add_command(...)`;重复调用拿到的是同一个
|
|
429
|
+
菜单,这次传的 `items` 追加到末尾
|
|
430
|
+
- `reset=True` 丢掉现有菜单重新挂一遍,改乱了可以用它恢复成默认四项
|
|
431
|
+
|
|
432
|
+
菜单开着时:拖动或缩放主窗口它会跟着走;点到外面、按 Esc、窗口失焦都会收起。
|
|
433
|
+
|
|
434
|
+
```python
|
|
435
|
+
from ctk_kit import attach_menu, PrimaryButton
|
|
436
|
+
|
|
437
|
+
save = PrimaryButton(frame, "保存")
|
|
438
|
+
attach_menu(save, [
|
|
439
|
+
("编辑", lambda btn: print("编辑", btn.cget("text"))),
|
|
440
|
+
("删除", lambda btn: print("删除", btn.cget("text"))),
|
|
441
|
+
])
|
|
442
|
+
```
|
|
443
|
+
|
|
444
|
+
输入框的菜单不用手挂,默认就有;增删改都围绕同一个菜单对象:
|
|
445
|
+
|
|
446
|
+
```python
|
|
447
|
+
from ctk_kit import FormEntry, attach_edit_menu
|
|
448
|
+
|
|
449
|
+
entry = FormEntry(frame) # 右键已有复制 / 粘贴 / 剪切 / 清空
|
|
450
|
+
menu = attach_edit_menu(entry) # 拿到的是同一个菜单对象
|
|
451
|
+
|
|
452
|
+
menu.add_separator() # 增
|
|
453
|
+
menu.add_command("插入时间戳", lambda w: w.insert("insert", "12:00:00 "))
|
|
454
|
+
|
|
455
|
+
menu.rename_command("插入时间戳", "插入当前时间") # 改:文字变化,回调不变
|
|
456
|
+
menu.remove_command("剪切") # 删:按文字删第一项
|
|
457
|
+
|
|
458
|
+
attach_edit_menu(entry, reset=True) # 恢复默认四项
|
|
459
|
+
|
|
460
|
+
FormEntry(frame, menu=False) # 不要右键菜单
|
|
461
|
+
FormEntry(frame, menu=[("只保留这一项", fn)]) # 完全自定义
|
|
462
|
+
```
|
|
463
|
+
|
|
464
|
+
### 表格(`table`)
|
|
465
|
+
|
|
466
|
+
- `Table(master, columns, *, row_height=40, header_height=40, max_visible_rows=8, striped=True, empty_text="暂无数据")`
|
|
467
|
+
- `columns` 每项 `(标题, 宽度, 对齐)`:宽度是逻辑像素,`None` 表示吃掉剩余宽度;
|
|
468
|
+
对齐取 `"w"` / `"center"` / `"e"`
|
|
469
|
+
- `row_height` 行高;`header_height` 表头高
|
|
470
|
+
- `max_visible_rows` 超过这个行数才出现滚动条,否则高度按行数自适应
|
|
471
|
+
- `striped` 隔行底色
|
|
472
|
+
- `empty_text` 没有数据时居中显示的文字
|
|
473
|
+
- 方法:`set_rows(rows)` 整批替换、`add_row(row)` 追加一行、`remove_row(index)` 删除一行、
|
|
474
|
+
`rows()` 取当前数据(单元格按 `str()` 转文本)
|
|
475
|
+
|
|
476
|
+
```python
|
|
477
|
+
from ctk_kit import Table
|
|
478
|
+
|
|
479
|
+
table = Table(frame, [("名称", 220, "w"), ("状态", 90, "center"), ("大小", None, "e")])
|
|
480
|
+
table.pack(fill="x")
|
|
481
|
+
table.set_rows([["配置文件", "正常", "12 KB"]])
|
|
482
|
+
```
|
|
483
|
+
|
|
484
|
+
### 图片(`image_view`,需要 Pillow)
|
|
485
|
+
|
|
486
|
+
- `ImageViewer(master, *, height=320, min_zoom=1.0, max_zoom=8.0, empty_text="还没有图片", on_zoom=None)`
|
|
487
|
+
- `set_image(path | Path | PIL.Image | None)`:换图;`None` 回到空态
|
|
488
|
+
- `fit()`:缩放到适配窗口;`set_zoom(倍数)`:指定倍数;`zoom()`:读当前倍数
|
|
489
|
+
- `min_zoom` 默认 `1.0`(最小就是适配窗口);要缩得更小自己传更小的值
|
|
490
|
+
- `max_zoom` 上限倍数
|
|
491
|
+
- `empty_text` 没有图片时的提示
|
|
492
|
+
- `on_zoom(倍数)` 倍数变化时回调
|
|
493
|
+
- 滚轮以光标为中心缩放;按住左键拖动看局部;双击回到适配窗口
|
|
494
|
+
|
|
495
|
+
```python
|
|
496
|
+
from ctk_kit import ImageViewer
|
|
497
|
+
|
|
498
|
+
viewer = ImageViewer(frame, height=420, on_zoom=lambda z: print(f"{z:.0%}"))
|
|
499
|
+
viewer.pack(fill="both", expand=True)
|
|
500
|
+
viewer.set_image(r"D:\photos\shot.png")
|
|
501
|
+
```
|
|
502
|
+
|
|
503
|
+
### 可折叠面板(`collapse`)
|
|
504
|
+
- `Collapsible(master, *, collapsed_text="显示代码", expanded_text="隐藏代码", expanded=False, button_height=36, on_toggle=None)`
|
|
505
|
+
- `collapsed_text` / `expanded_text`:收起、展开两个状态下的标题文字
|
|
506
|
+
- `expanded`:初始是否展开
|
|
507
|
+
- `button_height`:标题行高度
|
|
508
|
+
- `on_toggle(expanded)`:状态变化回调,参数是新状态
|
|
509
|
+
- 属性 `body`:内容容器,往里 pack 子控件;`button`:标题那个 `CTkButton`
|
|
510
|
+
- 方法:`expand()` / `collapse()` / `toggle()` / `set_expanded(flag)` / `set_texts(collapsed_text=…, expanded_text=…)`
|
|
511
|
+
- 只有标题行常驻,收起时内容区完全退出布局,不会给卡片留空隙
|
|
512
|
+
|
|
513
|
+
```python
|
|
514
|
+
from ctk_kit import Collapsible
|
|
515
|
+
|
|
516
|
+
panel = Collapsible(card, collapsed_text="查看实现", expanded_text="收起实现")
|
|
517
|
+
panel.pack(fill="x")
|
|
518
|
+
TextArea(panel.body, readonly=True).pack(fill="x", padx=10, pady=10)
|
|
519
|
+
```
|
|
520
|
+
|
|
521
|
+
### 文件与拖放(`files`,拖放需要 `tkinterdnd2`)
|
|
522
|
+
|
|
523
|
+
- `PathField(master, *, mode="file", placeholder="", height=38, button_text="浏览", title=None, on_change=None, accept_drop=True)`
|
|
524
|
+
- `mode="file"` 选文件、`"folder"` 选文件夹;选中后路径**覆盖**输入框内容
|
|
525
|
+
- `accept_drop=True` 时文件/文件夹可以直接拖到输入框上
|
|
526
|
+
- 方法:`get()` / `set(path)` / `clear()` / `browse()`(弹对话框并返回选中路径)
|
|
527
|
+
- `DropZone(master, on_path, *, mode="any", height=96, text="把文件或文件夹拖到这里", hint="")`
|
|
528
|
+
- `on_path(path)` 松手后回调;`mode` 取 `"any"` / `"file"` / `"folder"` 过滤类型
|
|
529
|
+
- `text` 主提示,`hint` 是下面那行小字
|
|
530
|
+
- `pick_path(master, *, mode="file", title=None, initialdir=None, filetypes=None)` → `str`
|
|
531
|
+
弹系统对话框,取消返回空字符串
|
|
532
|
+
- `has_dnd()` → `bool`:当前环境是否装了 `tkinterdnd2`。
|
|
533
|
+
|
|
534
|
+
拖放是可选能力:`pip install "ctk-kit[dnd]"`。没装时 `PathField` 的按钮照常可用,
|
|
535
|
+
`DropZone` 会显示成不可拖的提示。
|
|
536
|
+
|
|
537
|
+
### 多页面(`pages` / `sidebar`)
|
|
538
|
+
|
|
539
|
+
`SidebarNav` 把「左侧导航 + 右侧翻页」整个封装好:大标题、小标题、任意数量的
|
|
540
|
+
导航按钮、切页高亮、页面按需创建都在里面。
|
|
541
|
+
|
|
542
|
+
```python
|
|
543
|
+
from ctk_kit import App, SidebarNav
|
|
544
|
+
|
|
545
|
+
app = App(title="备份", size=(1000, 680))
|
|
546
|
+
nav = SidebarNav(
|
|
547
|
+
app,
|
|
548
|
+
title="备份",
|
|
549
|
+
subtitle="v0.9.1 · 本地备份工具",
|
|
550
|
+
pages={"任务": build_tasks, "设置": build_settings},
|
|
551
|
+
)
|
|
552
|
+
nav.pack(fill="both", expand=True)
|
|
553
|
+
nav.show("任务")
|
|
554
|
+
app.mainloop()
|
|
555
|
+
```
|
|
556
|
+
|
|
557
|
+
- `pages` 是 `{页面名: 建页函数}`;建页函数接收一个父容器,返回这一页的控件。
|
|
558
|
+
也可以直接传**页面类**:类构造接收父容器,实例就是页面,页面里用
|
|
559
|
+
`master.winfo_toplevel()` 就能拿到 App:
|
|
560
|
+
`pages={"任务": TaskPage, "设置": SettingsPage}`
|
|
561
|
+
- `bottom_pages`:不放进导航列表、放在侧边栏底部的页面(例如「设置」);
|
|
562
|
+
底部按钮用次要样式,`bottom_width` 控制宽度(默认 176)
|
|
563
|
+
- `width`:整数是固定逻辑像素(如 `200`);`0` 到 `1` 之间的小数是宽度比例
|
|
564
|
+
(如 `0.16`),窗口拉宽时侧边栏跟着变宽
|
|
565
|
+
- `logo`:大标题左侧的图标,默认 `True` 用内置 logo;`False` 不显示,传字符串
|
|
566
|
+
用自定义图片路径;`logo_size` 控制边长(默认 32 逻辑像素)
|
|
567
|
+
- 拖动窗口边缘时页面区会先保持旧尺寸,松手约 320ms 后再按新尺寸重排,
|
|
568
|
+
避免大页面在拖动过程中逐帧重画
|
|
569
|
+
- 方法:`show(name)` 切页、`page(name)` 取/建某一页的容器、
|
|
570
|
+
`add_page(name, builder, bottom=False)` / `remove_page(name)` 动态增删页面、
|
|
571
|
+
`set_appearance_mode(mode)` / `toggle_appearance()` 切外观(只重建当前页)
|
|
572
|
+
- 属性:`current`、`frames`、`names`、`rebuilder`(底层的 `PageRebuilder`)
|
|
573
|
+
- `App` 也内置了同名转发:`app.set_appearance_mode("light")` /
|
|
574
|
+
`app.toggle_appearance()`、`app.show_page(name)` / `app.current_page`。窗口上挂了
|
|
575
|
+
`nav`(即 `app.nav` 是 `SidebarNav`)时自动转给它、只重建当前页;没有导航时
|
|
576
|
+
直接切外观并重绘已有控件。中文 `"浅色"` / `"深色"` 也可以直接传。
|
|
577
|
+
|
|
578
|
+
底层 `PageRebuilder` 也可以单独用:
|
|
579
|
+
|
|
580
|
+
- `PageRebuilder(host, factory, pages, *, on_hide=None)`
|
|
581
|
+
- `factory(name)` 返回该页的控件
|
|
582
|
+
- `pages` 是页面名序列
|
|
583
|
+
- `on_hide(name)` 页面切走时回调
|
|
584
|
+
- `add_page(name)` / `remove_page(name)` 动态增删页面
|
|
585
|
+
- 方法:`build_all()` 把所有页面都建出来(启动时用)、`show(name)` 切页、
|
|
586
|
+
`rebuild(name)` 重建某一页
|
|
587
|
+
- 页面切到前台时调用它的 `on_show()`;切走或重建销毁前调用 `on_hide()`
|
|
588
|
+
(`PageBase` 已提供空实现,按需覆写)
|
|
589
|
+
|
|
590
|
+
## 设计令牌与外观
|
|
591
|
+
|
|
592
|
+
颜色全部是 `(浅色, 深色)` 二元组,用 `color_of()` 按当前外观取值:
|
|
593
|
+
|
|
594
|
+
```python
|
|
595
|
+
from ctk_kit import color_of
|
|
596
|
+
from ctk_kit.tokens import COLOR_ACCENT
|
|
597
|
+
|
|
598
|
+
color_of(COLOR_ACCENT) # 深色下返回 "#2f6fed"
|
|
599
|
+
```
|
|
600
|
+
|
|
601
|
+
- `apply_appearance(mode)`:切外观(`"light"` / `"dark"` / `"system"`),已有控件跟着重绘
|
|
602
|
+
- `apply_appearance_fast(mode, *, window=None)`:切外观但**不重绘已有控件**(切主题不卡),
|
|
603
|
+
之后自己重建或重绘需要的部分;`window` 传了就把窗口底色和标题栏一起刷
|
|
604
|
+
- `is_dark()`:当前是不是深色
|
|
605
|
+
- `repaint_native(widget, bg)`:给原生 tk 控件补刷背景色
|
|
606
|
+
- `recolor_tree(widget, bg, mode=None, *, deep=True)`:整棵子树按新外观重刷;
|
|
607
|
+
`deep=False` 只刷直接子层
|
|
608
|
+
- `set_titlebar_dark(window, dark)`:Windows 下把标题栏也切成深色
|
|
609
|
+
|
|
610
|
+
字体、圆角、间距、滚动条宽度也都在 `ctk_kit/tokens.py` 里,各组件默认值直接引用它们,
|
|
611
|
+
改一处全局生效。
|
|
612
|
+
|
|
613
|
+
## License
|
|
614
|
+
|
|
615
|
+
MIT
|