# `tkinter` --- Python interface to Tcl/Tk

ソースコード: Lib/tkinter/__init__.py

`tkinter` パッケージ ("Tk インターフェース") は、 Tcl/Tk GUI ツールキットに対する標準の Python インターフェースです。 Tk と `tkinter` は macOS を含むほとんどの Unix プラットフォームの他、 Windows システム上でも利用できます。

コマンドラインから `python -m tkinter` を実行すると簡素な Tk インターフェースを表示するウィンドウが開き、システムに `tkinter` が正しくインストールされたことが分かり、さらにインストールされた Tcl/Tk がどのバーションなのかが表示されるので、そのバージョンの Tcl/Tk ドキュメントを選んで読めます。

Tkinter supports a range of Tcl/Tk versions, built either with or without thread support. The official Python binary release bundles Tcl/Tk 8.6 threaded. See the source code for the `_tkinter` module for more information about supported versions.

Tkinter is not a thin wrapper, but adds a fair amount of its own logic to make the experience more pythonic. This documentation will concentrate on these additions and changes, and refer to the official Tcl/Tk documentation for details that are unchanged.

注釈

Tcl/Tk 8.5 (2007) introduced a modern set of themed user interface components along with a new API to use them. Both old and new APIs are still available. Most documentation you will find online still uses the old API and can be woefully outdated.

参考

- TkDocs

    Extensive tutorial on creating user interfaces with Tkinter. Explains key concepts, and illustrates recommended approaches using the modern API.

- Tkinter 8.5 reference: a GUI for Python

    Reference documentation for Tkinter 8.5 detailing available classes, methods, and options.

Tcl/Tk Resources:

- Tk commands

    Comprehensive reference to each of the underlying Tcl/Tk commands used by Tkinter.

- Tcl/Tk ホームページ

    Additional documentation, and links to Tcl/Tk core development.

Books:

- Modern Tkinter for Busy Python Developers

    By Mark Roseman. (ISBN 978-1999149567)

- Python GUI programming with Tkinter

    By Alan D. Moore. (ISBN 978-1788835886)

- Programming Python

    By Mark Lutz; has excellent coverage of Tkinter. (ISBN 978-0596158101)

- Tcl and the Tk Toolkit (2nd edition)

    By John Ousterhout, inventor of Tcl/Tk, and Ken Jones; does not cover Tkinter. (ISBN 978-0321336330)

## Architecture

Tcl/Tk is not a single library but rather consists of a few distinct modules, each with separate functionality and its own official documentation. Python's binary releases also ship an add-on module together with it.

Tcl

  Tcl is a dynamic interpreted programming language, just like Python. Though it can be used on its own as a general-purpose programming language, it is most commonly embedded into C applications as a scripting engine or an interface to the Tk toolkit. The Tcl library has a C interface to create and manage one or more instances of a Tcl interpreter, run Tcl commands and scripts in those instances, and add custom commands implemented in either Tcl or C. Each interpreter has an event queue, and there are facilities to send events to it and process them. Unlike Python, Tcl's execution model is designed around cooperative multitasking, and Tkinter bridges this difference (see Threading model for details).

Tk

  Tk is a Tcl package implemented in C that adds custom commands to create and manipulate GUI widgets. Each `Tk` object embeds its own Tcl interpreter instance with Tk loaded into it. Tk's widgets are very customizable, though at the cost of a dated appearance. Tk uses Tcl's event queue to generate and process GUI events.

Ttk

  Themed Tk (Ttk) is a newer family of Tk widgets that provide a much better appearance on different platforms than many of the classic Tk widgets. Ttk is distributed as part of Tk, starting with Tk version 8.5. Python bindings are provided in a separate module, `tkinter.ttk`.

Internally, Tk and Ttk use facilities of the underlying operating system, i.e., Xlib on Unix/X11, Cocoa on macOS, GDI on Windows.

When your Python application uses a class in Tkinter, e.g., to create a widget, the `tkinter` module first assembles a Tcl/Tk command string. It passes that Tcl command string to an internal `_tkinter` binary module, which then calls the Tcl interpreter to evaluate it. The Tcl interpreter will then call into the Tk and/or Ttk packages, which will in turn make calls to Xlib, Cocoa, or GDI.

## Tkinter モジュール

