Skip to content

Latest commit

 

History

History
552 lines (451 loc) · 13.2 KB

libbash_gui.md

File metadata and controls

552 lines (451 loc) · 13.2 KB
Raw

libbash.sh GUI documentation

Introduction

libbash.sh GUI features some functions to display dialogs and notifications for scripts with graphical interfaces.

GUI tools

GUI tools are commands used to display GUI dialogs and notifications to the user.

libbash.sh GUI currently supports the following GUI tools:

  • kdialog
  • zenity
  • osascript (Apple script for macOS)
  • cscript (VBscript for Windows)
  • dialog

Usage

libbash.sh GUI is loaded with -g or --gui option:

source "/path/to/libbash.sh" -g

Then call the functions described below.

The case of cron jobs (on Linux)

If you plan to execute a script from a cron job, dialogs (like notifications) may no be printed. It's because the $DISPLAY variable is not set in the cron job context.

To avoid that, you have to manually set the DISPLAY variable in your script with the command:

export DISPLAY=":0"

You can get users current display with the following command (replace myuser by your user):

who | grep "^myuser .*(:[0-9])$" | head -1 | sed "s/.*(\(:[0-9]*\))$/\1/g"

Note: If you set the DISPLAY variable AFTER integrate libbash GUI, then you have to reset the GUI tool with calling the lbg_set_gui function (see usage below).

Functions

All functions are named with the lbg_ prefix. Functions with a * are not fully supported on every OS yet (may change in the future).

GUI tools

lbg_get_gui

Get the current GUI tool name (see available tools above).

Usage

lbg_get_gui

Exit codes

  • 0: OK
  • 1: No GUI tool available on this system

Example

gui_tool=$(lbg_get_gui)

lbg_set_gui

Set a GUI tool to be used (see the supported tools above).

By default, the first tool available in the list is used. If no tool specified, the default one will be set. If multiple tools are given, the first available will be set.

e.g. if kdialog and zenity are installed, kdialog will be used over zenity, that's why you can set zenity if you prefer.

Usage

lbg_set_gui [GUI_TOOL...]

Exit codes

  • 0: GUI tool set
  • 1: GUI tool not supported
  • 3: GUI tool not available on this system
  • 4: GUI tool available, but no X server is currently running (stay in console mode)

Example

if lbg_set_gui zenity ; then
    echo "Using zenity for dialogs."
fi

Messages and notifications

lbg_display_info, lbg_info

Display an info message dialog.

Usage

lbg_display_info [OPTIONS] TEXT

or

lbg_info [OPTIONS] TEXT

Note: you can also give TEXT argument using stdin or pipes.

Options

-t, --title TEXT  Set a title to the dialog

Exit codes

  • 0: OK
  • 1: Usage error
  • 2: Unknown dialog error

Example

lbg_info "This is an info message."

lbg_display_warning, lbg_warning

Displays a warning message dialog.

Usage

lbg_display_warning [OPTIONS] TEXT

or

lbg_warning [OPTIONS] TEXT

Note: you can also give TEXT argument using stdin or pipes.

Options

-t, --title TEXT  Set a title to the dialog

Exit codes

  • 0: OK
  • 1: Usage error
  • 2: Unknown dialog error

Example

lbg_warning "This is a warning message."

lbg_display_error, lbg_error

Displays an error message dialog.

Usage

lbg_display_error [OPTIONS] TEXT

or

lbg_error [OPTIONS] TEXT

Note: you can also give TEXT argument using stdin or pipes.

Options

-t, --title TEXT  Set a title to the dialog

Exit codes

  • 0: OK
  • 1: Usage error
  • 2: Unknown dialog error

Example

lbg_display_error "This is an error message."

lbg_display_critical, lbg_critical

Displays a critical error mesage dialog.

Usage

lbg_display_critical [OPTIONS] TEXT

or

lbg_critical [OPTIONS] TEXT

Note: you can also give TEXT argument using stdin or pipes.

Options

-t, --title TEXT  Set a title to the dialog

Exit codes

  • 0: OK
  • 1: Usage error
  • 2: Unknown dialog error

Example

lbg_critical "This is a critical error message."

lbg_display_debug, lbg_debug

Displays a debug info message dialog.

Usage

lbg_display_debug [OPTIONS] TEXT

or

lbg_debug [OPTIONS] TEXT

Note: you can also give TEXT argument using stdin or pipes.

Options

-t, --title TEXT  Set a title to the dialog

Exit codes

  • 0: OK
  • 1: Usage error
  • 2: Unknown dialog error

Example

lbg_debug "This is a debug message."

lbg_notify

Displays a notification popup.

Usage

lbg_notify [OPTIONS] TEXT

Note: you can also give TEXT argument using stdin or pipes.

notify-send

On Linux systems, the notify-send command is used by default over zenity --notification command. We chose it because it is more powerful and have a better integration on every desktop environments. But if you want, you can use the --no-notify-send option to not use it and use your chosen GUI tool.

Options

-t, --title TEXT   Set a title to the notification
--timeout SECONDS  Timeout before notification disapears (if not set, use default system)
                   This option is NOT available on macOS
--no-notify-send   Do not use the notify-send command if exists*

* See above for more details

Exit codes

  • 0: OK
  • 1: Usage error
  • 2: Notification command error

Example

