====== Dialog - Terminal Menu Creator ======

[[https://invisible-island.net/dialog/|Dialog]] is a script-driven menu and text interface generation tool. For example, it has file pickers, menus, checklists, confirmations, calendars, progress bars, etc.

The official documentation and downloads are at [[https://invisible-island.net/dialog/#documentation]].

More screenshots and examples of all widgets are available at [[https://invisible-island.net/dialog/dialog-figures.html]].

===== Install =====

In Debian and most Linux distributions it's as simple as using the package manager to install:

<code bash>
apt install dialog
dpkg -L dialog
dialog --version
dialog --help
man dialog
</code>

If you want to build from source, simply download, configure, and make:

<code bash>
wget ftp://ftp.invisible-island.net/dialog/dialog.tar.gz
tar xzf dialog.tar.gz
cd dialog-1.3-20210324 # Or whatever it is
./configure --help | less # Check options
./configure
make
./dialog --version
./dialog --help
make install  # optional
</code>

===== Example usage =====

Here is an example of a menu with a list of choices:

<code bash>
# Generate a menu
dialog --menu "Open mail" 20 40 10 \
 "Account 1" "~/.muttrc.1" "Account 2" "~/.muttrc.2" \
 2>answer.txt
# answer.txt will contain 'Account 1' or 'Account 2'
</code>

Here is another example that shows how to get output a different way. This is out it is done in the examples in the source code.

<code bash>
# Create temp stream for current shell
exec 3>&1    

# Prompt with dialog and get response
user_text=$(dialog --inputbox Testing 0 0 2>&1 1>&3)

# Store return value of dialog process. 0 = success.
# Check if it's 0 to confirm they didn't cancel
exit_code=$?

# Close the temp stream
exec 3>&-

# Print the results
Echo "Program exit code: $exit_code"
echo "User input: $user_text"
</code>

===== Available options =====

Below you will find a list of all the options and menus available. Also refer to [[https://invisible-island.net/dialog/dialog-figures.html]] for screenshots and examples of all widgets.

There are also numerous script examples in the [[https://invisible-island.net/dialog/#download|source code]] in a directory called ''samples/''

<code>
$ dialog --help

cdialog (ComeOn Dialog!) version 1.2-20130523
Copyright 2000-2012,2013 Thomas E. Dickey
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

* Display dialog boxes from shell scripts *

Usage: dialog <options> { --and-widget <options> }
where options are "common" options, followed by "box" options

Special options:
  [--create-rc "file"]
Common options:
  [--ascii-lines] [--aspect <ratio>] [--backtitle <backtitle>] [--beep]
  [--beep-after] [--begin <y> <x>] [--cancel-label <str>] [--clear]
  [--colors] [--column-separator <str>] [--cr-wrap] [--date-format <str>]
  [--default-button <str>] [--default-item <str>] [--defaultno]
  [--exit-label <str>] [--extra-button] [--extra-label <str>]
  [--help-button] [--help-label <str>] [--help-status] [--hfile <str>]
  [--hline <str>] [--ignore] [--input-fd <fd>] [--insecure] [--item-help]
  [--keep-tite] [--keep-window] [--last-key] [--max-input <n>]
  [--no-cancel] [--no-collapse] [--no-cr-wrap] [--no-items] [--no-kill]
  [--no-label <str>] [--no-lines] [--no-mouse] [--no-nl-expand]
  [--no-ok] [--no-shadow] [--no-tags] [--nook] [--ok-label <str>]
  [--output-fd <fd>] [--output-separator <str>] [--print-maxsize]
  [--print-size] [--print-version] [--quoted] [--scrollbar]
  [--separate-output] [--separate-widget <str>] [--shadow]
  [--single-quoted] [--size-err] [--sleep <secs>] [--stderr] [--stdout]
  [--tab-correct] [--tab-len <n>] [--time-format <str>] [--timeout <secs>]
  [--title <title>] [--trace <file>] [--trim] [--version] [--visit-items]
  [--yes-label <str>]
Box options:
  --buildlist    <text> <height> <width> <tag1> <item1> <status1>...
  --calendar     <text> <height> <width> <day> <month> <year>
  --checklist    <text> <height> <width> <list height> <tag1> <item1> <status1>...
  --dselect      <directory> <height> <width>
  --editbox      <file> <height> <width>
  --form         <text> <height> <width> <form height> <label1> <l_y1> <l_x1> <item1> <i_y1> <i_x1> <flen1> <ilen1>...
  --fselect      <filepath> <height> <width>
  --gauge        <text> <height> <width> [<percent>]
  --infobox      <text> <height> <width>
  --inputbox     <text> <height> <width> [<init>]
  --inputmenu    <text> <height> <width> <menu height> <tag1> <item1>...
  --menu         <text> <height> <width> <menu height> <tag1> <item1>...
  --mixedform    <text> <height> <width> <form height> <label1> <l_y1> <l_x1> <item1> <i_y1> <i_x1> <flen1> <ilen1> <itype>...
  --mixedgauge   <text> <height> <width> <percent> <tag1> <item1>...
  --msgbox       <text> <height> <width>
  --passwordbox  <text> <height> <width> [<init>]
  --passwordform <text> <height> <width> <form height> <label1> <l_y1> <l_x1> <item1> <i_y1> <i_x1> <flen1> <ilen1>...
  --pause        <text> <height> <width> <seconds>
  --prgbox       <text> <command> <height> <width>
  --programbox   <text> <height> <width>
  --progressbox  <text> <height> <width>
  --radiolist    <text> <height> <width> <list height> <tag1> <item1> <status1>...
  --rangebox     <text> <height> <width> <min-value> <max-value> <default-value>
  --tailbox      <file> <height> <width>
  --tailboxbg    <file> <height> <width>
  --textbox      <file> <height> <width>
  --timebox      <text> <height> <width> <hour> <minute> <second>
  --treeview     <text> <height> <width> <list-height> <tag1> <item1> <status1> <depth1>...
  --yesno        <text> <height> <width>

Auto-size with height and width = 0. Maximize with height and width = -1.
Global-auto-size if also menu_height/list_height = 0.
</code>

===== .dialogrc file =====

You can specify settings in a ''~/.dialogrc'' file. There might also be one in your system under ''/etc/dialogrc''.

To generate a default rc file, run the following command.

<code bash>
# Create a ~/.dialogrc file
dialog --create-rc ~/.dialogrc
</code>

Then you'll have an rc file with all the color and options populated for you to modify.

==== Change colors ===

If you want to see some example rc files, check in the [[https://invisible-island.net/dialog/#download|source code]] in a directory called ''samples/''. For example ''whiptail.rc''. Screenshots are available at [[https://invisible-island.net/dialog/dialog-figures.html#list_colors]]. Refer to the file ''dlg_colors.h'' in the source code for a list of available colors. There aren't a ton, but it looks like there is:

  * ''BLACK''
  * ''WHITE''
  * ''CYAN''
  * ''BLUE''
  * ''YELLOW''
  * ''RED''

Also make sure ''use_color = ON'' and not OFF.

To override the default rc filename, set a ''DIALOGRC'' environment variable to specify the file you want to use.

Here is a sample ''.dialogrc'' file that has DevDungeon-ish themed colors:

<code text .dialogrc>
#
# Run-time configuration file for dialog
#
# Types of values:
#
# Number     -  <number>
# String     -  "string"
# Boolean    -  <ON|OFF>
# Attribute  -  (foreground,background,highlight?,underline?,reverse?)

# Set aspect-ration.
aspect = 0
# Set separator (for multiple widgets output).
separate_widget = ""
# Set tab-length (for textbox tab-conversion).
tab_len = 0
# Make tab-traversal for checklist, etc., include the list.
visit_items = OFF
# Shadow dialog boxes? This also turns on color.
use_shadow = OFF
# Turn color support ON or OFF
use_colors = ON
screen_color = (CYAN,BLACK,ON)
shadow_color = (RED,RED,ON)
dialog_color = (CYAN,BLACK,OFF)
title_color = (CYAN,BLACK,ON)
border_color = (CYAN,BLACK,ON)
button_active_color = (BLACK,CYAN,ON)
button_inactive_color = dialog_color
button_key_active_color = button_active_color
button_key_inactive_color = (WHITE,BLACK,ON)
button_label_active_color = (WHITE,CYAN,ON)
button_label_inactive_color = (WHITE,BLACK,ON)
inputbox_color = dialog_color
inputbox_border_color = dialog_color
searchbox_color = dialog_color
searchbox_title_color = title_color
searchbox_border_color = border_color
position_indicator_color = title_color
menubox_color = dialog_color
menubox_border_color = border_color
item_color = dialog_color
item_selected_color = button_active_color
tag_color = title_color
tag_selected_color = button_label_active_color
tag_key_color = button_key_inactive_color
tag_key_selected_color = (CYAN,BLACK,ON)
check_color = dialog_color
check_selected_color = button_active_color
uarrow_color = (RED,BLACK,ON)
darrow_color = uarrow_color
itemhelp_color = (WHITE,BLACK,OFF)
form_active_text_color = button_active_color
form_text_color = (WHITE,CYAN,ON)
form_item_readonly_color = (CYAN,WHITE,ON)
gauge_color = title_color
border2_color = dialog_color
inputbox_border2_color = dialog_color
searchbox_border2_color = dialog_color
menubox_border2_color = dialog_color
</code>