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. The option --classic will select the "classic" FLTK file/directory selection widget, but some options may not work.

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

You can also display two progress bars using the command --multi=[NUMBER]. The main bar, showing the overall progress, will reach 100% if the other bar has reached 100% after NUMBER iterations. Example:

(echo '#1/3'; echo 40; sleep 1; echo 80; sleep 1; echo 100; sleep 1; \
 echo '#2/3'; echo 40; sleep 1; echo 80; sleep 1; echo 100; sleep 1; \
 echo '#3/3'; echo 40; sleep 1; echo 80; sleep 1; echo '#Done.'; echo 100) | \
fltk-dialog --progress --multi=3

--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. You can set the range an the step. The options --min-value=3 --max-value=17 --step=0.2 for example will display a scale from 3 to 17 in 0.2 steps.

--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

Display text read from STDIN. Usage examples:

# simply show the contents of a text file
cat file.txt | fltk-dialog --text-info
fltk-dialog --text-info < file.txt

# show the output of the tar command extracting an archive
# automatically scroll down with --auto-scroll
tar xfv archive.tar.xz | fltk-dialog --text-info --auto-scroll

# display a license text and use --checkbox; OK button will be activated
# only if the user selects the checkbox
fltk-dialog --text-info --checkbox="I read this license and agree with its conditions" < LICENSE

--notification

Show up a notification message. Icon and timeout can be specified too.

Example:

fltk-dialog --notification \
  --title="Error" \
  --text="Something weird happened!" \
  --icon=icon.png \
  --timeout=3

With --libnotify you can use libnotify to display the message. Usage is the same but the timeout value might be ignored on some desktop environments.

--indicator

Shows an indicator as a small tile in the corner of the desktop. An icon can be set with --icon=ICON, the command to be executed when clicking on the tile must be given with --indicator=COMMAND (use shell scripts for complex commands). A tooltip message can be set with --text. Use --auto-close to remove the indicator icon when the command was run. Left click on the tile will execute the command, right click allows to move the tile and middle mouse closes it.

Tip: can be combined with --skip-taskbar and --always-on-top

Example using the global Firefox icon:

fltk-dialog --indicator="echo 'Hello World'" \
  --text="Click me!" \
  --icon=firefox \
  --auto-close \
  --skip-taskbar \
  --always-on-top

The legacy Xlib "minimize to tray" method is basically no longer supported on most DE's (or very broken/buggy), which is the reason why I have removed it and replaced with the small tile windows. In order to get a real tray icon you must use --native, --native-gtk or --native-qt.

You can change the icon or close the indicator using commands given with pipes. icon:NEWICON will change the icon, run will run the command and quit will close the tray/tile.

Example:

# setup pipe
pipe=$(mktemp -u)
mkfifo $pipe
exec 3<> $pipe

fltk-dialog --indicator="echo Hello" --listen <&3 &
echo "icon:firefox" >&3
echo "run" >&3
echo "quit" >&3

--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