tkinter --- Tcl/Tk 的 Python 接口

源代码: Lib/tkinter/__init__.py

tkinter 包 ("Tk interface") 是针对 Tcl/Tk GUI 工具包的标准 Python 接口。 Tk 和 tkinter 在包括 macOS 在内的大多数 Unix 平台以及 Windows 系统上均可用。systems.

在命令行运行 python -m tkinter 会打开一个演示简单 simple Tk 界面的窗口，以表明 tkinter 在你的系统上安装正确，还会显示所安装的 Tcl/Tk 版本，以便你参阅对应版本的 Tcl/Tk 文档。

Tkinter 支持多个 Tcl/Tk 版本，可附带或不不附带多线程支持。 Tcl/Tk 8.5.12 是受支持的最低版本；官方 Python 二进制发布包捆绑了 Tcl/Tk 9.0。 请参阅 _tkinter 模块的源代码了解有关受支持版本的更多信息。

在 3.11 版本发生变更: 对早于 8.5.12 的 Tcl/Tk 版本的支持已被移除。

Tkinter 并不只是做了简单的封装，而是增加了相当多的代码逻辑，让使用体验更具 Python 风格（pythonic） 。本文将集中介绍这些增加和变化部分，关于未改动部分的细节，请参考 Tcl/Tk 官方文档。

备注

Tcl/Tk 8.5 (2007) 引入了一个带主题的现代风格用户界面组件集以及专用的新 API (参见 tkinter.ttk)。 旧版和新版 API 均保持可用。 你能找到的大多数在线文档仍然是使用旧版 API 因而可能已极其过时。

这是一个 optional module。 如果它在你的 CPython 副本中缺失，请查看你的发行方（也就是说，向你提供 Python 的人）的文档。 如果你就是发行方，请参阅 针对可选模块的要求。

参见

  • TkDocs

    关于使用 Tkinter 创建用户界面的详细教程。 讲解了关键概念，并介绍了使用现代 API 的推荐方式。

  • Tkinter 8.5 参考手册：一种 Python GUI

    详细讲解可用的类、方法和选项的 Tkinter 8.5 参考文档。

Tcl/Tk 资源:

  • Tk 命令

    有关 Tkinter 所使用的每个底层 Tcl/Tk 命令的完整参考文档。

  • Tcl/Tk 主页

    额外的文档，以及 Tcl/Tk 核心开发相关链接。

书籍:

架构

Tcl/Tk 不是只有单个库，而是由几个不同的模块组成的，每个模块都有各自的功能和各自的官方文档。 Python 的二进制发行版还会再附加一个模块。

Tcl

Tcl 是一种动态解释型编程语言，正如 Python 一样。尽管它可作为一种通用的编程语言单独使用，但最常见的用法还是作为脚本引擎或 Tk 工具包的接口嵌入到 C 程序中。Tcl 库有一个 C 接口，用于创建和管理一个或多个 Tcl 解释器实例，并在这些实例中运行 Tcl 命令和脚本，添加用 Tcl 或 C 语言实现的自定义命令。每个解释器都拥有一个事件队列，某些部件可向解释器发送事件交由其处理。与 Python 不同，Tcl 的执行模型是围绕协同多任务而设计的，Tkinter 协调了两者的差别（详见 Threading model ）。

Tk

Tk 是一个用 C 语言实现的 Tcl 包，它添加了用于创建和操纵 GUI 部件的自定义命令。 每个 Tk 对象都嵌入了自己的 Tcl 解释器实例并将 Tk 加载到其中。 Tk 的部件是高度可定制的，但其代价则是过时的外观。 Tk 使用 Tcl 的事件队列来生成并处理 GUI 事件。

Ttk

带有主题的 Tk（Ttk）是较新加入的 Tk 部件，相比很多经典的 Tk 部件，在各平台提供的界面更加美观。自 Tk 8.5 版本开始，Ttk 作为 Tk 的成员进行发布。Python 则捆绑在一个单独的模块中， tkinter.ttk。

在内部，Tk 和 Ttk 使用下层操作系统的工具库，例如，在 Unix/X11 上是 Xlib，在 macOS 上是 Cocoa，在 Windows 上是 GDI。

当你的 Python 应用程序使用了 Tkinter 中的某个类，例如，创建一个控件时，tkinter 模块会先建立一个 Tcl/Tk 命令字符串。 它将这个 Tcl 命令字符串传给内部的 _tkinter 二进制模块，后者将调用 Tcl 解释器来对其求值。 Tcl 解释器再调用 Tk 和/或 Ttk 包，它们又将继续对 Xlib, Cocoa 或 GDI 进行调用。

Tkinter 模块

对 Tkinter 的支持分散于多个模块中。 大多数应用程序都会需要主 tkinter 模块，以及 tkinter.ttk 模块，后者提供了具有现代主题的控件集和相应的 API:

from tkinter import *
from tkinter import ttk

提供 Tk 支持的模块包括:

tkinter

主 Tkinter 模块。

tkinter.colorchooser

让用户选择颜色的对话框。

tkinter.commondialog

本文其他模块定义的对话框的基类。

tkinter.filedialog

允许用户指定文件的通用对话框，用于打开或保存文件。

tkinter.font

帮助操作字体的工具。

tkinter.messagebox

访问标准的 Tk 对话框。

tkinter.scrolledtext

内置纵向滚动条的文本组件。

tkinter.simpledialog

基础对话框和一些便捷功能。

tkinter.ttk

在 Tk 8.5 中引入的带主题的控件集，提供了与主 tkinter 模块中许多经典控件对应的现代化替代版本。

附加模块:

_tkinter

一个包含低层级 Tcl/Tk 接口的二进制模块。 它会被主 tkinter 模块自动导入，而绝不应被应用程序编写者直接使用。 它通常是一个共享库（或 DLL），但在某些情况下也可能与 Python 解释器动态链接。

idlelib

Python 的集成开发与学习环境（IDLE）。 基于 tkinter。

tkinter.constants

当向 Tkinter 调用传入各种形参时可被用来代替字符串的符号常量。 由主 tkinter 模块自动导入。

tkinter.dnd

针对 tkinter 的（实验性的）拖放支持。 当以 Tk DND 替代时它将被弃用。

turtle

Tk 窗口中的海龟绘图库。

Tkinter 重要提示

这一章节的设计目的不是要编写有关 Tk 或 Tkinter 的冗长教程。 要获取教程，请参阅之前列出的外部资源之一。 相反地，这一章节提供了对于 Tkinter 应用程序大致样貌的快速指导，列出了基本的 Tk 概念，并解释了 Tkinter 包装器的构造是什么样的。

这一章节的剩余部分将帮助你识别在你的 Tkinter 应用程序中需要的类、方法和选项，以及在哪里可以找到有关它们的更详细文档，包括官方 Tcl/Tk 参考手册等。

Hello World 程序

让我们先来看一个 Tkinter 的 "Hello World" 应用程序。 这并不是我们所能写出的最简短版本，但也足够说明你所需要了解的一些关键概念。

from tkinter import *
from tkinter import ttk
root = Tk()
frm = ttk.Frame(root, padding=10)
frm.grid()
ttk.Label(frm, text="Hello World!").grid(column=0, row=0)
ttk.Button(frm, text="Quit", command=root.destroy).grid(column=1, row=0)
root.mainloop()

在导入语句之后，下一行语句创建了一个 Tk 类的实例，它会初始化 Tk 并创建与其关联的 Tcl 解释器。 它还会创建一个顶层窗口，名为 root 窗口，它将被作为应用程序的主窗口。

下一行创建了一个框架控件，在本示例中它会包含我们即将创建的一个标签和一个按钮。 框架被嵌在 root 窗口内部。

下一行创建了一个带有静态文本字符串的标签控件。 grid() 方法被用来指明标签在包含它的框架控件中的相对布局（定位），其作用类似于 HTML 中的表格。

接下来创建了一个按钮控件，并放置到标签的右侧。 当被按下时，它将调用 root 窗口的 destroy() 方法。

最后，mainloop() 方法将所有控件显示出来，并响应用户输入直到程序终结。

重要的 Tk 概念

即便是这样简单的程序也阐明了以下关键 Tk 概念:

控件

Tkinter 用户界面是由一个个 控件 组成的。 每个控件都由相应的 Python 对象表示，由 ttk.Frame, ttk.Label 以及 ttk.Button 这样的类来实例化。

控件层级结构

控件按 层级结构 来组织。 标签和按钮包含在框架中，框架又包含在根窗口中。 当创建每个 子 控件时，它的 父 控件会作为控件构造器的第一个参数被传入。

配置选项

控件具有 配置选项，配置选项会改变控件的外观和行为，例如要在标签或按钮中显示的文本。 不同的控件类会具有不同的选项集。

几何管理

小部件在创建时不会自动添加到用户界面。一个像 grid 的 几何管理器 控制这些小部件在用户界面的位置。

事件循环

只有主动运行一个 事件循环，Tkinter 才会对用户的输入做出反应，改变你的程序，以及刷新显示。如果你的程序没有运行事件循环，你的用户界面不会更新。

了解 Tkinter 如何对 Tcl/Tk 进行包装

当你的应用程序使用 Tkinter 的类和方法时，Tkinter 内部汇编代表 Tcl/Tk 命令的字符串，并在连接到你的应用程序的 Tk 实例的 Tcl 解释器中执行这些命令。

无论是试图浏览参考文档，或是试图找到正确的方法或选项，调整一些现有的代码，亦或是调试 Tkinter 应用程序，有时候理解底层 Tcl/Tk 命令是什么样子的会很有用。

为了说明这一点，下面是 Tcl/Tk 等价于上面 Tkinter 脚本的主要部分。

ttk::frame .frm -padding 10
grid .frm
grid [ttk::label .frm.lbl -text "Hello World!"] -column 0 -row 0
grid [ttk::button .frm.btn -text "Quit" -command "destroy ."] -column 1 -row 0

Tcl 的语法类似于许多 shell 语言，其中第一个单词是要执行的命令，后面是该命令的参数，用空格分隔。不谈太多细节，请注意以下几点：

  • 用于创建控件 (如 ttk::frame) 的命令对应于 Tkinter 中的 widget 类。

  • Tcl 控件选项 (如 -text) 对应于 Tkinter 中的关键字参数。

  • 在 Tcl 中，控件是通过 路径名 引用的 (例如 .frm.btn)，而 Tkinter 则不使用名称而使用对象引用。

  • 控件在控件层次结构中的位置在其（层次结构）路径名中编码，该路径名使用一个 . （点）作为路径分隔符。根窗口的路径名是 . （点）。在 Tkinter 中，层次结构不是通过路径名定义的，而是通过在创建每个子控件时指定父控件来定义的。

  • 在 Tcl 中被实现为单独 命令 的操作 (如 grid 或 destroy) 在 Tkinter 控件对象上以 方法 表示。 稍后你将看到，在其他时候 Tcl 会使用在控件对象上作为方法调用的操作，它与 Tkinter 上所使用的东西相互对应。

我该如何...？这个选项会做...？

如果您不确定如何在 Tkinter 中做一些事情，并且您不能立即在您正在使用的教程或参考文档中找到它，这里有一些策略可以帮助您。

首先，请记住，在不同版本的 Tkinter 和 Tcl/Tk 中，各个控件如何工作的细节可能会有所不同。如果您正在搜索文档，请确保它与安装在系统上的 Python 和 Tcl/Tk 版本相对应。

在搜索如何使用 API 时，知道正在使用的类、选项或方法的确切名称会有所帮助。内省，无论是在交互式 Python shell 中，还是在 print() 中，都可以帮助你确定你需要什么。

要找出控件上可用的配置选项，请调用其 configure() 方法，它将返回包含每个对象的多种信息的字典，包括其默认值和当前值。 使用 keys() 来获取每个选项的名称。

btn = ttk.Button(frm, ...)
print(btn.configure().keys())

由于大多数控件都有许多共同的配置选项，因此找出特定于特定控件类的配置选项可能会很有用。将选项列表与更简单的控件（如框架）的列表进行比较是一种方法。

print(set(btn.configure().keys()) - set(frm.configure().keys()))

类似地，你可以使用标准函数 dir() 来查找控件对象的可用方法。如果您尝试一下，您会发现有超过200种常见的控件方法，因此再次确认那些特定于控件类的方法是有帮助的。

print(dir(btn))
print(set(dir(btn)) - set(dir(frm)))

线程模型

Python 和 Tcl/Tk 具有大不相同的线程模型，而 tkinter 会试图连接两者。 如果你要使用线程，你可能需要注意这一点。

一个 Python 解释器可能会关联很多线程。在 Tcl 中，可以创建多个线程，但每个线程都关联了单独的 Tcl 解释器实例。线程也可以创建一个以上的解释器实例，尽管每个解释器实例只能由创建它的那个线程使用。

由 tkinter 创建的每个 Tk 对象均包含一个 Tcl 解释器。 它还会记录解释器是由哪个线程创建的。 对 tkinter 的调用可从任何 Python 线程发起。 如果唤起的线程不是创建 Tk 对象的线程，则会自动向解释器的事件队列中发送一条事件，在执行该事件时，会向发起调用的 Python 线程返回结果。

Tcl/Tk 应用程序通常是事件驱动的，这意味着在完成初始化以后，解释器会运行一个事件循环 (即 Tk.mainloop) 并对事件做出响应。 因为它是单线程的，所以事件处理程序必须快速响应，否则会阻塞其他事件的处理。 为了避免此问题，不应在事件处理程序中执行任何长时间的计算，而应利用计时器将任务分成小块，或者在其他线程中运行。 这不同于其他很多 GUI 工具包，它们的 GUI 是在一个完全独立的线程中运行而独立于包括事件处理程序在内的所有代码。

如果 Tcl 解释器没有运行事件循环并处理解释器事件，则除运行 Tcl 解释器的线程外，任何其他线程发起的 tkinter 调用都会失败。

存在一些特殊情况：

  • 构建时不带线程支持的 Tcl/Tk 库现已很少见: Tcl/Tk 9.0 (捆绑的版本) 始终会感知线程，因此只有某些更旧的 8.x 构建版会有这种问题。 当库不支持线程时，tkinter 会从初始 Python 线程来调用库，即使那不是创建 Tcl 解释器的线程。 会有一个全局锁确保同一时间只发生一次调用。

  • 虽然 tkinter 允许你创建一个以上的 Tk 对象（带有自己的解释器），但所有属于同一线程的解释器均会共享同一个事件队列，这样很快就会一团糟。 在实际编程时，一次创建的 Tk 实例不要超过一个。 否则，最好在不同的线程中创建，并确保运行的是支持多线程的 Tcl/Tk 版本。

  • 为了防止 Tcl 解释器重新进入事件循环，阻塞事件处理程序并不是唯一的做法。甚至可以运行多个嵌套的事件循环，或者完全放弃事件循环。如果在处理事件或线程时碰到棘手的问题，请小心这些可能的事情。

  • 有少数几个 tkinter 函数目前只在从创建 Tcl 解释器的线程中调用才有效。

快速参考

设置选项

配置参数可以控制组件颜色和边框宽度等。可通过三种方式进行设置：

在对象创建时，使用关键字参数
fred = Button(self, fg="red", bg="blue")
在对象创建后，将参数名用作字典索引
fred["fg"] = "red"
fred["bg"] = "blue"
利用 config() 方法修改对象的多个属性
fred.config(fg="red", bg="blue")

备注

此处使用的 fg 和 bg 选项，以及用于控制控件外观的其他选项，均属于经典 tkinter 控件。 在引言中推荐的带主题 tkinter.ttk 控件不接受它们；请改用 ttk.Style 类要设置带主题控件的样式。 上文所示的三种设置选项的方式均适用于这两组控件。

关于这些参数及其表现的完整解释，请参阅 Tk 手册中有关组件的 man 帮助页。

请注意，man 手册页列出了每个部件的“标准选项”和“组件特有选项”。前者是很多组件通用的选项列表，后者是该组件特有的选项。标准选项在 options(3) man 手册中有文档。

本文没有区分标准选项和部件特有选项。有些选项不适用于某类组件。组件是否对某选项做出响应，取决于组件的类别；按钮组件有一个 command 选项，而标签组件就没有。

给定控件所支持的选项在控件的手册页中列出，也可在运行时通过在控件上不带参数地调用 config() 方法，或者调用 keys() 进行查询。 这些调用的返回值是一个键为选项名称字符串 (例如 'relief') 且其值为 5 元组的字典。

某些选项，比如 bg，是长名称普通选项的同义词 (bg 是 "background" 的缩写)。

索引

含意

示例

0

选项名称

'relief'

1

数据库查找的选项名称

'relief'

2

数据库查找的选项类

'Relief'

3

默认值

'raised'

4

当前值

'groove'

示例:

>>> print(fred.config())
{'relief': ('relief', 'relief', 'Relief', 'raised', 'groove')}

当然，输出的字典将包含所有可用选项及其值。这里只是举个例子。

几何管理

创建一个控件并不会让它显示出来。控件只有在交给几何管理器之后才会出现，几何管理器会计算它在其容器中的大小和位置，并在容器大小变化或内容更新时保持布局的实时更新。忘记调用几何管理器是初学者常犯的错误：控件虽然创建了，但界面上什么也不会显示。

Tk 提供了三种几何管理器。每个控件都继承了每一种几何管理器，因此任何控件都可以由其中任意一个来管理（但请参阅下文关于 grid 和 pack 不兼容的警告）。选择哪种管理器取决于你想要的布局类型。

grid

将控件按行和列排成一个二维表格。 这是最灵活的管理器也是默认的选择：在其他情况下需要使用多个嵌套帧的布局往往用单个网格即可表示，并且可以指定行和列要如何吸收额外的空间。

ttk.Label(frm, text="Name:").grid(column=0, row=0, sticky="w")
ttk.Entry(frm).grid(column=1, row=0)
ttk.Button(frm, text="OK").grid(column=1, row=1, sticky="e")
pack

将控件紧靠其容器的一侧堆叠 —— "top" （默认）、 "bottom"、 "left" 或 "right" —— 并可以使它们填充或扩展到剩余的空间中。 它便于进行简单的排列，例如单行或单列控件，或者由工具栏和状态栏框架的内容区域。

toolbar.pack(side="top", fill="x")
status.pack(side="bottom", fill="x")
body.pack(side="left", expand=True, fill="both")
place

将每个控件放置在显式位置，该位置可以作为绝对屏幕距离给出，也可以作为容器大小的分数给出。 它提供了最大的控制权，但具有最少的自动化行为，并且使用最少；它适用于特殊情况，例如重叠控件或精确的自定义布局。

background.place(x=0, y=0, relwidth=1.0, relheight=1.0)
badge.place(relx=1.0, rely=0.0, anchor="ne")

布局是通过嵌套构建的：在框架或顶层窗口内使用网格或包装控件（包括框架）。 顶层窗口由操作系统窗口管理器管理。 经典和风格化的 tkinter.ttk 控件可以互换管理。

警告

不要对共享同一容器的两个控件应用 pack() 和 grid()。 这两个管理器以不兼容的方式协商大小，并且当它们反复相互调整容器大小时，应用程序可能会挂起。 要将它们组合使用，请将每个管理器的控件保存在单独的框架中。

每个管理器接受的完整选项集及其值和默认值记录在 Grid.grid_configure(), Pack.pack_configure() 和 Place.place_configure() 下；另请参阅 grid(3tk), pack(3tk) 和 place(3tk) 手册页。

关联控件变量

某些控件可以将其当前值直接绑定到程序变量，从而使两者保持同步。 诸如 variable, textvariable, value, onvalue 和 offvalue 等选项设置了此连接：当用户更改控件时变量会更新，当设置变量时控件会重新绘制以匹配。

控件只能链接到 Variable 对象，而不能链接到普通的 Python 变量。 这不是 tkinter 的局限性，而是两种语言差异的结果：该链接依赖于每次值更改时都收到 Tcl 的通知，而 Python 没有提供在重新分配普通变量时做出反应的方法。 Variable 通过将其值保留在 Tcl 解释器内部并通过显式的 get() 和 set() 方法将其公开来避开这个问题。

现成的子类涵盖了常见的类型： StringVar, IntVar, DoubleVar 和 BooleanVar。 将一个子类作为控件的 textvariable （或 variable）选项传递，然后使用 get() 和 set() 读取并更新它；该控件会追踪它，无需您进行进一步操作。

只要控件使用该变量，就保留对该变量的引用 —— 例如将其存储为属性。 被垃圾回收的 Variable 会移除其底层的 Tcl 变量，从而中断与控件的连接（参见 Variable）。

例如：

import tkinter as tk
from tkinter import ttk

root = tk.Tk()

# 创建应用程序变量并赋予其初始值。
contents = tk.StringVar(value="this is a variable")

# 让输入控件追踪该变量。
entry = ttk.Entry(root, textvariable=contents)
entry.pack()

# 每当用户按下 Return 时打印当前值。
def print_contents(event):
    print("The current entry content is:", contents.get())

entry.bind("<Return>", print_contents)

# 从程序设置该变量会通过相同的链接更新输入框。
def clear():
    contents.set("")

ttk.Button(root, text="Clear", command=clear).pack()

root.mainloop()

窗口管理器

窗口管理器 是桌面中负责围绕每个顶层窗口绘制标题栏、边框和控件的部分，以及负责其标题、位置、大小和图标等内容的部分。 Tk 通过 Wm 混入类提供对这些内容的访问，该混入类由 Tk 根窗口和每个 Toplevel 继承。 因此，您可以直接在顶层窗口上调用窗口管理器方法。 每个方法都有一个短名称和一个等效的带 wm_ 前缀的名称，例如 title() 和 wm_title()。

无论顶层窗口的内容是由经典控件还是风格化 tkinter.ttk 控件构建，这些方法都会对顶层窗口起作用。 要访问包含任意控件的顶层窗口，请调用其 winfo_toplevel() 方法。

例如：

import tkinter as tk
from tkinter import ttk

root = tk.Tk()
root.title("My Application")
root.geometry("640x480")
root.minsize(320, 240)

ttk.Label(root, text="Hello").pack(padx=20, pady=20)

root.mainloop()

请参阅 Wm 了解窗口管理器方法的完整集合。

Tk 选项数据类型

Many widget options documented in the reference accept values of a small number of common types, described here. The standard options and their types are described in the options(3tk) manual page.

anchor

Legal values are points of the compass: "n", "ne", "e", "se", "s", "sw", "w", "nw", and also "center". The labelanchor option of LabelFrame and ttk.LabelFrame accepts also "en", "es", "wn" and "ws". The sticky option of the grid geometry manager accepts a combination of the compass directions, such as "nsew", or an empty string.

bitmap

There are ten built-in, named bitmaps: 'error', 'gray12', 'gray25', 'gray50', 'gray75', 'hourglass', 'info', 'questhead', 'question', 'warning'. On macOS the following bitmaps are available as well: 'application', 'accessory', 'folder', 'pfolder', 'trash', 'floppy', 'ramdisk', 'cdrom', 'preferences', 'querydoc', 'stop', 'note' and 'caution'. To specify an X bitmap file, give the full path to the file, preceded with an @, as in "@/usr/contrib/bitmap/gumby.bit".

boolean

You can pass the integers 0 or 1, True or False, or the strings "0", "1", "yes", "no", "true", "false", "on" or "off". The strings are matched ignoring case, and an unambiguous prefix, such as "t", is enough. Any non-zero integer means true.

callback -- 回调

This is any callable object. Most callbacks take no arguments. For example:

def print_it():
    print("hi there")
fred["command"] = print_it

Some options call it with arguments, such as the command option of Scale, which is called with the new value.

color