Support for Tkinter is spread across several modules. Most applications will need the main `tkinter` module, as well as the `tkinter.ttk` module, which provides the modern themed widget set and API:

    from tkinter import *
    from tkinter import ttk

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

  Construct a toplevel Tk widget, which is usually the main window of an application, and initialize a Tcl interpreter for this widget. Each instance has its own associated Tcl interpreter.

  The `Tk` class is typically instantiated using all default values. However, the following keyword arguments are currently recognized:

  screenName

    When given (as a string), sets the `DISPLAY` environment variable. (X11 only)

  baseName

    Name of the profile file. By default, baseName is derived from the program name (`sys.argv[0]`).

  className

    Name of the widget class. Used as a profile file and also as the name with which Tcl is invoked (argv0 in interp).

  useTk

    If `True`, initialize the Tk subsystem. The `tkinter.Tcl()` function sets this to `False`.

  sync

    If `True`, execute all X server commands synchronously, so that errors are reported immediately. Can be used for debugging. (X11 only)

  use

    Specifies the id of the window in which to embed the application, instead of it being created as an independent toplevel window. id must be specified in the same way as the value for the -use option for toplevel widgets (that is, it has a form like that returned by `winfo_id()`).

    Note that on some platforms this will only work correctly if id refers to a Tk frame or toplevel that has its -container option enabled.

  `Tk` reads and interprets profile files, named `.className.tcl` and `.baseName.tcl`, into the Tcl interpreter and calls `exec()` on the contents of `.className.py` and `.baseName.py`. The path for the profile files is the `HOME` environment variable or, if that isn't defined, then `os.curdir`.

  tk

    The Tk application object created by instantiating `Tk`. This provides access to the Tcl interpreter. Each widget that is attached the same instance of `Tk` has the same value for its `tk` attribute.

  master

    The widget object that contains this widget. For `Tk`, the master is `None` because it is the main window. The terms master and parent are similar and sometimes used interchangeably as argument names; however, calling `winfo_parent()` returns a string of the widget name whereas `master` returns the object. parent/child reflects the tree-like relationship while master/slave reflects the container structure.

  children

    The immediate descendants of this widget as a `dict` with the child widget names as the keys and the child instance objects as the values.

tkinter.Tcl(screenName=None, baseName=None, className='Tk', useTk=False)

  `Tcl()` はファクトリ関数で、 `Tk` クラスで生成するオブジェクトとよく似たオブジェクトを生成します。ただし Tk サブシステムを初期化しません。この関数は、余分なトップレベルウィンドウを作る必要がなかったり、 (X サーバを持たない Unix/Linux システムなどのように) 作成できない環境において Tcl インタプリタを駆動したい場合に便利です。 `Tcl()` で生成したオブジェクトに対して `loadtk()` メソッドを呼び出せば、トップレベルウィンドウを作成 (して、Tk サブシステムを初期化) します。

The modules that provide Tk support include:

`tkinter`

  Main Tkinter module.

`tkinter.colorchooser`

  ユーザに色を選択させるためのダイアログです。

`tkinter.commondialog`

  このリストの他のモジュールが定義しているダイアログの基底クラスです。

`tkinter.filedialog`

  ユーザが開きたいファイルや保存したいファイルを指定できるようにする共通のダイアログです。

`tkinter.font`

  フォントの扱いを補助するためのユーティリティです。

`tkinter.messagebox`

  標準的な Tk のダイアログボックスにアクセスします。

`tkinter.scrolledtext`

  垂直スクロールバー付きのテキストウィジェットです。

`tkinter.simpledialog`

  基本的なダイアログと便宜関数 (convenience function) です。

`tkinter.ttk`

  Themed widget set introduced in Tk 8.5, providing modern alternatives for many of the classic widgets in the main `tkinter` module.

Additional modules:

`_tkinter`

  A binary module that contains the low-level interface to Tcl/Tk. It is automatically imported by the main `tkinter` module, and should never be used directly by application programmers. It is usually a shared library (or DLL), but might in some cases be statically linked with the Python interpreter.

`idlelib`

  Python's Integrated Development and Learning Environment (IDLE). Based on `tkinter`.

`tkinter.constants`

  Symbolic constants that can be used in place of strings when passing various parameters to Tkinter calls. Automatically imported by the main `tkinter` module.

