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" の範囲に収まるよう強制的に値
   を設定します。
