Designing Simple front ends with dialog/Xdialog

By Sunil Thomas Thonikuzhiyil

1) Introduction

This article introduces dialog and Xdialog for building simple front ends to shell scripts. It assumes that you are familiar with shell programming.
The latest version of this document can be found at http://gnubox.dyndns.org:8080/~sunil/dialog.php.

dialog is a utility for building console-based front ends. Xdialog is a similar program for X. Both programs are more or less compatible and easy to program. Dialog is shipped with most GNU/Linux distributions. If you want to build from sources, a tarball can be obtained from here. Xdialog is available from here.

Both of these programs are free software and run on a variety of *nix platforms. Most of the examples given in this tutorial are adapted from examples given along with dialog sources.

2) Basics

Here is the first dialog script I tried. It displays a simple YES/NO box.

#!/bin/bash
DIALOG=${DIALOG=dialog}

$DIALOG --title " My first dialog" --clear \
        --yesno "Hello , this is my first dialog program" 10 30

case $? in
  0)
    echo "Yes chosen.";;
  1)
    echo "No chosen.";;
  255)
    echo "ESC pressed.";;
esac

Copy the above lines to a file say yesno.sh and give executable permission to it.

$chmod u+x yesno.sh

Now try running the program.

$./yesno.sh

A screen-shot of the above program is given below.

Now try changing the line.

 DIALOG=${DIALOG=dialog}

to

DIALOG=${DIALOG=Xdialog}

Try running it from an xterm. I got the following output.

Let us have a detailed look at the above program. The first line is basically a comment which also indicates that bash shell is used to run this program.

DIALOG=${DIALOG=dialog}

The above line sets the variable DIALOG to the value 'dialog'. The actual dialog box is drawn by the following line.

  $DIALOG --title "My first dialog" --clear \
        --yesno "Hello, this is my first dialog program" 10 30

Options used are
--title This option sets title of your box
--clear This option clears the screen before drawing
--yesnobox This draws the box with the text given inside the box.

The text to be printed inside yesnobox is given in double quotes. The text wraps depending on width of the box. You can use \n to force a new line. Last 2 numbers specify width and height of the box. You can move between "yes" and "no" using tabs.

The dialog program now waits for user input. When you press enter on "yes" or "no" or if you press escape key the program returns and the return value is available on shell variable $? which you can process further.

2) Reading input

The following program reads a string you input and prints it back.

#!/bin/sh
DIALOG=${DIALOG=dialog}
tempfile=`tempfile 2>/dev/null` || tempfile=/tmp/test$$
trap "rm -f $tempfile" 0 1 2 5 15

$DIALOG --title "My input box" --clear \
        --inputbox "Hi, this is a sample input box\n
Try entering your name below:" 16 51 2> $tempfile

retval=$?

case $retval in
  0)
    echo "Input string is `cat $tempfile`";;
  1)
    echo "Cancel pressed.";;
  255)
    if test -s $tempfile ; then
      cat $tempfile
    else
      echo "ESC pressed."
    fi
    ;;
esac

Try running the program under console and under X ( after changing dialog to Xdialog as above). See the results.

This program is slightly more complex than our previous yesno box program. The following lines set up a temporary file:

tempfile=`tempfile 2>/dev/null` || tempfile=/tmp/test$$
trap "rm -f $tempfile" 0 1 2 5 15

The first line above tries to create a temporary file using the utility tempfile. If it fails, a temporary file is manually set up in /tmp. The second line above sets up a trap routine. When the script exits (either normally or abnormally) the trap removes the tempfile. The numbers shown are the signals that will be trapped.

dialog is then invoked as below:

$DIALOG --title "My input box" --clear \
        --inputbox "Hi, this is a sample input box\n
         Try entering your name below:" 16 51 2> $tempfile

The dialog program writes its output to the standard error by default. Hence the input string you enter is echoed to standard error which we are redirecting to our tempfile. You can capture the entered text from tempfile for further processing.

3) Building a menu

Try the following program both in console and X (after changing dialog to Xdialog as before):

#!/bin/sh
DIALOG=${DIALOG=dialog}
tempfile=`tempfile 2>/dev/null` || tempfile=/tmp/test$$
trap "rm -f $tempfile" 0 1 2 5 15

$DIALOG --clear --title "My  favorite HINDI singer" \
        --menu "Hi, Choose  your favorite HINDI singer:" 20 51 4 \
        "Rafi"  "Mohammed Rafi" \
        "Mukesh" "Mukesh" \
        "Kishore" "Kishore Kumar" \
        "Saigal" "K L Saigal" \
        "Lata"  "Lata Mangeshkar" \
        "Yesudas"  "K J Yesudas" 2> $tempfile

retval=$?

choice=`cat $tempfile`

case $retval in
  0)
    echo "'$choice' is your favorite hindi singer";;
  1)
    echo "Cancel pressed.";;
  255)
    echo "ESC pressed.";;
esac

The results are as below

The logic is exactly similar to inputbox. We redirect the choice you have selected to a tempfile and then process return value of dialog and contents of the tempfile.

4) Radiolist and Checklist

Radiolists and checklists can be programmed just like menus. A simple radio list example is given below.

#! /bin/sh
DIALOG=${DIALOG=dialog}
tempfile=`tempfile 2>/dev/null` || tempfile=/tmp/test$$
trap "rm -f $tempfile" 0 1 2 5 15