Colors can be given as symbolic names, such as "red" or "light blue", or as strings representing RGB values in 4 bit: "#RGB", 8 bit: "#RRGGBB", 12 bit: "#RRRGGGBBB", or 16 bit: "#RRRRGGGGBBBB" ranges, where R,G,B here represent any legal hex digit. Tk provides a portable set of symbolic names available on all platforms; they are matched ignoring case and spaces, so "light blue", "Light Blue" and "lightblue" are the same color. The full list of names, including the platform-specific names of the current system colors (for example "systemButtonFace" on Windows or "systemWindowBody" on macOS), is given in the colors(3tk) manual page. winfo_rgb() returns the red, green and blue components of a color.

compound

Determines how to combine an image and a text displayed in a widget. Legal values are "none" (display the image if there is one, otherwise the text), "text", "image", "center" (display the text in the center of the image) and "top", "bottom", "left", "right" (display the image above, below, to the left of or to the right of the text). The themed widgets accept all these values, the classic widgets accept all except "text" and "image".

cursor

指针位于控件上方时要显示的光标名称。 Tk 提供了一组在所有平台上都可用的可移植光标名称（例如 "arrow", "watch", "cross" 或 "hand2"）；来自 cursorfont.h 的标准 X 光标名称也可以使用，无需带 XC_ 前缀（因此 XC_hand2 变为 "hand2"）。 完整的名称列表（包括平台专属的名称）在 cursors(3tk) 手册页中给出。 您还可以指定自己的位图和掩码文件。 在 Windows 上，可以直接使用光标文件（.cur 或 .ani），给出其路径并在前面加上 @，例如 "@C:/cursors/bart.ani"。

distance

屏幕距离可以用像素或绝对距离来指定。像素是数字，绝对距离是字符串，后面的字符表示单位: c 是厘米，i 是英寸，m 是毫米，p 则表示打印机的点数。 例如，3.5 英寸可表示为 "3.5i"。

font

Tk uses a font description such as {courier 10 bold}; in tkinter this is most naturally passed as a tuple of (family, size, *styles) (or as the equivalent string "Courier 10 bold"). Font sizes with positive numbers are measured in points; sizes with negative numbers are measured in pixels. The name of a named font, such as "TkDefaultFont", a tkinter.font.Font instance, or, on X11, an XLFD font name can be used as well.

justify

合法的值为字符串: "left", "center" 和 "right"。

orient

Legal values are "horizontal" and "vertical".

padding

This is a legal distance (see above), applied on all sides, or a sequence of up to four distances specifying the left, top, right and bottom padding. If fewer than four are specified, the bottom padding defaults to the top one, the right one to the left one, and the top one to the left one. It is only supported by the themed widgets.

region

Used for the scrollregion option of Canvas. This is a string with four space-delimited elements, each of which is a legal distance (see above), or a sequence of four such elements. For example: "2 3 4 5", (2, 3, 4, 5), "3i 2i 4.5i 2i" and "3c 2c 4c 10.43c" are all legal regions.

relief

确定控件的边框样式。 合法值为： "raised", "sunken", "flat", "groove", "ridge" 和 "solid"。

scrollcommand

这几乎就是带滚动条部件的 set() 方法，但也可是任一只有一个参数的部件方法。

state

Legal values are "normal", "disabled" and, depending on the widget, also "active", "hidden" (for Canvas items) or "readonly" (for Entry, Spinbox and the themed widgets). The themed widgets have in addition a more general set of states, which is manipulated with ttk.Widget.state.

wrap

Must be one of "none", "char" or "word" for the Text widget and its tags; for a tag an empty string means to use the widget's value.

绑定和事件

部件命令中的 bind 方法可觉察某些事件，并在事件发生时触发一个回调函数。bind 方法的形式是：

def bind(self, sequence, func, add=''):

其中：

sequence

是表示目标事件种类的字符串。 物理事件使用 <modifier-modifier-type-detail> 形式（例如 "<Enter>" 或 "<Control-Button-1>"）；应用程序定义的虚拟事件使用双尖括号，如 "<<Paste>>"。 （详情参见 bind(3tk) 手册页。）

func

是带有一个参数的 Python 函数，发生事件时将会调用。传入的参数为一个 Event 实例。（以这种方式部署的函数通常称为 回调函数。）

add

可选项， '' 或 '+' 。传入空字符串表示本次绑定将替换与此事件关联的其他所有绑定。传递 '+' 则意味着加入此事件类型已绑定函数的列表中。

例如：

def turn_red(self, event):
    event.widget["activeforeground"] = "red"

self.button.bind("<Enter>", self.turn_red)

请注意，在 turn_red() 回调函数中如何访问事件的 widget 字段。该字段包含了捕获 X 事件的控件。下表列出了事件可供访问的其他字段，及其在 Tk 中的表示方式，这在查看 Tk 手册时很有用处。

Tk

Tkinter 事件字段

Tk

Tkinter 事件字段

%f

focus

%A

char

%h

height

%E

send_event

%k

keycode

%K

keysym

%s

state

%N

keysym_num

%t

time

%T

type

%w

width

%W

widget

%x

x

%X

x_root

%y

y

%Y

y_root

%#

serial

%b

num

%d

detail

%D

delta

上面的 add 参数仅影响您自己进行的绑定。 每个控件还继承了实现其标准行为的 类绑定 —— 例如 Text 控件将 Control-t 绑定到调换两个字符。 这些在控件的 Tk 手册页的绑定部分（例如 text(3tk) 或 entry(3tk)）中有描述。

类绑定与您自己的绑定是分开处理的，因此自己绑定事件不会替换默认绑定；两者都会运行。 要抑制不需要的默认绑定，请在控件上绑定该事件并从回调中返回字符串 "break"。

index 参数

很多控件都需要传入 index 参数。该参数用于指明 Text 控件中的位置，或指明 Entry 控件中的字符，或指明 Menu 控件中的菜单项。

Entry 控件的索引（index、view index 等）

输入控件具有引用所显示文本中的字符位置的方法和选项。 每当需要索引时，您可以传入：

  • 一个整数，它表示字符的数字位置，从文本的开头开始计数，从 0 开始；

  • 字符串 "anchor"，它表示选择区域的锚点，使用控件的选择方法设置；

  • 字符串 "end"，它表示紧跟在最后一个字符之后的位置；

  • 字符串 "insert"，它表示紧跟在插入光标之后的字符；

  • 字符串 "sel.first" 和 "sel.last"，它们表示选择区域中的第一个字符和紧跟在最后一个字符之后的位置（如果没有选择区域，则使用这些是错误的）；

  • 由 @ 后跟一个整数构成的字符串，例如 "@6"，其中该整数被解释为输入框坐标系中的 x 像素坐标，选择跨越该点的字符。

Text 控件的索引

Text 控件的索引语法非常复杂，最好还是在 Tk 手册中查看。

Menu 索引（menu.invoke()、menu.entryconfig() 等）

菜单的某些属性和方法可以操纵特定的菜单项。只要属性或参数需要用到菜单索引，就可用以下方式传入：

  • 一个整数，指的是菜单项的数字位置，从顶部开始计数，从 0 开始；

  • 字符串 "active"，指的是当前光标所在的菜单；

  • 字符串 "last"，指的是上一个菜单项；

  • 由 @ 后跟一个整数构成的字符串，例如 "@6"，其中该整数被解释为菜单坐标系中的 y 像素坐标；

  • 表示没有任何菜单条目的字符串 "none" 经常与 menu.activate() 一同被用来停用所有条目，以及 ——

  • 与菜单项的文本标签进行模式匹配的文本串，从菜单顶部扫描到底部。请注意，此索引类型是在其他所有索引类型之后才会考虑的，这意味着文本标签为 last、active 或 none 的菜单项匹配成功后，可能会视为这些单词文字本身。

图片

通过 tkinter.Image 的各种子类可以创建相应格式的图片：

  • BitmapImage 对应 XBM 格式的图片。

  • PhotoImage 对应 PGM、PPM、GIF 和 PNG 格式的图片。后者自 Tk 8.6 开始支持。

这两种图片可通过 file 或 data 属性创建的（也可能由其他属性创建）。

在 3.13 版本发生变更: 添加了 PhotoImage 方法 copy_replace() 以将一个图像的某个区域拷贝到另一个图像，可能带有像素缩放和/或子采样。 为 PhotoImage 方法 copy(), zoom() 和 subsample() 添加了 from_coords 形参。 为 PhotoImage 方法 copy() 添加了 zoom 和 subsample 形参。

然后，可以在某些控件（例如标签、按钮、菜单）支持 image 选项的任何地方使用该图像对象。 在这些情况下，Tk 将不会保留对该图像的引用。 当对图像对象的最后一个 Python 引用被删除时，图像数据也将被删除，Tk 将在使用了该图像的任何地方显示一个空方框。

参见

Pillow 包增加了对 BMP, JPEG, TIFF 和 WebP 等多种格式的支持。

参考

本节记录了 tkinter 模块的类、方法、函数和常量。 它们中的大多数包装了 Tcl/Tk 命令；请查阅官方 Tcl/Tk 手册页以获取控件选项的完整列表和更多详细信息。

exception tkinter.TclError

当对 Tcl 解释器的调用失败时引发的异常，例如当为控件提供未知选项或无效值时。

基类与混入类

class tkinter.Misc

Misc 类是一个混入类，由 Tk 继承，并通过 BaseWidget 由每个控件继承。 它提供了所有 Tk 对象通用的庞大方法集：查询窗口信息、管理事件绑定和事件循环、控制键盘焦点和指针抓取、访问选择区域、剪贴板和选项数据库，以及各种实用程序和内省服务。 因为它们是继承的，所以这些方法在每个控件和 Tk 应用程序对象上都可用，并在此记录一次，而不是针对每个控件重复记录。

cget(key)

将此控件名为 key 的配置选项的当前值作为字符串返回。 表达式 widget[key] 是等效的，可以替代使用。

configure(cnf=None, **kw)

查询或修改控件的配置选项。 如果没有参数，则返回一个字典，将每个可用的选项名称映射到描述它的元组（其名称、X 资源名称、X 资源类、默认值和当前值）。 如果单个选项名称作为字符串给出，则仅返回该选项的元组。 如果给出了一个或多个关键字参数，或者将字典作为 cnf 传递，则将每个命名的选项设置为相应的值；表达式 widget[key] = value 以相同的方式设置单个选项。

config() 是 configure() 的别名。

keys()

返回此控件的所有配置选项名称的列表。

getboolean(s)

Interpret the string s as a Tcl boolean and return the corresponding bool. Tcl accepts values such as '1', '0', 'yes', 'no', 'true', 'false', 'on' and 'off'. Raise ValueError if s is not a valid boolean.

getdouble(s)

将字符串 s 解释为 Tcl 浮点数并将其作为 float 返回。 如果 s 不是有效数字，则引发 ValueError。

Added in version 3.5.

getint(s)

将字符串 s 解释为 Tcl 整数并将其作为 int 返回。 如果 s 不是有效整数，则引发 ValueError。

getvar(name)

返回名为 name 的 Tcl 全局变量的值。

setvar(name, value)

将名为 name 的 Tcl 全局变量设置为 value。

getvar() 和 setvar() 方法提供对 Tcl 变量的直接访问。 在大多数代码中，您将改用诸如 StringVar 或 IntVar 等 Variable 子类，它包装了一个 Tcl 变量并将其值与 Python 类型相互转换。

register(func, subst=None, needcleanup=1)

将 Python 可调用对象 func 注册为 Tcl 命令，并将新命令的名称作为字符串返回。 每当 Tcl 调用该命令时，都会调用 func；如果给出了 subst，则首先将其应用于命令的参数。 这是内部用于将 Python 回调转换为传递给 Tk 选项（例如 command）的命令名称的机制。 除非 needcleanup 为假，否则当控件被销毁时该命令会自动删除。

在 3.13 版本发生变更: 传递给 func 的参数不再转换为字符串。

deletecommand(name)

删除名为 name 的 Tcl 命令，例如之前由 register() 返回的命令。

nametowidget(name)

返回与 Tk 路径名 name 对应的控件实例。

send(interp, cmd, *args)

将带有给定 args 的 Tcl 命令 cmd 发送到在名称 interp 下注册的 Tcl 解释器，并返回其结果。 这并非在所有平台上都可用。

destroy()

销毁此控件及其所有后代控件，并删除与它们关联的 Tcl 命令。

tkraise(aboveThis=None)

在堆叠顺序中提升此控件，以便将其绘制在其同级控件的顶部。 如果给出了 aboveThis，则该控件将被移动为在堆叠顺序中刚好位于其上方。

lift() 是 tkraise() 的别名。

lower(belowThis=None)

在堆叠顺序中降低此控件，以便将其绘制在其同级控件的下方。 如果给出了 belowThis，则该控件将被移动为在堆叠顺序中刚好位于其下方。

tkraise()/lift() 和 lower() 被 Canvas 控件覆盖，它们在其中改为重叠画布数据项。

image_names()

返回当前存在于 Tcl 解释器中的所有图像的名称。

这被 Text 控件覆盖，其中 image_names() 改为返回其嵌入图像的名称。

image_types()

返回可用的图像类型，例如 photo 和 bitmap。

grid_anchor(anchor=None)

当容器大于网格且没有行或列具有非零权重时，设置控制网格放置在此容器内何处的锚点。 anchor 是通常的锚点字符串之一，例如 nw （默认）或 center。 在不带参数的情况下调用此方法无效。

anchor() 是 grid_anchor() 的别名。

Added in version 3.3.

grid_bbox(column=None, row=None, col2=None, row2=None)

将布置在此容器中的网格区域的边界框（以像素为单位）作为 4 元组 (xoffset, yoffset, width, height) 返回。 在没有参数的情况下，返回整个网格的边界框。 如果给出了 column 和 row，则该框跨越从第 0 行第 0 列的单元格到该单元格；如果还给出了 col2 和 row2，则它跨越从单元格 (column, row) 到单元格 (col2, row2)。

bbox() 是 grid_bbox() 的别名，但在 Canvas, Listbox, Spinbox, Text, ttk.Entry 和 ttk.Treeview 上除外，它们提供了自己的 bbox() 方法。

grid_columnconfigure(index, cnf={}, **kw)

查询或设置由此容器管理的网格的列（或若干列） index 的属性。 index 可以是列号；在设置选项时，它还可以是列号列表、用于影响每一列的字符串 all，或者是所占用的列受影响的子控件。 受支持的选项有：

minsize

列的最小大小，以像素为单位。

weight

一个整数，设置将任何额外空间的多少分配给该列。 权重为 0 会使列保持在其请求的大小，权重为 2 的列的增长速度是权重为 1 的列的两倍。

uniform

统一组的名称。 共享非空组名的列将保持严格与其权重成比例的大小。

pad

计算列的大小时，添加到该列中最大控件的额外空间（以像素为单位）。

如果使用单个选项名称，则返回该选项的值；如果没有选项，则返回包含所有选项的字典。

columnconfigure() 是 grid_columnconfigure() 的别名。

grid_rowconfigure(index, cnf={}, **kw)

查询或设置由此容器管理的网格的行（或若干行） index 的属性。 index 的解释与 grid_columnconfigure() 相同，并且受支持的选项（minsize, weight, uniform 和 pad）相同，应用于行而不是列。

rowconfigure() 是 grid_rowconfigure() 的别名。

grid_location(x, y)

返回包含位于位置 (x, y) 的像素的网格单元格的 (column, row)，以相对于此容器的像素给出。 对于网格上方或左侧的位置，相应坐标返回 -1。

grid_propagate()
grid_propagate(flag)

当此容器使用网格几何管理器管理其子控件时，启用或禁用几何传播。 当 flag 为真时，容器会自动调整自身大小以适应其子控件所请求的大小；当其为假时，其大小由你控制。 在不带参数调用时，以布尔值形式返回当前设置。

grid_size()

将由此容器管理的网格大小作为 (columns, rows) 元组返回。

size() 是 grid_size() 的别名，但在 Listbox 控件上除外，该控件提供了自己的 size() 方法。

grid_slaves(row=None, column=None)

返回在此容器网格中管理的子控件列表，最近管理的排在最前面。 如果给出了 row 或 column，则仅返回该行或该列中的子控件。

grid_content(row=None, column=None)

Same as grid_slaves(): return the child widgets managed in this container's grid, optionally restricted to a given row or column.

Added in version 3.15.

pack_propagate()
pack_propagate(flag)

当此容器使用包装几何管理器管理其子控件时，启用或禁用几何传播。 当 flag 为真时，容器会自动调整自身大小以适应其子控件所请求的大小；当其为假时，其大小由你控制。 在不带参数调用时，以布尔值形式返回当前设置。

propagate() 是 pack_propagate() 的别名。

pack_slaves()

返回由此容器使用包装几何管理器管理的子控件列表，按包装顺序排列。

slaves() 是 pack_slaves() 的别名。

pack_content()

Same as pack_slaves(): return the child widgets managed by this container with the pack geometry manager, in packing order.

content() is an alias of pack_content().

Added in version 3.15.

place_slaves()

返回由此容器使用放置几何管理器管理的子控件列表。

place_content()

Same as place_slaves(): return the child widgets managed by this container with the place geometry manager.

Added in version 3.15.

带有 bind 和 unbind 前缀的方法将事件模式与回调相关联并移除这些关联。

bind(sequence=None, func=None, add=None)

将此控件上的事件模式 sequence 绑定到可调用对象 func。

sequence 是一个事件模式，例如 '<Button-1>' （鼠标点击）或 '<KeyPress-a>'，也可以是多个此类紧接着相继发生的模式的串联。 当事件发生时， func 将被调用，并将描述该事件的 Event 实例作为其唯一参数；如果 func 返回字符串 'break'，则不会调用该事件的后续绑定。

如果 add 为真， func 将被添加到已绑定到 sequence 的所有函数中；否则它将替换它们。 该绑定仅适用于此控件。

bind() 返回一个字符串标识符（funcid），稍后可以将其传递给 unbind() 以移除该绑定，而不会泄漏关联的 Tcl 命令。

如果省略 func，则返回当前与 sequence 关联的绑定；如果 sequence 也被省略，则返回此控件上存在绑定的所有序列的列表。

bind_class(className, sequence=None, func=None, add=None)

类似于 bind()，但将 func 绑定到绑定标签 className 而不是单个控件，从而使该绑定适用于具有该标签的每个控件。 className 通常是控件类的名称，例如 'Button'，在这种情况下，绑定会影响该类的所有控件。 控件的绑定标签集合可以通过 bindtags() 进行检查和更改。

其余参数和返回值与 bind() 相同。

bind_all(sequence=None, func=None, add=None)

类似于 bind()，但将 func 绑定到特殊绑定标签 'all'，从而使该绑定适用于应用程序中的每个控件。

其余参数和返回值与 bind() 相同。

unbind(sequence, funcid=None)

移除此控件上事件模式 sequence 的绑定。

如果给出了 funcid，则仅移除由其标识的函数（之前调用 bind() 返回的值），并删除其关联的 Tcl 命令。 否则将销毁 sequence 的所有绑定，使其处于未绑定状态。

在 3.13 版本发生变更: 如果给出了 funcid，则仅解绑该回调；保留绑定到 sequence 的其他回调。

unbind_class(className, sequence)

从绑定标签 className 中移除事件模式 sequence 的所有绑定。 参见 bind_class()。

unbind_all(sequence)

从特殊绑定标签 'all' 中移除事件模式 sequence 的所有绑定。 参见 bind_all()。

bindtags(tagList=None)

如果省略 tagList，则返回与此控件关联的绑定标签的元组。 当控件中发生事件时，该事件会按顺序应用于该控件的每个绑定标签，并且对于每个标签，执行最具体的匹配绑定。 默认情况下，控件有四个绑定标签，按顺序依次为：其自身的路径名、其控件类、其最近的顶层祖先的路径名，以及 'all'。

如果给出了 tagList，它必须是一个字符串序列；控件的绑定标签将被设置为其元素，这决定了解析绑定的顺序。

带有 event_ 前缀的方法用于定义虚拟事件并以编程方式生成事件。

event_add(virtual, *sequences)

将虚拟事件 virtual （其名称形如 '<<Paste>>'）与由 sequences 给出的每个物理事件模式相关联，以便在它们中的任何一个发生时触发该虚拟事件。 如果 virtual 已经定义，则新序列将添加到其现有序列中。

event_delete(virtual, *sequences)

从与虚拟事件 virtual 关联的序列中移除 sequences 中的每一个。 当前未与 virtual 关联的序列将被忽略。 如果未给出 sequences，则将移除所有物理事件序列，从而使 virtual 不再被触发。

event_generate(sequence, **kw)

在此控件上生成事件 sequence，并安排对其进行处理，就像它来自窗口系统一样。 sequence 必须是单个事件模式，例如 '<Button-1>' 或 '<<Paste>>'，而不是多个模式的串联。 关键字参数指定事件的附加字段，例如用于指针位置的 x 和 y，或用于控制何时处理事件的 when；完整列表请参阅 Tk event 手册页。

event_info(virtual=None)

如果省略 virtual，则返回当前定义的所有虚拟事件的元组。 如果给出了 virtual，则返回当前与其关联的物理事件序列的元组，如果未定义则返回空元组。

带有 after 前缀的方法安排在延迟后或当应用程序处于空闲状态时运行回调。

after(ms, func=None, *args, **kw)

Schedule the callable func to be called after ms milliseconds, with args and kw passed to it as positional and keyword arguments. Return an identifier that can be passed to after_cancel() to cancel the call.

如果省略 func，则休眠 ms 毫秒，在此期间不处理任何事件，并返回 None。

在 3.10 版本发生变更: func 现在可以是任何可调用对象，而不仅限于函数。

在 3.14 版本发生变更: Keyword arguments are now passed to func.

after_cancel(id)

取消之前使用 after() 或 after_idle() 安排的回调。 id 必须是这些方法之一返回的标识符；传递不是此类标识符的值会引发 ValueError。 如果回调已经运行或已被取消，则此操作无效。

在 3.7 版本发生变更: 将 None （或任何假值）作为 id 传入现在会引发 ValueError。

after_idle(func, *args, **kw)

Schedule the callable func to be called, with args and kw passed to it, when the Tk main loop next becomes idle, that is, when it has no other events to process. Return an identifier that can be passed to after_cancel() to cancel the call.

在 3.14 版本发生变更: Keyword arguments are now passed to func.

after_info(id=None)

如果省略 id，则返回当前针对此解释器使用 after() 和 after_idle() 安排的所有回调的标识符元组。

如果给出了 id，它必须标识一个尚未运行或尚未被取消的回调，并且返回值是一个元组 (script, type)，其中 script 指代要调用的函数，而 type 为 'idle' 或 'timer'。 如果 id 不存在，则会引发 TclError。

Added in version 3.13.

mainloop(n=0)

进入 Tk 事件循环，该循环将处理事件直到所有窗口都被销毁。 通常在根窗口上调用一次此方法以运行应用程序。

quit()

退出 Tcl 解释器，导致 mainloop() 返回。

update()

进入事件循环，直到所有待处理的事件（包括空闲回调）都已处理完毕。 这会更新显示内容并处理已排队的任何事件，然后返回。

update_idletasks()

进入事件循环，直到所有待处理的空闲回调都已被调用。 这会更新窗口的显示（例如在几何发生更改后），但不处理由用户引发的事件。

wait_variable(name)

等待 Tcl 变量 name 被修改，在此期间继续处理事件以使应用程序保持响应。 name 通常是一个 Variable 实例，例如 IntVar 或 StringVar。

waitvar() 是 wait_variable() 的别名。

wait_window(window=None)

等待 window 被销毁，在此期间继续处理事件。 如果省略 window，则使用此控件。 这通常用于等待用户完成与对话框的交互。

wait_visibility(window=None)

等待 window 的可见性状态发生变化（例如当它首次出现在屏幕上时），在此期间继续处理事件。 如果省略 window，则使用此控件。 这通常用于在对新创建的窗口进行操作之前等待其变为可见。

