:mod:`Tkinter` --- Tcl/Tk への Python インタフェース
====================================================

.. module:: Tkinter
   :synopsis: グラフィカルユーザインタフェースを実現する Tcl/Tk へのインタフェース
.. moduleauthor:: Guido van Rossum <guido@Python.org>


:mod:`Tkinter` モジュール ("Tk インタフェース") は、
Tk GUI ツールキットに対する標準の Python インタフェースです。
Tk と :mod:`Tkinter` はほとんどの Unix プラットフォームの他、
Windows システム上でも利用できます。
(Tk 自体は Python の一部ではありません。 Tk は ActiveState で保守されて\
います。)

.. note::

   :mod:`Tkinter` は Python 3.0 において :mod:`tkinter` に改名されました。
   :term:`2to3` ツールはソースの 3.0 への変換時に自動的に import を対応させます。

.. seealso::

   `Python Tkinter Resources <http://www.python.org/topics/tkinter/>`_
      Python Tkinter Topic Guide では、Tk を Python から利用する上での情報と、その他の Tk
      にまつわる情報源を数多く提供しています。

   `An Introduction to Tkinter <http://www.pythonware.com/library/an-introduction-to-tkinter.htm>`_
      Fredrik Lundh のオンラインリファレンス資料です。

   `Tkinter reference: a GUI for Python <http://infohost.nmt.edu/tcc/help/pubs/lang.html>`_
      オンラインリファレンス資料です。

   `Python and Tkinter Programming <http://www.amazon.com/exec/obidos/ASIN/1884777813>`_
      John Graysonによる解説書 (ISBN 1-884777-81-3) です。


Tkinter モジュール
------------------

ほとんどの場合、本当に必要となるのは :mod:`Tkinter` モジュールだけ\
ですが、他にもいくつかの追加モジュールを利用できます。 Tk
インタフェース自体は :mod:`_tkinter` と言う名前の\
バイナリモジュール内にあります。このモジュールに入っているのは Tk
への低水準のインタフェースであり、アプリケーションプログラマが直接使ってはなりません。
:mod:`_tkinter` は通常共有ライブラリ (や DLL)
になっていますが、 Python インタプリタに静的にリンクされていることもあります。

Tk インタフェースモジュールの他にも、
:mod:`Tkinter` には Python モジュールが数多く入っています。最も重要なモジュールは、
:mod:`Tkinter` 自体と :mod:`Tkconstants` と呼ばれるモジュール\
の二つです。前者は自動的に後者を import するので、以下のように\
一方のモジュールを import するだけで Tkinter を使えるようになります::

   import Tkinter

あるいは、よく使うやり方で::

   from Tkinter import *

のようにします。


.. class:: Tk(screenName=None, baseName=None, className='Tk', useTk=1)

   :class:`Tk` クラスは引数なしでインスタンス化します。
   これは Tk のトップレベルウィジェットを生成します。
   通常、トップレベルウィジェットはアプリケーションのメインウィンドウに\
   なります。それぞれのインスタンスごとに固有の Tcl インタプリタが関連\
   づけられます。

   .. FIXME: The following keyword arguments are currently recognized:

   .. versionchanged:: 2.4
      *useTk* パラメタが追加されました.


.. function:: Tcl(screenName=None, baseName=None, className='Tk', useTk=0)

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

   .. versionadded:: 2.4

Tk をサポートしているモジュールには、他にも以下のようなモジュールが\
あります:

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

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

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

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

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

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

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

:mod:`Tkdnd`
   :mod:`Tkinter` 用のドラッグアンドドロップのサポートです。
   実験的なサポートで、Tk DND に置き替わった時点で撤廃されるはずです。

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

これらも Python 3.0 で改名されました。新たな ``tkinter`` パッケージの\
サブモジュールになったのです。


Tkinter お助け手帳 (life preserver)
-----------------------------------

.. sectionauthor:: Matt Conway


この節は、
Tk や Tkinter を全て網羅したチュートリアルを目指している\
わけではありません。むしろ、Tkinter のシステムを学ぶ上での指針を\
示すための、その場しのぎ的なマニュアルです。

