doc/ja_JP.eucJP/man/man3/dialog.3

.\"
.\" Copyright (c) 1995, Jordan Hubbard
.\"
.\" All rights reserved.
.\"
.\" This manual page may be used, modified, copied, distributed, and
.\" sold, in both source and binary form provided that the above
.\" copyright and these terms are retained, verbatim, as the first
.\" lines of this file.  Under no circumstances is the author
.\" responsible for the proper functioning of the software described herein
.\" nor does the author assume any responsibility for damages incurred with
.\" its use.
.\"
.\" %Id: dialog.3,v 1.8 1998/10/02 11:23:47 jkh Exp %
.\"
.\" $FreeBSD$
.Dd October 2, 1998
.Dt dialog 3
.Os FreeBSD 2
.Sh 名称
.Nm draw_shadow ,
.Nm draw_box ,
.Nm line_edit ,
.Nm strheight ,
.Nm strwidth ,
.Nm dialog_create_rc,
.Nm dialog_yesno ,
.Nm dialog_prgbox ,
.Nm dialog_msgbox ,
.Nm dialog_textbox ,
.Nm dialog_menu ,
.Nm dialog_checklist ,
.Nm dialog_radiolist ,
.Nm dialog_inputbox ,
.Nm dialog_clear_norefresh ,
.Nm dialog_clear ,
.Nm dialog_update ,
.Nm dialog_fselect ,
.Nm dialog_notify ,
.Nm dialog_mesgbox ,
.Nm dialog_gauge ,
.Nm init_dialog ,
.Nm end_dialog ,
.Nm use_helpfile ,
.Nm use_helpline ,
.Nm get_helpline ,
.Nm restore_helpline ,
.Nm dialog_ftree ,
.Nm dialog_tree
.Nd 簡単な ncurses ベースの GUI インタフェース
.Sh 解説
ダイアログライブラリは、固定表示メニュー、入力ボックス、ゲージ、
ファイルリクエスタ、その他の汎用「GUI」(多少誇張してあります。ncurses を
使用するからです) オブジェクトのかなり単純化したセットを
提供しようとしています。
ライブラリではシェルスクリプトライターユーティリティ (\fBdialog(1)\fR
コマンドを参照) 内にもルーツがあったため、初期の API は、
渡され、送られ、パースされるストリングを原始的に基礎としていました。
この API は後に拡張され、オリジナル
の引数または \fBdialogMenuItem\fR 構造の配列のどちらかを取るようになりました。
この結果、ユーザは、各コントロールの内部動作をさらに
制御できるようになりました。\fBdialogMenuItem\fR 構造の内部はパブリックです。

.nf
typedef struct _dmenu_item {
   char *\fBprompt\fR;
   char *\fBtitle\fR;
   int (*\fBchecked\fR)(struct _dmenu_item *self);
   int (*\fBfire\fR)(struct _dmenu_item *self);
   int (*\fBselected\fR)(struct _dmenu_item *self, int is_selected);
   void *\fBdata\fR;
   char \fBlbra\fR, \fBmark\fR, \fBrbra\fR;
} \fBdialogMenuItem\fR;
.fi

\fBprompt\fR ストリングと \fBtitle\fR ストリングは、かなり自明です。
メニューオブジェクトとユーザコードの間に緊密に結合されたフィードバックが
必要なとき、\fBchecked\fR 関数ポインタと \fBfire\fR 関数ポインタには
オプションの
ディスプレイと処置フックが備わっています (これらの
フックのために \fBdata\fR 変数が利用できます)。
\fB選択された\fR フックによって、コンテキストに応じた動作をかなり
実現するために、指定の項目が選択されているかどうかを
検証することもできます。さまざまな種類の項目タイプをシミュレートする
賢明ないくつかの方法が、\fBlbra\fR (デフォルト: '[')、
\fBmark\fR (デフォルト: ラジオメニューについては '*'、
チェックメニューについては 'X')、および
\fBrbra\fR (デフォルト: ']') の値を調整し、合理的な \fBchecked\fR フックを
宣言することで行えます。これは「マークされた」状態については TRUE、「マーク
されない」状態については FALSE を返すはずです。項目に対応する \fBfire\fR フック
がある場合、その項目は、何らかの方法で項目が「トグル」されたときもいつでも
呼び出され、次のコードの 1 つを返すはずです。
.nf