带有 focus_ 前缀的方法用于管理键盘焦点。

focus()

将此控件所在显示设备的键盘输入焦点定向到此控件。 如果应用程序当前未在此控件的显示设备上拥有输入焦点，则该控件会被记住为其顶层窗口的焦点窗口，并且下一次窗口管理器将焦点赋予顶层窗口时，焦点将被重定向到它。 focus() 是 focus_set() 的别名，但在 Canvas 和 ttk.Treeview 控件上除外，它们提供了自己的 focus() 方法。

focus_force()

将键盘输入焦点定向到此控件，即使应用程序当前并未拥有该控件所在显示设备的输入焦点也是如此。 应当谨慎使用此方法，如果一定要用的话；通常应用程序应当等待窗口管理器赋予其焦点，而不是主动索取焦点。

focus_get()

返回应用程序中当前具有键盘焦点的控件，如果应用程序中没有控件具有焦点，则返回 None。 使用 focus_displayof() 可以在多个显示设备下正确工作。

focus_displayof()

返回此控件所在的显示设备上当前具有键盘焦点的控件，如果在该显示设备上应用程序中没有控件具有焦点，则返回 None。

focus_lastfor()

返回与此控件处于同一顶层窗口的所有控件中最近拥有键盘焦点的控件；这是下一次窗口管理器将焦点赋予该顶层窗口时将接收焦点的控件。 如果该顶层窗口中没有任何控件曾获得过焦点，或者最近获得焦点的控件已被删除，则返回该顶层窗口本身。

tk_focusFollowsMouse()

重新配置 Tk 以使用隐式焦点模型，在该模型中，只要鼠标指针进入某个控件，焦点就会设置到该控件上。 一旦启用，此功能便不易禁用。

tk_focusNext()

返回键盘遍历顺序中位于此控件之后的下一个控件，如果没有则返回 None。 遍历顺序首先指向下一个子控件，然后递归到该子控件的子控件，接着指向堆叠顺序中更高的下一个兄弟控件。 如果某个控件的 takefocus 选项设置为 0，则会跳过该控件。 此方法用于 Tab 键的默认绑定。

tk_focusPrev()

返回键盘遍历顺序中位于此控件之前的上一个控件，如果没有则返回 None。 有关顺序是如何定义的，请参阅 tk_focusNext()。 此方法用于 Shift-Tab 键的默认绑定。

带有 grab_ 前缀的方法用于设置和查询输入捕获，输入捕获会将所有输入事件定向到单个控件。

grab_set()

在此控件上设置本地捕获。 捕获将指针事件限制在此控件及其子孙控件中：当指针位于该控件的子树之外时，按钮的按下、释放以及指针移动都会报告给执行捕获的控件，并且子树之外的窗口将变得无响应，直到释放捕获。 本地捕获仅影响执行捕获的应用程序。 本应用程序之前在该控件所在显示设备上设置的任何捕获都会自动释放。 设置捕获是使对话框成为模态窗口的常用方式：在捕获生效期间，用户无法与应用程序的其他窗口进行交互。

grab_set_global()

在此控件上设置全局捕获。 全局捕获类似于通过 grab_set() 设置的本地捕获，但它会锁定屏幕上的所有其他应用程序，因此只有此控件的子树对指针事件敏感，并且它还会捕获键盘。 请谨慎使用：使用全局捕获很容易导致显示设备无法使用，因为其他应用程序在释放捕获之前将停止接收事件。

grab_release()

释放此控件上的捕获（如果存在）；否则不执行任何操作。

grab_current()

返回本应用程序中针对此控件所在显示设备当前持有捕获的控件，如果没有此类控件则返回 None。

grab_status()

如果此控件上当前未设置捕获，则返回 None；如果设置了本地捕获，则返回 "local"；如果设置了全局捕获，则返回 "global"。

带有 selection_ 前缀的方法用于检索和管理 X 选择区。

selection_clear(**kw)

清除 X 选择区，使任何窗口都不再拥有它。 要清除的选择区由关键字参数 selection 给出，它是一个诸如 'PRIMARY' 或 'CLIPBOARD' 之类的 atom 名称；默认为 PRIMARY。 关键字参数 displayof 指定了一个用于确定要在其上操作的显示设备的控件，默认为此控件。

这会被 Entry, Listbox 和 Spinbox 控件重写，在这些控件中 selection_clear() 改为清除该控件自身的选择区。

selection_get(**kw)

返回当前 X 选择区的内容。 关键字参数 selection 指定选择区名称，默认为 PRIMARY。 关键字参数 type 指定返回数据的形式（所需转换目标），它是一个诸如 'STRING' 或 'FILE_NAME' 之类的 atom 名称；默认为 STRING，但在 X11 上除外，在 X11 上会优先尝试 UTF8_STRING，并使用 STRING 作为回退。 关键字参数 displayof 指定一个用于确定从中检索选择区的显示设备的控件，默认为此控件。

selection_handle(command, **kw)

将 command 注册为处理程序，以便在其他应用程序请求此控件所拥有的 X 选择区时提供该选择区。 当检索选择区时， command 会带两个参数被调用：起始字符偏移量和要返回的最大字符数，并且必须返回从该偏移量开始的选择区中至多那么多的字符；对于非常长的选择区，它会被以递增的偏移量重复调用。 关键字参数 selection 指定选择区名称（默认为 PRIMARY），关键字参数 type 给出处理程序提供的选择区形式（例如 'STRING' 或 'FILE_NAME'，默认为 STRING）。

selection_own(**kw)

使此控件成为其所在显示设备上 X 选择区的所有者。 前一个所有者（如果有）将收到已失去该选择区的通知。 关键字参数 selection 指定选择区名称，默认为 PRIMARY。

selection_own_get(**kw)

返回本应用程序中在包含此控件的显示设备上拥有 X 选择区的控件，如果本应用程序中没有控件拥有该选择区，则返回 None。 关键字参数 selection 指定选择区名称，默认为 PRIMARY。 关键字参数 displayof 指定一个用于确定要查询的显示设备的控件，默认为此控件。

带有 clipboard_ 前缀的方法用于管理剪贴板。

clipboard_append(string, **kw)

将 string 追加到 Tk 剪贴板，并在该控件所在的显示设备上声明对剪贴板的所有权。 在追加之前，应使用 clipboard_clear() 清空剪贴板；所有追加操作都应在返回事件循环之前完成，以便以原子方式更新剪贴板。 关键字参数 type 指定数据的形式，即 atom 名称，如 'STRING' 或 'FILE_NAME' （默认为 STRING），关键字参数 format 指定用于传输它的表示形式（默认为 STRING）。 关键字参数 displayof 指定一个确定目标显示设备的控件，默认为此控件。 可以使用 clipboard_get() 或 selection_get() 检索内容。

clipboard_clear(**kw)

在此控件所在的显示设备上声明对剪贴板的所有权，并移除之前的任何内容。 关键字参数 displayof 指定一个确定目标显示设备的控件，默认为此控件。

clipboard_get(**kw)

从此控件所在的显示设备上的剪贴板中检索数据。 关键字参数 type 指定返回数据的形式，即 atom 名称，如 'STRING' 或 'FILE_NAME'；默认为 STRING，但在 X11 上除外，在 X11 上会优先尝试 UTF8_STRING，并使用 STRING 作为回退。 关键字参数 displayof 指定一个确定显示设备的控件，默认为应用程序的根窗口。 这等价于 selection_get(selection='CLIPBOARD')。

带有 option_ 前缀的方法用于查询和修改 Tk 选项数据库。

option_add(pattern, value, priority=None)

向 Tk 选项数据库添加一个将 value 与 pattern 关联的选项。 pattern 由星号或点分隔的名称和/或类组成，采用通常的 X 格式。 priority 是介于 0 到 100 之间的整数，或者是符号名称 'widgetDefault' (20), 'startupFile' (40), 'userDefault' (60) 或 'interactive' (80) 之一；默认为 interactive。

option_clear()

清空 Tk 选项数据库。 下次向数据库添加或从中移除选项时，将自动重新加载来自 RESOURCE_MANAGER 属性或 .Xdefaults 文件的默认选项。

option_get(name, className)

从 Tk 选项数据库返回该控件在 name 和 className 下匹配的选项值；如果没有匹配的条目则返回空字符串。 当有多个条目匹配时，返回优先级最高的那一个；在优先级相同的条目中，返回最近添加的那一个。

option_readfile(fileName, priority=None)

读取名为 fileName 的文件（该文件应具有 X 资源数据库的标准格式，例如 .Xdefaults），并将其指定的所有选项添加到 Tk 选项数据库中。 priority 的解释方式与 option_add() 相同，且默认为 interactive。

bell(displayof=0)

使用该控件所在显示器的当前响铃相关设置在该显示器上响铃，并重置屏幕的屏幕保护程序。 如果 displayof 指定为一个控件，则在对应控件所在的显示器上响铃。

tk_setPalette(background, /)
tk_setPalette(*args, **kw)

为所有 Tk 控件元素设置新的配色方案。 现有的控件会被更新，并且选项数据库会被修改，以便后续创建的控件使用新颜色。 单个颜色参数会被视为常规背景颜色，并由此计算出完整的调色板。 或者，参数也可以作为指定选项数据库中各个选项的关键字 name/value 对传入。 可识别的选项名称有 activeBackground、 activeForeground、 background、 disabledForeground、 foreground、 highlightBackground、 highlightColor、 insertBackground、 selectColor、 selectBackground、 selectForeground 和 troughColor；对于未指定的任何选项，将计算出合理的默认值。

tk_bisque()

将应用程序的颜色恢复为 Tk 3.6 及更早版本中使用的浅褐色 (bisque) 配色方案。 提供此项是为了向后兼容。

tk_strictMotif(boolean=None)

查询或设置 Tk 的外观和风格是否应当严格遵循 Motif。 为真值的 boolean 将启用严格的 Motif 兼容（例如，鼠标滑过滑块时不会改变颜色）。 返回最终的设置结果。

带有 busy_ 前缀的方法用于管理窗口的繁忙状态，该状态会显示繁忙光标并忽略用户输入。

tk_busy_hold(**kw)

使此控件显示为繁忙状态。 会在该控件前放置一个透明窗口，从而阻止该控件及其在控件层次结构中的所有后代接收指针事件，并显示繁忙光标。 通常应在之后立即调用 update()，以确保在应用程序开始处理之前 hold 操作已生效。

唯一受支持的配置选项是 cursor，即控件繁忙时显示的光标；它可以取 configure() 所接受的任意值。

busy_hold()、 busy() 和 tk_busy() 是 tk_busy_hold() 的别名。

Added in version 3.13.

tk_busy_configure(cnf=None, **kw)

查询或修改繁忙窗口的配置选项。 该控件此前必须已通过 tk_busy_hold() 置为繁忙状态。 在没有参数的情况下，返回描述所有可用选项的字典；如果 cnf 是选项名称，则返回描述该选项的元组。 否则将给定的选项设为给定的值。 选项可以取 tk_busy_hold() 所接受的任意值。

选项数据库通过控件名称或类来引用。 例如，如果要将名为 frame 的 Frame 控件置为繁忙状态，可以通过以下任一调用为其指定繁忙光标:

w.option_add('*frame.busyCursor', 'gumby')
w.option_add('*Frame.BusyCursor', 'gumby')

busy_configure()、 busy_config() 和 tk_busy_config() 是 tk_busy_configure() 的别名。

Added in version 3.13.

tk_busy_cget(option)

返回繁忙配置 option 的当前值。 该控件此前必须已通过 tk_busy_hold() 置为繁忙状态，且 option 可以取该方法所接受的任意值。

busy_cget() 是 tk_busy_cget() 的别名。

Added in version 3.13.

tk_busy_forget()

使此控件不再繁忙，释放将其置为繁忙时分配的资源（包括透明窗口）。 控件将重新接收用户事件。 当控件被销毁时，这些资源也会被释放。

busy_forget() 是 tk_busy_forget() 的别名。

Added in version 3.13.

tk_busy_status()

如果控件当前处于繁忙状态则返回 True，否则返回 False。

busy_status() 是 tk_busy_status() 的别名。

Added in version 3.13.

tk_busy_current(pattern=None)

返回当前处于繁忙状态的控件列表。 如果指定了 pattern，则仅返回路径名与该模式匹配的繁忙控件。

busy_current() 是 tk_busy_current() 的别名。

Added in version 3.13.

带有 winfo_ 前缀的方法用于检索由 Tk 管理的窗口的信息。

winfo_atom(name, displayof=0)

返回名称为 name 的 atom（原子）的整数标识符，如果不存在则创建一个新的 atom。 如果指定了 displayof，则在该窗口的显示器上查找该 atom；否则在应用程序主窗口的显示器上查找。

winfo_atomname(id, displayof=0)

返回整数标识符为 id 的 atom 的文本名称。 这是 winfo_atom() 的逆操作。 如果指定了 displayof，则在该窗口的显示器上查找该标识符；否则在应用程序主窗口的显示器上查找。

winfo_cells()

返回该控件的颜色映射表中的单元数。

winfo_children()

返回包含作为该控件子项的控件列表，按堆叠顺序从最低到最高排列。 顶层窗口作为其逻辑父控件的子项返回。

winfo_class()

返回该控件的类名。

winfo_colormapfull()

如果已知该控件的颜色映射表已满则返回 True，否则返回 False。

winfo_containing(rootX, rootY, displayof=0)

返回包含由 rootX 和 rootY 所给出点的控件，如果此应用程序中没有窗口包含该点则返回 None。 坐标是以根窗口坐标系下的屏幕单位表示的。 如果指定了 displayof，则坐标指包含该窗口的屏幕；否则指应用程序主窗口的屏幕。

winfo_depth()

返回该控件的深度（即每像素的位数）。

winfo_exists()

如果该控件存在则返回 true，否则返回 false。

winfo_fpixels(number)

返回一个浮点值，给出对应于屏幕距离 number （例如 "2.0c" 或 "1i"）在控件中的像素数。 结果可能包含小数；若需要四舍五入的整数值，请使用 winfo_pixels()。

winfo_geometry()

Return the geometry of the widget, in the form widthxheight+x+y. All dimensions are in pixels. The position is relative to the parent widget; use winfo_rootx() and winfo_rooty() for the position on the screen. An offset can be negative; see geometry().

winfo_height()

返回该控件的高度（以像素为单位）。 当窗口刚创建时其高度为 1 像素；最终会由几何管理器进行更改。 另请参阅 winfo_reqheight()。

winfo_id()

返回该控件底层的平台专属标识符。 在 Unix 上这是 X window 标识符，在 Windows 上则是窗口句柄。

winfo_interps(displayof=0)

返回当前在特定显示器上注册的所有 Tcl 解释器名称的元组。 如果指定了 displayof，则返回值指的是该窗口的显示器；否则指应用程序主窗口的显示器。

winfo_ismapped()

如果该控件当前已映射则返回 true，否则返回 false。

winfo_manager()

返回当前负责该控件的几何管理器的名称，如果未由任何几何管理器管理则返回空字符串。

winfo_name()

返回该控件在其父级中的名称，而不是其完整路径名。

winfo_parent()

返回该控件父级的路径名，如果该控件是应用程序的主窗口则返回空字符串。

winfo_pathname(id, displayof=0)

返回标识符为 id 的窗口的路径名。 如果指定了 displayof，则在该窗口的显示器上查找该标识符；否则在应用程序主窗口的显示器上查找。

winfo_pixels(number)

返回对应于屏幕距离 number （例如 "2.0c" 或 "1i"）在控件中的像素数。 结果四舍五入为最接近的整数；若需要小数结果，请使用 winfo_fpixels()。

winfo_pointerx()

返回指针相对于屏幕根窗口（如果正在使用虚拟根窗口，则相对于虚拟根窗口）的 x 坐标（以像素为单位）。 如果指针与该控件不在同一屏幕上，则返回 -1。

winfo_pointerxy()

返回指针相对于屏幕根窗口（如果正在使用虚拟根窗口，则相对于虚拟根窗口）的坐标，形式为 (x, y) 元组（以像素为单位）。 如果指针与该控件不在同一屏幕上，则两个坐标均为 -1。

winfo_pointery()

返回指针相对于屏幕根窗口（如果正在使用虚拟根窗口，则相对于虚拟根窗口）的 y 坐标（以像素为单位）。 如果指针与该控件不在同一屏幕上，则返回 -1。

winfo_reqheight()

返回该控件所请求的高度（以像素为单位）。 这是该控件的几何管理器用于计算其几何尺寸的值。

winfo_reqwidth()

返回该控件所请求的宽度（以像素为单位）。 这是该控件的几何管理器用于计算其几何尺寸的值。

winfo_rgb(color)

返回与该控件中的 color 相对应的红、绿、蓝强度的 (r, g, b) 元组，范围在 0 到 65535 之间。 color 可以采用颜色选项所接受的任意形式指定。

winfo_rootx()

返回控件边框（或者如果该控件没有边框，则为控件本身）左上角在屏幕根窗口中的 x 坐标。

winfo_rooty()

返回控件边框（或者如果该控件没有边框，则为控件本身）左上角在屏幕根窗口中的 y 坐标。

winfo_screen()

返回与该控件关联的屏幕名称，形式为 displayName.screenIndex。

winfo_screencells()

返回该控件所在屏幕的默认颜色映射表中的单元数。

winfo_screendepth()

返回该控件所在屏幕根窗口的深度（即每像素的位数）。

winfo_screenheight()

返回该控件所在屏幕的高度（以像素为单位）。

winfo_screenmmheight()

返回该控件所在屏幕的高度（以毫米为单位）。

winfo_screenmmwidth()

返回该控件所在屏幕的宽度（以毫米为单位）。

winfo_screenvisual()

返回该控件所在屏幕的默认 visual 类别，为 "directcolor"、 "grayscale"、 "pseudocolor"、 "staticcolor"、 "staticgray" 或 "truecolor" 之一。

winfo_screenwidth()

返回该控件所在屏幕的宽度（以像素为单位）。

winfo_server()

返回包含该控件显示器服务器信息的字符串。 该字符串的确切格式可能因平台而异。

winfo_toplevel()

返回包含该控件的层级最顶层窗口。 在标准 Tk 中，这始终是一个 Toplevel 控件。

winfo_viewable()

如果该控件及其直至最近顶层窗口的所有祖先控件均已映射则返回 true，否则返回 false。

winfo_visual()

返回该控件的 visual 类别，为 "directcolor"、 "grayscale"、 "pseudocolor"、 "staticcolor"、 "staticgray" 或 "truecolor" 之一。

winfo_visualid()

返回该控件 visual 的 X 标识符。

winfo_visualsavailable(includeids=False)

返回描述该控件所在屏幕可用 visual 的列表。 每个条目由一个 visual 类别（参见 winfo_visual()）和随后的一个整数深度组成。 如果 includeids 为真，还会包含该 visual 的 X 标识符。

winfo_vrootheight()

返回与该控件关联的虚拟根窗口的高度（如果存在）；否则返回该控件所在屏幕的高度。

winfo_vrootwidth()

返回与该控件关联的虚拟根窗口的宽度（如果存在）；否则返回该控件所在屏幕的宽度。

winfo_vrootx()

返回与该控件关联的虚拟根窗口相对于其屏幕根窗口的 x 偏移量。 该值通常为零或负数，如果不存在虚拟根窗口则为 0。

winfo_vrooty()

返回与该控件关联的虚拟根窗口相对于其屏幕根窗口的 y 偏移量。 该值通常为零或负数，如果不存在虚拟根窗口则为 0。

winfo_width()

返回该控件的宽度（以像素为单位）。 当窗口刚创建时其宽度为 1 像素；最终会由几何管理器进行更改。 另请参阅 winfo_reqwidth()。

winfo_x()

返回控件边框（或者如果该控件没有边框，则为控件本身）左上角在其父控件中的 x 坐标。

winfo_y()

返回控件边框（或者如果该控件没有边框，则为控件本身）左上角在其父控件中的 y 坐标。

info_patchlevel()

将 Tcl/Tk 补丁级别作为具名元组返回，其包含与 sys.version_info 相同的五个字段： major、 minor、 micro、 releaselevel 和 serial。 releaselevel 为 'alpha'、 'beta' 或 'final'。 将其转换为字符串可得到采用常用 Tcl/Tk 标记表示的版本，例如最终版本的 '9.0.3' 或预发布的 '9.1b2'。

Added in version 3.11.

class tkinter.Wm

Wm 混入类提供了对窗口管理器的访问，允许应用程序控制顶层窗口的标题、几何尺寸和图标，调整其大小的方式，以及它如何响应窗口管理器协议等。 它被混入到 Tk 和 Toplevel 中，因此其方法在每个顶层窗口上都可用。 每个方法都有两种等效写法：简短名称和带 wm_ 前缀的名称（例如 title() 和 wm_title()）。 另请参阅 窗口管理器。

aspect(minNumer=None, minDenom=None, maxNumer=None, maxDenom=None)

限制窗口的宽高比（宽度与高度的比率）。 如果给定了全部四个参数，窗口管理器会将宽高比保持在 minNumer/minDenom 和 maxNumer/maxDenom 之间；传入空字符串将移除任何现有约束。 如果不带参数，则返回由四个当前值组成的元组，或者在没有生效的宽高比约束时返回 None。 wm_aspect() 是 aspect() 的别名。

attributes(*args, return_python_dict=False, **kwargs)

查询或设置窗口的平台专属属性。 如果不带参数，则返回平台专属标志及其值；将 return_python_dict 设为 true 传入可将它们作为字典获取。 传入单个选项名称（例如 'alpha' ）将返回该选项的值，选项也可以使用关键字参数设置（ alpha=0.5 ）。

可用属性因平台而异。 所有平台均支持：

alpha

窗口的不透明度，范围从 0.0 （完全透明）到 1.0 （完全不透明）。 在不支持透明度的地方，该值保持为 1.0。

appearance

窗口在 Windows 和 macOS 上是否以深色模式渲染： 'auto'、 'light' 或 'dark' （这对 X11 没有影响）。

fullscreen

窗口是否占据整个屏幕且没有边框。

topmost

窗口是否显示在所有其他窗口之上。

Windows 还额外支持：

disabled

窗口是否处于禁用状态。

toolwindow

窗口是否使用工具窗口样式。

transparentcolor

被设为完全透明的颜色，或者为空字符串表示无。

macOS 还额外支持：

class

底层的 Aqua 窗口是 nswindow 还是 nspanel；这只能在窗口创建之前进行设置。

modified

由窗口的关闭按钮和代理图标所显示的修改状态。

notify

应用程序的程序坞图标是否跳动以请求关注。

stylemask

底层 Aqua 窗口的样式掩码，以位名称列表形式给出，例如 titled 或 resizable。

tabbingid

窗口所属标签页分组的标识符。

tabbingmode

窗口是否可以作为标签页打开： 'auto'、 'preferred' 或 'disallowed'。

titlepath

由窗口代理图标所代表的文件的路径。

transparent

内容区域是否透明以及窗口阴影是否已关闭。

X11 还额外支持：

type

窗口管理器解释该窗口时应使用的窗口类型，或是按偏好顺序排列的类型列表，例如 'dialog' 或 'splash'。

zoomed

窗口是否已最大化。

备注

Tk 8.6 添加了 type 属性，Tk 9.0 添加了 appearance, class, stylemask, tabbingid 和 tabbingmode 属性。

在 X11 上，更改是以异步方式应用的，因此查询到的值可能尚未反映最近的请求。 wm_attributes() 是 attributes() 的别名。

在 3.13 版本发生变更: 现在可以通过名称查询单个属性而无需前缀 -，并且可以使用关键字参数来设置属性。 添加了 return_python_dict 参数。

自 3.13 版本弃用: 通过传入带前缀 - 的选项名称及其值作为两个位置参数来设置属性（如 w.attributes('-alpha', 0.5) ）的方式已被弃用；请改用关键字参数。

