# 37.5. `EasyDialogs` --- 基本的な Macintosh ダイアログ

`EasyDialogs` モジュールには、Macintosh で単純なダイアログ操作を行うためのルーチンが入っています。ダイアログはドックに現れる別のアプリケーションとして起動され、ダイアログが表示されるにはクリックされなければなりません。全てのルーチンは、オプションとしてリソース ID パラメタ id をとります。デフォルトの `DLOG` のリソース (タイプとアイテムナンバの両方) が一致するようなダイアログがあれば、 id を使ってダイアログ操作に使われるダイアログオブジェクト情報を上書きできます。詳細はソースコードを参照してください。

注釈

このモジュールは Python 3.x で削除されました。

`EasyDialogs` モジュールでは以下の関数を定義しています。

`EasyDialogs.``Message`(str[, id[, ok]])

  メッセージテキスト str 付きのモーダルダイアログを表示します。テキストの長さは最大255文字です。ボタンのテキストはデフォルトでは "OK" ですが、文字列の引数 ok を指定して変更できます。ユーザが "OK" ボタンをクリックすると処理を戻します。

`EasyDialogs.``AskString`(prompt[, default[, id[, ok[, cancel]]]])

  ユーザに文字列値の入力を促すモーダルダイアログを表示します。 prompt はプロンプトメッセージで、オプションの default 引数は入力文字列の初期値です（指定しなければ `""` を使います)。 "OK"と"Cancel"ボタンの文字列は ok と cancel の引数で変更できます。文字列の長さは全て最大255文字です。入力された文字列か、ユーザがキャンセルした場合には `None` を返します。

`EasyDialogs.``AskPassword`(prompt[, default[, id[, ok[, cancel]]]])

  ユーザに文字列値の入力を促すモーダルダイアログを表示します。 `AskString()` に似ていますが、ユーザの入力したテキストは点で表示されます。引数は `AskString()` のものと同じ意味です。

`EasyDialogs.``AskYesNoCancel`(question[, default[, yes[, no[, cancel[, id]]]]])

  プロンプト question と"Yes"、"No"、"Cancel" というラベルの3つボタンが付いたダイアログを表示します。ユーザが "Yes" を押した場合には `1` を、"No" ならば `0` を、 "Cancel" ならば `-1` を返します。 `RETURN` キーを押した場合は default の値 (default を指定しない場合は `0`) を返します。ボタンのテキストはそれぞれ引数 yes 、 no 、 cancel で変更できます。ボタンを表示したくなければ対応する引数に `""` を指定します。

`EasyDialogs.``ProgressBar`([title[, maxval[, label[, id]]]])

  プログレスバー付きのモードレスダイアログを表示します。これは後で述べる `ProgressBar` クラスのコンストラクタです。 title はダイアログに表示するテキスト文字列 (デフォルトの値は "Working...") で、 maxval は処理が完了するときの値です (デフォルトは `0` で、残りの作業量が不確定であることを示します)。 label はプログレスバー自体の上に表示するテキストです。

`EasyDialogs.``GetArgv`([optionlist[ commandlist[, addoldfile[, addnewfile[, addfolder[, id]]]]]])

  コマンドライン引数リストの作成を補助するためのダイアログを表示します。得られた引数リストを `sys.argv` の形式にします。これは `getopt.getopt()` の引数として渡すのに適した形式です。 addoldfile 、 addnewfile 、 addfolder はブール型の引数です。これらの引数が真の場合、それぞれ、実在のファイル、まだ (おそらく) 存在しないファイル、フォルダへのパスをコマンドラインのパスとして設定できます。 (注意: `getopt.getopt()` がファイルやフォルダ引数を認識できるようにするためには、オブションの引数がそれらより前に現れるようにしなければなりません。) 空白を含む引数は、空白をシングルクォートあるいはダブルクォートで囲んで指定できます。ユーザが "Cancel" ボタンを押した場合、 `SystemExit` 例外を送出します。

  optionlist には、ポップアップメニューで選べる選択肢を定義したリストを指定します。ポップアップメニューの要素には、次の2つの形式、 optstr または `(optstr, descr)` があります。 descr に短い説明文字列を指定すると、該当の選択肢をポップアップメニューで選択しいる間その文字列をダイアログに表示します。 optstr とコマンドライン引数の対応を以下に示します:

  optstr 形式 | コマンドライン形式
  --- | ---
  `x` | `-x` (short option)
  `x:` あるいは `x=` | `-x` (short option with value)
  `xyz` | `--xyz` (long option)
  `xyz:` あるいは `xyz=` | `--xyz` (long option with value)

  commandlist は cmdstr あるいは `(cmdstr, descr)` の形のアイテムからなるリストです。 descr は上と同じです。 cmdstr はポップアップメニューに表示されます。メニューを選択すると cmdstr はコマンドラインに追加されますが、それに続く `':'` や `'='` は (存在していれば) 取り除かれます。

  バージョン 2.0 で追加.