#define DITEM_SUCCESS      0 /* 完了成功 */
#define DITEM_FAILURE     -1 /*「起動(fire)」に失敗 */
#define DITEM_LEAVE_MENU  -2 /* 選択肢を「OK」として取り扱う */
#define DITEM_REDRAW      -3 /* メニューが変化している。描画し直せ */

ダイアログを任意の X、Y 位置に配置するために 2 つの専用のグローバルも
存在します(初期の設計者はかなり近視眼的で、これの準備をしませんでした)。
ゼロに設定されている場合、デフォルトの中央揃えが有効になります。

.fi

.Sh 書式
.Fd #include <dialog.h>
.Ft "void"
.Fn draw_shadow "WINDOW *win" "int y" "int x" "int height" "int width"

\fBx, y, width\fR、および \fBheight\fR の寸法を使用して、
curses ウィンドウ \fBwin\fR に陰を描画します。
処理成功すると 0 を返し、処理失敗すると -1 を返します。

.Ft "void"
.Fn draw_box "WINDOW *win" "int y" "int x" "int height" "int width" "chtype box" "chtype border"

\fBx, y, width\fR、および \fBheight\fR の寸法を使用して、
ボーダーのあるボックスを描画します。
\fBbox\fR と \fBborder\fR の属性が指定されている場合、ボックスと
オブジェクトのボーダー領域をペイントする間、それらが使用されます。

.Ft "int"
.Fo line_edit
.Fa "WINDOW *dialog"
.Fa "int box_y"
.Fa "int box_x"
.Fa "int flen"
.Fa "int box_width"
.Fa "chtype attrs"
.Fa "int first"
.Fa "unsigned char *result"
.Fa "int attr_mask"
.Fc

寸法が \fBbox_x, box_y\fR および \fBbox_width\fR の編集ボックスで
簡単なラインエディタを起動します。フィールドの長さは \fBflen\fR によって
制約され、指定された \fBfirst\fR キャラクタで開始します。
この \fBfirst\fR キャラクタはオプションで、
キャラクタ属性 \fBattrs\fR で表示されます。
編集中のストリングは \fBresult\fR に保存されます。

処理が成功した場合は 0 、処理が失敗した場合は -1 を返します。

.Ft "int"
.Fn strheight "const char *p"

改行をカウントしながら、\fBp\fR 内のストリングの高さを返します。

.Ft "int"
.Fn strwidth "const char *p"

改行をカウントしながら、\fBp\fR 内のストリングの幅を返します。

.Ft "void"
.Fn dialog_create_rc "unsigned char *filename"

デフォルトとして後で取り出すためにダイアログライブラリ設定
を \fBfilename\fR 内にダンプします。
処理が成功した場合は 0 、処理が失敗した場合は -1 を返します。

.Ft "int"
.Fn dialog_yesno "unsigned char *title" "unsigned char *prompt" "int height" "int width"

寸法が \fBheight\fR と \fBwidth\fR の \fBtitle\fR ストリングと
\fBprompt\fR ストリングを使用してテキストボックスを表示します。
また、下端に \fBYes\fR ボタンと \fBNo\fR ボタンのペアも表示します。
\fBYes\fR ボタンを選択すると、FALSE を返します。
\fBNo\fR ボタンを選択すると TRUE を返します。

.Ft "int"
.Fn dialog_prgbox "unsigned char *title" "const unsigned char *line" "int height" "int width" "int pause" "int use_shell"

コマンド \fBline\fR の出力が入っている、寸法が \fBheight\fR と
\fBwidth\fR のテキストボックスを表示します。
\fBuse_shell\fR が TRUE の場合、\fBline\fR は \fBsh(1)\fR への引数として
渡されます。そうでない場合は、単に
\fBexec(3)\fR に渡されます。
\fBpause\fR が TRUE の場合、実行が終了したときに、
最終的な確認リクエスタが供給されます。

処理が成功した場合は 0 、処理が失敗した場合は -1 を返します。

.Ft "int"
.Fn dialog_textbox "unsigned char *title" "unsigned char *prompt" "int height" "int width"