client(name=None)

将 name （应为运行应用程序的主机名称）存储在窗口的 WM_CLIENT_MACHINE 属性中，供窗口或会话管理器使用。 空字符串将删除该属性。 如果不带参数，则返回最后设置的名称，或者空字符串。 wm_client() 是 client() 的别名。

colormapwindows(*wlist)

操作 WM_COLORMAP_WINDOWS 属性，该属性告知窗口管理器哪些窗口具有私有颜色映射。 如果给定了 wlist，则用这些窗口覆盖该属性（它们的顺序是安装颜色映射的优先级顺序）。 如果不带参数，则返回当前在该属性中命名的窗口列表。 wm_colormapwindows() 是 colormapwindows() 的别名。

command(value=None)

将 value 存储在窗口的 WM_COMMAND 属性中，供窗口或会话管理器使用；它应该是一个包含用于调用该应用程序的命令词的列表。 空字符串将删除该属性。 如果不带参数，则返回最后设置的值，或者空字符串。 wm_command() 是 command() 的别名。

deiconify()

通过映射窗口以正常（非图标化）形式显示该窗口。 如果该窗口从未被映射过，这可确保它在首次映射时以取消图标化的状态显示。 在 Windows 上，窗口还会被提升并赋予焦点。 wm_deiconify() 是 deiconify() 的别名。

focusmodel(model=None)

设置或查询窗口的焦点模型。 model 可以是 'active' （窗口为其自身或其后代请求输入焦点，即使焦点在另一个应用程序中）或 'passive' （窗口依赖窗口管理器赋予其焦点）。 如果不带参数，则返回当前模型。 默认为 'passive'，这也是 focus() 命令所假定的。 wm_focusmodel() 是 focusmodel() 的别名。

forget(window)

从屏幕上取消映射 window，使其不再由窗口管理器管理。 此时 Toplevel 会被视为类似 Frame，不过它的 -menu 配置会被记住，如果该控件再次被管理，菜单会重新出现。 wm_forget() 是 forget() 的别名。

请勿与 Pack.forget() 相混淆。

Added in version 3.3.

frame()

如果窗口管理器已将窗口重定父级到装饰框架中，则返回包含该窗口的最外层装饰框架的平台专属窗口标识符；否则返回窗口本身的标识符。 wm_frame() 是 frame() 的别名。

geometry(newGeometry=None)

设置或查询窗口的几何尺寸。 newGeometry 的形式为 =widthxheight+x+y，其中 =、 widthxheight 以及 +x+y 位置中的任何一项都可以省略。 width 和 height 以像素为单位（对于网格化窗口则以网格单位为单位）；前面带有 + 的位置是从屏幕的左边缘或顶边缘测量的，而前面带有 - 的位置是从屏幕的右边缘或底边缘测量的。 偏移量可以为负，如 '200x100+-9+-8'，此时窗口边缘位于相应屏幕边缘之外。 空字符串将取消任何用户指定的几何尺寸，让窗口恢复为其固有尺寸。 如果不带参数，则以形如 '200x200+10+10' 的字符串返回当前的几何尺寸。 wm_geometry() 是 geometry() 的别名。

grid(baseWidth=None, baseHeight=None, widthInc=None, heightInc=None)

将窗口作为网格化窗口进行管理，并定义网格单位与像素之间的关系。 baseWidth 和 baseHeight 是窗口内部请求尺寸的网格单位数，而 widthInc 和 heightInc 是水平和垂直网格单位的像素大小。 空字符串将关闭网格化管理。 如果不带参数，则返回由四个当前值组成的元组，或者在窗口未网格化时返回 None。 wm_grid() 是 grid() 的别名。

请勿与网格几何管理器 Grid.grid() 相混淆。

group(pathName=None)

设置或查询一组相关联窗口的主导窗口。 pathName 给出主导窗口的路径名；例如，当主导窗口图标化时，窗口管理器可以取消映射该分组中的所有窗口。 空字符串将从任何分组中移除该窗口。 如果不带参数，则返回当前主导窗口的路径名，或者空字符串。 wm_group() 是 group() 的别名。

iconbitmap(bitmap=None, default=None)

设置或查询窗口管理器用于窗口图标的位图。 bitmap 指定 Tk 接受的标准形式之一的位图名称；空字符串将取消当前图标位图。 如果不带参数，则返回当前图标位图的名称，或者空字符串。 在 Windows 上， default 参数指定应用于所有没有自带图标的顶层窗口的图标（例如 .ico 文件）。 wm_iconbitmap() 是 iconbitmap() 的别名。

iconify()

将窗口图标化。 如果窗口尚未首次被映射，则安排其在最终被映射时以图标化状态显示。 wm_iconify() 是 iconify() 的别名。

iconmask(bitmap=None)

设置或查询用作图标掩码的位图（参见 iconbitmap() ）。 掩码为零之处不显示图标；为一之处显示图标位图的相应位。 空字符串将取消当前掩码。 如果不带参数，则返回当前图标掩码的名称，或者空字符串。 wm_iconmask() 是 iconmask() 的别名。

iconname(newName=None)

设置或查询窗口管理器在窗口图标内显示的名称。 如果不带参数，则返回当前图标名称，如果未设置则返回空字符串（此时窗口管理器通常会显示窗口标题）。 wm_iconname() 是 iconname() 的别名。

iconphoto(default=False, *images)

根据 images 中给出的一个或多个 PhotoImage 对象设置窗口的标题栏图标。 可以提供多种不同尺寸的图像（例如 16x16 和 32x32），以便窗口管理器可以选择合适的一个。 图像数据在调用时作为快照获取；后续对图像的更改不会反映出来。 如果 default 为 true，则该图标也会应用于将来创建的所有顶层窗口。 在 macOS 上仅使用第一张图像。 wm_iconphoto() 是 iconphoto() 的别名。

Added in version 3.3.

iconposition(x=None, y=None)

设置或查询给窗口管理器的关于窗口图标应放置在何处的提示。 空字符串将取消现有提示。 如果不带参数，则返回由两个当前值组成的元组，或者在没有提示生效时返回 None。 wm_iconposition() 是 iconposition() 的别名。

iconwindow(pathName=None)

设置或查询用作该窗口图标的窗口。 当窗口图标化时， pathName 会被映射以作为其图标，并在取消图标化时再次取消映射。 空字符串将取消该关联。 如果不带参数，则返回当前图标窗口的路径名，或者空字符串。 并非所有窗口管理器都支持图标窗口，而且该概念在非 X11 平台上毫无意义。 wm_iconwindow() 是 iconwindow() 的别名。

manage(widget)

将 widget 设为独立的顶层窗口，由窗口管理器为其添加标题栏等装饰。 只能使用 Frame、 LabelFrame 和 Toplevel 控件（ 不 接受 tkinter.ttk 版本）；传入任何其他控件类型都会引发错误。 wm_manage() 是 manage() 的别名。

Added in version 3.3.

maxsize(width=None, height=None)

设置或查询窗口允许的最大尺寸，以像素为单位（对于网格化窗口则以网格单位为单位）。 窗口管理器将窗口限制为不大于 width 和 height。 如果不带参数，则返回由当前最大宽度和高度组成的元组。 最大尺寸默认为屏幕尺寸。 wm_maxsize() 是 maxsize() 的别名。

minsize(width=None, height=None)

设置或查询窗口允许的最小尺寸，以像素为单位（对于网格化窗口则以网格单位为单位）。 窗口管理器将窗口限制为不小于 width 和 height。 如果不带参数，则返回由当前最小宽度和高度组成的元组。 最小尺寸默认为每个维度一个像素。 wm_minsize() 是 minsize() 的别名。

overrideredirect(boolean=None)

设置或查询窗口的 override-redirect 标志。 当设置了该标志时，窗口将被窗口管理器忽略：它不会被重定父级到装饰框架中，并且用户无法通过常规的窗口管理器控件来操作它。 如果不带参数，则返回一个布尔值指明是否设置了该标志，如果未设置则返回 None。 仅当窗口首次被映射或从撤回状态重新映射时，该标志才能被可靠地遵循。 wm_overrideredirect() 是 overrideredirect() 的别名。

positionfrom(who=None)

设置或查询窗口当前位置的来源。 who 可以是 'program' 或 'user'，指示该位置是由程序还是由用户请求的；空字符串将取消当前来源。 如果不带参数，则返回当前来源，如果未设置则返回空字符串。 当调用 geometry() 时，Tk 会自动将来源设置为 'user'，除非已被显式设置为 'program'。 wm_positionfrom() 是 positionfrom() 的别名。

protocol(name=None, func=None)

将 func 注册为窗口管理器协议 name （例如 'WM_DELETE_WINDOW'、 'WM_SAVE_YOURSELF' 或 'WM_TAKE_FOCUS' 等原子）的处理程序；每当窗口管理器发送该协议的消息时，就会调用 func。 Tk 会安装一个销毁窗口的默认 WM_DELETE_WINDOW 处理程序，该方法可以替换它。 如果 func 为空字符串，则移除该处理程序。 如果仅提供 name，则返回其注册的处理程序命令的名称，如果未设置则返回空字符串（不会报告默认的 WM_DELETE_WINDOW 处理程序）；如果不带参数，则返回当前具有处理程序的协议组成的元组。 wm_protocol() 是 protocol() 的别名。

resizable(width=None, height=None)

控制用户是否可以以交互方式调整窗口大小。 width 和 height 是布尔值，用于确定窗口的宽度和高度是否可以更改。 如果不带参数，则返回由两个 0/1 值组成的元组，指示各个维度当前是否可调整大小。 默认情况下，窗口在两个维度上均可调整大小。 wm_resizable() 是 resizable() 的别名。

sizefrom(who=None)

设置或查询窗口当前尺寸的来源。 who 可以是 'program' 或 'user'，指示该尺寸是由程序还是由用户请求的；空字符串将取消当前来源。 如果不带参数，则返回当前来源，如果未设置则返回空字符串。 wm_sizefrom() 是 sizefrom() 的别名。

state(newstate=None)

设置或查询窗口的状态。 如果不带参数，则返回当前状态： 'normal'、 'iconic'、 'withdrawn'、 'icon' 之一，或者仅在 Windows 和 macOS 上为 'zoomed'。 'iconic' 指已被图标化的窗口，而 'icon' 指用作另一个窗口图标的窗口（参见 iconwindow() ）；无法设置 'icon' 状态。 wm_state() 是 state() 的别名。

请勿与 ttk.Widget.state 相混淆。

title(string=None)

设置或查询窗口的标题，窗口管理器应将其显示在窗口的标题栏中。 如果不带参数，则返回当前标题。 标题默认为窗口的名称。 wm_title() 是 title() 的别名。

transient(master=None)

将窗口标记为代表 master （另一个顶层窗口的路径名）工作的临时窗口（例如下拉菜单或对话框）。 空字符串将清除临时状态。 如果不带参数，则返回当前主窗口的路径名，或者空字符串。 临时窗口会镜像其主窗口的状态变化，并可能由窗口管理器采用不同的装饰；将窗口设置为其自身的临时窗口是错误的。 wm_transient() 是 transient() 的别名。

withdraw()

从屏幕上撤回窗口，取消对其的映射并使窗口管理器忽略它。 如果该窗口从未被映射过，则它会改为在撤回状态下被映射。 有时需要先撤回窗口然后重新映射它（例如使用 deiconify() ），以便让某些窗口管理器注意到窗口属性的更改。 wm_withdraw() 是 withdraw() 的别名。

class tkinter.Pack

通过将控件紧靠其容器各侧堆叠来排列控件的几何管理器。 Pack 混入类由所有控件继承（通过 Widget ），并提供使用 pack 几何管理器管理控件的方法。 另请参阅 几何管理。

备注

Pack、 Place 和 Grid 都定义了简短的方法名称 forget()、 info()、 slaves()、 content() 和 propagate()。 在控件上，裸名称会解析为 pack 管理器的版本，因为在方法解析顺序中，无论实际管理该控件的是哪个管理器， Pack 和 Misc 均先于 Place 和 Grid；并且 configure() / config() 配置的是控件的选项，而不是其几何形状。 请使用显式的 pack_*、 grid_* 和 place_* 方法（以及用于几何配置的 pack、 grid、 place ）来操作特定的几何管理器。

pack_configure(cnf={}, **kw)
pack(cnf={}, **kw)

将控件打包在其容器内部，相对于已在其中打包的同级控件进行定位。 支持的选项有：

side

将控件紧靠容器的哪一侧打包： 'top' （默认）、 'bottom'、 'left' 或 'right'。

fill

是否拉伸控件以填满为其分配的单元： 'none' （默认）、 'x'、 'y' 或 'both'。

expand

控件是否应扩展以消耗其容器中的任何额外空间（布尔值，默认为 false）。

anchor

当分配单元大于控件时，将控件放置在该单元中的哪个位置：诸如 'n' 或 'sw' 的锚点（默认为 'center' ）。

ipadx, ipady

在控件的左右两边（ ipadx ）或上下两边（ ipady ）添加的内部填充，表示为屏幕距离（默认为 0 ）。

padx, pady

在控件的左右两侧（ padx ）或上下两侧（ pady ）保留的外部填充，表示为屏幕距离或两边各自距离组成的一对值（默认为 0 ）。

after

在打包顺序中将该控件放置在给定控件之后，使用相同的容器。

before

在打包顺序中将该控件放置在给定控件之前，使用相同的容器。

in_

用于打包该控件的容器；默认为父控件。

pack()、 configure() 和 config() 是 pack_configure() 的别名。

pack_forget()

取消映射该控件并将其从打包顺序中移除，遗忘其打包选项。 稍后可以使用 pack_configure() 再次打包它。 forget() 是 pack_forget() 的别名，但在 PanedWindow、 ttk.Notebook 和 ttk.PanedWindow 上除外，它们提供了各自的 forget() 方法。

请勿与 Wm.forget() 混淆。

pack_info()

返回该控件当前打包选项的字典。 info() 是 pack_info() 的别名。

pack_propagate()
pack_propagate(flag)

与 Misc.pack_propagate() 相同，将此控件视为容器：启用或禁用几何传播。 propagate() 是 pack_propagate() 的别名。

pack_slaves()

与 Misc.pack_slaves() 相同：返回打包在此控件中的控件列表。 slaves() 是 pack_slaves() 的别名。

pack_content()

Same as Misc.pack_content(). content() is an alias of pack_content().

Added in version 3.15.

class tkinter.Place

在其容器内将控件放置在明确位置和尺寸上的几何管理器。 所有控件都（通过 Widget）继承了 Place 混入类。 另请参阅 几何管理。

place_configure(cnf={}, **kw)
place(cnf={}, **kw)

将控件放置在其容器内的绝对或相对位置。 支持的选项包括：

x, y

控件锚点的绝对水平和垂直位置，采用屏幕距离表示（默认为 0）。

relx, rely

控件锚点的水平和垂直位置，表示为容器宽度和高度的分数，其中 0.0 为左边缘或上边缘， 1.0 为右边缘或下边缘。 如果同时给出了绝对和相对选项，它们的值将相加。

anchor

控件的哪个点放置在给定位置：如 'n' 或 'se' 等锚点（默认为 'nw'）。

width, height

控件的绝对宽度和高度，表示为屏幕距离。 默认使用控件所请求的尺寸。

relwidth, relheight

控件的宽度和高度，表示为容器宽度和高度的分数。 如果同时给出了绝对和相对选项，它们的值将相加。

bordermode

容器边框如何影响放置： 'inside' （默认值）度量边框内部区域， 'outside' 度量包括边框在内的区域，而 'ignore' 则使用正式的 X 区域。

in_

放置控件所相对于的容器；它必须是该控件的父控件或父控件的后代控件，默认为父控件。

place()、 configure() 和 config() 是 place_configure() 的别名。

place_forget()

取消映射该控件并将其从放置中移除，遗忘其放置选项。

place_info()

返回该控件当前放置选项的字典。

place_slaves()

与 Misc.place_slaves() 相同：返回放置在此控件中的控件列表。

place_content()

Same as Misc.place_content().

Added in version 3.15.

class tkinter.Grid

在其容器内将控件排列在行和列的二维网格中的几何管理器。 所有控件都（通过 Widget）继承了 Grid 混入类。 另请参阅 几何管理。

grid_configure(cnf={}, **kw)
grid(cnf={}, **kw)

将控件放置在其容器网格的单元格中。

请勿与 Wm.grid() 混淆。

支持的选项包括：

row, column

要放置控件的单元格的行和列，从 0 开始计数。 column 默认为同一 grid_configure() 调用中放置的上一个控件之后的列（或 0），而 row 默认为下一个空行。

rowspan, columnspan

控件应当跨越的行数和列数（默认为 1）。

sticky

当单元格大于控件时如何定位或拉伸控件：一个包含零个或多个字符 'n'、 's'、 'e' 和 'w' 的字符串，指明控件吸附到的单元格边。 同时指定 'n' 和 's' （或 'e' 和 'w'）会拉伸控件以填满单元格的高度（或宽度）。 默认值为 ''，这会将控件以其请求的尺寸居中。

ipadx, ipady

在控件的左右两边（ ipadx ）或上下两边（ ipady ）添加的内部填充，表示为屏幕距离（默认为 0 ）。

padx, pady

在控件的左右两侧（ padx ）或上下两侧（ pady ）保留的外部填充，表示为屏幕距离或两边各自距离组成的一对值（默认为 0 ）。

in_

要在其网格中放置该控件的容器；默认为父控件。

grid()、 configure() 和 config() 是 grid_configure() 的别名。

grid_forget()

取消映射该控件并将其从网格中移除，遗忘其网格选项。

grid_remove()

取消映射该控件并将其从网格中移除，但记住其网格选项，以便在再次将其放入网格时恢复到同一个单元格。

grid_info()

返回该控件当前网格选项的字典。

grid_bbox(column=None, row=None, col2=None, row2=None)

与 Misc.grid_bbox() 相同。 bbox() 是 grid_bbox() 的别名，但在 Canvas、 Listbox、 Spinbox、 Text、 ttk.Entry 和 ttk.Treeview 上除外，它们提供了各自的 bbox() 方法。

grid_columnconfigure(index, cnf={}, **kw)

与 Misc.grid_columnconfigure() 相同：查询或设置网格列的选项（例如 weight、 minsize、 pad 和 uniform）。 columnconfigure() 是 grid_columnconfigure() 的别名。

grid_rowconfigure(index, cnf={}, **kw)

与 Misc.grid_rowconfigure() 相同：查询或设置网格行的选项。 rowconfigure() 是 grid_rowconfigure() 的别名。

grid_location(x, y)

与 Misc.grid_location() 相同：返回覆盖 x, y 处像素的单元格的 (column, row)。 location() 是 grid_location() 的别名。

grid_size()

与 Misc.grid_size() 相同：返回一个给出网格大小的 (columns, rows) 元组。 size() 是 grid_size() 的别名，但在 Listbox 控件上除外，该控件提供了其自有的 size() 方法。

grid_propagate()
grid_propagate(flag)

与 Misc.grid_propagate() 相同。

grid_slaves(row=None, column=None)

与 Misc.grid_slaves() 相同：返回在网格中管理的控件，可以选择限制为特定的 row 和/或 column。

grid_content(row=None, column=None)

Same as Misc.grid_content().

Added in version 3.15.

class tkinter.XView

提供由 Entry、 Canvas、 Listbox、 Text 和 Spinbox 等控件所共享的水平滚动接口的混入类。 控件的 xview() 方法被注册为水平 Scrollbar 的 command。

xview(*args)

查询或更改视图的水平位置。 在不带参数的情况下，返回一个由介于 0 和 1 之间的两个分数构成的元组 (first, last)，给出当前可见文档的部分。 否则，参数将传递给 Tk xview 控件命令，通常由滚动条生成； xview_moveto() 和 xview_scroll() 提供了更方便的接口。

xview_moveto(fraction)

调整视图，使文档总宽度的 fraction 位于屏幕左侧之外。 fraction 是介于 0 和 1 之间的数字。

xview_scroll(number, what)

Shift the view left or right by number units. what is either 'units' or 'pages'; a negative number scrolls left and a positive one scrolls right. The Text widget accepts also 'pixels', and then number can be a screen distance, such as '1i'.

class tkinter.YView

提供由 Canvas、 Listbox 和 Text 等控件所共享的垂直滚动接口的混入类。 控件的 yview() 方法被注册为垂直 Scrollbar 的 command。

yview(*args)

查询或更改视图的垂直位置。 在不带参数的情况下，返回一个由介于 0 和 1 之间的两个分数构成的元组 (first, last)，给出当前可见文档的部分。 否则，参数将传递给 Tk yview 控件命令，通常由滚动条生成； yview_moveto() 和 yview_scroll() 提供了更方便的接口。

yview_moveto(fraction)

调整视图，使文档总高度的 fraction 位于屏幕顶部之外。 fraction 是介于 0 和 1 之间的数字。

yview_scroll(number, what)

Shift the view up or down by number units. what is either 'units' or 'pages'; a negative number scrolls up and a positive one scrolls down. The Text widget accepts also 'pixels', and then number can be a screen distance, such as '1i'.

class tkinter.BaseWidget(master, widgetName, cnf={}, kw={}, extra=())

所有控件的内部基类。 它继承自 Misc 并添加了创建底层 Tk 控件的机制；应用程序代码通常使用 Widget 或具体的控件类，而不是直接实例化 BaseWidget。

destroy()

销毁此控件及其所有子控件，移除对应的 Tk 控件并删除关联的 Tcl 命令。

class tkinter.Widget(master, widgetName, cnf={}, kw={}, extra=())

标准控件的内部基类。 它将 BaseWidget 与几何管理器混入类 Pack、 Place 和 Grid 相结合，使得每个控件都可以由这三种几何管理器中的任何一种进行管理。 具体的控件类（Button、 Label 等）派生自 Widget。

顶层控件

class tkinter.Tk(screenName=None, baseName=None, className='Tk', useTk=True, sync=False, use=None)

构造一个顶层 Tk 控件（通常是应用程序的主窗口），并为此控件初始化一个 Tcl 解释器。 每个实例都有其自己关联的 Tcl 解释器。 继承自 Misc 和 Wm。

要创建 Tcl 解释器而不初始化 Tk 子系统，请改用 Tcl() 工厂函数。

Tk 类通常全部使用默认值来初始化。 不过，目前还可识别下列关键字参数:

screenName

当（作为字符串）给出时，设置 DISPLAY 环境变量。 （仅限 X11）

baseName

预置文件的名称。 在默认情况下，baseName 是来自于程序名称 (sys.argv[0])。

className

控件类的名称。 会被用作预置文件同时也作为 Tcl 唤起的名称 (interp 中的 argv0)。

useTk

如果为 True，则初始化 Tk 子系统。 tkinter.Tcl() 函数会将其设为 False。

sync

如果为 True，则同步执行所有 X 服务器命令，以便立即报告错误。 可被用于调试。 （仅限 X11）

use

指定用于嵌入应用程序的窗口的 id，而不是将其创建为独立的顶层窗口。 id 的指定方式必须与顶层控件的 -use 选项的值相同（即，其形式类似于 winfo_id() 所返回的值）。

请注意在某些平台上只有当 id 是指向一个启用了 -container 选项的 Tk 框架或顶层窗口时此参数才能正确生效。

Tk 读取并解释预置文件，其名称为 .className.tcl 和 .baseName.tcl，进入 Tcl 解释器并基于 .className.py 和 .baseName.py 的内容来调用 exec()。 预置文件的路径为 HOME 环境变量，或者如果它未被定义，则为 os.curdir。

备注