`EasyDialogs.``AskFileForOpen`([message] [, typeList] [, defaultLocation] [, defaultOptionFlags] [, location] [, clientName] [, windowTitle] [, actionButtonLabel] [, cancelButtonLabel] [, preferenceKey] [, popupExtension] [, eventProc] [, previewProc] [, filterProc] [, wanted] )

  どのファイルを開くかをユーザに尋ねるダイアログを表示し、ユーザが選択したファイルを返します。ユーザがダイアログをキャンセルした場合には `None` を返します。 message はダイアログに表示するテキストメッセージです。 typeList は選択できるファイルタイプを表す 4 文字の文字列からなるリスト、 defaultLocation は最初に表示すルフォルダで、パス名、 `FSSpec` あるいは `FSRef` で指定します。 location はダイアログを表示するスクリーン上の位置 `(x, y)` です。 actionButtonLabel は OK ボタンの位置に "Open" の代わりに表示する文字列、 cancelButtonLabel は "Cancel" ボタンの位置に "Cancel" の代わりに表示する文字列です。 wanted は返したい値のタイプで、 `str` 、 `unicode` 、 `FSSpec` 、 `FSRef` およびそれらのサブタイプを指定できます。

  その他の引数の説明については Apple Navigation Services のドキュメントと `EasyDialogs` のソースコードを参照してください。

`EasyDialogs.``AskFileForSave`([message] [, savedFileName] [, defaultLocation] [, defaultOptionFlags] [, location] [, clientName] [, windowTitle] [, actionButtonLabel] [, cancelButtonLabel] [, preferenceKey] [, popupExtension] [, fileType] [, fileCreator] [, eventProc] [, wanted] )

  保存先のファイルをユーザに尋ねるダイアログを表示して、ユーザが選択したファイルを返します。ユーザがダイアログをキャンセルした場合には `None` を返します。 savedFileName は保存先のファイル名 (戻り値) のデフォルト値です。その他の引数の説明については `AskFileForOpen()` を参照してください。

`EasyDialogs.``AskFolder`([message] [, defaultLocation] [, defaultOptionFlags] [, location] [, clientName] [, windowTitle] [, actionButtonLabel] [, cancelButtonLabel] [, preferenceKey] [, popupExtension] [, eventProc] [, filterProc] [, wanted] )

  フォルダの選択をユーザに促すダイアログを表示して、ユーザが選択したフォルダを返します。ユーザがダイアログをキャンセルした場合には `None` を返します。引数についての説明は `AskFileForOpen()` を参照してください。

参考

Navigation Services Reference

  Programmer's reference documentation の Carbon framework の Navigation Services の項。

## 37.5.1. プログレスバーオブジェクト

`ProgressBar` オブジェクトでは、モードレスなプログレスバーダイアログのサポートを提供しています。定量プログレスバー (温度計スタイル) と不定量プログレスバー (床屋の螺旋看板スタイル) がサポートされています。プログレスバーの最大値がゼロ以上の場合には定量インジケータに、そうでない場合は不定量インジケータになります。

バージョン 2.2 で変更: 不定量プログレスバーのサポートを追加しました。

ダイアログは作られるとすぐに表示されます。ダイアログの "Cancel" ボタンを押すか、 `Cmd-.` (コマンドキーを押しながらピリオドを押す) か、あるいは `ESC` をタイプすると、ダイアログウィンドウを非表示にして `KeyboardInterrupt` を送出します (ただし、この応答は次にプログレスバーを更新するときまで、すなわち次に `inc()` または `set()` を呼び出してダイアログを更新するまで発生しません) 。それ以外の場合、プログレスバーは `ProgressBar` オブジェクトを廃棄するまで表示されたままになります。

`ProgressBar` オブジェクトには以下の属性とメソッドがあります。

`ProgressBar.``curval`

  プログレスバーの現在の値 (整数型あるいは長整数型) です。プログレスバーの通常のアクセスのメソッドによって `curval` を `0` と `maxval` の間にします。この属性を直接変更してはなりません。

`ProgressBar.``maxval`

  プログレスバーの最大値　(整数型あるいは長整数型) です; プログレスバー (温度計スタイル) では、 `curval` が `maxval` に等しい時に全量に到達します。 `maxval` が `0` の場合、不定量プログレスバー (床屋の螺旋看板スタイル) になります。この属性を直接変更してはなりません。

`ProgressBar.``title`([newstr])

  プログレスダイアログのタイトルバーのテキストを newstr に設定します。

`ProgressBar.``label`([newstr])

  プログレスダイアログ中のプログレスボックスのテキストを newstr に設定します。

`ProgressBar.``set`(value[, max])

  プログレスバーの現在値 `curval` を value に設定します。 max も指定した場合、 `maxval` を max にします。 value は前もって 0 と `maxval` の間になるよう強制的に設定されます。温度計バーの場合、変更内容を反映するよう表示を更新します。変更によって定量プログレスバーから不定量プログレスバーへ、あるいはその逆への推移が起こります。

`ProgressBar.``inc`([n])

  プログレスバーの `curval` を n だけ増やします。 n を指定しなければ `1` だけ増やします。 (n は負にもでき、その場合は `curval` を減少させます。) 変更内容を反映するようプログレスバーの表示を更新します。プログレスバーが不定量プログレスバーの場合、床屋の螺旋看板模様を 1 度「回転」させます。増減によって `curval` が 0 から `maxval` までの範囲を超えた場合、 0 と `maxval` の範囲に収まるよう強制的に値を設定します。