寸法が \fBheight\fR と \fBwidth\fR の、ストリング \fBprompt\fR の内容が
含まれているテキストボックスを表示します。

処理が成功した場合は 0 、処理が失敗した場合は -1 を返します。

.Ft "int"
.Fn dialog_menu "unsigned char *title" "unsigned char *prompt" "int height" "int width" "int menu_height" "int item_no" "void *itptr" "unsigned char *result, int *ch, int *sc"

寸法が \fBheight\fR と \fBwidth\fR のメニューを表示します。
このメニューには、\fBmenu_height\fR というオプションの内部メニューの高さが
あります。\fBitem_no\fR 引数と \fBitptr\fR 引数には特別な重要性があります。
これらは一緒になって、利用可能な 2 つの API のうちどちらを使用するかを
決定するからです。古い従来のインタフェースを使用するには、
\fBitem_no\fR が \fBitptr\fR (タイプは \fBchar **\fR である必要があります)
内に見つかるストリングポインタペアの数を表す正の整数である
必要があります。ストリングは各項目についてプロンプト内にあり
タイトル順であることが予測されます。
\fBresult\fR パラメータは、選択された項目の
プロンプトストリングがコピーされる配列を指すと予測されます。もっと新しい
インタフェースを使用するには、\fBitem_no\fR が、
\fBitptr\fR (タイプは \fBdialogMenuItem *\fR である必要があります) の指す
\fBdialogMenuItem\fR 構造の数を表す負の整数である必要があります。
項目ごとに 1 つの構造です。新しいインタフェースでは、\fBresult\fR 変数は、
単純なブール演算子 (ポインタではありません) として使用され、
\fBitptr\fR がメニュー構造を指すだけで、デフォルトの \fBOK\fR ボタンと
\fBCancel\fR ボタンが望ましい場合は、NULL にする必要があります。
\fBresult\fR が NULL でない場合、\fBitptr\fR は実際に、
メニュー項目リストの始点を過ぎた 2 位置を指すと予測されます。
この場合、\fBitptr\fR[-1] は \fBCancel\fR ボタンを表す項目を指すと
予測されます。ここから、 \fBprompt\fR 処置と \fBfire\fR 処置が
デフォルトの動作を上書きするために使用されます。
\fBitp-tr[-2]\fR は \fBOK\fR ボタンについて同じことをします。

どちらかの API 動作を使用すると、\fBch\fR 値と \fBsc\fR 値が渡され、
現在の項目選択が維持され、呼び出しの間で位置の値がスクロールされます。

処理が成功した場合は 0 、処理が失敗した場合または ESC の場合は -1 を返します。

.Ft "int"
.Fn dialog_checklist "unsigned char *title" "unsigned char *prompt" "int height" "int width" "int m_height" "int item_no" "void *itptr" "unsigned char *result"

寸法が \fBheight\fR と \fBwidth\fR のメニューを表示します。このメニューには、
\fBmenu_height\fR というオプションの内部メニューの高さがあります。
\fBitem_no\fR 引数と \fBitptr\fR 引数には特別な重要性があります。
これらは一緒になって、利用可能な 2 つの API のうちどちらを使用するか
を決定するからです。古い従来のインタフェースを使用するには、
\fBitem_no\fR が \fBitptr\fR (タイプは \fBchar **\fR である必要が
あります) 内に見つかるストリングポインタ要素の集合の数を表す正の
整数である必要があります。ストリングは各項目についてプロンプト内にあり
タイトルと状態 (「オン」または「オフ」) 順であることが予測されます。
\fBresult\fR パラメータは、選択された項目のプロンプトストリングが
コピーされる配列を指すと予測されます。
もっと新しいインタフェースを使用するには、\fBitem_no\fR が、
\fBitptr\fR (タイプは \fBdialogMenuItem *\fR である必要があります) の指す
\fBdialogMenuItem\fR 構造の数を表す負の整数である必要があります。項目ごとに
1 つの構造です。新しいインタフェースでは、\fBresult\fR 変数は、
単純なブール演算子 (ポインタではありません) として使用され、
\fBitptr\fR がメニュー構造を指すだけで、デフォルトの \fBOK\fR ボタンと
\fBCancel\fR ボタンが望ましい場合は、NULL にする必要があります。
\fBresult\fR が NULL でない場合、\fBitptr\fR は実際に、メニュー項目
リストの始点を過ぎた 2 位置を指すと予測されます。この場合、
\fBitptr[-1]\fR は \fBCancel\fR ボタンを表す項目を指すと予測されます。
ここから、\fBprompt\fR 処置と \fBfire\fR 処置が
デフォルトの動作を上書きするために使用されます。
\fBitptr[-2]\fR は \fBOK\fR ボタンについて同じことをします。

