DIALOG(1) USER COMMANDS DIALOG(1) NNNNAAAAMMMMEEEE dialog - display dialog boxes from shell scripts SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS ddddiiiiaaaalllloooogggg --------cccclllleeeeaaaarrrr ddddiiiiaaaalllloooogggg --------ccccrrrreeeeaaaatttteeee----rrrrcccc _f_i_l_e ddddiiiiaaaalllloooogggg --------pppprrrriiiinnnntttt----mmmmaaaaxxxxssssiiiizzzzeeee ddddiiiiaaaalllloooogggg _c_o_m_m_o_n-_o_p_t_i_o_n_s _b_o_x-_o_p_t_i_o_n_s DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN DDDDiiiiaaaalllloooogggg is a program that will let you to present a variety of questions or display messages using dialog boxes from a shell script. Currently, these types of dialog boxes are implemented: cccchhhheeeecccckkkklllliiiisssstttt, ggggaaaauuuuggggeeee, iiiinnnnffffoooobbbbooooxxxx, iiiinnnnppppuuuuttttbbbbooooxxxx, mmmmeeeennnnuuuu, mmmmssssggggbbbbooooxxxx (message), ppppaaaasssssssswwwwoooorrrrdddd, rrrraaaaddddiiiioooolllliiiisssstttt, ttttaaaaiiiillllbbbbooooxxxx, ttttaaaaiiiillllbbbbooooxxxxbbbbgggg, tttteeeexxxxttttbbbbooooxxxx, and yyyyeeeessssnnnnoooo (yes/no). OOOOPPPPTTTTIIIIOOOONNNNSSSS CCCCoooommmmmmmmoooonnnn OOOOppppttttiiiioooonnnnssss --------aaaassssppppeeeecccctttt _r_a_t_i_o Specify a nominal line width based on the length of the prompt string to use as a guide to forcibly wrapping lines that are too long relative to the dialog box. The default is 9. --------bbbbaaaacccckkkkttttiiiittttlllleeee _b_a_c_k_t_i_t_l_e Specifies a _b_a_c_k_t_i_t_l_e string to be displayed on the backdrop, at the top of the screen. --------bbbbeeeeeeeepppp Beep each time the screen is refreshed. --------bbbbeeeeeeeepppp----aaaafffftttteeeerrrr Beep if input is interrupted, e.g., by a control/C. --------bbbbeeeeggggiiiinnnn _y _x Specify the position of the upper left corner of a dia- log box on the screen. --------cccclllleeeeaaaarrrr The screen will be cleared to the ssssccccrrrreeeeeeeennnn aaaattttttttrrrriiiibbbbuuuutttteeee on exit. This may be used as the only option. --------ccccrrrr----wwwwrrrraaaapppp Interpret embedded newlines in the dialog text as a newline on the screen. Otherwise, the text for each dialog will display on a single line. --------ccccrrrreeeeaaaatttteeee----rrrrcccc _f_i_l_e Dialog Version 0.4 1 DIALOG(1) USER COMMANDS DIALOG(1) When ddddiiiiaaaalllloooogggg supports run-time configuration, this can be used to dump a sample configuration file to the file specified by _f_i_l_e. --------hhhheeeellllpppp Prints the help message to standard error. The help message also will be printed if no options are given. --------ddddeeeeffffaaaauuuullllttttnnnnoooo Make the default value of the yyyyeeeessss////nnnnoooo box a NNNNoooo. --------ddddeeeeffffaaaauuuulllltttt----iiiitttteeeemmmm _s_t_r_i_n_g Set the default item in a menu box. Normally the first item in the box is the default. --------nnnnoooo----kkkkiiiillllllll Tells ddddiiiiaaaalllloooogggg to put the ttttaaaaiiiillllbbbbooooxxxxbbbbgggg box in the back- ground, printing its process id to standard error. SIGHUP is disabled for the background process. --------nnnnoooo----sssshhhhaaaaddddoooowwww Suppress shadows which would be drawn to the right and bottom of each dialog box. --------nnnnooooccccaaaannnncccceeeellll Suppress the "Cancel" button in checklist, inputbox and menubox modes. A script can still test if the user pressed the ESC key to cancel to quit. --------pppprrrriiiinnnntttt----mmmmaaaaxxxxssssiiiizzzzeeee Print the maximum size of dialog boxes, i.e., the screen size, to the standard error. This must be used as the only option. --------pppprrrriiiinnnntttt----ssssiiiizzzzeeee Prints the size of each dialog box to standard error. --------pppprrrriiiinnnntttt----vvvveeeerrrrssssiiiioooonnnn Prints dialog's version to standard error. This may be the only option. --------sssseeeeppppaaaarrrraaaatttteeee----oooouuuuttttppppuuuutttt For checklist widgets, output result one line at a time, with no quoting. This facilitates parsing by another program. --------sssseeeeppppaaaarrrraaaatttteeee----wwwwiiiiddddggggeeeetttt _s_t_r_i_n_g Specify a string that will separate the output on stan- dard error from each widget. This is used to simplify parsing the result of a dialog with several widgets. --------sssshhhhaaaaddddoooowwww Dialog Version 0.4 2 DIALOG(1) USER COMMANDS DIALOG(1) Draw a shadow to the right and bottom of each dialog box. --------ssssiiiizzzzeeee----eeeerrrrrrrr Check the resulting size of a dialog box before trying to use it, printing the resulting size if it is larger than the screen. (This option is obsolete, since all new-window calls are checked). --------sssslllleeeeeeeepppp _s_e_c_s Sleep (delay) for the given number of seconds after processing a dialog box. --------ttttaaaabbbb----ccccoooorrrrrrrreeeecccctttt Convert each tab character to one or more spaces. Oth- erwise, tabs are rendered according to the curses library's interpretation. --------ttttaaaabbbb----lllleeeennnn _n Specify the number of spaces that a tab character occu- pies if the --------ttttaaaabbbb----ccccoooorrrrrrrreeeecccctttt option is given. The default is 8. --------ttttiiiittttlllleeee _t_i_t_l_e Specifies a _t_i_t_l_e string to be displayed at the top of the dialog box. BBBBooooxxxx OOOOppppttttiiiioooonnnnssss All dialog boxes have at least three parameters: _t_e_x_t the caption or contents of the box. _h_e_i_g_h_t the height of the dialog box. _w_i_d_t_h the width of the dialog box. Other parameters depend on the box type. --------cccchhhheeeecccckkkklllliiiisssstttt _t_e_x_t _h_e_i_g_h_t _w_i_d_t_h _l_i_s_t- _h_e_i_g_h_t [ _t_a_g _i_t_e_m _s_t_a_t_u_s ] ... A cccchhhheeeecccckkkklllliiiisssstttt box is similar to a mmmmeeeennnnuuuu box; there are multiple entries presented in the form of a menu. Instead of choosing one entry among the entries, each entry can be turned on or off by the user. The initial on/off state of each entry is specified by _s_t_a_t_u_s. On exit, a list of the _t_a_g strings of those entries that are turned on will be printed on _s_t_d_e_r_r. --------ggggaaaauuuuggggeeee _t_e_x_t _h_e_i_g_h_t _w_i_d_t_h [_p_e_r_c_e_n_t] A ggggaaaauuuuggggeeee box displays a meter along the bottom of the Dialog Version 0.4 3 DIALOG(1) USER COMMANDS DIALOG(1) box. The meter indicates the percentage. New percen- tages are read from standard input, one integer per line. The meter is updated to reflect each new percen- tage. If stdin is XXX, then subsequent lines up to another XXX are used for a new prompt. The gauge exits when EOF is reached on stdin. The _p_e_r_c_e_n_t value denotes the initial percentage shown in the meter. If not specified, it is zero. --------iiiinnnnffffoooobbbbooooxxxx _t_e_x_t _h_e_i_g_h_t _w_i_d_t_h An iiiinnnnffffoooo box is basically a mmmmeeeessssssssaaaaggggeeee box. However, in this case, ddddiiiiaaaalllloooogggg will exit immediately after display- ing the message to the user. The screen is not cleared when ddddiiiiaaaalllloooogggg exits, so that the message will remain on the screen until the calling shell script clears it later. This is useful when you want to inform the user that some operations are carrying on that may require some time to finish. --------iiiinnnnppppuuuuttttbbbbooooxxxx _t_e_x_t _h_e_i_g_h_t _w_i_d_t_h [_i_n_i_t] An iiiinnnnppppuuuutttt box is useful when you want to ask questions that require the user to input a string as the answer. If init is supplied it is used to initialize the input string. When inputing the string, the _B_A_C_K_S_P_A_C_E key can be used to correct typing errors. If the input string is longer than can be fitted in the dialog box, the input field will be scrolled. On exit, the input string will be printed on _s_t_d_e_r_r. --------mmmmeeeennnnuuuu _t_e_x_t _h_e_i_g_h_t _w_i_d_t_h _m_e_n_u-_h_e_i_g_h_t [ _t_a_g _i_t_e_m ] ... As its name suggests, a mmmmeeeennnnuuuu box is a dialog box that can be used to present a list of choices in the form of a menu for the user to choose. Choices are displayed in the order given. Each menu entry consists of a _t_a_g string and an _i_t_e_m string. The _t_a_g gives the entry a name to distinguish it from the other entries in the menu. The _i_t_e_m is a short description of the option that the entry represents. The user can move between the menu entries by pressing the _U_P/_D_O_W_N keys, the first letter of the _t_a_g as a hot-key, or the number keys _1-_9. There are _m_e_n_u-_h_e_i_g_h_t entries displayed in the menu at one time, but the menu will be scrolled if there are more entries than that. When ddddiiiiaaaalllloooogggg exits, the _t_a_g of the chosen menu entry will be printed on _s_t_d_e_r_r. --------mmmmssssggggbbbbooooxxxx _t_e_x_t _h_e_i_g_h_t _w_i_d_t_h A mmmmeeeessssssssaaaaggggeeee box is very similar to a yyyyeeeessss////nnnnoooo box. The only difference between a mmmmeeeessssssssaaaaggggeeee box and a yyyyeeeessss////nnnnoooo box is that a mmmmeeeessssssssaaaaggggeeee box has only a single OOOOKKKK button. You can use this dialog box to display any message you Dialog Version 0.4 4 DIALOG(1) USER COMMANDS DIALOG(1) like. After reading the message, the user can press the _E_N_T_E_R key so that ddddiiiiaaaalllloooogggg will exit and the calling shell script can continue its operation. --------ppppaaaasssssssswwwwoooorrrrddddbbbbooooxxxx _t_e_x_t _h_e_i_g_h_t _w_i_d_t_h [_i_n_i_t] A ppppaaaasssssssswwwwoooorrrrdddd box is similar to an input box, except that the text the user enters is not displayed. This is useful when prompting for passwords or other sensitive information. Be aware that if anything is passed in "init", it will be visible in the system's process table to casual snoopers. Also, it is very confusing to the user to provide them with a default password they cannot see. For these reasons, using "init" is highly discouraged. --------rrrraaaaddddiiiioooolllliiiisssstttt _t_e_x_t _h_e_i_g_h_t _w_i_d_t_h _l_i_s_t- _h_e_i_g_h_t [ _t_a_g _i_t_e_m _s_t_a_t_u_s ] A rrrraaaaddddiiiioooolllliiiisssstttt box is similar to a mmmmeeeennnnuuuu box. The only difference is that you can indicate which entry is currently selected, by setting its _s_t_a_t_u_s to _o_n. --------ttttaaaaiiiillllbbbbooooxxxx ffffiiiilllleeee hhhheeeeiiiigggghhhhtttt wwwwiiiiddddtttthhhh Display text from a file in a dialog box, as in a "tail -f" command. --------tttteeeexxxxttttbbbbooooxxxx ffffiiiilllleeee hhhheeeeiiiigggghhhhtttt wwwwiiiiddddtttthhhh A tttteeeexxxxtttt box lets you display the contents of a text file in a dialog box. It is like a simple text file viewer. The user can move through the file by using the _U_P/_D_O_W_N, _P_G_U_P/_P_G_D_N and _H_O_M_E/_E_N_D keys available on most keyboards. If the lines are too long to be displayed in the box, the _L_E_F_T/_R_I_G_H_T keys can be used to scroll the text region horizontally. For more convenience, forward and backward searching functions are also pro- vided. --------tttteeeexxxxttttbbbbooooxxxxbbbbgggg ffffiiiilllleeee hhhheeeeiiiigggghhhhtttt wwwwiiiiddddtttthhhh Display text from a file in a dialog box in a back- ground process, as in a "tail -f &" command. --------yyyyeeeessssnnnnoooo _t_e_x_t _h_e_i_g_h_t _w_i_d_t_h A yyyyeeeessss////nnnnoooo dialog box of size _h_e_i_g_h_t rows by _w_i_d_t_h columns will be displayed. The string specified by _t_e_x_t is displayed inside the dialog box. If this string is too long to be fitted in one line, it will be automati- cally divided into multiple lines at appropriate places. The _t_e_x_t string may also contain the sub-string "\_n" or newline characters `\_n' to control line break- ing explicitly. This dialog box is useful for asking questions that require the user to answer either yes or no. The dialog box has a YYYYeeeessss button and a NNNNoooo button, in which the user can switch between by pressing the Dialog Version 0.4 5 DIALOG(1) USER COMMANDS DIALOG(1) _T_A_B key. RRRRUUUUNNNN----TTTTIIIIMMMMEEEE CCCCOOOONNNNFFFFIIIIGGGGUUUURRRRAAAATTTTIIIIOOOONNNN 1. Create a sample configuration file by typing: "dialog --create-rc " 2. At start, ddddiiiiaaaalllloooogggg determines the settings to use as fol- lows: a) if environment variable DDDDIIIIAAAALLLLOOOOGGGGRRRRCCCC is set, its value determines the name of the configuration file. b) if the file in (a) can't be found, use the file $_H_O_M_E/._d_i_a_l_o_g_r_c as the configuration file. c) if the file in (b) can't be found, use compiled in defaults. 3. Edit the sample configuration file and copy it to some place that ddddiiiiaaaalllloooogggg can find, as stated in step 2 above. EEEENNNNVVVVIIIIRRRROOOONNNNMMMMEEEENNNNTTTT DDDDIIIIAAAALLLLOOOOGGGGRRRRCCCC Define this variable if you want to specify the name of the configuration file to use. FFFFIIIILLLLEEEESSSS $_H_O_M_E/._d_i_a_l_o_g_r_c default configuration file DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS Exit status is 0 if ddddiiiiaaaalllloooogggg is exited by pressing the YYYYeeeessss or OOOOKKKK button. 1 if the NNNNoooo or CCCCaaaannnncccceeeellll button is pressed. -1 if errors occur inside ddddiiiiaaaalllloooogggg or ddddiiiiaaaalllloooogggg is exited by pressing the _E_S_C key. BBBBUUUUGGGGSSSS Text files containing _t_a_b characters may cause problems with tttteeeexxxxtttt box. _T_a_b characters in text files must first be expanded to spaces before being displayed by tttteeeexxxxtttt box. Screen update is too slow. AAAAUUUUTTTTHHHHOOOORRRR Savio Lam (lam836@cs.cuhk.hk) - version 0.3 Stuart Herbert (S.Herbert@sheffield.ac.uk) - patch for ver- sion 0.4 Dialog Version 0.4 6 DIALOG(1) USER COMMANDS DIALOG(1) Thomas Dickey (updates for 0.9b) Dialog Version 0.4 7