Pythonまとめ(PySimpleGUI)
PythonでGUIを扱うときによく使うものがtkinterとPySimpleGUIがある。本稿ではPySimpleGUIの基本についてまとめる。
ライセンスとバージョンについて
PySimpleGUIはバージョン5からライセンスが変わりました。商用が有償となり、個人利用でもライセンス登録が必要です。なお、本記事はバージョン4.60で動作確認をしています。
この変更を受けてMITライセンスのTkEasyGUIがクジラ飛行机さんにより作成・公開されています。PySimpleGUIとよく似た構文で利用できるので、TkEasyGUIも検討してみてください。私が少し触ってみたときの記事もあります。
PySimpleGUI
PySimpleGUIはGUIライブラリtkinterを簡単に使えるようにしたラッパーライブラリである。簡単なGUIならPySimpleGUIで十分に対応できる。
基本的な書き方
サンプルを元にPySimpleGUIの基本的な仕組みを示す。
サンプル(1)

概要
これはメッセージを表示するだけのウィンドウのサンプルプログラムである。
はじめに、画面に表示するエレメントのレイアウトを作成する。レイアウトは、行ごとのリスト形式で指定する。
次に作成したレイアウトのリストを引数にWindowを作成し、read()メソッドを呼びだす。readメソッドは、GUIを表示し、イベントを読み込む。
window.readメソッドでclose引数をTrueにすると、readメソッドが終了したとき(すなわち何らかのイベントが発生したとき)に自動でwindowを閉じる。このサンプルでは閉じるボタンを押すとイベントが発生してウィンドウが閉じる。
サンプル(2)

概要
これはサンプル(1)とは異なり、ユーザの入力を受け取ったり、クリックなどイベントに応じた処理を行うサンプルである。このサンプルのポイントはwindow.read()でclose=Trueを指定していないことと、無限ループ(いわゆるイベントループ)でwindow.read()を繰り返し実行していることである。
readメソッドは通常、発生したイベントと状態を表す値のタプル(event, value)を返す。ループ内でこの値に応じた処理を行う。この例では3行目のボタンが押されたときの戻り値は('-buttonpush-', value)となり、'-buttonpush-'イベントが発生したことがわかる。
イベントの処理が終わると、無限ループで再びwindow.readに戻り、次のイベントの発生を待機する。このサンプルではウィンドウ右上の閉じるボタンをおしたときにbreakに到達し、無限ループが終了する。
キー
GUI上に表示するエレメントには識別可能な名前を付与できる。イベントの発生元エレメントを識別したり、エレメントの値を取得あるいは更新したりするときに使用する。たとえばsg.Button("Push", key="button1")
であればbutton1というキーのButtonエレメントが作成され、このボタンが押されたときのイベント名はbutton1になる。
PySimpleGUIの公式としてはキーの文字列は統一性の観点から'-キー名-'
のようにハイフンで囲まれたキー名を使用することを推奨している。キーを指定しなかった場合は、定義順に割り振られる番号であったり、ボタンのようにテキスト属性を持つ場合はそのテキストが使われたりする。
操作 | サンプル | 補足 |
---|---|---|
エレメントの取得 | window[key] | windowはsg.Windowオブジェクト |
値の取得 | value[key] | valueはwindow.read()で返される値(event,value) |
文字列以外のキー
キーは文字列が多く使われるが、タプルやオブジェクトも指定できる(リストは不可)。オブジェクトをキーとして使用するサンプルを示す。このサンプルではキーとして使うオブジェクトにイベントを処理するメソッドをもたせる実装である。オブジェクトをうまく使うことでイベントループの処理を簡潔に書けるケースがあるかもしれない。

イベント
window.readメソッドはGUIのイベントを読み込むメソッドである。テキストボックスのテキストが更新されたり、ボタンが押されたりすると、イベントが発生して、window.readメソッドが終了する。どういうときにイベントが発生するかはエレメントごとに異なる。
タイムアウトイベント
window.readメソッドでタイムアウトを設定すると、一定時間イベントが発生しなかったときにタイムアウトイベントが発生する。これはユーザ操作の有無によらず更新が必要な処理をするときなどに便利である。たとえば、以下は今の時間を表示するサンプルである。時間を更新するために100ミリ秒ごとにタイムアウトを発生させている。