`tkinter.dnd`

  (experimental) Drag-and-drop support for `tkinter`. This will become deprecated when it is replaced with the Tk DND.

`tkinter.tix`

  (deprecated) An older third-party Tcl/Tk package that adds several new widgets. Better alternatives for most can be found in `tkinter.ttk`.

`turtle`

  Tk ウィンドウ上でタートルグラフィックスを実現します。

## Tkinter お助け手帳

This section is not designed to be an exhaustive tutorial on either Tk or Tkinter. For that, refer to one of the external resources noted earlier. Instead, this section provides a very quick orientation to what a Tkinter application looks like, identifies foundational Tk concepts, and explains how the Tkinter wrapper is structured.

The remainder of this section will help you to identify the classes, methods, and options you'll need in your Tkinter application, and where to find more detailed documentation on them, including in the official Tcl/Tk reference manual.

### A Hello World Program

We'll start by walking through a "Hello World" application in Tkinter. This isn't the smallest one we could write, but has enough to illustrate some key concepts you'll need to know.

    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()

After the imports, the next line creates an instance of the `Tk` class, which initializes Tk and creates its associated Tcl interpreter. It also creates a toplevel window, known as the root window, which serves as the main window of the application.

The following line creates a frame widget, which in this case will contain a label and a button we'll create next. The frame is fit inside the root window.

The next line creates a label widget holding a static text string. The `grid()` method is used to specify the relative layout (position) of the label within its containing frame widget, similar to how tables in HTML work.

A button widget is then created, and placed to the right of the label. When pressed, it will call the `destroy()` method of the root window.

Finally, the `mainloop()` method puts everything on the display, and responds to user input until the program terminates.

### Important Tk Concepts

Even this simple program illustrates the following key Tk concepts:

widgets

  A Tkinter user interface is made up of individual widgets. Each widget is represented as a Python object, instantiated from classes like `ttk.Frame`, `ttk.Label`, and `ttk.Button`.

widget hierarchy

  Widgets are arranged in a hierarchy. The label and button were contained within a frame, which in turn was contained within the root window. When creating each child widget, its parent widget is passed as the first argument to the widget constructor.

configuration options

  Widgets have configuration options, which modify their appearance and behavior, such as the text to display in a label or button. Different classes of widgets will have different sets of options.

geometry management

  Widgets aren't automatically added to the user interface when they are created. A geometry manager like `grid` controls where in the user interface they are placed.

event loop

  Tkinter reacts to user input, changes from your program, and even refreshes the display only when actively running an event loop. If your program isn't running the event loop, your user interface won't update.

### Understanding How Tkinter Wraps Tcl/Tk

When your application uses Tkinter's classes and methods, internally Tkinter is assembling strings representing Tcl/Tk commands, and executing those commands in the Tcl interpreter attached to your application's `Tk` instance.

Whether it's trying to navigate reference documentation, trying to find the right method or option, adapting some existing code, or debugging your Tkinter application, there are times that it will be useful to understand what those underlying Tcl/Tk commands look like.

To illustrate, here is the Tcl/Tk equivalent of the main part of the Tkinter script above.

    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's syntax is similar to many shell languages, where the first word is the command to be executed, with arguments to that command following it, separated by spaces. Without getting into too many details, notice the following:

- The commands used to create widgets (like `ttk::frame`) correspond to widget classes in Tkinter.

- Tcl widget options (like `-text`) correspond to keyword arguments in Tkinter.

- Widgets are referred to by a pathname in Tcl (like `.frm.btn`), whereas Tkinter doesn't use names but object references.

- A widget's place in the widget hierarchy is encoded in its (hierarchical) pathname, which uses a `.` (dot) as a path separator. The pathname for the root window is just `.` (dot). In Tkinter, the hierarchy is defined not by pathname but by specifying the parent widget when creating each child widget.

- Operations which are implemented as separate commands in Tcl (like `grid` or `destroy`) are represented as methods on Tkinter widget objects. As you'll see shortly, at other times Tcl uses what appear to be method calls on widget objects, which more closely mirror what would is used in Tkinter.

### How do I...? What option does...?

If you're not sure how to do something in Tkinter, and you can't immediately find it in the tutorial or reference documentation you're using, there are a few strategies that can be helpful.