lbg_notify --timeout 5 "This notification will disapper in 5 seconds..."

User interaction

lbg_yesno

Displays a dialog to ask a question to answer by yes or no.

Usage

lbg_yesno [OPTIONS] TEXT

Options

-y, --yes         Set Yes as default button (not available on kdialog and zenity)
--yes-label TEXT  Change Yes label (not available on zenity and Windows)
--no-label TEXT   Change No label (not available on zenity and Windows)
-t, --title TEXT  Set a title to the dialog

Exit codes

  • 0: Yes
  • 1: Usage error
  • 2: No

Example

if ! lbg_yesno "Do you want to continue?" ; then
    exit
fi

lbg_choose_option

Displays a dialog to ask user to choose one or multiple options.

Chosen IDs are set into the $lbg_choose_option (array) variable.

Usage

lbg_choose_option [OPTIONS] CHOICE [CHOICE...]

Options

-d, --default ID[,ID...]  Option(s) to use by default (IDs starts to 1)
-m, --multiple            Allow user to choose between multiple options
-l, --label TEXT          Set a question label (default: "Choose an option:")
-t, --title TEXT          Set a title to the dialog

Exit codes

  • 0: OK
  • 1: Usage error
  • 2: Cancelled
  • 3: Bad choice

Example

if lbg_choose_option --label "Choose a planet:" --default 1 Earth Jupiter ; then
    chosen_planet=$lbg_choose_option
fi

if lbg_choose_option --multiple --label "Choose valid countries:" --default 1,2 France USA Neverland ; then
    chosen_countries=(${lbg_choose_option[@]})
fi

lbg_input_text

Displays a dialog to ask user to input a text.

Input text is stored into the $lbg_input_text variable.

Usage

lbg_input_text [OPTIONS] TEXT

Options

-d, --default TEXT  Default value
-t, --title TEXT    Set a title to the dialog

Exit codes

  • 0: OK
  • 1: Usage error
  • 2: Cancelled

Example

if lbg_input_text --default $(whoami) "Please enter your username:" ; then
    user_name=$lbg_input_text
fi

lbg_input_password

Displays a dialog to ask user to input a password.

WARNING: No password dialog is displayed on Windows (prompt in console).

Usage

lbg_input_password [OPTIONS] [QUESTION_TEXT]

Password is stored into the $lbg_input_password variable.

Options

-c, --confirm         Display a confirm password dialog
--confirm-label TEXT  Set the confirmation label (not available on zenity)
-m, --min-size N      Force password to have at least N characters
-t, --title TEXT      Set a title for the dialog
QUESTION_TEXT         Set a label for the question (not available on zenity)

Exit codes

  • 0: OK
  • 1: Usage error
  • 2: Cancelled
  • 3: Passwords mismatch
  • 4: Password is too short (if --min-size option is set)

Example

if lbg_input_password ; then
    user_password=$lbg_input_password
fi

Files and directories

lbg_choose_directory

Displays a dialog to choose an existing directory.

Path of the chosen directory is set into the $lbg_choose_directory variable.

Usage

lbg_choose_directory [OPTIONS] [PATH]

Options

-a, --absolute-path  Return absolute path of the directory
-t, --title TEXT     Set a title to the dialog
PATH                 Starting path (current directory by default)

WARNING: On Windows, starting path is not working when using cscript dialogs (but works in console mode).

Exit codes

  • 0: OK
  • 1: Usage error
  • 2: Cancelled
  • 3: Chosen path does not exists or is not a directory

Example

if lbg_choose_directory /opt ; then
    opt_path=$lbg_choose_directory
fi

lbg_choose_file

Displays a dialog to choose an existing file.

Path of the chosen file is set into the $lbg_choose_file variable.

Usage

lbg_choose_file [OPTIONS] [PATH]

Options

-s, --save           Save mode (create/save a file instead of open an existing one)
-f, --filter FILTER  Set file filters
                     e.g. -f "*.jpg" to filter by JPEG files
-a, --absolute-path  Return absolute path of the file
-t, --title TEXT     Set a title to the dialog
PATH                 Starting path or default file path (open current directory by default)

WARNING: File filters are not supported yet with dialog command.

Exit codes

  • 0: OK
  • 1: Usage error
  • 2: Cancelled
  • 3: Chosen path does not exists or is not a file (if open mode) or invalid parent directory (if save mode)
  • 4: Cannot get absolute path of the file*

* In this case, you can, however, retrieve the chosen path in the $lbg_choose_file variable.

Example

if lbg_choose_file --filter "*.txt" ; then
    text_file=$lbg_choose_file
fi

lbg_open_directory

Open directories in a graphical file browser.

Usage

lbg_choose_directory [OPTIONS] [PATH...]

Options

-e, --explorer CMD  Open directory with a custom application
PATH                Directory path (current directory by default)

Exit codes

  • 0: OK
  • 1: Usage error
  • 2: Explorer command does not exists
  • 3: Unknown error (happens often on Windows)
  • 4: One or more of the specified paths are not existing directories

Note: On some OS like Windows, this function may work but returns a bad exit code.

Example

# open home directory
lbg_open_directory ~

License

libbash.sh is licensed under the MIT License. See LICENSE.md for the full license text.

Credits

Author: Jean Prunneaux https://jean.prunneaux.com

Website: https://github.com/pruje/libbash.sh