アップデート
エレメントの値や状態を更新する場合はupdateメソッドを使用する。update()で設定した値は次のwindow.read()が呼び出されたときに反映される。もし、それより先に反映したいならwindow.refreshメソッドを呼び出す。updateで何が指定できるかはエレメントにより異なる。
updateの使用例は1つ上のタイムアウトの項目のサンプルを参照すること。
ロングタスク
長い時間がかかる処理をイベントループで行うと、その間GUIの処理が行われなくなり、プログラムがハングアップしたように見える。以下に例を示す。
ボタンを押すと、もう一度ボタンをクリックしたり、ウィンドウをドラッグで移動したりできなくなり、場合によってはウィンドウがホワイト・アウトする。この状態が処理が終わる(この例では10秒経過する)まで続く。


このような時間がかかる処理は、イベントループの処理を止めることなく行う必要がある。これには(1)PySimpleGUIの持つwindow.perform_long_operationメソッドを使用する方法や、(2)自身で別スレッドで処理を行う方法がある。
window.perform_long_operationを使用する方法
windowが持つperform_long_operationメソッドを使って、長い処理を自動で別スレッドで実行できる。処理が終了するとend_keyで指定したイベントが発生する。関数の戻り値はvalue[end_key]で取得できる。
スレッドを使用する方法
PySimpleGUIの機構に頼らず、単純に別スレッドを作成して長い処理を実行しても問題ない。この方法ではイベントが発生しないため、必要なら次の「進捗・完了の通知」に記載の方法で手動でイベントを発生させる。
進捗・完了の通知
window.write_event_valueメソッドを使うとイベントキューにイベントを登録でき、処理の進捗や完了を通知できる。プログレスバーで進捗を表示するサンプルを示す。

これはRunボタンを押すと選択された回数だけタスク処理を行うプログラムである。Runボタンを押すと-run-イベントが発生する。-run-イベント発生時はタスクを行う回数を読み取り、do_taskでタスクを実行するとともに、window["progress"].update(current_count=0, max=times)
でプログレスバーの現在の値を0に、上限値をタスクを行う回数にリセットする。
実際にタスクを行っているdummytask関数ではwindow.write_event_valueメソッドでWindowに進捗を通知する。進捗を通知するときはイベント名を-update-progress-とし、イベントの値は完了したタスクの回数にしている。
すると、通常はすぐにmain関数側で-update-progress-イベントが発生する。-update-progress-イベントが発生したときは、valueに完了したタスクの回数が格納されているので、その値をプログレスバーに反映させている。
テーマ
PySimpleGUIには色の組み合わせがテーマとして多数用意されている。sg.theme_previewer()で確認できる。

適用するには最初にsg.theme(使うテーマ名)を実行すれば良い。

テーマのカスタマイズ
既存のテーマの一部設定を変えるにはsg.theme...で始まるメソッドから変えたいものを探して実行する。ボタンの文字色を黒に変えるサンプルを示す。

独自テーマの作成
テーマは辞書型で定義されている。辞書を登録することで独自テーマが使用できる。詳細は公式サイトのサンプルを参照すること。
エレメント
PySimpleGUIではテキストボックスのようなUIの各要素をエレメントと呼ぶ。
汎用的なパラメータ
以下のパラメータは多くのエレメントで使用できる。
パラメータ名 | 意味 |
---|---|
key | エレメントを識別するキー名。 省略名のパラメータkも利用できる。 |
tooltip | マウスホバー時に表示するツールチップのテキスト |
size | (width, height)のタプル。通常は幅は文字数で高さは行数だが、画像などエレメントによってはピクセル指定の場合もある。 またあるしきい値以上の大きな値が指定された場合もピクセル値として処理される。 なお、高さが1の場合は省略して幅だけ指定することもできる。 省略名のパラメータsも利用できる。 |
font | タプル(フォント名, フォントサイズ, 装飾)でフォントを指定。装飾として使えるのは斜体(italic)、太字(bold)、装飾なし(normal)、下線(underline)、取り消し線(overstrike)。 |
colors | 色名または#RRGGBB形式の色指定 |
pad | 余白。デフォルト値は(5,3)で左右が5ピクセル、上下が3ピクセルである。 左右または上下で別々の値を指定するには((左,右),(上,下))のようにする。 また、タプルではなく単独の値を指定すると左右上下おなじ余白になる。 |
enable_events | エレメント固有のイベントを有効にする。どの様なイベントが有効になるかはエレメントにより異なる。 |
visible | エレメントの可視性を指定 |
disabled | ユーザが入力や選択できるエレメントで指定可能。 Trueの場合、エレメントがグレーアウトするなど、表示はされているものの操作を受け付けない状態となる。 |
right_click_menu | 右クリックしたときにメニュー(コンテキストメニュー)を表示する |
フォント名の補足
フォント名は英語の名前を指定しなければならない。Windowsで標準インストールされているフォントはWindows 11 font listに記載がある。いくつかのフォントを指定する例を示す。