$DIALOG --backtitle "Select your favorite singer" \
	--title "My favorite singer" --clear \
        --radiolist "Hi, you can select your favorite singer here  " 20 61 5 \
        "Rafi"  "Mohammed Rafi" off \
        "Lata"    "Lata Mangeshkar" ON \
        "Hemant" "Hemant Kumar" off \
        "Dey"    "MannaDey" off \
        "Kishore"    "Kishore Kumar" off \
        "Yesudas"   "K. J. Yesudas" off  2> $tempfile

retval=$?

choice=`cat $tempfile`
case $retval in
  0)
    echo "'$choice' is your favorite singer";;
  1)
    echo "Cancel pressed.";;
  255)
    echo "ESC pressed.";;
esac

A screen shot is shown below.

For trying out checklist just change --radiolist option in the above program to --checklist.

5) Building a Gauge

A gauge based on dialog can be used to indicate progress of your program. Building a gauge is slightly tricky. Look at the following example:

#!/bin/sh
DIALOG=${DIALOG=dialog}

COUNT=10
(
while test $COUNT != 110
do
echo $COUNT
echo "XXX"
echo "The new\n\message ($COUNT percent)"
echo "XXX"
COUNT=`expr $COUNT + 10`
sleep 1
done
) |
$DIALOG --title "My Gauge" --gauge "Hi, this is a gauge widget" 20 70 0

Here the dialog program gets its input from the code shown within the parentheses. This code emits the number to be used for gauge and the message to be shown. The message to be shown in the gauge box must be surrounded by echo "XXX". The screen-shot of a gauge is shown below.

6) File selections

Code for a typical file selection dialog box is shown below.

#!/bin/sh
DIALOG=${DIALOG=dialog}

FILE=`$DIALOG --stdout --title "Please choose a file" --fselect $HOME/ 14 48`

case $? in
	0)
		echo "\"$FILE\" chosen";;
	1)
		echo "Cancel pressed.";;
	255)
		echo "Box closed.";;
esac

Please note that the above program uses a different technique to capture the selected file. As mentioned previously all outputs from dialog is sent to standard error by default. However --stdout option can be used to send the output information to standard output which in turn can be assigned to a variable. This trick can be used in the case of other dialog boxes such as menubox yesnobox etc.

The file selection dialog presents 2 panes. You can use Tab key to switch between panes and space key to select a file. It is also possible to type into the input box of files select dialog.

7) Calendar and time boxes

a) Calendar

A calendar box displays month, day and year in separately adjustable windows. If the values for day, month or year are missing or negative, the current date's corresponding values are used. You can increment or decrement any of those using the left-, up-, right- and down-arrows. Use vi-style h, j, k and l for moving around the array of days in a month. Use tab or back tab to move between windows. If the year is given as zero, the current date is used as an initial value. On exit, the date is printed in the form day/month/year.

#!/bin/sh
DIALOG=${DIALOG=dialog}

USERDATE=`$DIALOG --stdout --title "CALENDAR" --calendar "Please choose a date..." 0 0 7 7 1981`

case $? in
  0)
    echo "Date entered: $USERDATE.";;
  1)
    echo "Cancel pressed.";;
  255)
    echo "Box closed.";;
esac

b) Time

The time dialog box allows you to select time. Try out the following program and see how it works.

#!/bin/sh

DIALOG=${DIALOG=dialog}
USERTIME=`$DIALOG --stdout --title "TIMEBOX" --timebox "Please set the time..." 0 0 12 34 56`

case $? in
  0)
    echo "Time entered: $USERTIME.";;
  1)
    echo "Cancel pressed.";;
  255)
    echo "Box closed.";;
esac

8) Other Features

Xdialog has some additional features such as tree-view, range-box, edit-box, etc. Please look here. Dialog man page has interesting information of some other options such as password box, tailbox etc. Also there are options for changing colors, shadow etc.

9) Tips

You can choose between dialog and Xdialog at run time using the following code snippet:

   if [ -z $DISPLAY ]
   then
   DIALOG=dialog
   else
    DIALOG=Xdialog
   fi
  

Try this program on console as well as under X and see the difference.

 #!/bin/sh
 if [ -z $DISPLAY ]
 then
 DIALOG=dialog
  else
   DIALOG=Xdialog
  fi
 $DIALOG --yesno "Is this fun" 0 0  
 

10) References

1) Manual page for dialog

It is a must read if you are planning to write some useful dialog scripts. There are several other options which allow you to modify the look and feel.

2) Dialog examples at http://www.fifi.org/doc/dialog/examples/.

All the examples in this tutorial are modified versions of examples found here. If you have Debian GNU/Linux the examples are available at /usr/share/doc/dialog/examples.

3) Thomas Dickey's dialog page: http://dickey.his.com/dialog/

4) Vincent Stemen's dialog page http://hightek.org/dialog/.

This page has comprehensive information on various dialog versions.

5) Xdialog documentation at http://thgodef.nerim.net/xdialog/doc/index.html.
This page has exhaustive information on Xdialog.

 

---

I work as consultant information technology at the Kerala Legislative Assembly Trivandrum India. I have been hooked on Linux since 1996. I have a Masters in Computer Science from Cochin University. I am interested in all sorts of operating systems. In my free time I love to listen to Indian classical music.