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 는, 건네받아 보내져 퍼스 되는 string를 원시적으로 기초로 하고 있었습니다. 이 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 string와 title string는, 꽤 자명합니다. 메뉴 오브젝트와 유저 코드의 사이에 긴밀히 결합된 피드백이 필요한 때, 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 개의 전용의 글로벌도
존재합니다(초기의 설계자는 꽤 근시안적이어, 이것의 준비를 하지 않았습니다).
제로로 설정되어 있는 경우, 디폴트의 centering가 유효하게 됩니다.

서식
#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 의 속성이 지정되어 있는 경우, 박스와 오브젝트의 경계 area를 paint 하는 동안, 그것들이 사용됩니다. 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 로 표시됩니다. 편집중의 string는 result 에 보존됩니다. 처리가 성공했을 경우는 0 , 처리가 실패했을 경우는 -1 을 돌려줍니다. int strheight(const char *p) 개행을 카운트 하면서, p 내의 string의 높이를 돌려줍니다. int strwidth(const char *p) 개행을 카운트 하면서, p 내의 string의 폭을 돌려줍니다. 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 string와 prompt string를 사용해 텍스트 박스를 표시합니다. 또, 하단에 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 의, string 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 ** 일 필요가 있습니다) 안에 발견되는 string 포인터 페어의 수를 나타내는 정의 정수이다 필요가 있습니다. string는 각 항목에 대해 prompt내에 있어 타이틀순서인 것이 예측됩니다. result 파라미터는, 선택된 항목의 prompt string가 카피되는 배열을 가리킨다고 예측됩니다. 좀 더 새롭다 인터페이스를 사용하려면 , 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 ** 일 필요가 어느) 안에 발견되는 string 포인터 요소의 집합의 수를 나타내는 정의 정수일 필요가 있습니다. string는 각 항목에 대해 prompt내에 있어 타이틀과 상태 ( 「온」또는 「오프」) 순서인 것이 예측됩니다. result 파라미터는, 선택된 항목의 prompt string가 카피되는 배열을 가리킨다고 예측됩니다. 좀 더 새로운 인터페이스를 사용하려면 , 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 버튼을 선택하면(자), 선택된 모든 항목에 대한 prompt치가 연결되어 result string에 넣어집니다. 새로운 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 ** 이다 필요가 있습니다) 안에 발견되는 string 포인터 요소의 집합의 수를 나타내는 정의 정수일 필요가 있습니다. string는 각 항목에 대해 prompt내에 있어 타이틀과 상태 ( 「온」또는 「오프」) 순서인 것이 예측됩니다. result 파라미터는, 선택된 항목의 prompt string가 카피되는 배열을 가리킨다고 예측됩니다. 좀 더 새로운 인터페이스를 사용하려면 , 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 박스의 상단 경계상에 centering로 표시됩니다. 트리 서브 윈도우의 윗쪽에 있는 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()를 작성했습니다.

버그
확실!