コンテキストメニューの定義

エレメントを右クリックしたときのメニュー(通称コンテキストメニュー)はright_click_menuパラメータで指定する。上の画像の場合は以下のように定義している。Menuエレメントとよく似た書式を使う。
メニューの定義は["", [コンテキストメニューの項目] ]
という形式である。項目にリストがあると、それは直前の項目の子項目という扱いになる。他に、!で始まる項目は無効化された状態になる、&に続く文字はキーボードショートカットとして利用できるなどがある。::keyについてはMenuエレメントの項目を参照。
ユーザに入力や選択を求めるエレメント

Input
一行の入力可能なテキストボックス。

パラメータ名 | デフォルト値 | 意味 |
---|---|---|
password_char | "" | 指定された場合、 入力した文字はすべてpassword_charで表示される。パスワード入力のテキストボックス用。 |
justification | None | テキストボックス内のテキストの配置。left, right, centerのいずれか。 |
enable_events | False | Trueにするとテキストボックスの内容が更新されるたびにイベントが発生する。 |
readonly | False | Trueの場合、ユーザはテキストボックスを更新不可能になる。 ただしテキストの選択はできる。 |
use_readonly_for_disable | True | Trueの場合、disabled=Trueのときにreadonly状態となり、変更はできないがテキストの選択はできるようになる。 Falseの場合は、disabled=Trueのときに、変更もテキストの選択もできない。 |
Multiline
複数行入力可能なテキストボックス。

パラメータ名 | デフォルト値 | 意味 |
---|---|---|
enter_submits | False | Trueの場合、Enterキーが入力されたときにイベントが発生する。 |
autoscroll | False | テキストボックスにデータが追加されたときに自動でスクロールする。 |
autoscroll_only_at_bottom | False | テキストボックスにデータが追加されたときに「スクロールバーが最下端のときだけ」自動でスクロールする。 |
horizontal_scroll | False | Trueの場合、水平方向のスクロールバーを表示する。 |
enable_events | False | Trueの場合、キー入力のたびにイベントが発生する。 |
justification | None | テキストボックス内のテキストの配置。left, right, centerのいずれか。 |
writeonly | False | Trueの場合、windows.readメソッドが返すvalueにこのエレメントの値が含まれなくなる。 これはこのエレメントを出力専用で利用し、イベント処理中にこのエレメントの値が不要な場合に用いる。 |
reroute_stdout | False | Trueの場合、標準出力への出力をこのエレメントに出力する。 |
reroute_stderr | False | Trueの場合、標準エラー出力への出力をこのエレメントに出力する。 |
Combo
ドロップダウンリストから選択可能なテキストボックス。自由入力も可能だが、できない設定もできる。

パラメータ名 | デフォルト値 | 意味 |
---|---|---|
enable_events | False | Trueの場合、選択されたときにイベントが発生する。 |
enable_per_char_events | False | Trueの場合、キー入力のたびにイベントが発生する。 |
readonly | False | Trueの場合、自由入力不可(選択肢からの選択のみ)になる。 |
Spin
上下ボタンで選択肢を変えるテキストボックス。自由入力も可能だが、できない設定もできる。

パラメータ名 | デフォルト値 | 意味 |
---|---|---|
enable_events | False | Trueの場合、選択されたときにイベントが発生する。 |
readonly | False | Trueの場合、自由入力不可(選択肢からの選択のみ)になる。 |
Radio
選択肢から1つを選ぶラジオボタン。選択肢グループが同じラジオボタンは1つしか選択できない。

パラメータ名 | デフォルト値 | 意味 |
---|---|---|
enable_events | False | Trueの場合、選択肢が選択されたときにイベントが発生する。 |
CheckBox
選択肢から複数を選ぶチェックボックス。

パラメータ名 | デフォルト値 | 意味 |
---|---|---|
enable_events | False | Trueの場合、選択状態が変化したときにイベントが発生する。 |
ListBox
多肢選択(複数選択可能)なリストボックス。