標準 API モデルでは、メニューは複数項目の選択をサポートしています。
各項目が選択を表すために 'X' キャラクタでマークされます。
OK ボタンを選択すると、選択されたすべての項目についてのプロンプト値が
連結されて \fBresult\fR ストリングに入れられます。

新しい API モデルでは、「チェックリスト」意味論を保持する必要は
実際にはありません。各項目がどのように表示されるか、
「選択された」としてどのようにマークされるかについての
実際的にほとんどのことは完全に構成可能だからです。
「ラジオ」動作、「チェックリスト」動作、および標準メニュー項目動作の
項目のグループを実際に組み入れていた 1 つのチェックリストメニューを
得ることができるでしょう。
新しい API モデルで \fBdialog_radiolist\fR よりも
\fBdialog_checklist\fR を呼び出す唯一の理由は、
ベース動作を継承することです。もはやそれによって制約されなくなります。

処理が成功した場合は 0、処理が失敗した場合または ESC の場合は -1 を返します。

.Ft "int"
.Fn dialog_radiolist "unsigned char *title" "unsigned char *prompt" "int height" "int width" "int m_height" "int item_no" "void *it" "unsigned char *result"

寸法が \fBheight\fR と \fRwidth\fR のメニューを表示します。このメニューには、
\fBmenu_height\fR というオプションの内部メニューの高さがあります。
\fBitem_no\fR 引数と \fBitptr\fR 引数には特別な重要性があります。
これらは一緒になって、利用可能な 2 つの API のうちどちらを使用するかを
決定するからです。古い従来のインタフェースを使用するには、
\fBitem_no\fR が \fBitptr\fR (タイプは \fBchar **\fR である
必要があります) 内に見つかるストリングポインタ要素の集合の数を表す正の
整数である必要があります。ストリングは各項目についてプロンプト内にあり
タイトルと状態 (「オン」または「オフ」) 順であることが予測されます。
\fBresult\fR パラメータは、選択された項目のプロンプトストリングが
コピーされる配列を指すと予測されます。
もっと新しいインタフェースを使用するには、\fBitem_no\fR が、
\fBitptr\fR (タイプは \fBdialogMenuItem *\fR である必要があります) の指す
\fBdialogMenuItem\fR 構造の数を表す負の整数である必要があります。項目ごとに
1 つの構造です。新しいインタフェースでは、\fBresult\fR 変数は、
単純なブール演算子 (ポインタではありません) として使用され、
\fBitptr\fR がメニュー構造を指すだけで、デフォルトの \fBOK\fR ボタンと
\fBCancel\fR ボタンが望ましい場合は、NULL にする必要があります。
\fBresult\fR が NULL でない場合、\fBitptr\fR は実際に、メニュー項目
リストの始点を過ぎた 2 位置を指すと予測されます。この場合、
\fBitptr[-1]\fR は \fBCancel\fR ボタンを表す項目を指すと予測されます。
ここから、 \fBprompt\fR 処置と \fBfire\fR 処置がデフォルトの動作を
上書きするために使用されます。\fBitptr[-2]\fR は \fBOK\fR ボタンについて
同じことをします。