在 Windows 上，创建 Tcl 解释器（通过实例化 Tk 或调用 Tcl()）如果尚未设置进程的 HOME 环境变量，则会将其设置为 %HOMEDRIVE%%HOMEPATH% （或 USERPROFILE，或 c:\）。 这是由 Tcl 完成的，可能会影响读取 HOME 的其他代码。

tk

通过实例化 Tk 创建的 Tk 应用程序对象。 这提供了对 Tcl 解释器的访问。 每个被附加到相同 Tk 实例的控件都具有相同的 tk 属性值。

master

包含此控件的控件对象。 对于 Tk， master 为 None，因为它是主窗口。 术语 master 和 parent 很相似，有时作为参数名称互换使用；但是，调用 winfo_parent() 会返回控件名称的字符串，而 master 返回该对象。 parent/child 反映了树状关系，而 master （或 container）/content 反映了容器结构。

children

以 dict 表示的此控件的直接下级其中的键为子控件名称而值为子实例对象。

destroy()

销毁此控件及其所有后代控件，并且对于主窗口，结束与底层 Tcl 解释器的连接。

loadtk()

完成 Tk 子系统的加载和初始化。 这仅在创建解释器时未包含 Tk（例如通过 Tcl()）时才需要；当 useTk 为 true 时会自动调用它。

readprofile(baseName, className)

读取用户的配置文件 .className.tcl 和 .baseName.tcl 并将其 source 到 Tcl 解释器中，并执行对应的 .className.py 和 .baseName.py 文件。 这会在初始化期间被调用；参见上文对构造器的描述。

report_callback_exception(exc, val, tb)

报告回调异常。 当异常从 Tkinter 回调中传播出来时将调用此方法； exc、 val 和 tb 是 sys.exc_info() 所返回的异常类型、值和回溯。 默认实现会将回溯打印到 sys.stderr。 可以重写它以自定义错误处理，例如在对话框中显示回溯。

class tkinter.Toplevel(master=None, cnf={}, **kw)

Toplevel 控件是一个顶层窗口，类似于 Frame，不同之处在于它的 X 父级是屏幕的根窗口，而不是其逻辑父级。 它的主要用途是充当对话框和其他控件集合的容器；它唯一可见的特征是其背景和可选的 3-D 边框。 值得注意的选项包括 menu，它将一个 Menu 安装为窗口的菜单栏。 继承自 BaseWidget 和 Wm，因此顶层窗口由窗口管理器管理。 完整的选项列表请参阅 Tk toplevel 手册页。

控件类

class tkinter.Button(master=None, cnf={}, **kw)

Button 控件显示文本字符串、位图或图像，并在用户按下它时（通过在按钮上点击鼠标按键 1，或者当按钮拥有焦点时按下空格键）调用命令。 继承自 Widget。 除了标准控件选项之外，按钮还接受 Tk button 手册页中记录的选项，例如 command （按下按钮时调用的回调）、 textvariable、 state 和 default。

invoke()

调用与按钮关联的命令（如果有），并返回其结果；如果按钮没有关联命令，则返回空字符串。 如果按钮的状态为 disabled，则此操作将被忽略。

flash()

通过多次重新显示按钮，在激活与正常颜色之间交替以使按钮闪烁。 闪烁结束时，按钮将保持调用该方法时的正常或激活状态。 如果按钮的状态为 disabled，则此操作将被忽略。

class tkinter.Canvas(master=None, cnf={}, **kw)

Canvas 控件实现了结构化图形。 它可以显示任意数量的 项，例如圆弧、线条、椭圆、多边形、矩形、文本、位图、图像和嵌入窗口，这些项可以被绘制、移动、重新着色并绑定到事件。 继承自 Widget、 XView 和 YView，因此可以通过 xview() 和 yview() 水平和垂直滚动视图。 完整的控件和项选项列表请参阅 Tk canvas 手册页。

每个项都有一个唯一的整数 id （在创建时分配），以及零个或多个字符串 tag。 tag 是一个不具有整数形式的任意字符串；同一个 tag 可以被多个项共享，这使得 tag 非常便于对项进行分组。 特殊的 tag 'all' 匹配画布中的每个项，而 'current' 匹配鼠标指针下最顶层的项。 大多数方法接受一个 tagOrId 参数，该参数可以是一个指定单个项的整数 id，也可以是一个指定零个或多个项的 tag；正如 Tk canvas 手册页中所述，tag 还可以是由运算符 &&、 ||、 ^、 ! 和圆括号组合而成的 tag 逻辑表达式。 当对单个项进行操作的方法被传入匹配多个项的 tagOrId 时，它通常会使用显示列表中匹配的最底层的项。

这些项保存在一个确定绘制顺序的 显示列表 中：列表中靠后的项绘制在靠前的项之上。 新创建的项放置在列表的顶部；可以使用 tag_raise() 和 tag_lower() 更改顺序。

create_arc(*args, **kw)
create_bitmap(*args, **kw)
create_image(*args, **kw)
create_line(*args, **kw)
create_oval(*args, **kw)
create_polygon(*args, **kw)
create_rectangle(*args, **kw)
create_text(*args, **kw)
create_window(*args, **kw)

创建对应类型的新项并返回其整数 id。 每个方法的调用方式为 create_TYPE(coord..., **options)：前面的位置参数给出了定义该项的坐标（作为单独的数值、数值构成的单个序列或坐标对），关键字参数则设置特定于该项的选项。 坐标和屏幕距离可以作为数值（解释为像素）给出，也可以作为带有单位后缀的字符串（'m'、 'c'、 'i' 或 'p' 分别表示毫米、厘米、英寸或打印机点数）给出，但总是以像素为单位存储和返回。

项类型包括： arc （椭圆局部的圆弧形区域，由外接矩形的两个对角顶点 x1, y1, x2, y2 定义）； bitmap （位于点 x, y 的双色位图）； image （位于点 x, y 的 Tk 图像）； line （穿过点 x1, y1, ..., xn, yn 的直线或曲线）； oval （内接于矩形 x1, y1, x2, y2 的圆或椭圆）； polygon （穿过点 x1, y1, ..., xn, yn 的闭合多边形）； rectangle （顶点为 x1, y1, x2, y2 的矩形）； text （位于点 x, y 的文本字符串）；以及 window （在点 x, y 处嵌入画布的子控件，通过 window 选项指定）。

大多数项类型都接受一组通用的 标准项选项，以及特定于每种类型的少数选项。 选项名称作为关键字参数传递，不带前导连字符。

标准项选项包括：

fill

用于填充项内部的颜色，或者用于绘制 line 项或 text 项字符的颜色。 空字符串（除 line 和 text 外所有类型的默认值）表示不对项进行填充。

outline

用于绘制项轮廓的颜色。 空字符串表示不绘制轮廓。

width

轮廓的宽度，默认为 1.0。 如果 outline 为空则无效。

dash

轮廓的虚线样式，可以指定为以像素为单位的线段长度序列，也可以指定为由字符 '.'、 ','、 '-'、 '_' 和空格组成的字符串。 空样式（默认值）会绘制实线轮廓。

dashoffset

进入 dash 样式的起始偏移量（以像素为单位）。 如果没有 dash 样式则会被忽略。

stipple

在填充项时用作点描样式的位图。 仅在 X11 上得到良好支持。

outlinestipple

在绘制轮廓时用作点描样式的位图。 如果 outline 为空则无效。

offset, outlineoffset

填充和轮廓点描样式的偏移量，指定为 'x,y' 或如 'n'、 'se' 或 'center' 等侧边方位。 点描偏移量仅在 X11 上受支持。

state

覆盖该项的画布状态；为 'normal'、 'disabled' 或 'hidden' 之一。

tags

与该项关联的单个标签或标签序列，将替换任何现有的标签。

其中许多选项具有 active... 和 disabled... 变体（例如 activefill、 disabledfill、 activewidth、 disableddash、 activeoutline、 disabledstipple），当该项是激活项（位于鼠标指针下方）或处于禁用状态时，它们会覆盖基本选项。

以下项类型支持附加选项。

对于 arc 项：

start

圆弧角度范围的起始位置，以从 3 点钟位置逆时针测量的度数为单位。

extent

角度范围的大小，以从 start 开始逆时针方向的度数为单位。

style

圆弧的绘制方式： 'pieslice' （默认）、 'chord' 或 'arc'。

对于 line 项：

arrow

在何处绘制箭头： 'none' （默认）、 'first' 、 'last' 或 'both'。

arrowshape

描述箭头形状的由三个距离组成的序列。

capstyle

线端的绘制方式： 'butt' （默认）、 'projecting' 或 'round'。

joinstyle

线顶点的绘制方式： 'round' （默认）、 'bevel' 或 'miter'。

smooth

平滑方法：假值（默认）表示不进行平滑，或者为 'true'/'bezier' 或 'raw' 将线条绘制为曲线。

splinesteps

当启用 smooth 时，用于逼近每条样条曲线的线段数量。

对于 polygon 项：

joinstyle, smooth, splinesteps

与 line 项相同，应用于多边形的轮廓。

对于 text 项：

text

要显示的字符串；换行符将开始新行。

font

用于文本的字体。

justify

文本行的对齐方式： 'left' （默认）、 'right' 或 'center'。

anchor

文本相对于其定位点的放置方式，默认为 'center'。

width

最大行长度；如果非零，行将在空格处折行。

angle

围绕其定位点将文本逆时针旋转的度数，从 0.0 到 360.0 （默认为 0.0 ）。

underline

要添加下划线的字符的索引，或者用 -1 表示无。

对于 bitmap 项：

bitmap

要显示的位图。

anchor

位图相对于其定位点的放置方式。

background, foreground

用于位图的 0 和 1 像素的颜色；空的 background 会使 0 像素透明。 两者都具有 active... 和 disabled... 变体，而 bitmap 具有 activebitmap 和 disabledbitmap 变体。

对于 image 项：

image

要显示的 Tk 图像，此前已使用图像协议创建。

anchor

图像相对于其定位点的放置方式。

这两个选项都具有在激活和禁用状态下使用的 active... 和 disabled... 变体（activeimage、 disabledimage）。

对于 window 项：

window

要嵌入的控件；它必须是画布或其祖先控件之一的子控件，且不能是顶层窗口。

anchor

窗口相对于其定位点的放置方式。

width, height

要分配给窗口的大小；如果为零（默认值），则为窗口赋予其请求的大小。

oval 和 rectangle 项没有特定于类型的选项；它们仅使用标准项选项。

备注

Tk 8.6 added the angle option for text items.

coords(tagOrId)
coords(tagOrId, coordList, /)
coords(tagOrId, /, *coordList)

查询或修改某个项的坐标。 若仅提供 tagOrId，则返回由 tagOrId 指定项的浮点坐标列表（如果匹配多个项，则为第一个匹配项）。 若提供了新坐标，则用它们替换该项的坐标；与 create_* 方法类似，坐标可以作为单独的数字、单个序列或成对坐标给出。 返回的坐标始终以像素为单位，无论用于指定它们的单位是什么；对于矩形、椭圆和圆弧，它们的顺序为左、上、右、下。

在 3.12 版本发生变更: 参数现已扁平化：坐标可以作为单独的参数、单个序列或成对分组给出，类似于 create_* 方法。

move(tagOrId, xAmount, yAmount, /)

在画布坐标空间中移动由 tagOrId 指定的每个项，方法是将 xAmount 加到该项的每个 x 坐标，将 yAmount 加到该项的每个 y 坐标。

moveto(tagOrId, x='', y='')

移动由 tagOrId 指定的项，使层级最低的匹配项的第一个坐标对（边界框的左上角）位于位置 (x, y)。 x 或 y 可以是空字符串，在这种情况下对应的坐标保持不变。 所有匹配的项保持它们之间的相对位置。

Added in version 3.8.

scale(tagOrId, xOrigin, yOrigin, xScale, yScale, /)

在画布坐标空间中重新缩放由 tagOrId 指定的所有项的坐标。 每个 x 坐标都会被调整，使其与 xOrigin 的距离按 xScale 的倍数改变；每个 y 坐标也是如此，使其与 yOrigin 的距离按 yScale 的倍数改变（倍数为 1.0 时坐标保持不变）。

delete(*tagOrIds)

删除由 tagOrIds 参数指定的每个项。

dchars(tagOrId, first, /)
dchars(tagOrId, first, last, /)

从由 tagOrId 指定的每个项中，删除从 first 到 last （包含）范围内的字符（对于文本项）或坐标（对于线条和多边形项）； last 默认为 first。 不支持索引的项将忽略此操作。

insert(tagOrId, beforeThis, string, /)

将 string 插入到由 tagOrId 指定的每个项中索引为 beforeThis 的字符或坐标之前。 对于线条和多边形项， string 必须是有效的坐标序列。

itemcget(tagOrId, option)

返回由 tagOrId 指定的项（如果匹配多个，则为层级最低的匹配项）的配置选项 option 的当前值。 这类似于 cget() 但适用于单个项。

itemconfigure(tagOrId, cnf=None, **kw)

查询或修改由 tagOrId 指定的项的配置选项。 这与 configure() 类似，不同之处在于它适用于单个项而不是整个画布。 在没有提供选项时，它返回一个描述第一个匹配项当前选项的字典；否则它会在每个匹配项上设置给定的选项。 合法的选项是相应的 create_* 方法所接受的选项。 itemconfig() 是 itemconfigure() 的别名。

type(tagOrId)

返回由 tagOrId 指定的项的类型（如果匹配多个，则为第一个匹配项），例如 'rectangle' 或 'text'；如果 tagOrId 未匹配任何项，则返回 None。

gettags(tagOrId, /)

返回由 tagOrId 指定的项所关联标签的元组（如果匹配多个项，则为按显示列表顺序排列的第一个匹配项）。 如果没有项匹配或该项没有标签，则返回一个空元组。

dtag(tagOrId, /)
dtag(tagOrId, tagToDelete, /)

从由 tagOrId 指定的每个项中移除标签 tagToDelete （默认为 tagOrId ）。 没有该标签的项不受影响。

addtag(newtag, searchSpec, /, *args)

将标签 newtag 添加到由搜索规范 searchSpec （以及任何后续 args ）选定的每个项。 searchSpec 是 'above'、 'all'、 'below'、 'closest'、 'enclosed'、 'overlapping' 或 'withtag' 之一；下面的 addtag_* 方法是提供这些形式的便捷包装器。

addtag_above(newtag, tagOrId)

将标签 newtag 添加到显示列表中紧邻 tagOrId 上方（之后）的项。

addtag_all(newtag)

将标签 newtag 添加到画布中的所有项。

addtag_below(newtag, tagOrId)

将标签 newtag 添加到显示列表中紧邻 tagOrId 下方（之前）的项。

addtag_closest(newtag, x, y, halo=None, start=None)

将标签 newtag 添加到最接近点 (x, y) 的项。 如果给出了 halo，则该点指定距离内的任何项都将被视为与该点重叠。 如果给出了 start （标签或 ID），则选择显示列表中位于 start 下方的最高的最接近项，这可用于逐步遍历所有最接近的项。

addtag_enclosed(newtag, x1, y1, x2, y2)

将标签 newtag 添加到完全包含在矩形 (x1, y1, x2, y2) 内的每个项，其中 x1 <= x2 且 y1 <= y2。

addtag_overlapping(newtag, x1, y1, x2, y2)

将标签 newtag 添加到与矩形 (x1, y1, x2, y2) 重叠或包含在其中的每个项，其中 x1 <= x2 且 y1 <= y2。

addtag_withtag(newtag, tagOrId)

将标签 newtag 添加到由 tagOrId 指定的每个项。

find(searchSpec, /, *args)

返回由搜索规范 searchSpec （以及任何后续 args ）选定的所有项的 ID 元组，按堆叠顺序排列，层级最低的项排在最前。 搜索规范可以采用 addtag() 所接受的任何形式。 下面的 find_* 方法是围绕它的更便捷的包装器。

find_above(tagOrId)

返回一个元组，其中包含显示列表中紧邻 tagOrId 上方的项的 ID。

find_all()

按堆叠顺序返回画布中所有项的 ID 元组。

find_below(tagOrId)

返回一个元组，其中包含显示列表中紧邻 tagOrId 下方的项的 ID。

find_closest(x, y, halo=None, start=None)

返回一个元组，其中包含最接近点 (x, y) 的项的 ID。 halo 和 start 的解释与 addtag_closest() 相同。

find_enclosed(x1, y1, x2, y2)

返回完全包含在矩形 (x1, y1, x2, y2) 内的所有项的 ID 元组。

find_overlapping(x1, y1, x2, y2)

返回与矩形 (x1, y1, x2, y2) 重叠或包含在其中的所有项的 ID 元组。

find_withtag(tagOrId)

返回由 tagOrId 指定的所有项的 ID 元组。

tag_raise(tagOrId, aboveThis=None, /)

将由 tagOrId 指定的所有项移动到显示列表中紧邻 aboveThis 所指定项上方的新位置；如果省略了 aboveThis，则移动到显示列表的顶部。 当移动多个项时，它们的相对顺序保持不变。 这对嵌入式窗口项没有影响，它们的堆叠顺序由 Misc.tkraise() 和 Misc.lower() 控制。 lift() 和 tkraise() 是 tag_raise() 的别名。

tag_lower(tagOrId, belowThis=None, /)

将由 tagOrId 指定的所有项移动到显示列表中紧邻 belowThis 所指定项下方的新位置；如果省略了 belowThis，则移动到显示列表的底部。 当移动多个项时，它们的相对顺序保持不变。 这对嵌入式窗口项没有影响。 lower() 是 tag_lower() 的别名。

备注

在 Canvas 上， tkraise()/lift() 和 lower() 会重新堆叠画布项，遮蔽了继承的用于重新堆叠控件本身的 Misc.tkraise()/Misc.lift() 和 Misc.lower() 方法，因此这些方法不可用。

tag_bind(tagOrId, sequence=None, func=None, add=None)

为由 tagOrId 指定的所有项将回调 func 绑定到事件 sequence，以便每当其中一个项发生该事件时就调用 func。 这类似于 Widget.bind 但作用于画布项而不是整个控件；只有鼠标、键盘和虚拟事件可以被绑定。 鼠标事件被定向到当前项，键盘事件被定向到焦点项（参见 focus()）。 如果 add 为真值，则新绑定将添加到同一序列的任何现有绑定中，而不是替换它们。 返回已绑定函数的标识符，该标识符可以传递给 tag_unbind()。

tag_unbind(tagOrId, sequence, funcid=None)

为由 tagOrId 指定的所有项移除事件 sequence 的绑定。 如果给出了 funcid，则仅解除该回调的绑定并注销（由 tag_bind() 返回）。

在 3.13 版本发生变更: 如果给出了 funcid，则仅解除该回调的绑定。

bbox(tagOrId, /, *tagOrIds)

返回一个 4 元组 (x1, y1, x2, y2)，给出包围由 tagOrId 和任何后续 tagOrIds 指定的所有项的近似边界框（以像素为单位）。 结果可能会比真实边界框高估几个像素。 如果没有任何项匹配或匹配的项没有任何可显示内容，则返回 None。

这会遮蔽继承的 Misc.bbox()；对于网格边界框，请使用 grid_bbox()。

canvasx(screenx, gridspacing=None)

给定窗口 x 坐标 screenx，返回显示在该位置的画布 x 坐标。 如果给出了 gridspacing，则结果将舍入到最接近的 gridspacing 单位的倍数。

canvasy(screeny, gridspacing=None)

给定窗口 y 坐标 screeny，返回显示在该位置的画布 y 坐标。 如果给出了 gridspacing，则结果将舍入到最接近的 gridspacing 单位的倍数。

focus()
focus(tagOrId, /)

当提供 tagOrId 时，将画布的键盘焦点设置给由 tagOrId 指定且支持插入光标的第一个项；如果不存在此类项，则焦点保持不变。 如果 tagOrId 是空字符串，则重置焦点，使任何项都不具有焦点。 若未提供参数，则返回当前具有焦点的项的 ID，若没有任何项具有焦点则返回空字符串。 只有当一个项是焦点项且其所属画布具有输入焦点时，该项才会显示插入光标。

这会遮蔽继承的 Misc.focus()；要聚焦控件本身，请使用 focus_set()。

icursor(tagOrId, index, /)

将由 tagOrId 指定的各项的插入光标设置到紧接在 index 所指定的字符之前。 不支持插入光标的项不受影响。 该光标仅在项具有焦点时才会显示，但其位置可以随时设置。

index(tagOrId, index, /)

以整数形式返回 tagOrId 中与 index 相对应的数值索引，后者是位置的文本描述（对于文本项是字符的索引，对于线条和多边形项是坐标的索引）。 如果 tagOrId 匹配多个项，则使用支持索引的第一个项。

select_adjust(tagOrId, index)

调整 tagOrId 中离 index 最近的选区端点，使其位于 index 处，并将另一端作为后续调用 select_to() 的锚点。 如果选区当前不在 tagOrId 中，则其行为类似于 select_to()。

select_clear()

如果选区在此画布中，则清除选区；否则不执行任何操作。

select_from(tagOrId, index)

将选择锚点设置在由 tagOrId 给定的项中紧接在 index 给定的字符之前。 这不会改变选区本身；它为后续调用 select_to() 设置固定端。

select_item()

返回持有选区的项的 id，如果选区不在此画布中则返回 None。 与 find() 和 find_* 方法不同，此方法以字符串而非整数的形式返回 id。

select_to(tagOrId, index)

将选区设置为 tagOrId 中介于选择锚点与 index 之间的字符，包含 index。 锚点是由最近一次调用 select_adjust() 或 select_from() 所设置的。

scan_mark(x, y)

记录 x, y 以及当前视图，供后续调用 scan_dragto() 时使用。 这通常绑定到控件内的鼠标按键按下事件。

scan_dragto(x, y, gain=10)

将画布滚动 x, y 与最后一次调用 scan_mark() 时传入的坐标之差的 gain 倍。 这通常绑定到控件中的鼠标移动事件，从而产生在窗口中高速拖动画布的效果。

postscript(cnf={}, **kw)

生成画布部分或全部内容的 PostScript（封装 PostScript，3.0 版）表示。 如果给出了 file 或 channel 选项，则 PostScript 会写入其中并返回一个空字符串；否则将其作为字符串返回。 默认情况下只生成窗口中当前可见的区域，因此通常需要先调用 update() 或者使用 width 和 height 选项。 支持的选项包括 colormap, colormode, file, fontmap, height, pageanchor, pageheight, pagewidth, pagex, pagey, rotate, width, x 以及 y。

class tkinter.Checkbutton(master=None, cnf={}, **kw)

Checkbutton 控件显示文本字符串、位图或图像以及一个方形指示器，并在被按下时切换布尔选中状态。 它具有普通按钮的所有行为，此外还可以被选中：选中时指示器绘制有勾选标记，并且关联的变量被设置为 onvalue；取消选中时指示器绘制为空白，变量被设置为 offvalue。 继承自 Widget。 除了标准控件选项之外，复选按钮还接受 Tk checkbutton 手册页中记录的选项，例如 variable, onvalue, offvalue 和 command。

invoke()

执行与用户用鼠标按下复选按钮时完全相同的操作：切换按钮的选中状态并调用关联的命令（如果有的话）。 返回该命令的结果，如果复选按钮未关联命令则返回空字符串。 如果复选按钮的状态为 disabled 则此操作会被忽略。

select()

选中复选按钮并将关联的变量设置为其 onvalue。

deselect()

取消选中复选按钮并将关联的变量设置为其 offvalue。

toggle()

切换按钮的选中状态，重新显示该按钮并修改其关联变量以反映新状态。

flash()

通过多次重新显示复选按钮使其闪烁，在活动颜色和正常颜色之间交替变换。 闪烁结束时，复选按钮将保留在调用该方法时的相同正常或活动状态。 如果复选按钮的状态为 disabled 则此操作会被忽略。

class tkinter.Entry(master=None, cnf={}, **kw)

