dialog(3)

draw_shadow, draw_box, line_edit, strheight, strwidth, dialog_create_rc, dialog_yesno, dialog_prgbox, dialog_msgbox, dialog_textbox, dialog_menu, dialog_checklist, dialog_radiolist, dialog_inputbox, dialog_clear_norefresh, dialog_clear, dialog_update, dialog_fselect, dialog_notify, dialog_mesgbox, dialog_gauge, init_dialog, end_dialog, use_helpfile, use_helpline, get_helpline, restore_helpline, dialog_ftree, dialog_tree − 簡単な ncurses ベースの GUI インタフェース

ダイアログライブラリは、固定表示メニュー、入力ボックス、ゲージ、ファイル リクエスタ、その他の汎用「GUI」(多少誇張してあります。ncurses を使用する からです) オブジェクトのかなり単純化したセットを提供しようとしています。 ライブラリではシェルスクリプトライターユーティリティ (dialog(1) コマンド を参照) 内にもルーツがあったため、初期の API は、渡され、送られ、パースさ れるストリングを原始的に基礎としていました。この API は後に拡張され、オリ ジナルの引数または dialogMenuItem 構造の配列のどちらかを取るようになりま した。この結果、ユーザは、各コントロールの内部動作をさらに制御できるよう になりました。dialogMenuItem 構造の内部はパブリックです。

typedef struct _dmenu_item {
   char *prompt;
   char *title;
   int (*checked)(struct _dmenu_item *self);
   int (*fire)(struct _dmenu_item *self);
   int (*selected)(struct _dmenu_item *self, int is_selected);
   void *data;
   char lbra, mark, rbra;
} dialogMenuItem;

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

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

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

#include <dialog.h>

void

draw_shadow(WINDOW *win, int y, int x, int height, int width);

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

void

draw_box(WINDOW *win, int y, int x, int height, int width, chtype box, chtype border);

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

int

strheight(const char *p);

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

int
strwidth(const char *p);

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

void
dialog_create_rc(unsigned char *filename);

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

int
dialog_yesno(unsigned char *title, unsigned char *prompt, int height, int width);

寸法が height と width の title ストリングと prompt ストリングを使用して テキストボックスを表示します。また、下端に Yes ボタンと No ボタンのペアも 表示します。 Yes ボタンを選択すると、FALSE を返します。 No ボタンを選択す ると TRUE を返します。

int
dialog_prgbox(unsigned char *title, const unsigned char *line, int height, int width, int pause, int use_shell);

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

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

int
dialog_textbox(unsigned char *title, unsigned char *prompt, int height, int width);

寸法が height と width の、ストリング prompt の内容が含まれているテキスト ボックスを表示します。

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

int
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);

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

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

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

int
dialog_checklist(unsigned char *title, unsigned char *prompt, int height, int width, int m_height, int item_no, void *itptr, unsigned char *result);

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

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

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

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

int
dialog_radiolist(unsigned char *title, unsigned char *prompt, int height, int width, int m_height, int item_no, void *it, unsigned char *result);

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

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

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

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

int
dialog_inputbox(unsigned char *title, unsigned char *prompt, int height, int width, unsigned char *result);

寸法が height と width の title と prompt を表示するボックス内に 1 行のテ キスト入力フィールドを表示します。入力されたフィールドは result に保存さ れます。

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

char *
dialog_fselect(char *dir, char *fmask);

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

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

int
dialog_dselect(char *dir, char *fmask);

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

void
dialog_notify(char *msg);

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

int
dialog_mesgbox(unsigned char *title, unsigned char *prompt, int height, int width);

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

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

void
dialog_gauge(char *title, char *prompt, int y, int x, int height, int width, int perc);

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

void
use_helpfile(char *helpfile);

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

void
use_helpfile(char *helpfile);

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

char *
get_helpline(void);

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

void
dialog_clear_norefresh(void);

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

void
dialog_clear(void);

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

void
dialog_update(void);

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

void
init_dialog(void);

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

int
dialog_ftree(unsigned char *filename, unsigned char FS, unsigned char *title, unsigned char *prompt, int height, int width, int menu_height, unsigned char **result);

dialog_ftree は、ファイル filename からのデータで記述されたツリーを表示し ます。ファイル内のデータは find(1) 出力のように見えるはずです。 find(1) 出力の場合、フィールド分離子 FS は ´/´ になります。 height と width が正 の数である場合、これらは dialog_ftree ボックス全体の絶対サイズを設定しま す。 height と width が負の数である場合、 dialog_ftree ボックスのサイズは 自動的に計算されます。 menu_height は dialog_ftree ボックス内のツリーサブ ウィンドウの高さを設定し、また設定する必要があります。 title は、dialog_ftree ボックスの上端ボーダー上に中央揃えで表示されます。ツリー サブウィンドウの上方にある dialog_ftree 内部に prompt が表示され、行を分 割するために ´\n´ を入れることができます。ツリーをナビゲートするに は、UP/DOWN または ´+´/´-´, PG_UP/PG_DOWN または ´b´/SPACE および HOME/END または ´g´/´G´ を押します。ツリーのリーフを選択するには、 TAB ま たは LEFT/RIGHT を押し、OK ボタン次いで ENTER を押します。ファイル名には find(1) 出力のようなデータを組み入れることができます。 -d オプションを指 定した find(1) の出力とも同じようにです。ツリーのリーフに移行するパスは存 在しなくてかまいません。このようなデータはファイル名からフィードされたと きに訂正されます。

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

int
dialog_tree(unsigned char **names, int size, unsigned char FS, unsigned char *title, unsigned char *prompt, int height, int width, int menu_height, unsigned char **result);

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

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

関連項目

dialog(1), ncurses(3)

主要な作者は Savio Lam ⟨lam836@cs.cuhk.hk⟩ と考えられます。長年に渡る貢献 が
Stuart Herbert ⟨S.Herbert@sheffield.ac.uk⟩,
Marc van Kempen ⟨wmbfmk@urc.tue.nl⟩,
Andrey Chernov ⟨ache@freebsd.org⟩,
Jordan Hubbard ⟨jkh@freebsd.org⟩ および
Anatoly A. Orehovsky ⟨tolik@mpeks.tomsk.su⟩ によって行われました。

これらの関数は FreeBSD-2.0 では dialog(1) コマンドとして現れましたが、す ぐに Andrey Chernov によってライブラリとコマンドに分割されました。 Marc van Kempen がその他のコントロールとオブジェクトのほとんどを作成しました。 Jordan Hubbard が dialogMenuItem 革新とこのマニュアルページを追加しまし た。 Anatoly A. Orehovsky が dialog_ftree() と dialog_tree() を作成しまし た。

確実!

FreeBSD October 2, 1998 FreeBSD