パラメータ名 | デフォルト値 | 意味 |
---|---|---|
select_mode | sg.LISTBOX_SELECT_MODE_SINGLE | 選択モード。以下のいずれか。 sg.LISTBOX_SELECT_MODE_SINGLE(単一選択) sg.LISTBOX_SELECT_MODE_MULTIPLE(選択肢をクリックするたびに選択状態が切り替わる) sg.LISTBOX_SELECT_MODE_BROWSE(単一選択? 詳しい情報なし) sg.LISTBOX_SELECT_MODE_EXTENDED(CtrlやShiftを押しながらクリックで範囲選択) |
enable_events | False | Trueの場合、選択肢がクリックされたときにイベントが発生する。 |
justification | left | ボックス内のテキストの配置。left, right, centerのいずれか。 |
no_scrollbar | False | Trueの場合、スクロールバーを表示しない。 |
horizontal_scroll | False | Trueの場合、水平方向のスクロールバーを表示する。 |
Slider
指定範囲の数値から値を選択するスライダー。

パラメータ名 | デフォルト値 | 意味 |
---|---|---|
disable_number_display | False | Trueの場合、現在の値を表示しない。 |
enable_events | False | Trueの場合、スライダーが移動されたときにイベントが発生する。 |
ボタン
Button
押すことでイベントが発生し、処理のトリガーとなるエレメント。

パラメータ名 | デフォルト値 | 意味 |
---|---|---|
button_type | None | ボタンのタイプを指定するものだが、Buttonでは使用すべきでない。 |
image_source image_filename image_data | None | ボタンに画像を表示する。 他にimage_sizeで画像のサイズをimage_subsampleで縮小率、image_zoomで拡大率を指定できる。 |
use_ttk_buttons | None | Trueの場合、テーマ付きButtonを使用する。 |
特別な機能を持つ予め定義されたButton
PySimpleGUIではファイル選択やカレンダーによる日付ピックなどの機能があらかじめついたボタンが用意されている。
CalendarButton
カレンダーから日付選択できるボタン。このボタンはイベントを発生しない。選択された日付はtargetのエレメントに出力される。

パラメータ名 | デフォルト値 | 意味 |
---|---|---|
target | None | 選択された日付を設定するInputやTextなどのエレメント。 |
format | None | 日付の書式。 |
close_when_date_chosen | True | Trueの場合、日付をクリックすると決定する。Falseの場合、日付をクリックし、OKボタンを押すと決定する。 |
default_date_m_d_y | (None,None,None) | 最初に選択されている年月日 |
locale | None | 曜日に適用するロケール。ja-jpで曜日が日本語になる。 |
day_abbreviations | None | 曜日の表示名を個別に指定する。デフォルトではSun、Mon、…だが[*"日月火水木金土"] を指定すると日本語表記になる |
begin_at_sunday_plus | 0 | 週の始まりの曜日。日曜日を基準として0=日曜日、1=月曜日、…、6=土曜日。 |
month_names | None | 月名。デフォルトではJanuary、February、…だが[ f"{x}月" for x in range(1,13) ] とすると1月、2月…という日本語表記になる |
ColorChooserButton
パレットから色を選択できるボタン。このボタンはイベントを発生しない。