First, remember that the details of how individual widgets work may vary across different versions of both Tkinter and Tcl/Tk. If you're searching documentation, make sure it corresponds to the Python and Tcl/Tk versions installed on your system.

When searching for how to use an API, it helps to know the exact name of the class, option, or method that you're using. Introspection, either in an interactive Python shell or with `print()`, can help you identify what you need.

To find out what configuration options are available on any widget, call its `configure()` method, which returns a dictionary containing a variety of information about each object, including its default and current values. Use `keys()` to get just the names of each option.

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

As most widgets have many configuration options in common, it can be useful to find out which are specific to a particular widget class. Comparing the list of options to that of a simpler widget, like a frame, is one way to do that.

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

Similarly, you can find the available methods for a widget object using the standard `dir()` function. If you try it, you'll see there are over 200 common widget methods, so again identifying those specific to a widget class is helpful.

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

### Navigating the Tcl/Tk Reference Manual

As noted, the official Tk commands reference manual (man pages) is often the most accurate description of what specific operations on widgets do. Even when you know the name of the option or method that you need, you may still have a few places to look.

While all operations in Tkinter are implemented as method calls on widget objects, you've seen that many Tcl/Tk operations appear as commands that take a widget pathname as its first parameter, followed by optional parameters, e.g.

    destroy .
    grid .frm.btn -column 0 -row 0

Others, however, look more like methods called on a widget object (in fact, when you create a widget in Tcl/Tk, it creates a Tcl command with the name of the widget pathname, with the first parameter to that command being the name of a method to call).

    .frm.btn invoke
    .frm.lbl configure -text "Goodbye"

In the official Tcl/Tk reference documentation, you'll find most operations that look like method calls on the man page for a specific widget (e.g., you'll find the `invoke()` method on the ttk::button man page), while functions that take a widget as a parameter often have their own man page (e.g., grid).

You'll find many common options and methods in the options or ttk::widget man pages, while others are found in the man page for a specific widget class.

You'll also find that many Tkinter methods have compound names, e.g., `winfo_x()`, `winfo_height()`, `winfo_viewable()`. You'd find documentation for all of these in the winfo man page.

注釈

Somewhat confusingly, there are also methods on all Tkinter widgets that don't actually operate on the widget, but operate at a global scope, independent of any widget. Examples are methods for accessing the clipboard or the system bell. (They happen to be implemented as methods in the base `Widget` class that all Tkinter widgets inherit from).

## Threading model

Python and Tcl/Tk have very different threading models, which `tkinter` tries to bridge. If you use threads, you may need to be aware of this.

A Python interpreter may have many threads associated with it. In Tcl, multiple threads can be created, but each thread has a separate Tcl interpreter instance associated with it. Threads can also create more than one interpreter instance, though each interpreter instance can be used only by the one thread that created it.

Each `Tk` object created by `tkinter` contains a Tcl interpreter. It also keeps track of which thread created that interpreter. Calls to `tkinter` can be made from any Python thread. Internally, if a call comes from a thread other than the one that created the `Tk` object, an event is posted to the interpreter's event queue, and when executed, the result is returned to the calling Python thread.

Tcl/Tk applications are normally event-driven, meaning that after initialization, the interpreter runs an event loop (i.e. `Tk.mainloop()`) and responds to events. Because it is single-threaded, event handlers must respond quickly, otherwise they will block other events from being processed. To avoid this, any long-running computations should not run in an event handler, but are either broken into smaller pieces using timers, or run in another thread. This is different from many GUI toolkits where the GUI runs in a completely separate thread from all application code including event handlers.

If the Tcl interpreter is not running the event loop and processing events, any `tkinter` calls made from threads other than the one running the Tcl interpreter will fail.

A number of special cases exist:

- Tcl/Tk libraries can be built so they are not thread-aware. In this case, `tkinter` calls the library from the originating Python thread, even if this is different than the thread that created the Tcl interpreter. A global lock ensures only one call occurs at a time.

- While `tkinter` allows you to create more than one instance of a `Tk` object (with its own interpreter), all interpreters that are part of the same thread share a common event queue, which gets ugly fast. In practice, don't create more than one instance of `Tk` at a time. Otherwise, it's best to create them in separate threads and ensure you're running a thread-aware Tcl/Tk build.