Entry 控件显示单行文本并允许用户对其进行编辑。 继承自 Widget 和 XView；由于输入框可容纳过长而无法完全放入窗口中的字符串，因此它们支持通过 xview() 进行水平滚动。

除了标准控件选项之外，输入框还接受 Tk entry 手册页中记录的选项。 值得注意的选项包括 textvariable （与输入框内容保持同步的变量名）、 show （如果设置，每个字符都将显示为给定字符而不是其真实值，这对于密码输入很有用）、 validate 和 validatecommand （它们共同允许回调接受或拒绝编辑），以及 state （'normal', 'disabled' 或 'readonly' 之一）。

下列许多方法都带有一个 index 参数，用于选取输入框字符串中的字符。 如 Tk entry 手册页中所述， index 可以是数字（从 0 开始计数）、 'insert' （紧接在插入光标之后的字符）、 'end' （紧接在最后一个字符之后）、 'anchor' （选择锚点）、 'sel.first' 和 'sel.last' （选区的两端），或者是 @x （在窗口中覆盖像素 x 坐标 x 的字符）。 超出范围的索引会被舍入到最接近的合法值。

delete(first, last=None)

删除从索引 first 开始直到但不包括索引 last 的字符。 如果省略 last，则仅删除 first 处的单个字符。

get()

返回输入框的当前字符串。

insert(index, string)

将 string 插入到由 index 给定的字符紧前位置。

icursor(index)

安排将插入光标显示在由 index 给定的字符紧前位置。

index(index)

返回与 index 相对应的数值索引。

selection_adjust(index)

定位选区中离由 index 给出的字符最近的一端，并将该端调整为位于 index 处（包含但不超出该字符）；另一端成为后续调用 selection_to() 的锚点。 如果输入框中没有选区，则会在 index 与最新的锚点之间创建新的选区（包含两端）。 select_adjust() 是 selection_adjust() 的别名。

selection_clear()

如果选区当前在此控件中，则清除选区。 如果选区不在此控件中，则该方法没有任何效果。 select_clear() 是 selection_clear() 的别名。

备注

这会遮蔽继承的 Misc.selection_clear()，该方法用于清除 X 选区；该方法在 Entry 上不可用。

selection_from(index)

将选择锚点设置在由 index 给定的字符紧前位置，而不改变选区。 select_from() 是 selection_from() 的别名。

selection_present()

如果输入框中有选中的字符则返回 True，否则返回 False。 select_present() 是 selection_present() 的别名。

selection_range(start, end)

设置选区以包含从由 start 索引的字符开始到紧接在 end 之前的字符结束的所有字符。 如果 end 指向与 start 相同的字符或更早的字符，则选区将被清除。 select_range() 是 selection_range() 的别名。

selection_to(index)

在锚点与 index 之间设置选区：如果 index 在锚点之前，则选区从 index 开始直到但不包括锚点；如果 index 在锚点之后，则从锚点开始直到但不包括 index；如果它们重合，则什么也不会发生。 锚点是由最近一次调用 selection_from() 或 selection_adjust() 所设置的。 如果输入框中没有选区，则会使用最新的锚点创建一个新选区。 select_to() 是 selection_to() 的别名。

scan_mark(x)

记录 x 和输入框窗口中的当前视图，供后续调用 scan_dragto() 时使用。 通常与控件内的鼠标按键按下事件相关联。

scan_dragto(x)

计算 x 与最后一次调用 scan_mark() 时传入的 x 之间的差值，并将视图向左或向右调整该差值的 10 倍。 通常与鼠标移动事件关联，以产生在窗口中高速拖动输入框的效果。

class tkinter.Frame(master=None, cnf={}, **kw)

Frame 控件是一个简单的容器。 其主要用途是充当复杂窗口布局的隔断或容器；它的唯一特性是其背景以及可选的 3D 边框以使框架显得凸起或凹陷。 继承自 Widget。 完整的选项列表请参阅 Tk frame 手册页。

class tkinter.Label(master=None, cnf={}, **kw)

Label 控件显示非交互式的文本字符串、位图或图像。 显示的文本可通过 text 选项设置或通过 textvariable 关联到变量，并且可以使用 image 选项来显示图像。 文本必须全部采用单一字体，但可以占用多行，并且可以通过 underline 选项为某个字符添加下划线。 继承自 Widget。 完整选项列表请参阅 Tk label 手册页。

class tkinter.LabelFrame(master=None, cnf={}, **kw)

LabelFrame 控件是一个容器，它具备 Frame 的特性以及显示标签的能力。 标签文本通过 text 选项设置并通过 labelanchor 进行定位，或者可以通过将其作为 labelwidget 选项传入来使用任意控件作为标签。 继承自 Widget。 完整选项列表请参阅 Tk labelframe 手册页。

class tkinter.Listbox(master=None, cnf={}, **kw)

Listbox 控件显示单行文本项列表，每行一项，用户可以选择其中一项或多项。 选取的行为方式由 selectmode 选项控制，该选项为 browse （默认值；最多一项，可用鼠标拖动）、 single （最多一项）、 multiple （任意数量的项，逐项切换）或 extended （任意数量的项，包括不连续范围，通过点击和拖动选择）之一。 继承自 Widget, XView 和 YView，因此可以通过 xview() 和 yview() 水平和垂直滚动视图。 完整选项列表请参阅 Tk listbox 手册页。

许多方法都接受一个标识特定项的 index 参数。 如 Tk listbox 手册页中所述， index 可以是数值索引（从顶部的 0 开始计数）、 'active' （带有位置光标的项，使用 activate() 设置）、 'anchor' （选择锚点，使用 selection_anchor() 设置）、 'end' （最后一项，或者对于 index() 和 insert() 则是紧接其后的位置），或者 @x,y （列表框窗口中覆盖像素坐标 x, y 的项）。 名为 first 和 last 的参数是相同形式的索引。

insert(index, *elements)

将给定的 elements 作为新项插入到由 index 给定的项紧前面。 如果 index 为 'end'，新项将追加到列表末尾。

delete(first, last=None)

删除从 first 到 last （包含两端）范围内的各项。 如果省略 last，它默认为 first，因此会删除单个项。

get(first, last=None)

如果省略 last，则返回由 first 给定的项的内容，如果 first 指向不存在的项则返回空字符串。 如果给出了 last，则返回包含从 first 到 last （包含两端）范围内所有项的元组。

size()

返回列表框中的项的总数。

这会遮蔽继承的 Misc.size()；网格大小请使用 grid_size()。

index(index)

返回与 index 对应的整数索引值，如果 index 超出范围则返回 None。 如果 index 为 'end'，结果为列表框中项数的计数（而不是最后一项的索引）。

bbox(index)

返回一个描述由 index 给定的项的文本边界框（以相对于控件的像素为单位）的元组 (x, y, width, height)。 如果该项在屏幕上没有任何部分可见，或者 index 指向不存在的项，则返回 None；如果该项仅部分可见，结果仍会给出该项的完整区域，包括不可见的部分。

这会遮蔽继承的 Misc.bbox()；对于网格边界框，请使用 grid_bbox()。

nearest(y)

给定列表框窗口内的 y 坐标，返回离该 y 坐标最近的可见项的索引。

see(index)

调整视图以使由 index 给定的项可见。 如果该项已经可见，则该方法没有任何效果；如果它靠近窗口边缘，列表框仅滚动刚好足以将其带入该边缘视野的距离，否则列表框会滚动以使该项居中。

activate(index)

将活动项设置为由 index 给定的项。 如果 index 超出项的范围，则激活最接近的项。 当控件具有输入焦点时，活动项将按 activestyle 选项指定的方式绘制，并且其索引可通过 'active' 索引来检索。

curselection()

返回一个包含当前选中的所有项的数值索引的元组，如果没有选中任何项则返回一个空元组。

selection_anchor(index)

将选择锚点设置为由 index 给定的项。 如果 index 指向不存在的项，则使用最接近的项。 选择锚点是用鼠标拖出选区时固定的一端选区端点，之后可以通过 'anchor' 索引来引用。 select_anchor() 是 selection_anchor() 的别名。

selection_clear(first, last=None)

取消选择从 first 到 last （包含两者）范围内所有已选中的项。 此范围之外各项的选中状态不会改变。 select_clear() 是 selection_clear() 的别名。

备注

这会遮蔽继承的 Misc.selection_clear()，该方法用于清除 X selection；该方法在 Listbox 上不可用。

selection_includes(index)

如果由 index 指定的项当前已被选中则返回 True，否则返回 False。 select_includes() 是 selection_includes() 的别名。

selection_set(first, last=None)

选择从 first 到 last （包含两者）范围内的所有项，不影响该范围之外各项的选中状态。 select_set() 是 selection_set() 的别名。

itemcget(index, option)

返回由 index 指定的项的配置选项 option 的当前值。

itemconfigure(index, cnf=None, **kw)

查询或修改由 index 指定的项的配置选项。 这与 configure() 类似，不同之处在于它应用于单个项而不是整个列表框。 在不带选项时，它会返回一个描述该项当前选项的字典；否则会设置给定的选项。 支持的项选项有 background, foreground, selectbackground 和 selectforeground。 itemconfig() 是 itemconfigure() 的别名。

scan_mark(x, y)

记录 x, y 以及当前视图，供后续调用 scan_dragto() 时使用。 这通常绑定到控件内的鼠标按键按下事件。

scan_dragto(x, y)

将列表框滚动 x, y 与上次调用 scan_mark() 所传入坐标之差的 10 倍。 这通常绑定到控件中的鼠标移动事件，产生在窗口中高速拖动列表的效果。

class tkinter.Menu(master=None, cnf={}, **kw)

Menu 控件显示一列菜单项，每个菜单项可以是一个命令、一个复选按钮、一个单选按钮、一个级联项（会弹出关联的子菜单）或一条分隔线。 菜单可以用作顶层窗口的菜单栏、由级联项或菜单按钮弹出的下拉菜单，以及弹出菜单。 继承自 Widget。

许多菜单项方法都接受一个用于选择所要操作菜单项的 index 参数。 正如 Tk menu 手册页中所述， index 可以是数字索引（从顶部的 0 开始计数）、 'active' （当前处于活动状态的项）、 'end' 或 'last' （最底部的项）、 'none' （完全没有项，在 Tcl 中写作 {} ）、 @y （覆盖菜单窗口中像素 y 坐标 y 的项），或者是从上到下与各菜单项标签相匹配的模式。

add(itemType, cnf={}, **kw)

向菜单底部添加一个新菜单项。 itemType 为 'command', 'cascade', 'checkbutton', 'radiobutton' 或 'separator' 之一，用于确定新菜单项的类型；其余选项用于对其进行配置。 便捷方法 add_command(), add_cascade(), add_checkbutton(), add_radiobutton() 和 add_separator() 会使用对应的 itemType 调用该方法。

菜单项由以下选项进行配置，但并非每个选项都适用于所有菜单项类型（分隔线不接受其中任何选项）：

label

要在菜单项中显示的文本。

command

当菜单项被调用时所调用的函数（命令、复选按钮和单选按钮菜单项）。

accelerator

显示在菜单项右侧的字符串，用于提示快捷键；它本身并不会创建按键绑定。

underline

标签中要加下划线以用于键盘导航的字符索引。

state

'normal', 'active' 或 'disabled' 之一。

image

用于替代或与文本标签一起显示的图像。

compound

图像相对于文本的显示位置： 'none' （默认值）, 'text', 'image', 'top', 'bottom', 'left' 或 'right'。

bitmap

用于替代文本标签显示的位图。

font

用于文本的字体。

background, foreground

该菜单项在正常状态下的背景和前景颜色（在 macOS 上被忽略）。

activebackground, activeforeground

当菜单项处于活动状态时所使用的背景和前景颜色（在 macOS 上被忽略）。

columnbreak

如果为真，该菜单项将开启一个新列，而不是放置在前一个菜单项的下方。

hidemargin

如果为真，将省略菜单项周围的标准边距，这在将菜单用作调色板时非常有用。

menu

由级联项弹出的子菜单；它必须是此菜单的子控件。

variable

与复选按钮或单选按钮菜单项关联的变量。

onvalue, offvalue

当复选按钮菜单项被选中或清除时存储在 variable 中的值。

value

当单选按钮菜单项被选中时存储在 variable 中的值。

indicatoron

是否显示复选按钮或单选按钮菜单项的指示器。

selectcolor

复选按钮或单选按钮菜单项在被选中时其指示器的颜色。

selectimage

当复选按钮或单选按钮菜单项被选中且同时指定了 image 时所显示的图像。

add_cascade(cnf={}, **kw)

向菜单底部添加一个新的级联菜单项。 级联菜单项具有一个由其 menu 选项指定的关联子菜单，该子菜单必须是此菜单的子控件；弹出该菜单项会在其旁边弹出子菜单。

add_checkbutton(cnf={}, **kw)

向菜单底部添加一个新的复选按钮菜单项。 当被调用时，复选按钮菜单项会在其 onvalue 和 offvalue 之间切换，将结果存储在其关联的 variable 中，并显示一个指示器表明其是否被选中。

add_command(cnf={}, **kw)

向菜单底部添加一个新的命令菜单项。 命令菜单项的行为与按钮非常相似：当它被调用时，由其 command 选项指定的回调将被调用。

add_radiobutton(cnf={}, **kw)

向菜单底部添加一个新的单选按钮菜单项。 共享同一个 variable 的单选按钮菜单项组成一个组，其中一次只能选中一个；选择某个菜单项会将其 value 存储到该变量中。

add_separator(cnf={}, **kw)

向菜单底部添加一条分隔线。 分隔线显示为一条水平分割线，不能被激活或调用。

insert(index, itemType, cnf={}, **kw)

与 add() 相同，不同之处在于新菜单项被插入到由 index 指定的菜单项紧前方，而不是附加到菜单末尾。 itemType 为 'command', 'cascade', 'checkbutton', 'radiobutton' 或 'separator' 之一。 便捷方法 insert_command(), insert_cascade(), insert_checkbutton(), insert_radiobutton() 和 insert_separator() 会使用对应的 itemType 调用该方法。

insert_cascade(index, cnf={}, **kw)

在 index 给出的条目之前插入一个新的级联条目（参见 add_cascade() ）。

insert_checkbutton(index, cnf={}, **kw)

在 index 给出的条目之前插入一个新的复选按钮条目（参见 add_checkbutton() ）。

insert_command(index, cnf={}, **kw)

在 index 给出的条目之前插入一个新的命令条目（参见 add_command() ）。

insert_radiobutton(index, cnf={}, **kw)

在 index 给出的条目之前插入一个新的单选按钮条目（参见 add_radiobutton() ）。

insert_separator(index, cnf={}, **kw)

在 index 给出的条目之前插入一条分隔线（参见 add_separator() ）。

delete(index1, index2=None)

删除 index1 和 index2 之间（包含两者）的所有菜单条目。 如果省略 index2 ，则默认为 index1 ，从而仅删除单个条目。 尝试删除撕下条目的操作会被忽略；请改为通过更改 tearoff 选项将其移除。

entrycget(index, option)

返回 index 给出的条目的配置选项 option 的当前值。

entryconfigure(index, cnf=None, **kw)

查询或修改 index 给出的条目的配置选项。 这与 configure() 类似，不同之处在于它应用于单个条目而不是整个菜单。 在不带选项时，它返回一个描述该条目当前选项的字典；否则它设置给定的选项。 支持的选项是该条目类型对应的 add() 所接受的选项。 entryconfig() 是 entryconfigure() 的别名。

index(index)

返回对应于 index 的数字索引，如果 index 未选择任何条目则返回 None 。

type(index)

返回 index 给出的条目的类型： 'command' 、 'cascade' 、 'checkbutton' 、 'radiobutton' 、 'separator' 或 'tearoff' （针对撕下条目）之一。

activate(index)

将 index 给出的条目设为活动条目，以其活动颜色重新显示它，并取消激活任何先前处于活动状态的条目。 如果 index 未选择任何条目，或者所选条目处于禁用状态，则菜单最终将没有活动条目。

invoke(index)

调用 index 给出的条目的动作，就像它被点击了一样。 如果该条目已被禁用，则没有任何效果。 如果该条目有关联的 command ，则返回该命令的结果；否则结果为空字符串。

post(x, y)

在根窗口坐标 x 和 y 处的屏幕上显示菜单，必要时对其进行调整以使整个菜单可见。 如果指定了 postcommand 选项，则在弹出菜单之前对该选项求值。

tk_popup(x, y, entry='')

在根窗口坐标 x 和 y 处将菜单作为弹出窗口弹出。 如果给出了 entry ，则对菜单进行定位以使该条目显示在鼠标指针下方。

unpost()

取消映射菜单以使其不再显示，同时取消弹出任何已弹出的下级级联子菜单。 这在 Windows 和 macOS 上没有效果，这两个系统会自行管理菜单的取消弹出。

xposition(index)

返回 index 给出的条目在菜单窗口中最左侧像素的 x 坐标。

Added in version 3.3.

yposition(index)

返回 index 给出的条目在菜单窗口中最顶部像素的 y 坐标。

class tkinter.Menubutton(master=None, cnf={}, **kw)

一个 Menubutton 微件用于显示文本字符串、位图或图像，并在用户按下它时弹出由其 menu 选项给出的关联 Menu 。 与 Label 类似，它可以显示 text 、 textvariable 或 image ，并且 direction 选项控制菜单相对于按钮出现的位置。 继承自 Widget 。 完整选项列表请参阅 Tk menubutton 手册页。

class tkinter.Message(master=None, cnf={}, **kw)

一个 Message 微件用于显示非交互式的文本字符串，该字符串由 text 选项给出或通过 textvariable 链接到变量。 与 Label 不同，它将字符串拆分为多行以产生给定的宽高比，在单词边界处选择换行，并且可以将文本左对齐、居中或右对齐。 继承自 Widget 。 完整选项列表请参阅 Tk message 手册页。

class tkinter.OptionMenu(master, variable, value, *values, **kwargs)

A helper subclass of Menubutton that displays a pop-up menu of mutually exclusive choices. variable is a Variable kept in sync with the selection, value is the initial choice, and values are the remaining menu entries. The keyword argument command may be given a callback that is invoked with the selected value, and the keyword argument name sets the Tk widget name.

destroy()

销毁微件，同时清理关联的弹出菜单。

在 3.14 版本发生变更: Added support for the name keyword argument.

class tkinter.PanedWindow(master=None, cnf={}, **kw)

一个 PanedWindow 是一个几何管理器微件，它将任意数量的子 panes （窗格）排列成一行（当 orient 为 'horizontal' 时）或一列（当 orient 为 'vertical' 时）。 每个窗格包含一个微件，并且每对相邻的窗格之间由一个可移动的 sash （分割条）隔开，用户可以使用鼠标拖动该分割条以调整其两侧微件的大小。 继承自 Widget 。

orient 选项选择布局方向， sashwidth 设置每个分割条的宽度，而 sashrelief 设置其浮雕样式。 当 showhandle 为真时，每个分割条上都会绘制一个小控制柄，用户可以抓住它来拖动分割条。 完整选项列表请参阅 Tk panedwindow 手册页。

add(child, **kw)

将 child 作为新窗格添加到 panedwindow 中，放置在任何现有窗格之后。 关键字参数为 child 指定每个窗格的管理选项；它们可以是 paneconfigure() 接受的任何选项。

remove(child)

从 panedwindow 中移除包含 child 的窗格。 child 的所有几何管理选项都将被遗忘。 forget() 是 remove() 的别名。 这会屏蔽继承的几何管理器 forget() ；请使用 pack_forget() 、 grid_forget() 或 place_forget() 从其管理器中移除微件本身。

panes()

按顺序返回由 panedwindow 管理的微件元组，每个窗格对应一个微件。

panecget(child, option)

返回包含 child 的窗格的管理选项 option 的当前值。 option 可以是 paneconfigure() 允许的任何值。

paneconfigure(tagOrId, cnf=None, **kw)

查询或修改包含微件 tagOrId 的窗格的管理选项。 在不带选项时，它返回一个描述该窗格所有可用选项的字典；当给定单个选项名称作为字符串时，它返回该选项的描述；否则它设置给定的选项。 支持的选项包括 after 和 before （在另一个受管理的窗口之后或之前插入窗格）、 height 和 width （窗口的外部尺寸，包括任何边框）、 minsize （窗格维度上的最小尺寸）、 padx 和 pady （在窗口两侧留出的额外空间）、 sticky （使用字符 n 、 s 、 e 和 w 构成的字符串在超大窗格中定位或拉伸窗口）、 hide （隐藏窗格，同时将其保留在窗格列表中）以及 stretch （如何为窗格分配额外空间： 'always' 、 'first' 、 'last' 、 'middle' 或 'never' 之一）。 paneconfig() 是 paneconfigure() 的别名。

identify(x, y)

识别位于以窗口坐标表示的由 x 和 y 给出的点下方的 panedwindow 组件。 如果该点位于分割条或分割条控制柄上方，则结果是一个包含分割条或控制柄索引以及指示它是位于分割条还是控制柄上方的单词的二元元组，例如 (0, 'sash') 或 (2, 'handle') 。 如果该点位于 panedwindow 的任何其他部分上方，则结果为空字符串。

sash(*args)

查询或更改 panedwindow 中分割条的位置。 这是对 Tk sash 子命令的浅层包装；通常应该改用便捷方法 sash_coord() 、 sash_mark() 和 sash_place() 。

sash_coord(index)

返回 index 给出的分割条的当前 x 和 y 坐标对， index 必须是介于 0 和比 panedwindow 中窗格数量少 1 之间的整数。 返回的坐标是包含分割条的区域左上角的坐标。

sash_mark(index)

记录 index 给出的分割条的当前鼠标位置，以便与后续拖动分割条的操作一起用于移动分割条。

sash_place(index, x, y)

将 index 给出的分割条放置在坐标 x 和 y 处。

proxy(*args)

查询或更改分割条代理的位置，该代理是在使用非不透明调整大小时拖动分割条所显示的“幽灵”分割条。 这是对 Tk proxy 子命令的浅层包装；通常应该改用便捷方法 proxy_coord() 、 proxy_forget() 和 proxy_place() 。

proxy_coord()

返回包含最新代理位置的 x 和 y 坐标的元组。

proxy_forget()

从显示中移除代理。

proxy_place(x, y)

将代理放置在坐标 x 和 y 处。

class tkinter.Radiobutton(master=None, cnf={}, **kw)

一个 Radiobutton 微件用于显示文本字符串、位图或图像以及菱形或圆形指示器，并从多个选项中选择一个。 它具有普通按钮的所有行为，此外还可以被选中：通常多个单选按钮共享一个 variable ，选中一个会将该变量设置为该单选按钮的 value ；每个单选按钮还会监视该变量，并在该变量更改时自动选中或取消选中自身。 继承自 Widget 。 除了标准的微件选项之外，单选按钮还接受 Tk radiobutton 手册页中记录的选项，例如 variable 、 value 和 command 。

invoke()

执行就像用户用鼠标按下单选按钮时所发生的操作：选中该按钮并调用关联的命令（如果有）。 返回该命令的结果，或者如果没有与单选按钮关联的命令则返回空字符串。 如果单选按钮的状态为 disabled ，则此操作将被忽略。

select()

选中单选按钮并将关联的变量设置为对应于此微件的值。

deselect()

取消选中单选按钮并将关联的变量设置为空字符串。 如果此单选按钮当前未被选中，则这不会产生任何效果。

flash()

通过多次重新显示单选按钮使其闪烁，在活动颜色和普通颜色之间交替。 在闪烁结束时，单选按钮保持与调用该方法时相同的普通或活动状态。 如果单选按钮的状态为 disabled ，则此操作将被忽略。

class tkinter.Scale(master=None, cnf={}, **kw)