謝辞:

* Tkinter は Steen Lumholt と Guido van Rossum が作成しました。

* Tk は John Ousterhout が Berkeley の在籍中に作成しました。

* この Life Preserver は Virginia 大学の Matt Conway 他が書きました。

* html へのレンダリングやたくさんの編集は、Ken Manheimer が FrameMaker
  版から行いました。

* Fredrik Lundh はクラスインタフェース詳細な説明を書いたり\
  内容を改訂したりして、現行の Tk 4.2 に合うようにしました。

* Mike Clarkson はドキュメントをLaTeX 形式に変換し、
  リファレンスマニュアルのユーザインタフェースの章をコンパイルしました。


この節の使い方
^^^^^^^^^^^^^^

この節は二つの部分で構成されています: 前半では、背景となることがらを
(大雑把に) 網羅しています。後半は、キーボードの横に置けるような手軽な\
リファレンスになっています。

「ホゲホゲ (blah) するにはどうしたらよいですか」
という形の問いに答えよう\
と思うなら、まず Tk で「ホゲホゲ」する方法を調べてから、この\
ドキュメントに戻ってきてその方法に対応する :mod:`Tkinter` の\
関数呼び出しに変換するのが多くの場合最善の方法になります。 Python
プログラマが Tk ドキュメンテーションを見れば、たいてい\
正しい Python コマンドの見当をつけられます。従って、
Tkinter を使うには Tk についてほんの少しだけ知っていればよいと\
いうことになります。
このドキュメントではその役割を果たせないので、次善の策として、
すでにある最良のドキュメントについていくつかヒントを示しておく\
ことにしましょう:

* Tk の man マニュアルのコピーを手に入れるよう強く勧めます。
  とりわけ最も役立つのは :file:`mann` ディレクトリ内にあるマニュアルです。
  ``man3`` のマニュアルページは Tk ライブラリに対する C インタフェース\
  についての説明なので、スクリプト書きにとって取り立てて役に立つ内容\
  ではありません。

* Addison-Wesley は John Ousterhout の書いた
  Tcl and the Tk Toolkit (ISBN 0-201-63337-X) という名前の本\
  を出版しています。この本は初心者向けの Tcl と Tk の良い入門書です。
  内容は網羅的ではなく、詳細の多くは man マニュアル任せにしています。

* たいていの場合、
  :file:`Tkinter.py` は参照先としては最後の地 (last resort)
  ですが、それ以外の手段で調べても分からない場合には\
  救いの地 (good place) になるかもしれません。


.. seealso::

   `ActiveState Tclホームページ <http://tcl.activestate.com/>`_
      Tk/Tcl の開発は ActiveState で大々的に行われています。

   `Tcl and the Tk Toolkit <http://www.amazon.com/exec/obidos/ASIN/020163337X>`_
      Tcl を考案した John Ousterhout による本です。

   `Practical Programming in Tcl and Tk <http://www.amazon.com/exec/obidos/ASIN/0130220280>`_
      Brent Welch の百科事典のような本です。


簡単なHello Worldプログラム
^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

   from Tkinter import *

   class Application(Frame):
       def say_hi(self):
           print "hi there, everyone!"

       def createWidgets(self):
           self.QUIT = Button(self)
           self.QUIT["text"] = "QUIT"
           self.QUIT["fg"]   = "red"
           self.QUIT["command"] =  self.quit

           self.QUIT.pack({"side": "left"})

           self.hi_there = Button(self)
           self.hi_there["text"] = "Hello",
           self.hi_there["command"] = self.say_hi

           self.hi_there.pack({"side": "left"})


       def __init__(self, master=None):
           Frame.__init__(self, master)
           self.pack()
           self.createWidgets()

   root = Tk()
   app = Application(master=root)
   app.mainloop()
   root.destroy()


Tcl/Tk を (本当に少しだけ) 見渡してみる
---------------------------------------