パラメータ名 | デフォルト値 | 意味 |
---|---|---|
target | None | 選択された色を反映するInputやTextなどのエレメント。#RRGGBBフォーマット。 |
SaveAs、FileSaveAs、FileBlowse、FilesBrowse、FolderBrowse
ファイルやフォルダを選択するダイアログを表示するボタン。このボタンはイベントを発生しない。
SaveAsとFileSaveAsは同じであり、ファイルの保存先を選択するときにつかうダイアログが表示される。FileBlowseとFilesBrowseはファイルを開くときにつかうダイアログが表示される。違いはファイルを複数選択できるかどうかである。FolderBrowseはフォルダを選択するときに使うダイアログが表示される。
いずれも選択されたファイルやフォルダはtargetに設定されたInputやTextなどのエレメントに出力される。
パラメータ名 | デフォルト値 | 意味 |
---|---|---|
target | None | 選択されたファイル、フォルダを入力するInputやTextなどのエレメント。 |
initial_folder | None | 最初に開くフォルダ。デフォルトは最後に使用したフォルダになる。 |
file_types ※FolderBrowse以外 | (('All Files','.*'),) | 表示するファイルのフィルターリスト |
default_extension ※SaveAs、FileSaveAsのみ | None | ファイル名が拡張子なしのときに自動で付与する拡張子 |
files_delimiter ※FilesBrowseのみ | ';' | 複数ファイルが選択されたときの区切り文字 |
RealtimeButton
押されている間イベントが発生し続けるボタン。通常のボタンはボタンを押して離したときに1回だけイベントが発生するが、RealTimeButtonは長押しするとイベントが何回も発生する。
CloseButton、DummyButton
押すとウィンドウを閉じるボタン。CloseButtonは通常のボタンと同様にイベントが発生するが、DummyButtonはイベントが発生しない。
よく使う予め定義されたButton
OKボタンやキャンセルボタンのようによく使うボタンが予め定義されている。基本的にはデフォルトのテキストが指定されている形で、ボタンの動作の変化は多分ない。ここではリストのみ示す:sg.Cancel、sg.Exit、sg.Help、sg.No、sg.OK、sg.Ok、sg.Open、sg.Quit、sg.Submit、sg.Save、sg.Yes
データの表示に関するエレメント
Image
画像を表示するエレメント。GIFかPNGのみ。
パラメータ名 | デフォルト値 | 意味 |
---|---|---|
subsample | None | 画像データの間引き度合い。 2の場合、ピクセル2個につき1ピクセルのデータを取り出すことを意味し、画像のサイズが元々の50%となる。 ※Xの場合、画像のサイズは1/X倍になる。 |
enable_events | False | Trueの場合、画像がクリックされたときにイベントが発生する。 |
公式サイトにはzoomオプションが有るように書いているが、Ver.4.60.5ではエラーとなった。
Graph
独自座標系を持つキャンバス。

この例ではキャンバスのサイズは(200,200)だが、キャンバスになにか描画するときはキャンバスの左下が(-10,-5)、右上が(10,15)の座標系で位置を指定する。キャンバスに描画するメソッドとしてdraw_xxxxが用意されている。なおGraphエレメントは同じ機能を持つメソッドが2つあるケースが有る。たとえば点を描画するDrawPointとdraw_pointである。これはPEP8のコーディング規約に準ずるようにメソッドを追加したためであり、将来的に廃止される可能性があるDrawPointは使用するべきでない。
描画オブジェクト | サンプル |
---|---|
点 | graph.draw_point((30,100), size=4, color="red") |
直線 | graph.draw_line( (10,90), (50,90), color="grey", width=2 ) |
連続する線 | graph.draw_lines( [(10,80), (20,80), (80,90)], color="orange", width=3 ) |
四角形 | graph.draw_rectangle( (70,100), (80,80), fill_color="#aacc66", line_color="red", line_width=1 ) |
多角形 | graph.draw_polygon( [(10,70), (30,70), (80,60), (20,60)], fill_color="lightblue" ) |
円 | graph.draw_circle( (50,50), radius=7, fill_color="pink", line_width=0 ) |
楕円 | graph.draw_oval( (10,50), (30,40), fill_color="black" ) |
扇形、円弧 | graph.draw_arc( (60,50), (90,30), extent=50, start_angle=40, fill_color="blue" ) |
テキスト | graph.draw_text("TEXT", location=(10,30), text_location=sg.TEXT_LOCATION_BOTTOM_LEFT) |
画像 | graph.draw_image( data=sg.ICON_BUY_ME_A_COFFEE, location=(10,30) ) graph.draw_image( filename="ファイル名", location=(10,30) ) |

draw_xxxメソッドは戻り値としてオブジェクトのIDを返す。そのIDを使用してオブジェクトを移動したり、削除したりできる。
操作 | メソッド |
---|---|
削除 | delete_figure( ID ) |
移動 | move_figure( ID, deltaX, deltaY) |
再配置 | relocate_figure( ID, X, Y) |
前後関係 | send_figure_to_back( ID ) bring_figure_to_front( ID ) |
ボタンを押すたびにランダムに円を描画する例を示す。

Canvas
tk.Canvasのラッパー。tk_canvasプロパティでtk.Canvasが取得できるので、それに対して操作が行える。
Table
データを表組みで表示するエレメント。