一个 Scale 微件允许用户通过沿滑槽移动滑块来选择数值。 它可以垂直或水平定向，并且可以选择显示标签和当前值。 继承自 Widget 。

除了标准的微件选项之外，scale 还接受 Tk scale 手册页中记录的选项，例如 from_ 、 to 、 resolution 、 orient 、 tickinterval 、 variable 和 command 。 与 tkinter 中其他地方一样，Tk 选项名称开头的 - 被省略； from 拼写为 from_ 是因为 from 是 Python 关键字。

对于非整数的 resolution，请参阅 数字值与语言区域。

get()

返回 scale 的当前值。 如果 scale 的 resolution 产生整数，则结果为整数，否则为浮点数。

set(value)

将 scale 设置为 value ，并相应地移动滑块。 如果 scale 被禁用，则这不会产生任何效果。

coords(value=None)

返回一个元组 (x, y) ，给出滑槽中心线上对应于 value 的点相对于微件的像素坐标。 如果省略 value ，则使用 scale 的当前值。

identify(x, y)

返回一个描述在像素坐标 x 、 y 处的 scale 部分的字符串： 'slider' 、 'trough1' （滑块上方或左侧的滑槽部分）、 'trough2' （滑块下方或右侧的滑槽部分），或者如果该点不在这些元素中的任何一个之上，则返回空字符串。

class tkinter.Scrollbar(master=None, cnf={}, **kw)

一个 Scrollbar 微件用于显示一个滑块和两个箭头，允许用户滚动关联的微件，例如 Listbox 、 Text 、 Canvas 或 Entry 。 通过将该微件的 xscrollcommand 或 yscrollcommand 选项设置为滚动条的 set() 方法，并将滚动条的 command 选项设置为被滚动微件的 xview() 或 yview() 方法，将其连接到被滚动的微件。 继承自 Widget 。

get()

将当前滚动条设置作为包含两个介于 0 和 1 之间的分数的元组 (first, last) 返回，该元组描述了当前可见文档的部分，即最后传递给 set() 的内容。

set(first, last)

设置滚动条。 first 和 last 是介于 0 和 1 之间的分数，给出关联文档可见部分的起始和结束位置。 该方法通常被注册为被滚动微件的 xscrollcommand 或 yscrollcommand 并由该微件调用。

activate(index=None)

将元素 index （ 'arrow1' 、 'slider' 或 'arrow2' 之一）标记为活动，并根据 activebackground 和 activerelief 选项显示它。 如果省略 index ，则返回当前活动元素的名称，或者如果没有元素处于活动状态则返回 None 。

在 3.5 版本发生变更: index 参数现在是可选的。

delta(deltax, deltay)

返回一个浮点数，表示滚动条设置的小数变化量，对应于将滑块水平移动 deltax 像素（对于水平滚动条）或垂直移动 deltay 像素（对于垂直滚动条）。

fraction(x, y)

返回一个介于 0 和 1 之间的浮点数，指示像素坐标 x 、 y 处的点位于滑槽中的位置：0 对应于滑槽的顶部或左侧，1 对应于滑槽的底部或右侧。

identify(x, y)

返回像素坐标 x 、 y 下的元素名称（例如 'arrow1' ），或者如果该点不位于滚动条的任何元素中，则返回空字符串。

class tkinter.Spinbox(master=None, cnf={}, **kw)

A Spinbox widget is an Entry-like widget with a pair of up/down arrow buttons that let the user step through a range of values in addition to editing the value directly. The set of values may be a numeric range given by the from_, to and increment options, or an explicit list of strings given by the values option (which takes precedence over the range). Each time an arrow is invoked the command callback, if any, is called; the boolean wrap option controls whether stepping past either end of the range wraps around to the other end; the format option specifies how numeric values are formatted; and the validate option enables validation of the entered text. Inherits from Widget and XView.

对于非整数的 increment，请参阅 数字值与语言区域。

许多方法接受一个 index 参数，用于标识微调框字符串中的字符。 如 Tk spinbox 手册页中所述， index 可以是数字索引（从 0 开始计数）、 'anchor' （选择锚点）、 'end' （紧随最后一个字符之后）、 'insert' （紧随插入光标之后的字符）、 'sel.first' 或 'sel.last' （选择的末端），或者是 @x （覆盖窗口中像素 x 坐标 x 的字符）。

get()

返回微调框的字符串。

insert(index, s)

在紧邻 index 给出的字符之前插入字符串 s 的字符。

delete(first, last=None)

删除微调框的一个或多个字符。 first 是要删除的第一个字符的索引，而 last 是紧接在要删除的最后一个字符之后的字符的索引。 如果省略 last ，则删除 first 处的单个字符。

icursor(index)

安排将插入光标显示在由 index 给定的字符紧前位置。

index(index)

以字符串形式返回对应于 index 的数字索引。

bbox(index)

返回一个由四个整数组成的元组 (x, y, width, height) ，描述由 index 给出的字符的边界框。 x 和 y 是字符左上角相对于微件的像素坐标，而 width 和 height 是其以像素为单位的大小。 边界框可能指向窗口可见区域之外的区域。

这会遮蔽继承的 Misc.bbox()；对于网格边界框，请使用 grid_bbox()。

identify(x, y)

返回像素坐标 x 、 y 处的窗口元素名称： 'buttondown' 、 'buttonup' 、 'entry' 或 'none' 之一。

invoke(element)

调用由 element 给出的微调按钮（ 'buttonup' 或 'buttondown' ），触发与其关联的操作。

scan(*args)

对 Tk scan 微件子命令的浅层包装，用于实现视图的快速拖动： scan('mark', x) 记录 x 和当前视图，而 scan('dragto', x) 相对于该标记调整视图。 scan_mark() 和 scan_dragto() 方法包装了这两种形式。

scan_mark(x)

在微调框窗口中记录 x 和当前视图，以便与后续的 scan_dragto() 调用一起使用。 这通常与微件中的鼠标按键按下相关联。

scan_dragto(x)

将视图调整为 x 与传递给上一次 scan_mark() 调用的 x 之差的 10 倍。 这通常与鼠标移动事件相关联，从而产生通过窗口高速拖动微调框的效果。

selection(*args)

对 Tk selection 微件子命令的浅层包装，用于调整微调框内的选择。 根据第一个参数，它有几种形式，例如 selection('adjust', index) 、 selection('clear') 、 selection('element', ?elem?) 、 selection('from', index) 、 selection('present') 、 selection('range', start, end) 以及 selection('to', index) 。 selection_adjust() 、 selection_clear() 、 selection_element() 、 selection_from() 、 selection_present() 、 selection_range() 和 selection_to() 方法包装了这些形式。

selection_adjust(index)

定位最接近 index 给出的字符的选择末端，并将该选择末端调整为位于 index 处（包括但不超出 index ）。 另一端成为将来 selection_to() 调用的锚点。 如果选择当前不在微调框中，则会创建一个新的选择，以包含 index 与最近的锚点之间的字符（包含两者）。

selection_clear()

如果选择当前在此微件中，则清除选择。 如果选择不在此微件中，则该方法不起作用。

备注

这会屏蔽继承的 Misc.selection_clear() ，该方法用于清除 X 选择；该方法在 Spinbox 上不可用。

selection_element(element=None)

设置或获取当前选定的元素。 如果给出了 element （ 'buttonup' 、 'buttondown' 或 'none' 之一），则选中该微调按钮并显示为凹陷状态；否则返回当前选定元素的名称。

selection_from(index)

将选择锚点设置在紧邻 index 给出的字符之前，而不改变选择本身。

Added in version 3.8.

selection_present()

如果微调框中有选中的字符则返回 True ，否则返回 False 。

Added in version 3.8.

selection_range(start, end)

设置选择以包含从 start 索引的字符开始到紧邻 end 之前的字符结束的字符。 如果 end 指向与 start 相同的字符或更早的字符，则清除选择。

Added in version 3.8.

selection_to(index)

设置 index 与锚点之间的选择。 如果 index 在锚点之前，则选择从 index 开始直到但不包括锚点；如果它在锚点之后，则选择从锚点开始直到但不包括 index ；如果它相同，则不执行任何操作。 锚点是由最近的 selection_from() 或 selection_adjust() 调用设置的锚点。 如果选择不在此微件中，则使用最近的锚点创建新的选择。

Added in version 3.8.

class tkinter.Text(master=None, cnf={}, **kw)

一个 Text 微件用于显示和编辑多行文本。 文本的某些部分可以使用 tags （标签）设置样式，特定位置可以使用浮动的 marks （标记）进行注释，并且可以在文本中嵌入任意图像和其他微件。 该微件还提供了无限制的撤销/重做机制，并支持共享相同底层数据的对等微件。 继承自 Widget 、 XView 和 YView ，因此可以使用 xview() 和 yview() 水平和垂直滚动视图。 完整选项列表请参阅 Tk text 手册页。

大多数方法接受一个或多个用于标识文本内位置的 index 参数。 如 Tk text 手册页中所述，索引是一个由基准（base）组成的字符串，后面可选择跟一个或多个修饰符（modifier）。 基准可以是 'line.char' （第 line 行，第 char 个字符，其中行从 1 开始计数，行内字符从 0 开始计数； 'line.end' 指的是结束该行的换行符）、 'end' （紧随最后一个换行符之后的位置）、标记的名称、 'tag.first' 或 'tag.last' （带有 tag 标签的第一个字符，或紧随最后一个此类字符之后的位置）、嵌入图像或窗口的名称，或者是 @x,y （覆盖微件中像素坐标 x 、 y 的字符）。 诸如 '+5 chars' 、 '-3 lines' 、 'linestart' 、 'lineend' 、 'wordstart' 或 'wordend' 的修饰符相对于其基准调整索引；多个修饰符可以组合并从左到右应用，例如 'insert wordstart - 1 c' 。

insert(index, chars, *args)

在紧邻 index 处字符之前插入字符串 chars （如果 index 为 'end' ，则紧邻最后的换行符之前）。 默认情况下，新文本继承插入点两侧存在的任何标签。 如果给出了 args ，它由交替出现的 tagList 、 chars 值组成：前面的 chars 准确接收所列出的标签（标签列表可以是单个标签名称或名称序列），覆盖周围的标签。

delete(index1, index2=None)

删除从 index1 开始到但不包括 index2 的字符范围。 如果省略 index2 ，则删除 index1 处的单个字符。 微件始终将换行符保留为其最后一个字符，因此会将其删除的删除操作会相应地进行调整。

replace(index1, index2, chars, *args)

用 chars 替换从 index1 开始到但不包括 index2 的字符范围。 这等同于在 index1 处执行 delete() 后跟一个 insert() ； args 的解释与 insert() 相同。

Added in version 3.3.

get(index1, index2=None)

以字符串形式返回从 index1 开始到但不包括 index2 的文本。 如果省略 index2 ，则返回 index1 处的单个字符。 嵌入的图像和窗口会从结果中省略。

index(index)

以规范的 'line.char' 形式返回对应于 index 的位置。

compare(index1, op, index2)

使用关系运算符 op 比较 index1 和 index2 的位置， op 必须是 '<' 、 '<=' 、 '==' 、 '>=' 、 '>' 或 '!=' 之一，并返回布尔结果。

count(index1, index2, *options, return_ints=False)

统计 index1 和 index2 之间所请求种类的条目数量；如果 index1 在 index2 之后，则计数为负。 options 中的每一项指定要统计的一种条目类型： 'chars' 、 'displaychars' 、 'displayindices' 、 'displaylines' 、 'indices' 、 'lines' 、 'xpixels' 或 'ypixels' （默认值，在未给出选项时使用，为 'indices' ）。 伪选项 'update' 强制在对后续选项求值之前重新计算任何过时的布局信息。 当 return_ints 为真且给出了单个计数选项时，返回一个普通整数；否则返回一个每个计数选项对应一个整数的元组（如果结果为空则返回 None ）。

Added in version 3.3.

在 3.13 版本发生变更: 添加了 return_ints 参数。

see(index)

调整视图以使 index 给出的字符可见。 如果它已经可见，该方法不起作用；如果它距离视野不远，则微件仅滚动刚好足以将其带到最近的边缘，否则它会滚动以使 index 居中显示在窗口中。

bbox(index)

返回一个元组 (x, y, width, height) ，以像素为单位给出 index 处字符可见部分的边界框，或者如果该字符在屏幕上不可见，则返回 None 。

这会遮蔽继承的 Misc.bbox()；对于网格边界框，请使用 grid_bbox()。

dlineinfo(index)

返回一个元组 (x, y, width, height, baseline) ，描述包含 index 的显示行：前四个值以像素为单位给出该行的边界框，而 baseline 给出从区域顶部向下测量的基线偏移量。 如果该显示行在屏幕上不可见，则返回 None 。

mark_set(markName, index)

将名为 markName 的标记设置在紧邻 index 处字符之前的位置，如果该标记尚不存在则创建它。 以这种方式创建的标记默认具有右 gravity （向右吸附）。

mark_unset(*markNames)

移除 markNames 中命名的每个标记。 特殊的 insert 和 current 标记不能被移除。

mark_names()

返回微件中当前设置的所有标记的名称元组。

mark_gravity(markName, direction=None)

如果省略 direction ，则返回标记 markName 的 gravity （吸附方向），为 'left' 或 'right' 。 否则将其 gravity 设置为 direction 。 gravity 决定了在标记位置插入的文本出现在标记的哪一侧：具有右 gravity （默认）的标记保持在此类文本的右侧。

mark_next(index)

返回位于 index 处或其之后的第一个标记的名称，如果没有则返回 None 。 当 index 是标记的名称时，搜索将从紧跟该标记之后开始。

mark_previous(index)

返回位于 index 处或其之前的最后一个标记的名称，如果没有则返回 None 。 当 index 是标记的名称时，搜索将从紧邻该标记之前开始。

tag_add(tagName, index1, *args)

将标签 tagName 添加到从 index1 开始到但不包括 args 中的下一个索引的字符范围。 args 中可以跟有更多的索引对来标记额外的范围；末尾的单个索引仅标记该索引处的字符。

tag_remove(tagName, index1, index2=None)

从 index1 开始到但不包括 index2 的字符中移除标签 tagName （如果省略 index2 ，则从 index1 处的单个字符中移除）。 即使没有任何字符带有该标签，标签本身也继续存在。

tag_delete(*tagNames)

删除 tagNames 中指定的各个标签，将它们从所有字符中移除，并丢弃它们的选项和绑定。

tag_configure(tagName, cnf=None, **kw)

查询或修改标签 tagName 的配置选项。 这与 configure() 类似，不同之处在于它应用于标签而非整个控件：在没有选项时，它返回一个描述当前选项的字典，否则它设置给定的选项。 以这种方式定义标签还会使其优先级高于任何现有标签。

支持的标签选项，均用于控制已标记文本的外观，具体如下：

font

用于文本的字体。

foreground

用于文本的颜色。

background

用于文本后方区域的颜色。

fgstipple, bgstipple

用于点画前景（文本）和背景的位图；仅在 X11 上得到良好支持。

borderwidth

根据 relief 在文本周围绘制的边框宽度（默认为 0 ）。

relief

文本边框的 3D 外观： 'flat' （默认）、 'raised' 、 'sunken' 、 'ridge' 、 'groove' 或 'solid' 。

offset

用于上标和下标，文本高出基线（或者若为负数，则低于基线）的距离。

underline

Whether to underline the text (a boolean).

underlinefg

下划线的颜色；默认为文本颜色。

overstrike

是否在文本中间穿过一条删除线。

overstrikefg

删除线的颜色；默认为文本颜色。

elide

文本是否被省略（隐藏）。

justify

如何对齐显示行的第一个字符： 'left' （默认）、 'right' 或 'center' 。

wrap

如何折行过长的行： 'char' 、 'word' 或 'none' 。

lmargin1, lmargin2

逻辑行的第一个显示行以及其余显示行的缩进量（以像素为单位）。

lmargincolor

左边距区域的颜色。

rmargin

右侧边距（以像素为单位）。

rmargincolor

右边距区域的颜色。

spacing1, spacing2, spacing3

在逻辑行的第一个显示行上方、各个显示行之间以及其最后一个显示行下方的额外间距（以像素为单位）。

tabs

制表位集合，形式与控件的 tabs 选项相同。

tabstyle

制表位的解释方式： 'tabular' 或 'wordprocessor' 。

selectbackground, selectforeground

文本被选中时使用的背景色和前景色。

备注

Tk 8.6 添加了 lmargincolor 、 overstrikefg 、 rmargincolor 、 selectbackground 、 selectforeground 和 underlinefg 选项。

tag_config() 是 tag_configure() 的别名。

tag_cget(tagName, option)

返回标签 tagName 的配置选项 option 的当前值。

tag_names(index=None)

如果省略 index ，则返回控件中定义的所有标签名称组成的元组；否则仅返回应用于 index 处字符的标签名称。 名称按优先级从低到高排序。

tag_ranges(tagName)

返回一个由索引组成的元组，用于描述带有标签 tagName 的所有文本范围。 结果交替包含起始和结束索引，因此元素 2*i 和 2*i+1 界定第 i 个范围。

tag_nextrange(tagName, index1, index2=None)

从 index1 开始向前搜索（如果给定 index2 则至多到此）带有标签 tagName 的第一个字符范围，并返回包含其起始和结束索引的二元组，如果不存在此类范围则返回一个空元组。

tag_prevrange(tagName, index1, index2=None)

从 index1 开始向后搜索（如果给定 index2 则至多向下到此）带有标签 tagName 的最近前置字符范围，并返回包含其起始和结束索引的二元组，如果不存在此类范围则返回一个空元组。

tag_raise(tagName, aboveThis=None)

提高标签 tagName 的优先级，使其刚好高于 aboveThis 的优先级，如果省略 aboveThis 则提升至所有标签中的最高优先级。 当重叠标签的显示选项冲突时，优先级较高的标签胜出。

tag_lower(tagName, belowThis=None)

降低标签 tagName 的优先级，使其刚好低于 belowThis 的优先级，如果省略 belowThis 则降至所有标签中的最低优先级。

tag_bind(tagName, sequence, func, add=None)

将带有标签 tagName 的字符上的事件 sequence 绑定到回调函数 func ，以便在该类字符上发生该事件时调用 func 。 如果 add 为真值，则该绑定将与 sequence 的任何现有绑定一同添加，否则将替换它们。 其工作方式类似于 bind() 并返回新绑定的标识符。

tag_unbind(tagName, sequence, funcid=None)

移除带有标签 tagName 的字符上的事件 sequence 的绑定。 如果给定了 funcid ，则仅移除该绑定（由 tag_bind() 返回）并注销其回调函数。

在 3.13 版本发生变更: 如果给出了 funcid，则仅解除该回调的绑定。

image_create(index, cnf={}, **kw)

在 index 处嵌入图像并返回分配给该图像实例的名称，该名称随后可用作索引或传递给其他 image_* 方法。 在 cnf 和 kw 中给出的选项包括 image （要显示的 Tk 图像）、 name （实例的基本名称）、 align 、 padx 和 pady 。

image_cget(index, option)

返回位于 index 处的嵌入图像的配置选项 option 的当前值。

image_configure(index, cnf=None, **kw)

查询或修改位于 index 处的嵌入图像的配置选项，类似于 configure() 但应用于该图像。

image_names()

返回控件中嵌入的所有图像名称组成的元组。

备注

这将遮盖继承的 Misc.image_names() （该方法返回 Tcl 解释器中所有图像的名称）；该方法在 Text 上不可用。

window_create(index, cnf={}, **kw)

Embed a window (any widget) at index. The options, given in cnf and kw, include window (the widget to embed), create (a callback that creates the widget on demand), align, the boolean stretch (whether the widget is stretched vertically to the height of the line), padx and pady. The embedded widget must be a descendant of the text widget's parent.

window_cget(index, option)

返回位于 index 处的嵌入窗口的配置选项 option 的当前值。

window_configure(index, cnf=None, **kw)

查询或修改位于 index 处的嵌入窗口的配置选项，类似于 configure() 但应用于该窗口。

window_config() 是 window_configure() 的别名。

window_names()

返回控件中嵌入的所有窗口名称组成的元组。

edit(*args)

Tk edit 控件命令的底层包装器，用于控制撤销/重做机制以及已修改标志； args 为 edit 子命令及其参数。 下面的 edit_*() 方法是围绕它的轻量包装器，通常使用起来更方便。

edit_modified(arg=None)

如果省略 arg ，则返回已修改标志的当前状态（真或假）；每当插入或删除文本时，该标志都会自动设置。 否则将该标志设置为布尔值 arg 。

edit_undo()

撤销最近的编辑操作，即自上一个分隔符以来撤销栈上记录的所有插入和删除操作，并将其移动到重做栈。 如果撤销栈为空则引发 TclError 。 除非 undo 选项为真值，否则不起作用。 自 Tk 9.0 起，返回界定已更改文本范围的索引元组。

edit_redo()

重新应用最近撤销的编辑操作（前提是此后未进行过进一步编辑），并将其移回撤销栈。 如果重做栈为空则引发 TclError 。 除非 undo 选项为真值，否则不起作用。 自 Tk 9.0 起，返回界定已更改文本范围的索引元组。

edit_reset()

清空撤销栈和重做栈。

edit_separator()

向撤销栈压入一个分隔符，用于在撤销和重做时标记编辑操作之间的边界。 除非 undo 选项为真值，否则不起作用。 当 autoseparators 选项为真值时，分隔符会自动插入。

search(pattern, index, stopindex=None, forwards=None, backwards=None, exact=None, regexp=None, nocase=None, count=None, elide=None, *, nolinestop=None, strictlimits=None)

