tksimple_gui.py ライブラリの技術ドキュメント
ライブラリの機能や目的
tksimple_gui.py は、Pythonの標準GUIライブラリである tkinter を使用したグラフィカルユーザーインターフェース（GUI）の作成を簡素化するためのユーティリティライブラリです。特に、GUIウィジェットの定義と管理、ユーザー入力とプログラム変数の連携、および基本的なGUIレイアウトの構築を容易にすることを目的としています。
主な機能は以下の通りです。
宣言的なウィジェット定義: 辞書のリストを用いて、
Entry、Button、Label、Listbox、Combobox、Checkbox、Radiobutton、ファイルパス選択などの様々なウィジェットを容易に定義し、配置できます。変数との自動連携: 定義したウィジェットとプログラム内の変数を、ウィジェットタイプに応じて
StringVar、IntVar、DoubleVar、BooleanVarなどのtkinter変数を通して自動的に連携させ、ウィジェットからの入力をプログラム変数に反映させることが可能です。カスタムダイアログの簡素化:
tkinter.simpledialog.Dialogを拡張し、宣言的に定義されたウィジェットリストに基づいてカスタム設定ダイアログを簡単に作成できます。基本的なレイアウト補助: ツールバー、ペイン分割（PanedWindow）、タブ付きインターフェース（Notebook）といった一般的なGUIレイアウトの構築を補助する機能を提供します。
スクロール可能なリストボックス: 標準の
Listboxにスクロール機能を追加したtkScrolledListboxを提供します。
このライブラリは、複雑な tkinter のAPIを直接操作することなく、構造化された方法でGUIを構築したい開発者にとって有用です。特に、設定画面やデータ入力フォームなど、定型的なGUI要素を迅速に作成する場合に、コードの記述量を減らし、可読性を向上させることを目指しています。
importする方法
このライブラリを他のPythonプログラムから利用するには、通常のモジュールimport文を使用します。
import tksimple_gui
# ライブラリ内の関数やクラスを使用する例
# 例えば、tkWidgets クラスを利用する場合:
# from tksimple_gui import tkWidgets
必要な非標準ライブラリとインストール方法
このライブラリは tklib という非標準ライブラリに依存しています。
tkinter 自体はPythonの標準ライブラリですが、tksimple_gui.py は tklib.tkimport を介して tkinter をロードしています。
tklib は pip コマンドでインストールできます。
pip install tklib
importできる変数と関数
以下は、tksimple_gui.py モジュールから直接インポートできる主要な変数、関数、およびクラスです。
関数
get_window_from_plt(plt)
動作:
matplotlib.pyplotオブジェクトから、関連するtkinterウィンドウオブジェクトを取得します。これは、matplotlibのプロットをtkinterアプリケーションに組み込む際に、ルートウィンドウへの参照が必要な場合に役立ちます。引数:
plt(module):matplotlib.pyplotモジュール、またはmatplotlib.figure.Figureのマネージャーオブジェクトにアクセスできるオブジェクト。
戻り値:
tkinterのルートウィンドウオブジェクト。
show_varibles(config)
動作: 指定された
configオブジェクトの属性のうち、アンダースコア (_) で始まらず、かつcallable（関数やメソッド）ではない、そしてリストやタプルではない属性のキー、値、型を標準出力に表示します。デバッグや設定内容の確認に有用です。引数:
config(object): 表示する属性を持つ任意のオブジェクト（通常はtkParamsのインスタンス）。
戻り値:
None
update_variables(config, vars)
動作:
add_widgets関数によってconfigオブジェクトに格納されたtkinter変数（例えばtk.StringVar,tk.IntVarなど、var_プレフィックスを持つ属性）から現在の値を取得し、その値を対応するvarsオブジェクトの属性に設定します。これにより、GUIウィジェットでのユーザー入力をプログラム内の変数に反映させることができます。引数:
config(object):add_widgetsによって生成されたウィジェット変数を持つ設定オブジェクト。vars(object): ウィジェットから取得した値を設定する変数オブジェクト。
戻り値:
None
add_widgets(parent, widgets, vars=None, config=None, **kwargs)
動作: Tkinterの親ウィジェット (
parent) 内に、widgetsの定義に従って複数のGUIウィジェットを動的に追加します。ウィジェットは、辞書のリストで定義され、フレームごとにグループ化されます。varsが提供された場合、varsオブジェクトのメンバ変数の値がウィジェットの初期値として設定されます。configオブジェクトは、作成されたフレーム、ウィジェットオブジェクト、およびそれらに関連するtkinter変数を保持するために使用されます。引数:
parent(tk.Widget): ウィジェットを追加する親Tkinterウィジェット（例:tk.Frame,tk.Tk）。widgets(list of list of dict): 追加するウィジェットの定義の多次元リスト。外側のリストはフレームを表し、内側のリストは各フレーム内のウィジェットの定義辞書を含みます。各ウィジェット定義辞書は、以下のキーを持つことができます:"type"(str, 必須): ウィジェットのタイプ（"widget","button","label","entry","listbox","combobox","checkbox","radiobutton","path"）。"widget_type"(str, オプション, デフォルト:"widget"):typeが"widget"の場合に、configに格納される属性名のプレフィックス。"varname"(str, オプション): ウィジェットに関連付けられる変数の名前。configオブジェクト内ではvar_{varname}として、varsオブジェクト内では{varname}としてアクセスされます。"vartype"(str, オプション, デフォルト:"str"):entryウィジェットで変数を作成する際の変数の型（"str","float","int","bool"）。"value"(any, オプション): ウィジェットの初期値。"label"(str, オプション, デフォルト:"no text"):labelウィジェットのテキスト。"text"(str, オプション, デフォルト:"no text"):button,checkboxウィジェットのテキスト。"width"(int, オプション): ウィジェットの幅。"height"(int, オプション): ウィジェットの高さ。"command"(callable, オプション):buttonウィジェットでクリック時に実行される関数、またはpathウィジェットのボタンコマンド。"options"(list, オプション):listbox,combobox,radiobuttonウィジェットの選択肢。"sel"(int or str, オプション):listbox,combobox,radiobuttonの初期選択。"state"(str, オプション):entryウィジェットの状態（例:"readonly","disabled"）。"save_dialog"(bool, オプション, デフォルト:False):pathウィジェットでファイル選択ダイアログを保存用にするか開く用にするか。"file_types"(list of tuple, オプション, デフォルト:[("all", "*")]):pathウィジェットのファイル選択ダイアログで表示するファイルタイプ。"initial_dir"(str, オプション, デフォルト:.):pathウィジェットのファイル選択ダイアログの初期ディレクトリ。"title"(str, オプション, デフォルト:"Choose file"):pathウィジェットのファイル選択ダイアログのタイトル。"side"(str, オプション, デフォルト:"left"):packメソッドのside引数。"anchor"(str, オプション):packメソッドのanchor引数。"expand"(bool, オプション):packメソッドのexpand引数。"fill"(str, オプション):packメソッドのfill引数。
vars(object, オプション): ウィジェットの初期値として使われ、ウィジェットからの入力が格納される変数オブジェクト。デフォルトはconfigと同じ。config(tkParams, オプション): 作成されたウィジェットや関連するtkinter変数を格納するための設定オブジェクト。デフォルトは新しいtkParamsオブジェクト。**kwargs:top_frame.pack()に渡される追加のキーワード引数。
戻り値:
top_frame(tk.Frame): 全てのウィジェットを格納する最上位のフレーム。config(tkParams): ウィジェットの参照（例:button_{name}）、ウィジェットに関連付けられたtkinter変数（例:var_{varname}）、およびフレームのリスト (config.frames) を含む設定オブジェクト。
クラス
tkScrolledListbox
目的:
tkinter.Listboxに垂直スクロールバーの機能を追加したカスタムウィジェットです。継承:
tk.Listbox初期化メソッド:
__init__(self, master, **key)引数:
master(tk.Widget): このリストボックスの親ウィジェット。**key:tkinter.Listboxのコンストラクタに渡される任意のキーワード引数。
メソッド:
clear(self)動作: リストボックス内の全ての項目を削除します。
引数: なし
戻り値: なし
CustomDialog_with_config
目的:
tkinter.simpledialog.Dialogを拡張し、add_widgets関数を使用して宣言的に定義されたウィジェットに基づいて、設定入力用のカスタムダイアログを作成します。継承:
tkinter.simpledialog.Dialog初期化メソッド:
__init__(self, master, config, vars, title = None)3重引用符内ドキュメント: 「A custom dialog class that extends the simpledialog.Dialog class using config. Args: master: The parent widget for the dialog. config: An object representing the configuration. config.widgets: A list of widgets to display in the dialog. The list is a list of dictionalies of widget configurations, which refer to the variable names, types and values in vars. vars: An object of variables. title: The title of the dialog (optional).」
引数:
master(tk.Widget): ダイアログの親ウィジェット。config(object): 設定オブジェクト。このオブジェクトのconfig.widgets属性には、add_widgets関数で定義されるウィジェットのリストが含まれている必要があります。vars(object): ウィジェットからの入力値を格納するための変数オブジェクト。title(str, オプション): ダイアログのタイトル。
メソッド:
body(self, master)動作: ダイアログの本体部分を構築します。
add_widgets関数を呼び出し、self.config.widgetsに基づいてウィジェットを配置します。引数:
master(tk.Widget): ダイアログのボディとなるフレーム。
戻り値: なし
apply(self)動作: ダイアログが「OK」ボタンなどで閉じられた際に呼び出され、ダイアログ内のウィジェット（特に
entryタイプ）から現在の値を取得し、self.varsオブジェクトの対応する属性に更新します。型変換にはtklib.tkutils.pconv_by_typeが使用されます。引数: なし
戻り値: なし（
self.config.retをTrueに設定）。
tkWidgets
目的: Tkinter GUIの構築をより高レベルで抽象化し、構造化された方法でコンポーネントを追加するためのヘルパークラスです。
tkParamsオブジェクトを使用して設定と変数を管理します。継承:
tklib.tkobject.tkObject初期化メソッド:
__init__(self, parent = None, plt = None, config = None, vars = None)引数:
parent(tk.Widget, オプション): このウィジェット群が配置される親ウィジェット。plt(module, オプション):matplotlib.pyplotモジュールへの参照（get_window_from_pltで使用）。config(tkParams, オプション): 設定を保持するためのtkParamsオブジェクト。デフォルトは新しいtkParamsインスタンス。vars(tkParams, オプション): 変数を保持するためのtkParamsオブジェクト。デフォルトは新しいtkParamsインスタンス。
メソッド:
set_font(self, family = "Helvetica", size = 10, weight = "normal")動作: 親ウィジェットとその全ての子ウィジェットのデフォルトフォントを設定します。
引数:
family(str, オプション, デフォルト:"Helvetica"): フォントファミリー。size(int, オプション, デフォルト:10): フォントサイズ。weight(str, オプション, デフォルト:"normal"): フォントの太さ（"normal"または"bold"）。
戻り値: なし
add_toolbar(self, parent = None)動作: ツールバーとして使用できる
tk.Frameを追加し、上部にパックします。引数:
parent(tk.Widget, オプション): ツールバーを追加する親ウィジェット。指定がない場合は、インスタンスのself.parentを使用します。
戻り値:
tk.Frame: 作成されたツールバーフレーム。
add_paned_window(self, parent = None, width = None, sashwidth = 2)動作: 左右に分割された
tk.PanedWindowを追加し、その中に2つのtkinter.ttk.Notebookウィジェットを配置します。これにより、分割されたレイアウトでタブ付きインターフェースを簡単に構築できます。引数:
parent(tk.Widget, オプション): ペインウィンドウを追加する親ウィジェット。指定がない場合は、インスタンスのself.parentを使用します。width(int, オプション): 左側のノートブックの幅。sashwidth(int, オプション, デフォルト:2): ペインの分割線（サッシュ）の幅。
戻り値:
main_pane(tk.PanedWindow): メインのペインウィンドウ。left_notebook(ttk.Notebook): 左側のノートブックウィジェット。right_notebook(ttk.Notebook): 右側のノートブックウィジェット。
add_tab(self, parent = None)動作: タブ付きインターフェースとして使用できる
tkinter.ttk.Notebookウィジェットを親ウィジェットに追加します。引数:
parent(tk.Widget, オプション): ノートブックを追加する親ウィジェット。指定がない場合は、インスタンスのself.parentを使用します。
戻り値:
ttk.Notebook: 作成されたノートブックウィジェット。
add_page(self, notebook = None, title = "main", bg = 'dim gray')動作: 指定された
notebookウィジェットに新しいページ（タブ）を追加し、そのページ用のtk.Frameを返します。引数:
notebook(ttk.Notebook, オプション): ページを追加するノートブックウィジェット。指定がない場合は、インスタンスのself.notebookを使用します。title(str, オプション, デフォルト:"main"): ページのタブに表示されるタイトル。bg(str, オプション, デフォルト:'dim gray'): ページフレームの背景色。
戻り値:
tk.Frame: 新しく作成されたページフレーム。
get_window_from_plt(self, plt)動作:
matplotlib.pyplotオブジェクトから、関連するtkinterウィンドウオブジェクトを取得し、それをインスタンスのself.pltに設定します。これは、グローバル関数get_window_from_pltのラッパーです。引数:
plt(module):matplotlib.pyplotモジュール、またはmatplotlib.figure.Figureのマネージャーオブジェクトにアクセスできるオブジェクト。
戻り値:
tkinterのルートウィンドウオブジェクト。
add_widgets(self, parent, widgets, vars = None, config = None, **kwargs)動作: グローバル関数
add_widgetsのラッパーです。ウィジェットを追加する際に、インスタンスのself.configとself.varsをデフォルト値として使用できるようにします。引数:
parent(tk.Widget): ウィジェットを追加する親Tkinterウィジェット。widgets(list of list of dict): 追加するウィジェットの定義の多次元リスト。add_widgets関数の説明を参照してください。vars(object, オプション):add_widgetsに渡す変数オブジェクト。デフォルトはインスタンスのself.vars。config(tkParams, オプション):add_widgetsに渡す設定オブジェクト。デフォルトはインスタンスのself.config。**kwargs:add_widgetsに渡される追加のキーワード引数。
戻り値:
add_widgets関数と同じく、top_frameとconfigオブジェクト。
show_varibles(self, vars, heading = None)動作: グローバル関数
show_variblesのラッパーです。指定されたvarsオブジェクトの属性を表示します。引数:
vars(object): 表示する属性を持つ任意のオブジェクト。heading(str, オプション): 表示の前に出力される見出しテキスト。
戻り値: なし
update_variables(self, config = None, vars = None)動作: グローバル関数
update_variablesのラッパーです。ウィジェットの値をプログラム変数に更新する際に、インスタンスのself.configとself.varsをデフォルト値として使用できるようにします。引数:
config(object, オプション):update_variablesに渡す設定オブジェクト。デフォルトはインスタンスのself.config。vars(object, オプション):update_variablesに渡す変数オブジェクト。デフォルトはインスタンスのself.vars。
戻り値: なし
main scriptとして実行したときの動作
tksimple_gui.py には if __name__ == "__main__": ブロックが存在しないため、このファイルを直接Pythonインタプリタで実行しても、特別な動作は定義されていません。このファイルは、他のPythonスクリプトからインポートして利用されるライブラリとして設計されています。