- Blocking event handlers are not the only way to prevent the Tcl interpreter from reentering the event loop. It is even possible to run multiple nested event loops or abandon the event loop entirely. If you're doing anything tricky when it comes to events or threads, be aware of these possibilities.

- There are a few select `tkinter` functions that presently work only when called from the thread that created the Tcl interpreter.

## 簡単なリファレンス

### オプションの設定

オプションは、色やウィジェットの境界線幅などを制御します。オプションの設定には三通りの方法があります:

オブジェクト生成時、キーワード引数を使用する

      fred = Button(self, fg="red", bg="blue")

オブジェクト生成後、オプション名を辞書インデックスのように扱う

      fred["fg"] = "red"
      fred["bg"] = "blue"

オブジェクト生成後に、config()メソッドを使って複数の属性を更新する

      fred.config(fg="red", bg="blue")

オプションとその振る舞いに関する詳細な説明は、該当するウィジェットの Tk の man ページを参照してください。

man ページには、各ウィジェットの "STANDARD OPTIONS (標準オプション)" と "WIDGET SPECIFIC OPTIONS (ウィジェット固有のオプション)" がリストされていることに注意してください。前者は多くのウィジェットに共通のオプションのリストで、後者は特定のウィジェットに特有のオプションです。標準オプションの説明は man ページの options(3) にあります。

このドキュメントでは、標準オプションとウィジェット固有のオプションを区別していません。オプションによっては、ある種のウィジェットに適用できません。あるウィジェットがあるオプションに対応しているかどうかは、ウィジェットのクラスによります。例えばボタンには `command` オプションがありますが、ラベルにはありません。

あるウィジェットがどんなオプションをサポートしているかは、ウィジェットの man ページにリストされています。また、実行時にウィジェットの `config()` メソッドを引数なしで呼び出したり、 `keys()` メソッドを呼び出したりして問い合わせることもできます。メソッド呼び出しを行うと辞書型の値を返します。この辞書は、オプションの名前がキー (例えば `'relief'`) になっていて、値が 5 要素のタプルになっています。

`bg` のように、いくつかのオプションはより長い名前を持つ共通のオプションに対する同義語になっています (`bg` は "background" を短縮したものです)。短縮形のオプション名を `config()` に渡すと、 5 要素ではなく 2 要素のタプルを返します。このタプルには、同義語の名前と「本当の」オプション名が入っています (例えば `('bg', 'background')`)。

インデックス | 意味 | 使用例
--- | --- | ---
0 | オプション名 | `'relief'`
1 | データベース検索用のオプション名 | `'relief'`
2 | データベース検索用のオプションクラス | `'Relief'`
3 | デフォルト値 | `'raised'`
4 | 現在の値 | `'groove'`

以下はプログラム例です:

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

もちろん、実際に出力される辞書には利用可能なオプションが全て表示されます。上の表示例は単なる例にすぎません。

### Packer

packer は Tk のジオメトリ管理メカニズムの一つです。ジオメトリマネージャは、複数のウィジェットの位置を、それぞれのウィジェットを含むコンテナ - 共通の マスタ (master) からの相対で指定するために使います。やや扱いにくい placer (あまり使われないのでここでは取り上げません) と違い、packer は定性的な関係を表す指定子 - 上 (above) 、 〜の左 (to the left of) 、 引き延ばし (filling) など - を受け取り、厳密な配置座標の決定を全て行ってくれます。

どんな マスタ ウィジェットでも、大きさは内部の "スレイブ (slave) ウィジェット" の大きさで決まります。 packer は、スレイブウィジェットを pack 先のマスタウィジェット中のどこに配置するかを制御するために使われます。望みのレイアウトを達成するには、ウィジェットをフレームにパックし、そのフレームをまた別のフレームにパックできます。さらに、一度パックを行うと、それ以後の設定変更に合わせて動的に並べ方を調整します。

ジオメトリマネージャがウィジェットのジオメトリを確定するまで、ウィジェットは表示されないので注意してください。初心者のころにはよくジオメトリの確定を忘れてしまい、ウィジェットを生成したのに何も表示されず驚くことになります。ウィジェットは、(例えば packer の `pack()` メソッドを適用して) ジオメトリを確定した後で初めて表示されます。