Search for pattern starting at index and return the index of the first character of the first match, or an empty string if there is no match. Searching stops at stopindex if given; otherwise it wraps around the ends of the text until the starting position is reached again. The following boolean keyword flags control the search: forwards or backwards select the direction (forward is the default); exact (the default) or regexp select literal or regular-expression matching; nocase makes the match case-insensitive; elide causes hidden text to be searched as well; nolinestop (regexp only) lets . and [^ match newlines; and strictlimits requires the whole match to lie within index and stopindex. If count is a Variable, the number of index positions in the match is stored in it.

在 3.15 版本发生变更: Added the nolinestop and strictlimits parameters.

search_all(pattern, index, stopindex=None, *, forwards=None, backwards=None, exact=None, regexp=None, nocase=None, count=None, elide=None, nolinestop=None, overlap=None, strictlimits=None)

Like search(), but find every match in the searched range and return a tuple of the starting indices of all matches (empty if there are none). By default overlapping matches are not reported; passing a true overlap returns every match that is not wholly contained in another. If count is a Variable, it receives a list with one element per match.

Added in version 3.15.

scan_mark(x, y)

记录 x, y 以及当前视图，供后续调用 scan_dragto() 时使用。 这通常绑定到控件内的鼠标按键按下事件。

scan_dragto(x, y)

将控件滚动 x 、 y 与传递给上一次 scan_mark() 调用的坐标之差的 10 倍。 这通常绑定到鼠标移动事件，产生在窗口中高速拖动文本的效果。

debug(boolean=None)

如果省略 boolean ，则返回是否启用了 B 树数据结构的内部一致性检查。 否则启用或禁用它们。 该设置由所有文本控件共享，并可能显著降低容纳大量文本的控件的运行速度。

dump(index1, index2=None, command=None, **kw)

返回控件中从 index1 开始到但不包括 index2 的内容（如果省略 index2 则仅返回 index1 处的片段），包括文本以及关于标记 (mark)、标签 (tag)、图像和窗口的信息。 结果是一个 (key, value, index) 三元组列表，其中 key 为 'text' 、 'mark' 、 'tagon' 、 'tagoff' 、 'image' 或 'window' 之一。 默认情况下会报告所有种类；将关键字参数 all 、 text 、 mark 、 tag 、 image 或 window 中的任一个设为真值将限制仅转储所选种类。 如果给定了 command ，则会对每个三元组调用一次并以这三个值作为参数，且不返回任何内容。

peer_create(newPathName, cnf={}, **kw)

创建一个具有路径名 newPathName 的对等文本控件，该控件共享此控件的底层数据（文本、标记、标签、图像和撤销栈）。 通过任何对等控件所做的更改都会反映在所有对等控件中。 默认情况下，对等控件涵盖与此控件相同的行；可以提供包括 startline 和 endline 在内的标准文本选项来覆盖此设置。

Added in version 3.3.

peer_names()

返回该控件对等控件的路径名元组，不包括该控件本身。

Added in version 3.3.

yview_pickplace(*what)

调整视图以使 what 给出的位置可见。 这是已废弃的等效项，应当改用 see() 。

变量类

class tkinter.Variable(master=None, value=None, name=None)

Tk 变量包装器的基类。 Tk 变量是存储在 Tcl 解释器中的值，可以通过其 variable 或 textvariable 选项链接到控件（参见 关联控件变量 ），以便更改双向传播：更新变量会更新与其绑定的每个控件，而用户编辑此类控件也会更新该变量。

master 是其 Tcl 解释器拥有该变量的控件；如果省略，则使用默认根窗口。 value 是初始值；如果省略，则使用类型特定的默认值。 name 是变量在 Tcl 解释器中的名称；如果省略，则会生成形式为 'PY_VARnum' 的唯一名称。 如果 name 与现有变量匹配且省略了 value ，则保留现有值。

在大多数情况下，您应该使用以下类型化子类之一 —— StringVar 、 IntVar 、 DoubleVar 或 BooleanVar —— 而不是直接使用 Variable 。

备注

当一个 Variable 被垃圾回收时，其 Tcl 变量将被取消设置。 只要有控件链接到它，就请保留对它的引用，例如将其存储为属性而不是局部变量。 否则 Tk 会重新创建 Tcl 变量以保持控件正常工作，但它再也不会被取消设置，每个丢弃的包装器都会泄漏一个 Tcl 变量。

在 3.10 版本发生变更: 两个变量现在仅在具有相同名称、属于相同类且属于同一个 Tcl 解释器时，比较结果才相等（ == ）。

get()

返回变量的当前值。 对于基类，该值以字符串形式返回；类型化的子类会将其转换为相应的 Python 类型。

set(value)

将变量设置为 value 。 initialize() 是 set() 的别名。

Added in version 3.3: initialize 拼写形式。

trace_add(mode, callback)

注册在按照 mode 访问变量时调用的 callback 。 mode 是字符串 'array' 、 'read' 、 'write' 或 'unset' 之一，或者是此类字符串的列表或元组。

触发时，将使用三个参数调用 callback ：Tcl 变量的名称、索引（如果该变量不是数组的元素，则为空字符串），以及触发调用的 mode 。

返回已注册回调函数的内部名称，该名称可以传递给 trace_remove() 。

Added in version 3.6.

trace_remove(mode, cbname)

从变量中移除跟踪回调函数。 mode 必须与传递给 trace_add() 的 mode 匹配，而 cbname 是由 trace_add() 返回的回调函数名称。

Added in version 3.6.

trace_info()

返回一个描述当前在变量上设置的所有跟踪的 (modes, cbname) 对列表，其中 modes 是模式字符串的元组， cbname 是内部回调函数名称。

Added in version 3.6.

trace_variable(mode, callback)

注册在按照 mode 访问变量时调用的 callback 。 mode 是字符串 'r' 、 'w' 或 'u' 之一，分别代表读取 (read)、写入 (write) 或取消设置 (unset)。 返回已注册回调函数的内部名称。 trace() 是 trace_variable() 的别名。

自 3.6 版本弃用: 改用 trace_add() 。 此方法包装了一个在 Tcl 9.0 中已被移除的 Tcl 特性。

trace_vdelete(mode, cbname)

移除通过 trace_variable() 为 mode 注册的名为 cbname 的跟踪回调函数。

自 3.6 版本弃用: 改用 trace_remove() 。 此方法包装了一个在 Tcl 9.0 中已被移除的 Tcl 特性。

trace_vinfo()

返回使用 trace_variable() 在变量上设置的所有跟踪的 (mode, cbname) 对列表。

自 3.6 版本弃用: 改用 trace_info() 。 此方法包装了一个在 Tcl 9.0 中已被移除的 Tcl 特性。

class tkinter.StringVar(master=None, value=None, name=None)

保存字符串的 Variable 子类。 默认值为 '' 。

get()

将变量的值作为 str 返回。

class tkinter.IntVar(master=None, value=None, name=None)

保存整数的 Variable 子类。 默认值为 0 。

get()

将变量的值作为 int 返回。

class tkinter.DoubleVar(master=None, value=None, name=None)

保存浮点数的 Variable 子类。默认值为 0.0。

get()

将变量的值作为 float 返回。

备注

浮点数值在解析时总是以句点 (.) 作为小数点，但 Spinbox, Scale 和 ttk.Spinbox 会根据 LC_NUMERIC 区域设置对其进行格式化。 在使用逗号的区域设置下，它们生成的值 get() 无法读取，从而引发 TclError。 将 LC_NUMERIC 设为使用句点的区域设置（例如 'C'）以避免此问题。

class tkinter.BooleanVar(master=None, value=None, name=None)

保存布尔值的 Variable 子类。默认值为 False。

get()

将变量的值作为 bool 返回。如果该值无法被解释为布尔值，则引发 ValueError。

set(value)

将变量设为 value 并将其转换为布尔值。 initialize() 是 set() 的别名。

Added in version 3.3: initialize 拼写形式。

图像类

class tkinter.Image(imgtype, name=None, cnf={}, master=None, **kw)

Tk 图像的基类。 imgtype 是 Tk 图像类型，为 'photo' 或 'bitmap' 之一。 图像是一个具名对象，可以通过控件的 image 选项由控件显示；删除对 Image 对象的所有引用将删除底层的 Tk 图像。 通常应创建 PhotoImage 或 BitmapImage 而不是直接创建 Image。

图像的配置选项由 cnf 和 kw 给出，随后可以通过映射协议（使用 image[key]）或使用 configure() 方法进行查询和更改。

configure(**kw)

修改图像的一个或多个配置选项。 有效选项取决于图像类型；参见 PhotoImage 和 BitmapImage。 config() 是 configure() 的别名。

height()

返回图像的高度，以像素为单位。

width()

返回图像的宽度，以像素为单位。

type()

返回图像的类型，即创建它时所使用的 imgtype 的值（例如 'photo' 或 'bitmap'）。

class tkinter.PhotoImage(name=None, cnf={}, master=None, **kw)

全彩色图像（Tk photo 图像类型），在内部存储，每个像素具有不同程度的透明度。 它可以读写 GIF、PPM/PGM 以及（在 Tk 8.6 及更高版本中）PNG 文件，读取 SVG 文件（在 Tk 9.0 及更高版本中），并在控件中绘制。 继承自 Image。

配置选项包括 data （作为字符串的图像内容）、 file （从中读取内容的文件名）、 format （文件格式处理程序名称）、 width 和 height （图像大小，在逐块构建图像时使用）、 gamma 以及 palette。

blank()

清空图像；即，将整个图像设为没有数据，使其显示为透明，并透出显示该图像的任何窗口的背景。

cget(option)

返回配置选项 option 的当前值。

copy(*, from_coords=None, zoom=None, subsample=None)

返回一个包含此图像副本的新 PhotoImage。

from_coords 指定要拷贝的源图像矩形子区域。 它必须是一个由 1 到 4 个整数组成的元组或列表 (x1, y1, x2, y2)。 (x1, y1) 和 (x2, y2) 指定矩形的对角。 如果未指定 x2 和 y2，它们默认为源图像的右下角。 拷贝的像素包含矩形的左边缘和上边缘，但不包含下边缘或右边缘。 如果未给出 from_coords，则拷贝整个源图像。

如果指定了 zoom 或 subsample，图像将按照 zoom() 或 subsample() 方法中的方式进行变换。 该值必须为单个整数或一对整数。

在 3.13 版本发生变更: 增加了 from_coords, zoom 和 subsample 形参。

copy_replace(sourceImage, *, from_coords=None, to=None, shrink=False, zoom=None, subsample=None, compositingrule=None)

将一个区域从 sourceImage （必须为 PhotoImage）拷贝到此图像中，可能带有像素缩放和/或子采样。 如果未指定任何选项，则会将整个 sourceImage 拷贝到此图像中，从坐标 (0, 0) 开始。

from_coords 指定要拷贝的源图像矩形子区域，如同在 copy() 方法中一样。

to 指定目标图像中受影响的矩形子区域。 它必须是一个由 1 到 4 个整数组成的元组或列表 (x1, y1, x2, y2)。 如果未指定 x2 和 y2，它们默认为 (x1, y1) 加上源区域的大小（若指定了子采样和缩放，则为处理后的大小）。 如果指定了 x2 和 y2，则在必要时会复制源区域以平铺方式填满目标区域。

如果 shrink 为真，在必要时将减小目标图像的大小，使得被拷贝的目标区域位于图像的右下角。

如果指定了 zoom 或 subsample，图像将按照 zoom() 或 subsample() 方法中的方式进行变换。 该值必须为单个整数或一对整数。

compositingrule 指定源图像中的透明像素如何与目标图像合并。 使用 'overlay' （默认值）时，目标图像的原有内容保持可见，就好像源图像被印在一张透明胶片上并放置在目标图像上方一样。 使用 'set' 时，目标图像的原有内容将被丢弃，源图像将按原样使用。

Added in version 3.13.

data(format=None, *, from_coords=None, background=None, grayscale=False)

返回图像数据。

format 指定要使用的图像文件格式处理程序的名称。 如果未给出，数据将作为一个由字符串组成的元组（每行一个元素）返回，其中包含以空格分隔的（每个像素/列一个元素）采用 #RRGGBB 格式的颜色。

from_coords 指定要返回的图像矩形区域。 它必须是一个由 1 到 4 个整数组成的元组或列表 (x1, y1, x2, y2)。 如果仅指定了 x1 和 y1，该区域将从 (x1, y1) 延伸到图像的右下角。 如果给出了全部四个坐标，它们指定区域的对角，包含 (x1, y1) 但不包含 (x2, y2)。 如果未给出 from_coords，则返回整个图像。

如果指定了 background，数据将不包含任何透明度信息；所有透明像素的颜色都会被替换为指定的颜色。

如果 grayscale 为真，数据将不包含颜色信息；所有像素数据都会被转换为灰度。

Added in version 3.13.

get(x, y)

将坐标 (x, y) 处像素的颜色作为一个由三个介于 0 和 255 之间的整数组成的 (r, g, b) 元组返回，分别表示红、绿、蓝分量。

put(data, to=None)

将图像的像素设为 data 中给出的颜色， data 必须是字符串或像素颜色水平行的嵌套序列（例如 "{red green} {blue yellow}"）。

to 指定数据要拷贝到的图像区域的坐标。 它必须是一个由 2 或 4 个整数组成的元组或列表 (x1, y1) 或 (x1, y1, x2, y2)，给出该区域的左上角以及可选的右下角。 默认位置是 (0, 0)。

read(filename, format=None, *, from_coords=None, to=None, shrink=False)

从名为 filename 的文件中将图像数据读取到图像中。

format 指定文件中图像数据的格式。

from_coords 指定要拷贝到目标图像的图像文件数据的矩形子区域。 它必须是一个由 1 到 4 个整数组成的元组或列表 (x1, y1, x2, y2)。 如果仅指定了 x1 和 y1，该区域将从 (x1, y1) 延伸到文件中图像的右下角。 如果给出了全部四个坐标，它们指定区域的对角。 如果未给出 from_coords，则读取文件中的整个图像。

to 指定要将数据读取到的图像区域左上角的坐标。 默认值为 (0, 0)。

如果 shrink 为真，在必要时将减小图像的大小，使得读入文件数据的区域位于图像的右下角。

Added in version 3.13.

subsample(x, y='', *, from_coords=None)

返回一个基于此图像的新 PhotoImage，但仅使用 X 方向上的每第 x 个像素以及 Y 方向上的每第 y 个像素。 如果未给出 y，它默认为与 x 相同的值。

from_coords 指定要拷贝的源图像矩形子区域，如同在 copy() 方法中一样。

在 3.13 版本发生变更: 增加了 from_coords 形参。

transparency_get(x, y)

如果坐标 (x, y) 处的像素完全透明则返回 True，否则返回 False。

Added in version 3.8.

transparency_set(x, y, boolean)

如果 boolean 为真则将坐标 (x, y) 处的像素设为完全透明，否则设为完全不透明。

Added in version 3.8.

write(filename, format=None, from_coords=None, *, background=None, grayscale=False)

将图像数据从图像写入名为 filename 的文件。

format 指定要使用的图像文件格式处理程序的名称。 如果未给出，则根据文件扩展名推断格式。

from_coords 指定要写入的图像矩形区域。 它必须是一个由 1 到 4 个整数组成的元组或列表 (x1, y1, x2, y2)。 如果仅指定了 x1 和 y1，该区域将从 (x1, y1) 延伸到图像的右下角。 如果给出了全部四个坐标，它们指定区域的对角。 如果未给出 from_coords，则写入整个图像。

如果指定了 background，数据将不包含任何透明度信息；所有透明像素的颜色都会被替换为指定的颜色。

如果 grayscale 为真，数据将不包含颜色信息；所有像素数据都会被转换为灰度。

在 3.13 版本发生变更: 增加了 background 和 grayscale 形参。

zoom(x, y='', *, from_coords=None)

返回一个新的 PhotoImage，将此图像在 X 方向放大 x 倍，在 Y 方向放大 y 倍。 如果未给出 y，它默认为与 x 相同的值。

from_coords 指定要拷贝的源图像矩形子区域，如同在 copy() 方法中一样。

在 3.13 版本发生变更: 增加了 from_coords 形参。

class tkinter.BitmapImage(name=None, cnf={}, master=None, **kw)

从 X11 位图创建的双色图像（Tk bitmap 图像类型）。 每个像素显示前景色、背景色或不显示任何内容（产生透明效果）。 继承自 Image。

配置选项包括 data 或 file （源位图，以 X11 位图格式的字符串或该格式的文件名给出）、 maskdata 或 maskfile （掩码位图，采用相同形式），以及 foreground 和 background （两种颜色）。 对于掩码为 0 的像素，图像不显示任何内容；对于其他像素，当源为 1 时显示前景色，当源为 0 时显示背景色。 如果 background 被设为空字符串，则背景像素是透明的。

BitmapImage 除了从 Image 继承的方法之外，没有自己的方法。

其他类

class tkinter.Event

传递给通过 Misc.bind() 绑定的回调函数的事件属性容器。 一个 Event 实例具有以下属性，每个属性对应于底层 Tk 事件的一个字段；根据事件类型，某些属性可能会设置为字符串 '??' 以指示它们没有实际意义。 参见 绑定和事件。

serial

事件的序列号。

num

按下或释放的鼠标按键（针对按钮事件）。

focus

窗口是否具有焦点（针对 Enter 和 Leave 事件）。

height
width

窗口的新高度和宽度（针对 Configure 和 Expose 事件）。

keycode

按下或释放的按键的代码。

state

事件的状态，表现为一个数字（针对大多数事件）或字符串（针对 Visibility 事件）。

time

事件的时间戳（以毫秒为单位）。

x
y

指针相对于微件的位置（以像素为单位）。

x_root
y_root

指针相对于屏幕左上角的位置（以像素为单位）。

char

键入的字符，表现为字符串（针对按键事件）。

send_event

如果事件是由另一个应用程序发送的，则为 True 。

keysym

按下或释放的按键的符号名称。

keysym_num

keysym 的数值。

type

事件的 EventType 。

widget

发生事件的微件。

delta

鼠标滚轮旋转的量（针对 MouseWheel 事件）。

user_data

The data string of a virtual event, as passed to the data option of Misc.event_generate(). It is '??' for non-virtual events.

Added in version 3.15.

detail

A fixed detail string for Enter, Leave, FocusIn, FocusOut and ConfigureRequest events (see the Tcl/Tk documentation). It is '??' for other events.

Added in version 3.15.

class tkinter.EventType(*values)

枚举 Tk 事件类型的 enum.StrEnum ，用作 Event.type 的值。 其成员包括 KeyPress 、 KeyRelease 、 ButtonPress 、 ButtonRelease 、 Motion 、 Enter 、 Leave 、 FocusIn 、 FocusOut 、 Configure 、 Map 、 Unmap 、 Expose 、 Destroy 和 MouseWheel 等。

Added in version 3.6.

class tkinter.CallWrapper(func, subst, widget)

包装 Python 回调以便可以从 Tcl 调用的内部辅助程序。 func 是 Python 函数， subst 是预处理 Tcl 参数的可选函数， widget 是用于错误报告的微件。 实例由 Misc.register() 自动创建；该类通常不直接使用。

模块级函数

tkinter.Tcl(screenName=None, baseName=None, className='Tk', useTk=False)

Tcl() 函数是一个工厂函数，它创建的对象与 Tk 类创建的对象非常相似，只是它不初始化 Tk 子系统。 这在不想创建无关顶层窗口或无法创建顶层窗口（例如没有 X 服务器的 Unix/Linux 系统）的环境中驱动 Tcl 解释器时非常有用。 通过调用其 loadtk() 方法，由 Tcl() 对象创建的对象可以创建一个 Toplevel 窗口（并初始化 Tk 子系统）。

tkinter.NoDefaultRoot()

阻止隐式默认根窗口的创建。 之后 tkinter 不再自动创建共享默认根窗口，并且依赖于根窗口的操作——例如在没有显式 master 的情况下构造微件——将引发 RuntimeError 。 在大型应用程序中尽早调用此函数以显式指定根窗口。

tkinter.mainloop(n=0)

在默认根窗口上运行 Tk 主事件循环，直到所有窗口都被销毁。 等同于在默认根窗口上调用 Misc.mainloop() 。

tkinter.getboolean(s)

Convert the Tcl boolean string s (one of '1', 'true', 'yes', 'on' and similar, or their false counterparts) to a Python bool. Raise ValueError for an invalid value.

tkinter.getdouble(s)

将 s 转换为浮点数。 这是内置的 float 。

tkinter.getint(s)

将 s 转换为整数。 这是内置的 int 。

tkinter.image_names()

返回默认根窗口解释器中所有现有图像的名称。

tkinter.image_types()

返回默认根窗口解释器中可用的图像类型（例如 'photo' 和 'bitmap' ）。

文件处理程序

Tk 允许为文件操作注册和注销一个回调函数，当对文件描述符进行 I/O 时，Tk 的主循环会调用该回调函数。每个文件描述符只能注册一个处理程序。示例代码如下：

import tkinter
widget = tkinter.Tk()
mask = tkinter.READABLE | tkinter.WRITABLE
widget.tk.createfilehandler(file, mask, callback)
...
widget.tk.deletefilehandler(file)

在 Windows 系统中不可用。

由于不知道可读取多少字节，你可能不希望使用 BufferedIOBase 或 TextIOBase 的 read() 或 readline() 方法，因为这些方法必须读取预定数量的字节。 对于套接字，可使用 recv() 或 recvfrom() 方法；对于其他文件，可使用原始读取方法或 os.read(file.fileno(), maxbytecount)。

Widget.tk.createfilehandler(file, mask, func)

注册文件处理程序的回调函数 func。 file 参数可以是具备 fileno() 方法的对象（例如文件或套接字对象），也可以是整数文件描述符。 mask 参数是下述三个常量的逻辑“或”组合。回调函数将用以下格式调用：

callback(file, mask)
Widget.tk.deletefilehandler(file)

注销文件处理函数。

tkinter.READABLE
tkinter.WRITABLE
tkinter.EXCEPTION

Constants used in the mask arguments.

常量

以下符号常量在 tkinter 和 tkinter.constants 命名空间中均可用。

tkinter.TRUE
tkinter.YES
tkinter.ON

真值，全部等于整数 1 。

tkinter.FALSE
tkinter.NO
tkinter.OFF

假值，全部等于整数 0 。

tkinter.N
tkinter.S
tkinter.E
tkinter.W
tkinter.NE
tkinter.NW
tkinter.SE
tkinter.SW
tkinter.NS
tkinter.EW
tkinter.NSEW
tkinter.CENTER

罗盘方向（ 'n' 、 's' 、 'e' 、 'w' 以及对角线和边缘）加上 CENTER （ 'center' ），用作 anchor 和 sticky 选项的值以及被 Misc.grid_anchor() 等方法使用。

tkinter.LEFT
tkinter.RIGHT
tkinter.TOP
tkinter.BOTTOM

打包器的 side 选项的边（参见 Pack.pack_configure() ）。

tkinter.X
tkinter.Y
tkinter.BOTH
tkinter.NONE

打包器的 fill 选项的值： 'x' 、 'y' 、 'both' 或 'none' 。

tkinter.RAISED
tkinter.SUNKEN
tkinter.FLAT
tkinter.RIDGE
tkinter.GROOVE
tkinter.SOLID

relief 选项的值，用于控制微件的 3D 边框。

tkinter.HORIZONTAL
tkinter.VERTICAL

Scale 、 Scrollbar 和 PanedWindow 等微件的 orient 选项的值。

tkinter.CHAR
tkinter.WORD

Text 微件的 wrap 选项的值，用于选择按字符或单词边界换行。

tkinter.BASELINE

文本对齐值 'baseline' 。

tkinter.INSIDE
tkinter.OUTSIDE

放置器的 bordermode 选项的值（参见 Place.place_configure() ）。

tkinter.INSERT
tkinter.CURRENT
tkinter.END
tkinter.ANCHOR
tkinter.SEL
tkinter.SEL_FIRST
tkinter.SEL_LAST

Text 、 Entry 、 Listbox 和 Canvas 微件使用的符号索引，例如 'insert' （插入光标）、 'current' 、 'end' 、 'anchor' 以及选择范围的边界（ 'sel.first' 和 'sel.last' ）。

tkinter.ALL

特殊标记 'all' ，它匹配 Canvas 的每个项目或 Text 的每个字符（例如 canvas.delete(ALL) ）。

tkinter.NORMAL
tkinter.DISABLED
tkinter.ACTIVE
tkinter.HIDDEN

各种微件和项目的 state 选项的值。

tkinter.CASCADE
tkinter.CHECKBUTTON
tkinter.COMMAND
tkinter.RADIOBUTTON
tkinter.SEPARATOR

菜单条目类型，用作 Menu.add() 和 Menu.insert() 的 itemType 参数。

tkinter.SINGLE
tkinter.BROWSE
tkinter.MULTIPLE
tkinter.EXTENDED

Listbox 微件的 selectmode 选项的值。

tkinter.PIESLICE
tkinter.CHORD
tkinter.ARC

Canvas 圆弧项目的 style 选项的值。

tkinter.BUTT
tkinter.PROJECTING
tkinter.ROUND
tkinter.BEVEL
tkinter.MITER

Canvas 线条项目的 capstyle （ 'butt' 、 'projecting' 、 'round' ）和 joinstyle （ 'round' 、 'bevel' 、 'miter' ）选项的值。

tkinter.FIRST
tkinter.LAST

Canvas 线条项目的 arrow 选项的值，指示哪一端有箭头。

tkinter.MOVETO
tkinter.SCROLL

由 Scrollbar 传递给滚动微件的 XView.xview() 或 YView.yview() 方法的第一个参数。

tkinter.UNITS
tkinter.PAGES

XView.xview_scroll() 和 YView.yview_scroll() 的 what 参数的值。

tkinter.UNDERLINE
tkinter.NUMERIC
tkinter.DOTBOX

其他选项值: 'underline', 'numeric' 和 'dotbox'。