パラメータ名 | デフォルト値 | 意味 |
---|---|---|
enable_events | False | Trueの場合、行の選択状態が変化したときにイベントが発生する。value[event]にはクリック後に選択状態にある行の番号が含まれる。 選択モードで選択不可(none)の場合はこのイベントは発生しない。 |
enable_click_events | False | Trueの場合、行がクリックされたときにイベントが発生する。このイベントがenable_eventsよりも先に発生する。eventは(キー名、'+CLICKED+', (クリックされた行,列) ) となり、value[event]にはクリック前に選択状態にある行の番号が含まれる |
num_rows | None | 一度に表示する行数。 Tableではsizeパラメータの使用は禁止となっている。 |
auto_size_columns | True | Trueの場合、列の幅を自動的に決定する。 |
col_widths | None | 各列の幅を指定する。auto_size_columnsがTrueの場合は無視される。 |
display_row_numbers | False | 行番号を表示する。 starting_row_numberで始まりの番号を指定でき、デフォルトは0。 |
Tableは見た目関連のプロパティがかなり多いため、公式サイトを参照すること。
Tree
木構造のデータを表示するエレメント。木構造にはTreeDataクラスを使う。

単純な木構造だけでなく、Tableと組み合わせた様な表示もできる。Table表示の部分はvaluesで指定する。

パラメータ名 | デフォルト値 | 意味 |
---|---|---|
enable_events | False | Trueの場合、行がクリックされたときにイベントが発生する。value[event]にはクリック後に選択状態にある行の番号が含まれる。 選択モードで選択不可(none)の場合はこのイベントは発生しない。 |
num_rows | None | 一度に表示する行数。 Tableではsizeパラメータの使用は禁止となっている。 |
auto_size_columns | True | Trueの場合、列の幅を自動的に決定する。 |
col_widths | None | 各列の幅を指定する。auto_size_columnsがTrue(デフォルト)の場合は無視される。 |
col0_width | 10 | 左端列の幅を指定する。 |
エレメントの配置に関するエレメント
Frame
複数のエレメントを一つにまとめて枠で囲むエレメント。

Column
複数のエレメントを1つにまとめるエレメント。

Tab / TabGroup
タブでページを切り替えられるエレメント

Tabではタブの見出しとタブの中のレイアウトを指定する。タブの見出しはタブグループの中で重複していないこと。
TabGroupのレイアウトとして作成したタブを指定する。このレイアウトは他のエレメントとは異なりList[List[Tab]]形式である。
パラメータ名 | デフォルト値 | 意味 |
---|---|---|
tab_location | None | タブの表示位置。以下のいずれか。 上側:top、topleft、topright 下側:bottom、bottomleft、bottomright 左側:left、lefttop、leftbottom 右側:right、righttop、rightbottom |
enable_events | False | Trueの場合、タブが切り替えられたときにイベントが発生する。value[event]には新しく選択されたタブのキーが含まれる。 |
なお、tabgroup.find_key_from_tab_nameメソッドでタブの見出しからキーを取得できる。
Separator
区切り線を描くエレメント。線の方向によりVerticalSeparatorとHorizontalSeparatorの2つがある。

Push
他のエレメントを押し出すように伸び縮みするエレメント(のようなもの)。伸び縮みの方向によりPushとVPushがある。

ウィンドウに関するエレメント
Window
1つのウィンドウを表すエレメント。下表にウィンドウに関わる主なパラメータを示す。これ以外にウィンドウ内のエレメントのデフォルト値を指定するパラメータなども用意されている。
パラメータ名 | デフォルト値 | 意味 |
---|---|---|
location | (None, None) | ウィンドウを表示する位置 |
relative_location | (None, None) | ウィンドウを表示する位置。locationからrelative_locationの値の分だけずらす。 |
margins | (None, None) | ウィンドウ内部の余白。 |
auto_close | False | Trueの場合、ウィンドウが自動で閉じる。auto_close_durationで閉じるまでの秒数を指定できる。デフォルトは3秒。 |
keep_on_top | None | Trueの場合、他のウィンドウより常に上に表示される。 |
alpha_channel | None | ウィンドウの透過性を指定する。1が可視、0が透明。 |
grab_anywhere | False | Trueの場合、ウィンドウのどこでも(Inputなどの一部を除く)マウスクリックで掴んで動させられる。 |
grab_anywhere_using_control | True | Trueの場合、ウィンドウをCtrl+マウスクリックで掴んで移動させられる。 |
resizable | False | Trueの場合、ウィンドウのサイズを変更できる。 |
disable_close | False | Trueの場合、ウィンドウを閉じられなくなる。 |
disable_minimize | False | Trueの場合、ウィンドウが最小化しなくなる。 |
modal | False | Trueの場合、モーダルウィンドウになる。 |
use_custom_titlebar | None | Trueの場合、標準のタイトルバーをカスタムされたタイトルバーを使用する。カスタムには以下のパラメータが使用できる。 titlebar_background_color titlebar_text_color titlebar_font titlebar_icon(file or base64 bytes) |
return_keyboard_events | False | Trueの場合、キーが押されたときにイベントが発生する。イベント名は押されたキーになる。 |
Menu
windowの上側にメニューを表示するエレメント。