pack() メソッドは、キーワード引数つきで呼び出せます。キーワード引数は、ウィジェットをコンテナ内のどこに表示するか、メインのアプリケーションウィンドウをリサイズしたときにウィジェットがどう振舞うかを制御します。以下に例を示します:

    fred.pack()                     # defaults to side = "top"
    fred.pack(side="left")
    fred.pack(expand=1)

### Packer のオプション

packer と packer の取りえるオプションについての詳細は、man ページや John Ousterhout の本の183ページを参照してください。

anchor

  アンカーの型です。 packer が区画内に各スレイブを配置する位置を示します。

expand

  ブール値で、 `0` または `1` になります。

fill

  指定できる値は `'x'` 、 `'y'` 、 `'both'` 、 `'none'` です。

ipadx および ipady

  スレイブウィジェットの各側面の内側に行うパディング幅を表す長さを指定します。

padx および pady

  スレイブウィジェットの各側面の外側に行うパディング幅を表す長さを指定します。

side

  指定できる値は `'left'`, `'right'`, `'top'`, `'bottom'` です。

### ウィジェット変数を関連付ける

ウィジェットによっては、(テキスト入力ウィジェットのように) 特殊なオプションを使って、現在設定されている値をアプリケーション内の変数に直接関連付けできます。このようなオプションには `variable`, `textvariable`, `onvalue`, `offvalue` および `value` があります。この関連付けは双方向に働きます: 変数の値が何らかの理由で変更されると、関連付けされているウィジェットも更新され、新しい値を反映します。

残念ながら、現在の `tkinter` の実装では、`variable` や `textvariable` オプションでは任意の Python の値をウィジェットに渡せません。この関連付け機能がうまく働くのは、`tkinter` 内で Variable というクラスからサブクラス化されている変数によるオプションだけです。

Variable には、 `StringVar`, `IntVar`, `DoubleVar`, `BooleanVar` といった便利なサブクラスがすでにすでに数多く定義されています。こうした変数の現在の値を読み出したければ、 `get()` メソッドを呼び出します。また、値を変更したければ `set()` メソッドを呼び出します。このプロトコルに従っている限り、それ以上なにも手を加えなくてもウィジェットは常に現在値に追従します。

例えば:

    import tkinter as tk

    class App(tk.Frame):
        def __init__(self, master):
            super().__init__(master)
            self.pack()

            self.entrythingy = tk.Entry()
            self.entrythingy.pack()

            # Create the application variable.
            self.contents = tk.StringVar()
            # Set it to some value.
            self.contents.set("this is a variable")
            # Tell the entry widget to watch this variable.
            self.entrythingy["textvariable"] = self.contents

            # Define a callback for when the user hits return.
            # It prints the current value of the variable.
            self.entrythingy.bind('<Key-Return>',
                                 self.print_contents)

        def print_contents(self, event):
            print("Hi. The current entry content is:",
                  self.contents.get())

    root = tk.Tk()
    myapp = App(root)
    myapp.mainloop()

### ウィンドウマネージャ

Tk には、ウィンドウマネジャとやり取りするための `wm` というユーティリティコマンドがあります。`wm` コマンドにオプションを指定すると、タイトルや配置、アイコンビットマップなどを操作できます。`tkinter` では、こうしたコマンドは `Wm` クラスのメソッドとして実装されています。トップレベルウィジェットは `Wm` クラスからサブクラス化されているので、`Wm` のメソッドを直接呼び出せます。

あるウィジェットの入っているトップレベルウィンドウを取得したい場合、大抵は単にウィジェットのマスタを参照するだけですみます。とはいえ、ウィジェットがフレーム内にパックされている場合、マスタはトップレベルウィンドウではありません。任意のウィジェットの入っているトップレベルウィンドウを知りたければ `_root()` メソッドを呼び出してください。このメソッドはアンダースコアがついていますが、これはこの関数が `Tkinter` の実装の一部であり、Tk の機能に対するインターフェースではないことを示しています。

以下に典型的な使い方の例をいくつか挙げます:

    import tkinter as tk

    class App(tk.Frame):
        def __init__(self, master=None):
            super().__init__(master)
            self.pack()

    # create the application
    myapp = App()

    #
    # here are method calls to the window manager class
    #
    myapp.master.title("My Do-Nothing Application")
    myapp.master.maxsize(1000, 400)

    # start the program
    myapp.mainloop()

### Tk オプションデータ型

