Home

fltk-dialog

fltk-dialog is meant to start dialog windows from a shell script. This can be used to make user interaction easier.

Here I will explain the different dialog types and give some usage examples.

--message

A simple message box with a "close" button. Return code (echo $?) is always 0.

Usage example:

fltk-dialog \
  --message \
  --title="Example" \
  --text="Hello World"

Hint: line breaks make your code easier to read if you add a lot of command line parameters.

--warning

A message box with an "OK" button and a "Cancel" button. Return code is 1 if "Cancel" is clicked or if the window was closed (Alt+F4), clicking "OK" returns 0.

Example:

fltk-dialog --warning \
  --title="Warning!" \
  --text="Something went wrong!"

You can use the command directly in an if-else statement to make use of the return code:

if fltk-dialog --warning \
  --title="$title" \
  --text="$text"
then
  do_something_ok
else
  do_something_cancel
fi

Or you can use the special shell variable $? to get the exit code of the last executed command:

fltk-dialog --warning \
  --title="$title" \
  --text="$text"

if [ $? -eq 0 ]; then
  do_something_ok
else
  do_something_cancel
fi

--question

A yes/no question dialog. "Yes" returns 0, "No" and closing the window returns 1.

Example:

if ! fltk-dialog --question \
  --title="Continue" \
  --text="Do you really want to continue?"
then
  exit
fi

You can also alter the text of the buttons with --yes-label=TEXT and --no-label=TEXT:

if ! fltk-dialog --question \
  --title="Continue" \
  --text="Do you want to continue?" \
  --yes-label="Continue" \
  --no-label="Stop"
then
  exit
fi

If required a third button, which will return 2 if clicked, can be added with --alt-label=TEXT:

fltk-dialog --question \
  --title="Continue" \
  --text="Do you want to continue?" \
  --yes-label="Continue" \
  --no-label="Stop" \
  --alt-label="Go back"

case $? in
  0) action_continue ;;
  1) exit ;;
  2) action_back ;;
esac

--dnd

A drag & drop window. You can drag files/directories/symbolic links, hypertext links and selected text into it. The filenames, links or text will be printed on the shell. Return code is always 0.

--file / --directory

A file/directory selection dialog. Returns 1 if cancelled, otherwise 0. The full path of the selected file/directoy will be printed on the shell. With --file --native or --directory --native you can also choose the system's native selection dialog, which may look and integrate better into your desktop environment. If fltk-dialog can't start the native dialog, it will fall back to FLTK's version. You can also try to explicitly run the Qt or GTK dialog by using --native-qt or --native-gtk instead of --native.

Example:

file=$(fltk-dialog --file \
  --native \
  --title="Select a file you want to copy")

if [ $? -eq 0 ]; then
  cp "$file" "$HOME/$(basename $file)"
fi

--entry

A text entry dialog. Returns 1 if cancelled, otherwise 0.

Example:

name=$(fltk-dialog \
  --entry \
  --title="Username" \
  --text="Select a username:")

if [ $? -eq 0 ]; then
  echo "Username: $name"
fi

--password

Same as --entry, but instead of the entered characters only dots will be visible. Use this wisely! It's better to use gksudo or kdesudo if you need a graphical sudo password entering form.

--progress

Shows a progress bar. Information on the progress is taken from STDIN. Lines beginning with a # will change the text, lines beginning with a number will change the progress.

Example:

(echo 40; sleep 1; \
 echo 80; sleep 1; \
 echo 99; sleep 1; \
 echo '#Done' && \
 echo '100') | fltk-dialog --progress

If you cannot or don't want to display the exact progress you can use a "pulsating" widget with --progress --pulsate. A pulsating progress bar can be stopped with the line STOP.

Example:

(echo '#Work in progress... '; \
 sleep 4; \
 echo '#Work in progress... done.'; \
 echo 'STOP') | fltk-dialog --progress --pulsate

--calendar / --date

Displays a calendar or a more simplistic dialog for date selection and returns the selected date. The default format for the returned date is Y-M-D.

You can use --format=FORMAT to set the output using glibc date formats. Interpreted sequences for FORMAT are (using the date 2006-01-08):

%%: literal %
%-d, %d: day [8, 08]
%-m, %m: month [1, 01]
%y, %Y: year [06, 2006]
%-j, %j: day of the year [8, 008]
%A, %a: weekday name [Sunday, Sun]
%-V, %V: ISO 8601 week number [1, 01]
%B, %b: month name [January, Jan]
%u: day of the week, Monday being 1 [7]

Example:

fltk-dialog --calendar --format="Week %-V, %A, %B %-d, %Y"

--color

Color selection dialog. Returns the selected color in 4 different formats, separated by a pipe (|) symbol: RGB (range 0.000-1.000)|RGB (range 0-255)|HTML hex|HSV

As an example, here is the output when selecting blue: 0.000 0.000 1.000|0 0 255|#000ff|4.000 1.000 1.000

--scale

This will display a horizontal slider with a default range of 0-100. On "OK" the selected value will be returned.

--checklist

Create a multiple choice selection list. Items for the list are separated with a pipe (|) symbol. Pressing "OK" it will return a pipe separated list with the labels TRUE for selected items and FALSE for items that weren't selected.

For example: creating a list of fruits with --checklist="Apple|Banana|Cherry|Orange" and picking Apple and Cherry will return TRUE|FALSE|TRUE|FALSE.

--radiolist

Create a radio button list. This is similar to --checklist, but you can only select one item at a time. The selected item's label will be returned.

For example: creating a list of fruits with --radiolist="Apple|Banana|Cherry|Orange" and picking Cherry will return Cherry.

--dropdown

Create a drop-down menu. It's the same as --radiolist but with a drop-down menu button.

--html

Use --html=FILE to view an HTML file. The HTML support is very limited. You can use it as a document viewer, i.e. for manuals or license texts.

--text-info

To do.

--notification

Show up a notification message. This requires libnotify.

Example: fltk-dialog --notification --title="Error" --text="Something weird happened!"

--font

A font selection dialog. The selected font and font size, separated by a pipe (|), will be returned. An example output would be: sans bold italic|14