メニューは[ 見出し, [見出し配下の項目] ]という形式で定義する。サンプルのExport Asのように入れ子にすることもできる。例のOpenのように!で始まる項目は無効化された状態になる。
&に続く文字はキーボードショートカットとして利用できるようになる。サンプルでAltキーを押すと以下のようにFileのFにアンダーラインが引かれ、ショートカット文字を示してくれる。

項目のキー
メニューの項目を選択するとイベントが発生する。このときのイベント名は項目名が使われる。たとえば、メニューの中からFile→Openをユーザが選択した場合、Openイベントが発生する。項目名はユーザが見てわかるようなテキストとなるため、イベント名としては使いづらいことがある。そこで項目名に「::」に続けてキーを記載することができる。たとえば"Open::Menu-File-Open"のようにメニューの項目を定義すると、画面上に表示される項目としては「Open」となり、選択するときに発生するイベント名としては「Open::Menu-File-Open」となる。
event='Open::Menu-File-Open'
value={0: 'Open::Menu-File-Open'}
StatusBar
windowの下側で状態を表すテキストを表示するエレメント。

このサンプルではStatusBarのパラメータauto_size_textにFalseを指定している。デフォルト値のままだと、最初に指定したテキストに応じて横幅が決定されるようで、以下のようにテキストを更新したときに画面上で途切れて見えることがあった。auto_size_textをFalseにすることで解消できている。

ポップアップ
ポップアップは事前に定義されたダイアログウィンドウである。ポップアップはエレメントではなくウィンドウを表示するメソッドである。
popup
すべてのポップアップの基本となるメソッド。基本的にはこのメソッドを直接使用しないが、パラメータは他のpopupと共通のものが多いため記載する。
パラメータ名 | デフォルト値 | 意味 |
---|---|---|
*args | ポップアップに表示するテキスト。可変長引数で複数指定した場合は改行して表示される。 | |
title | ポップアップのタイトル。省略した場合はargs[0]。 | |
button_color | None | ボタンの色。背景色を指定するか、(文字色,背景色)とタプルで指定する。 |
text_color | None | テキストの色。 |
auto_close | False | Trueの場合、ウィンドウが自動で閉じる。auto_close_durationで閉じるまでの秒数を指定できる(デフォルトは3秒)。 |
keep_on_top | None | Trueの場合、他のウィンドウより常に上に表示される。 |
non_blocking | False | Trueの場合、ポップアップの終了を待つことなくpopup関数が終了する。 |
grab_anywhere | False | Trueの場合、ポップアップのどこでもマウスクリックで掴んで動させられる。 |
line_width | MESSAGE_BOX_LINE_WIDTH | ポップアップに表示するテキストの最大幅。最大幅を超えるテキストは改行して表示される。 デフォルトはMESSAGE_BOX_LINE_WIDTHで定義された値となる。 |
no_titlebar | False | Trueの場合、タイトルバーを表示しない。タイトルバーにある閉じるボタンも表示されないので注意。 |
location | (None,None) | ポップアップの表示位置を指定する。指定しない場合は通常は画面中央となる。 |
relative_location | (None,None) | ポップアップの表示位置をlocationからの相対位置で指定する。 |
modal | False | Trueの場合、モーダルウィンドウになる。 |
custom_text | None | ポップアップに表示するボタンのテキストをカスタマイズする。文字列strまたは文字列のタプル(str, str)。 タプルの場合は複数のボタンのテキストをそれぞれ指定する。 |
any_key_closes | False | Trueの場合、ポップアップがアクティブな状態でキー入力があるとポップアップを閉じる。 |
様々なポップアップ
ポップアップを表示するメソッドは多数用意されている。ボタンを押すとポップアップが表示されるサンプルプログラムを示す。

