manページ  — dialog

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
line_edit(WINDOW *dialog, int box_y, int box_x, int flen, int box_width, chtype attrs, int first, unsigned char *result, int attr_mask);

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

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

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 が表示され、行を分割するために  ' を 入れることができます。ツリーをナビゲートするには、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 からのポインタが入れられます。

主要な作者は 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> によって行われました。

確実!