標準 API モデルでは、メニューは複数の項目の 1 つだけの選択をサポートします。
現在アクティブな項目は `*' でマークされます。

新しい API モデルでは、「ラジオボタン」意味論を保持する必要は
実際にはありません。各項目がどのように表示されるか、
「選択された」としてどのようにマークされるかについての
実際的にすべてのことが完全に構成可能だからです。「チェックリスト」動作、
「ラジオ」動作および標準メニュー項目動作の項目のグループを実際に組み入れた
1 つのチェックリストメニューを得ることができます。
新しい API モデルで \fBdialog_checklist\fR よりも
\fBdialog_radiolist\fR を呼び出す唯一の理由は、ベース動作を継承することです。

処理が成功した場合は 0 を返し、Cancel の場合は 1 を返し、
処理が失敗するかまたは ESC の場合は -1 を返します。

.Ft "int"
.Fn dialog_inputbox "unsigned char *title" "unsigned char *prompt" "int height" "int width" "unsigned char *result"

寸法が \fBheight\fR と \fBwidth\fR の \fBtitle\fR と
\fBprompt\fR を表示するボックス内に 1 行のテキスト入力フィールドを表示します。
入力されたフィールドは \fBresult\fR に保存されます。

処理が成功した場合は 0 を返し、
処理が失敗するかまたは ESC の場合は -1 を返します。

.Ft "char *"
.Fn dialog_fselect "char *dir" "char *fmask"

\fBdir\fR で開始し、\fBfmask\fR に一致するファイル名だけを表示する
ファイルセレクタダイアログを呼び出します。

選択されたファイル名または NULL を返します。

.Ft "int"
.Fn dialog_dselect "char *dir" "char *fmask"

\fBdir\fR で開始し、\fBfmask\fR に一致するディレクトリ名だけを表示する
ファイルセレクタダイアログを呼び出します。選択されたファイル名
または NULL を返します。

.Ft "void"
.Fn dialog_notify "char *msg"

\fBmsg\fR が入った一般的な "hey, you!" 通知ダイアログを呼び出します。

.Ft "int"
.Fn dialog_mesgbox "unsigned char *title" "unsigned char *prompt" "int height" "int width"

通知ダイアログに類似していますが、
\fBtitle\fR, \fBprompt\fR, \fBwidth\fR および \fBheight\fR を
さらに制御できます。このオブジェクトは、\fBdialog_notify\fR と違って、
ユーザ確認も待機します。

処理が成功した場合は 0 を返し、処理が失敗した場合は -1 を返します。

.Ft "void"
.Fn dialog_gauge "char *title" "char *prompt" "int y" "int x" "int height" "int width" "int perc"

水平の棒グラフスタイルのゲージを表示します。\fBperc\fR についての
\fB100\fR という値はフルゲージを構成し、
\fB0\fR という値は空のゲージを構成します。

.Ft "void"
.Fn use_helpfile "char *helpfile"

コンテキストに応じたヘルプをサポートしているどのメニューについても、
\fBF1\fR キー
が押されるたびにこのファイル上のテキストボックスオブジェクトが
起動されます。

.Ft "void"
.Fn use_helpfile "char *helpfile"

表示されているメニューの下に便利なこの行を表示します。

.Ft "char *"
.Fn get_helpline "void"

便利なテキスト行の現在の値を取得します。

.Ft "void"
.Fn dialog_clear_norefresh "void"

画面をクリアしてダイアログ背景色にしますが、内容はリフレッシュしません。

.Ft "void"
.Fn dialog_clear "void"

ただちに画面をクリアしてダイアログの背景色に戻します。

.Ft "void"
.Fn dialog_update "void"

延期中の画面リフレッシュを今、行います。

.Ft "void"
.Fn init_dialog "void"

ダイアログライブラリをシャットダウンします (正気に戻る必要がある場合は
これを呼び出してください) 。

.Ft "int"
.Fn dialog_ftree "unsigned char *filename" "unsigned char FS" \
"unsigned char *title" "unsigned char *prompt" "int height" "int width" \
"int menu_height" "unsigned char **result"

\fBdialog_ftree\fR は、ファイル \fBfilename\fR からのデータで
記述されたツリーを表示します。ファイル内のデータは
\fBfind(1)\fR 出力のように見えるはずです。
\fBfind(1)\fR 出力の場合、フィールド分離子 \fBFS\fR は \fB\'/\'\fR になります。
\fBheight\fR と \fBwidth\fR が正の数である場合、これらは
\fBdialog_ftree\fR ボックス全体の絶対サイズを設定します。
\fBheight\fR と \fBwidth\fR が負の数である場合、
\fBdialog_ftree\fR ボックスのサイズは自動的に計算されます。
\fBmenu_height\fR は \fBdialog_ftree\fR ボックス内の
ツリーサブウィンドウの高さを設定し、また設定する必要があります。
\fBtitle\fR は、\fBdialog_ftree\fR ボックスの上端ボーダー上に
中央揃えで表示されます。
ツリーサブウィンドウの上方にある \fBdialog_ftree\fR 内部に
\fBprompt\fR が表示され、行を分割するために \fB\'\\n\'\fR を
入れることができます。ツリーをナビゲートするには、\fBUP/DOWN\fR または
\fB\'+\'/\'-\'\fR, \fBPG_UP/PG_DOWN\fR または
\fB\'b\'/SPACE\fR および \fBHOME/END\fR または
\fB\'g\'/\'G\'\fR を押します。ツリーのリーフを選択するには、
\fBTAB\fR または \fBLEFT/RIGHT\fR を押し、\fBOK\fR ボタン次いで
\fBENTER\fR を押します。ファイル名には \fBfind(1)\fR 出力のような
データを組み入れることができます。
\fB-d\fR オプションを指定した \fBfind(1)\fR の出力とも同じようにです。
ツリーのリーフに移行するパスは存在しなくてかまいません。
このようなデータはファイル名からフィードされたときに訂正されます。

\fBOK\fR ボタンを選択すると、関数は 0 と選択したリーフ (ツリーの
ルートからリーフへのパス) を指すポインタを結果に入れて返します。
ツリーの作成用に割り振られたメモリは、既存の \fBdialog_ftree\fR を
終了するときに解放されます。
結果の行用のメモリは必要であれば後で手動で解放します。
\fBCancel\fR ボタンを選択すると、関数は 1 を返します。
\fBESC\fR で \fBdialog_ftree\fR を終了する場合、関数は -1 を返します。

.Ft "int" 
.Fo dialog_tree 
.Fa "unsigned char **names" 
.Fa "int size"
.Fa "unsigned char FS" 
.Fa "unsigned char *title" 
.Fa "unsigned char *prompt"
.Fa "int height" 
.Fa "int width" 
.Fa "int menu_height"
.Fa "unsigned char **result"
.Fc

\fBdialog_tree\fR は、\fBdialog_ftree\fR と非常に類似したツリーを表示しますが、
例外がいくつかあります。ツリーを作成するためのソースデータは、
サイズが \fBsize\fR のリーフへのパスの配列 \fBnames\fR です (\fBfind(1)\fR
出力に類似しています) 。
しかし、\fBdialog_ftree\fR でのようにデータの訂正はありません。
このように、正しいツリーを表示するためには、配列には正しいデータが
既に入っている必要があります。
なお、セッションごとに \fBdialog_tree\fR の独自の各使用法がメモリに保持され、
後で、同じ \fBnames\fR, \fBsize\fR, \fBFS\fR, \fBheight\fR, 
\fBwidth\fR および \fBmenu_height\fR で \fBdialog_tree\fR を呼び出すときに、
ツリーサブウィンドウ内のカーソルの位置が復元されます。

関数は \fBdialog_ftree\fR と同じ結果を返します。
0 が返された場合、結果には配列 \fBnames\fR からのポインタが入れられます。

.Sh 関連項目
.Xr dialog 1 ,
.Xr ncurses 3
.Sh 作者
主要な作者は
.An Savio Lam Aq lam836@cs.cuhk.hk
と考えられます。長年に渡る貢献が
.An Stuart Herbert Aq S.Herbert@sheffield.ac.uk ,
.An Marc van Kempen Aq wmbfmk@urc.tue.nl ,
.An Andrey Chernov Aq ache@freebsd.org ,
.An Jordan Hubbard Aq jkh@freebsd.org
および
.An Anatoly A. Orehovsky Aq tolik@mpeks.tomsk.su
によって行われました。
.Sh 歴史
これらの関数は
.Em FreeBSD-2.0
では
.Xr dialog 1
コマンドとして現れましたが、
すぐに Andrey Chernov によってライブラリとコマンドに分割されました。
Marc van Kempen がその他のコントロールとオブジェクトのほとんどを作成しました。
Jordan Hubbard が dialogMenuItem 革新とこのマニュアルページを追加しました。
Anatoly A. Orehovsky が dialog_ftree() と dialog_tree() を作成しました。
.Sh バグ
確実!