"tkinter" --- Tcl/Tk の Python インターフェース
***********************************************

**ソースコード:** 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* 引数で使う定数です。