anchor

  指定できる値はコンパスの方位です: `"n"` 、 `"ne"` 、 `"e"` 、 `"se"` 、 `"s"` 、 `"sw"` 、 `"w"` 、 `"nw"` 、および `"center"` 。

bitmap

  八つの組み込み、名前付きビットマップ: `'error'` 、 `'gray25'` 、 `'gray50'` 、 `'hourglass'` 、 `'info'` 、 `'questhead'` 、 `'question'` 、 `'warning'` 。 X ビットマップファイル名を指定するために、 `"@/usr/contrib/bitmap/gumby.bit"` のような `@` を先頭に付けたファイルへの完全なパスを与えてください。

boolean

  整数 0 または 1 、あるいは、文字列 `"yes"` または `"no"` を渡すことができます。

callback

  これは引数を取らない Python 関数ならどれでも構いません。例えば:

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

color

  Colors can be given as the names of X colors in the rgb.txt file, 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. See page 160 of Ousterhout's book for details.

cursor

  `cursorfont.h` の標準Xカーソル名を、接頭語 `XC_` 無しで使うことができます。例えば、handカーソル(`XC_hand2`)を得るには、文字列 `"hand2"` を使ってください。あなた自身のビットマップとマスクファイルを指定することもできます。 Ousterhout の本の179ページを参照してください。

distance

  スクリーン上の距離をピクセルか絶対距離のどちらかで指定できます。ピクセルは数値として与えられ、絶対距離は文字列として与えられます。絶対距離を表す文字列は、単位を表す終了文字 (センチメートルには `c` 、インチには `i` 、ミリメートルには `m` 、プリンタのポイントには `p`)を伴います。例えば、3.5インチは `"3.5i"` と表現します。

font

  Tkはフォント名の形式に `{courier 10 bold}` のようなリストを使います。正の数のフォントサイズはポイント単位で使用され、負の数のサイズはピクセル単位と見なされます。

geometry

  これは `widthxheight` 形式の文字列です。ここでは、ほとんどのウィジェットに対して幅と高さピクセル単位で (テキストを表示するウィジェットに対しては文字単位で)表されます。例えば: `fred["geometry"] = "200x100"` 。

justify

  指定できる値は文字列です: `"left"` 、 `"center"` 、 `"right"` 、そして `"fill"` 。

region

  これは空白で区切られた四つの要素をもつ文字列です。各要素は指定可能な距離です(以下を参照)。例えば: `"2 3 4 5"` と `"3i 2i 4.5i 2i"` と `"3c 2c 4c 10.43c"` は、すべて指定可能な範囲です。

relief

  ウィジェットのボーダのスタイルが何かを決めます。指定できる値は: `"raised"` 、 `"sunken"` 、 `"flat"` 、 `"groove"` 、と `"ridge"` 。

scrollcommand

  これはほとんどの場合スクロールバーウィジェットの `set()` メソッドですが、1 個の引数を取るあらゆるウィジェットにもなりえます。

wrap

  次の中の一つでなければなりません: `"none"` 、 `"char"` 、あるいは `"word"` 。

### バインドとイベント

ウィジェットコマンドからの bind メソッドによって、あるイベントを待つことと、そのイベント型が起きたときにコールバック関数を呼び出すことができるようになります。 bind メソッドの形式は:

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

ここでは:

sequence

  is a string that denotes the target kind of event. (See the bind(3tk) man page, and page 201 of John Ousterhout's book, Tcl and the Tk Toolkit (2nd edition), for details).

func

  は一引数を取り、イベントが起きるときに呼び出される Python 関数です。イベント・インスタンスが引数として渡されます。 (このように実施される関数は、一般に callbacks として知られています。)

add

  はオプションで、 `''` か `'+'` のどちらかです。空文字列を渡すことは、このイベントが関係する他のどんなバインドをもこのバインドが置き換えることを意味します。 `'+'` を使う仕方は、この関数がこのイベント型にバインドされる関数のリストに追加されることを意味しています。

例えば:

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

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

イベントのウィジェットフィールドが `turn_red()` コールバック内でどのようにアクセスされているかに注目してください。このフィールドは X イベントを捕らえたウィジェットを含んでいます。以下の表はアクセスできる他のイベントフィールドとそれらの Tk での表現方法の一覧です。Tk man ページを参照するときに役に立つでしょう。

Tk | Tkinter イベントフィールド | Tk | Tkinter イベントフィールド
--- | --- | --- | ---
%f | focus | %A | char
%h | 高さ | %E | send_event
%k | keycode | %K | keysym
%s | state | %N | keysym_num
%t | time | %T | type
%w | 幅 | %W | widget
%x | x | %X | x_root
%y | y | %Y | y_root

### index パラメータ

多くのウィジェットにはパラメータ "index" を渡す必要があります。これらはテキストウィジェット内の特定の位置や、エントリウィジェット内の特定の文字、あるいはメニューウィジェット内の特定のメニューアイテムを指定するために使用されます。

エントリウィジェットのインデックス(インデックス、ビューインデックスなど)

  エントリウィジェットは表示されているテキスト内の文字位置を参照するオプションを持っています。テキストウィジェットにおけるこれらの特別な位置にアクセスするために、次の `tkinter` 関数を使うことができます:

テキストウィジェットのインデックス

  テキストウィジェットに対するインデックス記法はとても機能が豊富で、 Tk manページでよく説明されています。

メニューのインデックス(menu.invoke()、menu.entryconfig()など)

  メニューに対するいくつかのオプションとメソッドは特定のメニュー項目を操作します。メニューインデックスはオプションまたはパラメータのために必要とされるときはいつでも、以下のものを渡すことができます:

  - ウィジェット内の数字の先頭からの位置を指す整数。先頭は 0。

  - 文字列 `"active"`。現在カーソルがあるメニューの位置を指します。

  - 文字列 `"last"` 。最後のメニューを指します。

  - `@6` のような `@` が前に来る整数。ここでは、整数がメニューの座標系における y ピクセル座標として解釈されます。

  - 文字列 `"none"`。どんなメニューエントリもまったく指しておらず、ほとんどの場合、すべてのエントリの動作を停止させるために menu.activate() と一緒に使われます。そして、最後に、

  - メニューの先頭から一番下までスキャンしたときに、メニューエントリのラベルに一致したパターンであるテキスト文字列。このインデックス型は他すべての後に考慮されることに注意してください。その代わりに、それは `last` 、 `active` または `none` とラベル付けされたメニュー項目への一致は上のリテラルとして解釈されることを意味します。

### 画像

様々な形式の画像を、それに対応する `tkinter.Image` のサブクラスを使って作成できます:

- XBM 形式の画像のための `BitmapImage` 。

- PGM, PPM, GIF, PNG 形式の画像のための `PhotoImage` 。 最後のは Tk 8.6 からサポートされるようになりました。

画像のどちらの型でも `file` または `data` オプションを使って作られます (その上、他のオプションも利用できます)。

`image` オプションがウィジェットにサポートされるところならどこでも、画像オブジェクトを使うことができます (例えば、ラベル、ボタン、メニュー)。これらの場合では、Tk は画像への参照を保持しないでしょう。画像オブジェクトへの最後の Python の参照が削除されたときに、画像データも削除されます。そして、どこで画像が使われていようとも、Tk は空の箱を表示します。

参考

The Pillow package adds support for formats such as BMP, JPEG, TIFF, and WebP, among others.

## ファイルハンドラ

Tk を使うとコールバック関数の登録や解除ができ、ファイルディスクリプタに対する入出力が可能なときに、Tk のメインループからその関数が呼ばれます。 ファイルディスクリプタ1つにつき、1つだけハンドラは登録されます。コード例です:

    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()` メソッドを使うといいです。その他のファイルには、 raw 読み込みか `os.read(file.fileno(), maxbytecount)` を使ってください。

Widget.tk.createfilehandler(file, mask, func)

  ファイルハンドラであるコールバック関数 func を登録します。 file 引数は、 (ファイルやソケットオブジェクトのような) `fileno()` メソッドを持つオブジェクトか、整数のファイルディスクリプタとなります。 mask 引数は、以下にある3つの定数の組み合わせの OR を取ったものです。コールバックは次のように呼ばれます:

      callback(file, mask)

Widget.tk.deletefilehandler(file)

  ファイルハンドラの登録を解除します。

_tkinter.READABLE
_tkinter.WRITABLE
_tkinter.EXCEPTION

  mask 引数で使う定数です。