クラス階層は複雑に見えますが、実際にプログラムを書く際には、アプリケーションプログラマはほとんど常にクラス階層の最底辺にあるクラスしか参照しません。

注意:

* クラスのいくつかは、特定の関数を一つの名前空間下にまとめるために\
  提供されています。こうしたクラスは個別にインスタンス化するためのもの\
  ではありません。

* :class:`Tk` クラスはアプリケーション内で一度だけインスタンス化\
  するようになっています。アプリケーションプログラマが明示的に\
  インスタンス化する必要はなく、他のクラスがインスタンス化されると\
  常にシステムが作成します。

* :class:`Widget` クラスもまた、インスタンス化して使うようには\
  なっていません。このクラスはサブクラス化して「実際の」ウィジェットを\
  作成するためのものです。(C++ で言うところの、
  '抽象クラス (abstract class)' です)。

このリファレンス資料を活用するには、Tk の短いプログラムを読んだり、
Tk コマンドの様々な側面を知っておく必要がままあるでしょう。
(下の説明の :mod:`Tkinter` 版は、
:ref:`tkinter-basic-mapping` 節を参照してください。)

Tk スクリプトは Tcl プログラムです。全ての Tcl プログラムに同じく、
Tk スクリプトはトークンをスペースで区切って並べます。
Tk ウィジェットとは、ウィジェットの *クラス* 、
ウィジェットの設定を行う *オプション* 、
そしてウィジェットに役立つことをさせる *アクション*
をあわせたものに過ぎません。

Tk でウィジェットを作るには、常に次のような形式のコマンドを使います::

   classCommand newPathname options

*classCommand*
   どの種類のウィジェット (ボタン、ラベル、メニュー、...) を作るかを表します。

*newPathname*
   作成するウィジェットにつける新たな名前です。Tk 内の全ての名前は一意\
   になっていなければなりません。一意性を持たせる助けとして、
   Tk 内のウィジェットは、ファイルシステムにおけるファイルと同様、
   *パス名 (pathname)* を使って名づけられます。
   トップレベルのウィジェット、すなわち *ルート* は ``.``  (ピリオド)
   という名前になり、その子ウィジェット階層もピリオドで\
   区切ってゆきます。ウィジェットの名前は、例えば
   ``.myApp.controlPanel.okButton`` のようになります。

*options*
   ウィジェットの見た目を設定します。場合によってはウィジェットの挙動も\
   設定します。オプションはフラグと値がリストになった形式をとります。 Unix
   のシェルコマンドのフラグと同じように、フラグの前には '-' がつ\
   き、複数の単語からなる値はクオートで囲まれます。

以下に例を示します::

   button   .fred   -fg red -text "hi there"
      ^       ^     \_____________________/
      |       |                |
    class    new            options
   command  widget  (-opt val -opt val ...)

ウィジェットを作成すると、ウィジェットへのパス名は新しいコマンドに\
なります。この新たな *widget command* は、プログラマが新たに作成した\
ウィジェットに *action* を実行させる際のハンドル (handle) に\
なります。C では someAction(fred, someOptions) と表し、
C++ では fred.someAction(someOptions) と表すでしょう。Tkでは::

   .fred someAction someOptions

のようにします。オブジェクト名 ``.fred`` はドットから始まっているので注意してください。

読者の想像の通り、 *someAction* に指定できる値はウィジェット\
のクラスに依存しています: fred がボタンなら ``.fred disable`` は\
うまくいきます (fred はグレーになります) が、fred がラベルならうまく\
いきません (Tkではラベルの無効化をサポートしていないからです)。

*someOptions* に指定できる値はアクションの内容に依存しています。
``disable`` のようなアクションは引数を必要としませんが、
テキストエントリボックスの ``delete`` コマンドのようなアクションには\
テキストを削除する範囲を指定するための引数が必要になります。


.. _tkinter-basic-mapping:

基本的な Tk プログラムと Tkinter との対応関係
---------------------------------------------

Tkのクラスコマンドは、Tkinterのクラスコンストラクタに対応しています。 ::

   button .fred                =====>  fred = Button()