用意されたポップアップは、よく使われるボタンが用意されたポップアップ、自動で閉じるポップアップ、ブロックしないポップアップ、特殊な機能を持つポップアップなど多岐にわたる。
メソッド名 | 説明 |
---|---|
popup_ok | OKボタンを持つポップアップ。戻り値は押したボタンのテキスト。 |
popup_ok_cancel | OKボタンとCancelボタンを持つポップアップ。戻り値は押したボタンのテキスト。 |
popup_cancel | Cancelボタンを持つポップアップ。戻り値は押したボタンのテキスト。 |
popup_yes_no | YesボタンとNoボタンを持つポップアップ。戻り値は押したボタンのテキスト。 |
popup_error | 強調されたErrorボタンを持つポップアップ。戻り値は押したボタンのテキスト。 |
popup_no_buttons | ボタンを持たないポップアップ。戻り値は通常None。 |
popup_no_titlebar | タイトルバーを持たず、OKボタンを持つポップアップ。 button_typeで表示するボタンを指定できる。 |
popup_get_date | 日付選択のためのカレンダーをポップアップ。戻り値は(月,日,西暦)のタプル。 start_mon, start_day, start_year:初期に選択された日付 month_names:月の表示名。デフォルトではJan、Feb、...。month_names=[ f"{x}月" for x in range(1,13) ]とすると日本語表記になる。 begin_at_sunday_plus:週の始まり曜日。日曜日が0で土曜日が6。 locale:曜日のロケール。"ja-jp"で日本語表記になる。 day_abbreviations:曜日の表示名を個別に指定する。デフォルトではSun、Mon、...。day_abbreviations=[*"日月火水木金土"]とすると日本語表記になる。 close_when_chosen:Trueの場合、OKボタンが表示されず、カレンダー上で日付を選択するとウィンドウが閉じる。 |
popup_get_file | ファイル選択ボタンを持つポップアップ。戻り値は選択されたファイル。 no_window:Trueの場合、ウィンドウを表示することなくファイル選択ダイアログを開く。 save_as:Trueの場合、ファイル保存ダイアログ、Falseの場合はファイルオープンダイアログを使う default_path:デフォルトでテキストボックスに表示されるパス default_extension:save_asがTrueのとき、選択されたファイルが拡張子なしの場合に自動付与される拡張子 initial_folder:Browseボタンを押したときに初期で開くフォルダ multiple_files:Trueの場合、複数選択可能 file_types:表示するファイルのリスト。デフォルトは(("ALL Files", ". *"),) files_delimiter:複数選択時の区切り文字 show_hidden:隠しファイルを表示するか選択できるようにする。Windowsでは効果なし? history:Trueの場合、過去に選択されたパスが保存され、ドロップダウンで選択できるようにする history_setting_filename:過去に選択されたパスの保存先。 |
popup_get_folder | フォルダ選択ボタンを持つポップアップ。 no_window:Trueの場合、ウィンドウを表示することなくフォルダ選択ダイアログを開く。 default_path:デフォルトでテキストボックスに表示されるパス initial_folder:Browseボタンを押したときに初期で開くフォルダ history:Trueの場合、過去に選択されたパスが保存され、ドロップダウンで選択できるようにする history_setting_filename:過去に選択されたパスの保存先。 |
popup_get_text | テキストボックスを持つポップアップ default_text:テキストボックスのデフォルト値 password_char:パスワード入力用のマスク |
popup_notify | Androidのトーストのようにゆっくり現れ、一定時間後ゆっくり消える通知。アイコン付き。 icon:表示するアイコン。sg.SYSTEM_TRAY_MESSAGE_ICON_CRITICALなど定義されたものが利用できる display_duration_in_ms:メッセージが表示されている時間(ミリ秒) fade_in_duration:フェードイン・アウトにかける時間(ミリ秒) |
popup_auto_close | 自動で閉じるポップアップ |
popup_non_blocking | ブロックしないポップアップ |
popup_quick | ブロックしないポップアップ |
popup_quick_message | ブロックしないタイトルバーなしのポップアップ |
popup_scrolled | スクロール可能なテキストボックスとOKボタンを持つポップアップ yes_no:Trueの場合、OKボタンのかわりにYES・NOボタンを表示する |
popup_animated | スピナーのようなアニメーションGIFを表示するポップアップ 他と違って使用方法が独特なため、後述 |
popup_error_with_traceback | PySimpleGUIが使用するエラーダイアログ。エラーのトレースバックなどの情報が表示される。 |
popup_animated
このポップアップは他とは使い方が違う。ループで繰り返しこのメソッドを呼び出す。メソッドを呼び出すたびにアニメーションGIFの次のフレームが表示され、Noneを指定することで終了する。
