Command Line – dialog

Many Bash scripts do not need interfaces. They are run by admins, who are comfortable at the command line. However, if a script is used by everyday users, it may be more friendly if it uses a dialog box for input and messages. For over 25 years, a leading command for boxes has been dialog [1], which can be called from a script so that users can enter input in an ncurses interface. It then returns them to the script when they exit.

The command structure of dialog is somewhat unusual (Listing 1). In addition to the appearance of options in two separate places, note the quotation marks around the text, and the order of height, width, and other box type options. Height is expressed as the number of lines and width as the number of monospaced characters.

The design of the resulting box varies with the options selected. However, it will always have text and may have buttons (such as Yes, No, Help, or OK) or radio buttons for making selections. It may also have a back title for easy identification. When necessary, the box can be navigated by using arrow keys, and it is not supported by a mouse (Figure 1). Once a selection is made, then generally the script will continue with if/then/else statements that correspond to each selection.

Figure 1: A progress bar with a back title in the top left corner.

Generally, the easiest way to design a box is to open another prompt and run the basic dialog command repeatedly until you have a structure ready to add to the script. Use the Esc key to return to the prompt after the resulting box is displayed. Unless the background for the dialog box matches the background color for the terminal, you will see conflicting colors after returning to the prompt unless you enter the clear command or a sufficient number of new commands.

Using Box Options

It makes sense to begin with the available types of boxes, one of which must always be used in a dialog command. All boxes can use the self-explanatory text, height, and width options. Text appears after the box type in quotation marks, while height and width options follow, expressed in lines and characters respectively.

Other options must follow the width. Available options depend on the type of box, as shown in Table 1.

A simple message box (Figure 2) would use a command like:

dialog --title "Choose" --msgbox 'Invalid option. Choose again' 6 20

Figure 2: A simple message box.

A more complicated example is a checklist, which asks for a selection (see Listing 2 and Figure 3).

Figure 3: A checklist box, with the default choice set to Accept.

Listing 2 shows items prefaced with an identifying tag and followed by a status for the default display, as well as the end of line markers.

Other boxes have similar structures, modified by any common command options. For example, the message box given above might have a help button added to it with the addition of a --help button option (Figure 4).

Figure 4: The same checklist box as in Figure 3, but with the addition of a Help button.

For a complete description of each option, see the man page. Some options have restrictions, most of which are logical enough when you stop to think. For example, a help button can only be added to checklist, radio list, and menu boxes. There would be no point to adding a help button to a message box, for instance, which requires no user interaction.

Screenshots of other boxes are available online [2].

Common Dialog Options

Common dialog options affect the look and general functionality of the command. --ascii-line replaces the ncurses widgets used to create a box with plus and minus signs instead (Figure 5). Ordinarily, a box is centered on the screen, but you can also use --begin Y X to set the vertical and horizontal coordinates for the upper left corner of the box. You can also set the dimensions of a box with --aspect WIDTH/HEIGHT. With --scrollbar, a scrollbar is added to the box, while --no-shadow suppresses the default shadow to the right and bottom of the box – an option which gives ncurses a flatter but more modern-looking appearance.

Figure 5: The same box as in Figure 4, but with boxes drawn with ASCII line art rather than ncurses widgets.

--color expresses settings prefaced by a \Z . It uses the numbers 0-7 to choose ANSI colors: black, red, green, yellow, blue, magenta, cyan, and white – in that order. However, contrary to what you might expect from the name, --color also sets font weights and effects: b sets bold, and B turns off bold, while u turns on underlining and U turns it off. The settings are cumulative, so Z\u\3 produces green, underlined text. To restore default settings, use \Zn.

Many of the common options have to do with how the buttons in a box are used. Options like --no-cancel suppress the display of a specific button altogether. Others, like --help button add a button to types of boxes that could use one; a gauge box, for example, would have no use for a Help button, since there is no interaction. Others, like --exit-label STRING, --ok-label STRING, --no-label STRING, and --yes-label STRING replace the standard button titles, making the buttons more versatile. In boxes like menus, checklists, and radio lists that require a selection of a list of items, you can also use --item-help to add help for each item, and --default-item STRING to select which choices are selected by default.

Still other items affect what happens after a dialog displays. For example, --stdout prints the result of a dialog interaction to standard input and --stderr to standard error, which may simplify scripting. Script writers may also use --sleep SECONDS to pause a script after it processes input from a dialog box or --and-widget to force dialog to move to the next box after the current one is processed without resuming the script.

dialog's options total in the dozens, and setting up the command structure can be laborious. For this reason, you may want to run dialog --create-rc FILE in your home directory to create a default look and function for the command. The file uses the current settings of your current terminal. Although you probably want to leave the top of the line untouched, there are many choices that are self-explanatory enough to edit. This file can be overridden by options entered at the command line, but can save considerable time if you use dialog regularly (Figure 6).

Figure 6: Part of the dialog configuration file.

Alternatives to Dialog

While dialog is the most common option for adding partial interfaces to scripts, both whiptail [3] and zenity [4] offer a similar, if less complete command structure. However, zenity's man page is perhaps needlessly complex, dividing options into 10 different categories that at first make it difficult to see the overall command structure. Moreover, zenity uses GTK+ rather than ncurses.

In addition, Xdialog [5] is intended as a drop-in replacement for dialog, and is referenced in dialog's man pages to mention a few minor differences. However, dialog remains the most extensive and more commonly used. As primitive as ncurses may appear to modern users, it is generally adequate for the purposes of most scripts.