オブジェクトの親 (master) は、オブジェクトの作成時に指定した新たな名前から\
非明示的に決定されます。Tkinter では親を明示的に指定します。 ::

   button .panel.fred          =====>  fred = Button(panel)

Tk の設定オプションは、ハイフンをつけたタグと値の組からなるリストで\
指定します。Tkinter では、オプションはキーワード引数にして\
インスタンスのコンストラクタに指定したり、
:meth:`config` にキーワード引数を指定して呼び出したり、インデクス指定を使って\
インスタンスに代入したりして設定します。オプションの設定については
:ref:`tkinter-setting-options` 節を参照してください。　 ::

   button .fred -fg red        =====>  fred = Button(panel, fg = "red")
   .fred configure -fg red     =====>  fred["fg"] = red
                               OR ==>  fred.config(fg = "red")

Tk でウィジェットにアクションを実行させるには、ウィジェット名を\
コマンドにして、その後にアクション名を続け、必要に応じて引数 (オプション) を続けます。
Tkinter では、クラスインスタンスのメソッドを呼び出して、
ウィジェットのアクションを呼び出します。
あるウィジェットがどんなアクション (メソッド) を実行できるかは、
Tkinter.py モジュール内にリストされています。 ::

   .fred invoke                =====>  fred.invoke()

Tk でウィジェットを packer (ジオメトリマネジャ) に渡すには、
pack コマンドをオプション引数付きで呼び出します。 Tkinter では
Pack クラスがこの機能すべてを握っていて、
様々な pack の形式がメソッドとして実装されています。
:mod:`Tkinter` のウィジェットは全て Packer からサブクラス化\
されているため、pack 操作にまつわる全てのメソッドを継承しています。 Form
ジオメトリマネジャに関する詳しい情報については
:mod:`Tix` モジュールのドキュメントを参照してください。 ::

   pack .fred -side left       =====>  fred.pack(side = "left")


Tk と Tkinter はどのように関わっているのか
------------------------------------------

上から下に、呼び出しの階層構造を説明してゆきます:

あなたのアプリケーション (Python)
   まず、 Python アプリケーションが :mod:`Tkinter` を呼び出します。

Tkinter ( Python モジュール)
   上記の呼び出し (例えば、ボタンウィジェットの作成) は、
   *Tkinter* モジュール内で実現されており、Python で書かれています。
   この Python で書かれた関数は、コマンドと引数を解析して変換し、あたかも\
   コマンドが Python スクリプトではなく Tk スクリプトから来たように\
   みせかけます。

tkinter (C)
   上記のコマンドと引数は *tkinter*  (小文字です。注意してください)
   拡張モジュール内の C 関数に渡されます。　

Tk Widgets (C and Tcl)
   上記の C 関数は、Tk ライブラリを構成する C 関数の入った別の C
   モジュールへの呼び出しを行えるようになっています。 Tk は C と Tcl
   を少し使って実装されています。
   Tk ウィジェットの Tcl 部分は、ウィジェットのデフォルト動作をバインド\
   するために使われ、Python で書かれた :mod:`Tkinter` モジュールが
   import される時点で一度だけ実行されます。(ユーザがこの過程を目にする\
   ことはありません。)

Tk (C)
   Tkウィジェットの Tk 部分で実装されている最終的な対応付け操作によって...

Xlib (C)
   Xlib ライブラリがスクリーン上にグラフィックスを描きます。


簡単なリファレンス
------------------


.. _tkinter-setting-options:

オプションの設定
^^^^^^^^^^^^^^^^

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

オブジェクトを作成する時にキーワード引数を使う
   ::

      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 マニュアルの :manpage:`options(3)` にあります。

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

