script-dialog

Create bash scripts that utilize the best dialog system that is available. Intended for Linux, but has been tested on macOS and Windows, and should work on other unix-like OSs.

• If it's launched from a GUI (like a .desktop shortcut or the dolphin file manager),
  1. It will prefer kdialog in Qt-based desktops and zenity in other environments.
  2. If neither of those are available, then relaunch-if-not-visible will relaunch the app in a terminal so that a terminal UI can be used.
• If it's launched in a terminal,
  1. It will use whiptail or dialog.
  2. If neither of those are available, then it will fallback to basic terminal input/output with tools like read and echo.

To Use

Source script-dialog.sh. Then use the library's variables and functions. The test.sh script will contain examples of each feature.

The following example assumes it's in the same folder as your script:

    SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
    source "${SCRIPT_DIR}"/script-dialog.sh

    APP_NAME="My Utility Script"

    ACTIVITY="Intro"
    message-info "Hello!"

Modular Structure

The library is organized into modular files for easier maintenance and development. When you source script-dialog.sh, it automatically loads all required modules:

script-dialog.sh         # Main entry point - sources all modules
├── init.sh              # Environment detection and variable initialization
├── helpers.sh           # Internal helper functions and utilities
├── messages.sh          # Message boxes (info, warn, error, pause, yesno, display-file)
├── inputs.sh            # Input dialogs (inputbox, password, userandpassword)
├── lists.sh             # Selection lists (checklist, radiolist)
├── progressbar.sh       # Progress bar functions
├── pickers.sh           # File and folder pickers
├── datepicker.sh        # Date picker dialog
└── extras/
    ├── test.sh          # Test script demonstrating all features
    └── screenshot-dialogs.sh  # Utility for capturing dialog screenshots

For users: Nothing changes! Simply source script-dialog.sh as before and all functions will be available.

For contributors: You can now edit individual function files in the root directory without dealing with a large monolithic file. Each module focuses on a specific type of dialog functionality.

FAQ

Scripts open in a text editor instead of running, what gives? One of 2 things has happened:

• The script has not been marked as "executable" in it's permission properties.

  That's the execute bit, chmod +x test.sh, for you terminal folks.

• Some desktop environments do this as default script behavior, assuming scripts are only run from terminal and edited from GUIs.

  You may have to change your file manager preferences on scripts or "Executable Text Files", or right click and choose to "Run As Program".

  The latter option may run the script in a terminal instead of GUI. Not much can be done about "GNOME choses to force scripts to open via terminal" type issues. If this is for a permanent script, create an application shortcut (by creating a .desktop file in $HOME/.local/share/applications/).

Global Variables

Name	Use	Description
APP_NAME	User-defined	The script's app name, for title bars
ACTIVITY	User-defined	The current activity, for title bars
INTERFACE	Override or Detected	the GUI or TUI to use
GUI	Detected	Whether the interface is a GUI not TUI
DETECTED_DESKTOP	Detected	Desktop in use
SCRIPT_DIALOG_CANCEL_EXIT_CODE	Optional override	Exit code when a dialog is cancelled (default: 124)
NOCOLORS	Optional override	disables otherwise-detected use of colored/bolded text basic CLI
NOSYMBOLS	Optional override	disables otherwise-detected use of unicode symbols in TUIs
ZENITY_HEIGHT	Optional override	height of zenity dialogs
ZENITY_WIDTH	Optional override	width of zenity dialogs

Functions

Name	Description	Arguments	Output or Return
superuser	Attempts to run a privileged command (sudo or equivalent)	Command to run with elevated privilege	return code 0 if success, non-zero otherwise
relaunch-if-not-visible	if neither GUI nor terminal interfaces can be used, relaunch the script in a terminal emulator
message-info	Display an 'info' message box	The text to display
message-warn	Display a 'warning' message box	The text to display
message-error	Display an 'error' message box	The text to display
messagebox	Display a message box	The text to display
pause	Display a "Continue or Quit" dialog with optional message	Optional message (defaults to "Continue?")	Exits script if user chooses Quit, returns 0 if Continue
yesno	Display a yes-no decision message box	The text to display	return code 0 if yes, 1 if no
inputbox	Display a text input box	The text to display The initial input value	the entered text
userandpassword	Display a (single or series of) input box(es) for entering a username and a password	The name of the username variable The name of the password variable The initial username input value The text to display for username entry The text to display for password entry
password	Display an input box for entering a password	The text to display for password entry	the entered text
display-file	Display the contents of a file	The file whose text to display width of GUI display (512 if omitted) height of GUI display (640 if omitted)
checklist	Display a list of multiply-selectable items	The file whose text to display Number of options First item's value First item's description First item's default checked status (ON or OFF) (repeat for all items)	Value text of the selected item (or the default item)
radiolist	Display a list of singularly-selectable items	The file whose text to display Number of options First item's value First item's description First item's default selected status (ON or OFF) (repeat for all items)	Value text of the selected item (or the default item)
progressbar	A pipe that displays a progressbar	the current value of the bar (repeatable, should be piped)
progressbar_update	Updates the value of the progressbar (call from within the progressbar piped block)	the new percentage value the new status text
progressbar_finish	Completes the progressbar (call from within the progressbar piped block)
filepicker	Display a file selector dialog	The starting folder "save" or "open" (assume "open" if omitted)	Path to selected file
folderpicker	Display a folder selector dialog	The starting folder	Path to selected folder
datepicker	Display a calendar date selector dialog	The starting folder	Selected date text (DD/MM/YYYY)

Screenshot Utility

The screenshot-dialogs.sh script helps create screenshots of dialog features using different interfaces. This is useful for:

• Documenting features in pull requests
• Creating visual demonstrations of dialog variations
• Testing dialog appearance across different interfaces

Note: This utility requires a graphical environment (X11 or Wayland) to capture screenshots. It will not work in headless environments.

Usage

# Screenshot all available interfaces with common dialogs
./screenshot-dialogs.sh

# Screenshot a specific interface with all common dialogs
./screenshot-dialogs.sh --interface zenity

# Screenshot a specific dialog type with all available interfaces
./screenshot-dialogs.sh --dialog info

# Screenshot a specific interface and dialog type
./screenshot-dialogs.sh --interface whiptail --dialog yesno

# Specify custom output directory
./screenshot-dialogs.sh --output ./my-screenshots

# Show all options
./screenshot-dialogs.sh --help

Requirements

The script requires one of the following screenshot tools to be installed:

For Wayland:

• grim - works with wlroots-based compositors (Sway, Wayfire, etc.)
• wayshot - alternative for wlroots-based compositors
• gnome-screenshot - recommended for GNOME Wayland (Mutter compositor)
• spectacle - recommended for KDE Plasma Wayland

Note: grim and wayshot require the wlr-screencopy-unstable-v1 protocol, which is not supported by GNOME's Mutter or KDE's KWin compositors. The script automatically detects your compositor and prioritizes the appropriate tool.

For X11:

• import (from ImageMagick) - recommended for X11
• scrot
• maim
• gnome-screenshot
• spectacle

Installation:

• On Ubuntu/Debian (GNOME Wayland): sudo apt install gnome-screenshot
• On Ubuntu/Debian (KDE Wayland): sudo apt install spectacle
• On Ubuntu/Debian (wlroots Wayland): sudo apt install grim
• On Ubuntu/Debian (X11): sudo apt install imagemagick
• On macOS: brew install imagemagick