あるウィジェットがどんなオプションをサポートしているかは、ウィジェット\
の man マニュアルにリストされています。また、実行時にウィジェットの
:meth:`config` メソッドを引数なしで呼び出したり、
:meth:`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
^^^^^^

.. index:: single: packing (widgets)

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

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

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

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

   fred.pack()                     # デフォルトでは、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`` があります。
この関連付けは双方向に働きます: 変数の値が何らかの理由で\
変更されると、関連付けされているウィジェットも更新され、新しい値を\
反映します。

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

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

例えば::

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

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

           # アプリケーション変数です
           self.contents = StringVar()
           # 変数の値を設定します
           self.contents.set("this is a variable")
           # エントリウィジェットに変数の値を監視させます
           self.entrythingy["textvariable"] = self.contents

           # ユーザがリターンキーを押した時にコールバックを呼び出させます
           # これで、このプログラムは、ユーザがリターンキーを押すと
           # アプリケーション変数の値を出力するようになります。
           self.entrythingy.bind('<Key-Return>',
                                 self.print_contents)

       def print_contents(self, event):
           print "hi. contents of entry is now ---->", \
                 self.contents.get()


ウィンドウマネジャ
^^^^^^^^^^^^^^^^^^

.. index:: single: window manager (widgets)

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

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

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

   from Tkinter import *
   class App(Frame):
       def __init__(self, master=None):
           Frame.__init__(self, master)
           self.pack()


   # アプリケーションを作成します
   myapp = App()

   #
   # ウィンドウマネジャクラスのメソッドを呼び出します。
   #
   myapp.master.title("My Do-Nothing Application")
   myapp.master.maxsize(1000, 400)

   # プログラムを開始します
   myapp.mainloop()


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

.. index:: single: Tk Option Data Types

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
   色は rgb.txt ファイルの X カラーの名前か、
   または RGB 値を表す文字列として与えられます。
   RGB 値を表す文字列は、4ビット: ``"#RGB"``, 8
   bit: ``"#RRGGBB"``, 12 bit" ``"#RRRGGGBBB"``, あるいは、16 bit
   ``"#RRRRGGGGBBBB"`` の範囲を取ります。
   ここでは、R,G,Bは適切な十六進数ならどんなものでも表します。
   詳細は、Ousterhout の本の160ページを参照してください。

cursor
   :file:`cursorfont.h` の標準Xカーソル名を、接頭語 ``XC_``
   無しで使うことができます。
   例えば、handカーソル(:const:`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
   これはほとんど常にスクロールバー・ウィジェットの :meth:`!set` メソッドですが、
   一引数を取るどんなウィジェットメソッドでもあり得ます。例えば、
   Python ソース配布の :file:`Demo/tkinter/matt/canvas-with-scrollbars.py`
   ファイルを参照してください。

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


バインドとイベント
^^^^^^^^^^^^^^^^^^

.. index::
   single: bind (widgets)
   single: events (widgets)

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

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

ここでは:

sequence
   は対象とするイベントの型を示す文字列です。
   (詳細については、bind の man ページと
   John Ousterhout の本の201ページを参照してください。)

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

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

例えば::

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

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

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

   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


index パラメータ
^^^^^^^^^^^^^^^^

たくさんのウィジェットが渡される"index"パラメータを必要とします。
これらはテキストウィジェットでの特定の場所や、
エントリウィジェットでの特定の文字、あるいは、
メニューウィジェットでの特定のメニュー項目を指定するために使われます。

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

   AtEnd()
      テキストの最後の位置を参照します

   AtInsert()
      テキストカーソルの位置を参照します

   AtSelFirst()
      選択されたテキストの先頭の位置を指します

   AtSelLast()
      選択されているテキストおよび最終的に選択されたテキストの末尾の位置を示します。

   At(x[, y])
      ピクセル位置 *x*, *y* (テキストを一行だけ含むテキストエントリウィジェット\
      の場合には *y* は使われない)の文字を参照します。

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

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

  * 頭から数えられ、0で始まるウィジェットの数字の位置を指す整数。

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

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

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

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

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


画像
^^^^

Bitmap/Pixelmap 画像を :class:`Tkinter.Image` のサブクラスを使って作ることができます:

* :class:`BitmapImage` は X11 ビットマップデータに対して使えます。

* :class:`PhotoImage` は GIF と PPM/PGM カラービットマップに対して使えます。

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

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