YAD(1)

NAME
yad - display GTK+ dialogs

SYNOPSIS
yad [options]

DESCRIPTION
YAD is a program that will display GTK+ dialogs, and return (either in the return code, or on standard output) the users input. This allows you to present information, and ask for information from the user, from all manner of shell scripts.

YAD is the fork of Zenity program.

OPTIONS
This program follows the usual GNU command line syntax, with long options starting with two dashes (`-').

Dialog options

--calendar
    Display calendar dialog.

--color
    Display color selection dialog.

--dnd
    Display drag-and-drop box.

--entry
    Display text entry dialog.

--icons
    Display box with shortcut icons.

--file
    Display file selection dialog.

--font
    Display font selection dialog.

--form
    Display form dialog

--list
    Display list dialog

--notification
    Display notification icon.

--progress
    Display progress indication dialog.

--text-info
    Display text information dialog.

--scale
    Display scale dialog.

General options

--title=TITLE
    Set the dialog title.

--window-icon=ICONPATH
    Set the window icon.

--width=WIDTH
    Set the dialog width.

--height=HEIGHT
    Set the dialog height.

--timeout=TIMEOUT
    Set the dialog timeout in seconds.

--timeout-indicator=POSITION
    Show timeout indicator in given position. Positions are top, bottom, left or right. Style of indicator may be set through the gtkrc file. See http://code.google.com/p/yad/wiki/TimeoutIndicator for details.

--kill-parent
    Send SIGTERM to parent process.

--text=STRING
    Set the dialog text.

--image=IMAGE
    Set the dialog image which appears on the left side of dialog. IMAGE might be file name or icon name from current icon theme.

--image-on-top
    Show image above main widget instead of left.

--icon-theme=THEME
    Use specified GTK icon theme instead of default.

--button=BUTTON:ID
    Add the dialog button. May be used several times. ID is an exit code. BUTTON may be gtk stock item name for predefined buttons (like gtk-close or gtk-ok) or simple text label. Full list of stock items may be found in gtk-demo program, in snippet called "Stock Items and Icon Browser". If no buttons specified OK and Cancel buttons used.

--no-buttons
    Don't show buttons.

--no-markup
    Don't use pango markup in dialog's text.

--always-print-result
    Always print result.

--dialog-sep
    Show separator between dialog and buttons.

--sticky
    Make window visible on all desktops.

--fixed
    Make window fixed width and height.

--center
    Place window on center of screen.

--mouse
    Place window under mouse position.

--on-top
    Place window over other windows.

--undecorated
    Make window undecorated (remove title and window borders).

--geometry=WIDTHxHEIGHT+X+Y
    Use standard X Window geometry notation for placing dialog. When this option is used, width, heidht, mouse and center options are ignored.

Calendar options

--day=INT
    Set the calendar day.

--month=INT
    Set the calendar month.

--year=INT
    Set the calendar year.

--date-format=PATTERN
    Set the format for the returned date.

Color selection options

--init-color=COLOR
    Set initial color value.

--extra
    Show extra information about color in returned string.

--palette[=FILENAME]
    Show palette ans set predefined colors from given filename. By default used /etc/X11/rgb.txt.

Drag-and-Drop box options

--command=CMD
    Run command when data received. Data strings pass to command as an agrument. By default data just prints to stdout.

Text entry options

--entry-label=STRING
    Set the entry label text.

--entry-text=STRING
    Set the initial entry text.

--hide-text
    Hide the entry text.

--completion
    Use completion instead of combo-box.

--editable
    Allow changes to text in combo-box.

--numeric
    Use spin button instead of text entry. Additional parameters in command line treats as minimum and maximum values and step value (in that order). All this values are optional. Default range is from 0 to 65535 with step 1. Any extra data specified in command line adds as an items of combo-box entry, except of numeric mode.

Iconbox options

--read-dir=DIRECTORY
    Read .desktop files from specified directory.

--generic
    Use field GenericName instead of Name for shortcut label.

--sort-by-name
    Use field Name instead of filename for sorting items.

--descend
    Sort items in descending order. If data reads from stdin this option is useless without --sort-by-name.

--stdin
    Read data from stdin. Data must be in order - Name, Tooltip, Icon, Command, InTerm separated by newline. InTerm is a case insensitive boolean constant (TRUE or FALSE).

--item-width
    Set items width.

--term
    Pattern for terminal. By default use `xterm -e %s' where %s replaced by the command. If both directory and stdin specified, content of iconbox will be read from directory.

File selection options

--filename=FILENAME
    Set the filename.

--multiple
    Allow selection of multiple filenames in file selection dialog.

--directory
    Activate directory-only selection.

--save
    Activate save mode.

--separator=STRING
    Specify separator character when returning multiple filenames.

--confirm-overwrite[=TEXT]
    Confirm file selection if filename already exists. Optional argument is a text for confirmation dialog.

Font selection options

--fontname=FILENAME
    Set the initial font.

--preview
    Set the preview text.

Form options

--field=LABEL[:TYPE]
    Add field to form. Type may be H, RO, NUM, CHK, CB, FL, DIR, FN or CLR. H - hidden field type. All characters are displayed as the invisible char. RO - field is in read-only mode. NUM - field is a numeric. Initial value format for this field is VALUE[!RANGE[!STEP]], where RANGE must be in form MIN..MAX. `!' is a default item separator. CHK - checkbox field. Initial value is a case insensitive boolean constant (TRUE or FALSE). CB - combo-box field. Initial value is a list VAL1!VAL2!.... The separator is the same as in NUM field. FL - file selection button. DIR - directory selection button. FN - font selection button. CLR - color selection button.

--align=TYPE
    Set alignment of fields labels. Possible types are left, center or right. Default is left.

--separator=STRING
    Set output separator character. Default is `|'.

--item-separator=STRING
    Set separator character for combo-box or scale values. Default is `!'.

Additional data in command line interprets as a default values for form fields.

List options

--column=STRING[:TYPE]
    Set the column header. Types are TEXT, NUM, FLT, CHK, IMG or TIP. TEXT type is default. Use NUM for integers and FTL for double values. TIP is used for define tooltip column. IMG may be path to image or icon name from currnet GTK+ icon theme. Size of icons may be set in config file. Image field prints as empty value. Special column names @fore@, @back@ and @font@ sets corresponding rows attributes. Values of those columns don't show in results.

--checklist
    Use check boxes for first column.

--separator=STRING
    Set output separator characters.

--multiple
    Allow multiple rows to be selected.

--editable
    Allow changes to text.

--no-headers
    Do not show column headers

--print-all
    Print all data from the list.

--print-column=NUM
    Specify what column will be printed to standard output. 0 may be used to print all columns (this is default).

--hide-column=NUMBER
    Hide a specific column.

--expand-column=NUMBER
    Set the column expandable by default. 0 sets all columns expandable.

--limit=NUMBER
    Set the number of rows in list dialog. Will be shown only the last NUMBER rows. This option will take effect only when data reading from stdin.

Notification options

--command=CMD
    Set the command running when clicked on the icon.

--listen
    Listen for commands on stdin. See NOTIFICATION section.

--separator=STRING
    Set separator character for menu values. Default is `|'.

--item-separator=STRING
    Set separator character for menu items. Default is `!'.

See NOTIFICATION section for more about separators.

Progress options

When the --progress option is used, yad reads lines of progress data from stdin. When the lines begin with # the text after # is displayed in the progress bar label. Numeric values treats like a persents for progress bar.

--progress-text=STRING
    Set text in progress bar to STRING.

--percentage=INT
    Set initial percentage.

--rtl
    Set Right-To-Left progress bar direction.

--auto-close
    Close dialog when 100% has been reached.

--auto-kill
    Kill parent process if cancel button is pressed.

--pulsate
    Pulsate progress bar.

Text options

--filename=FILENAME
    Open specified file.

--editable
    Allow changes to text.

--fore=COLOR
    Set foreground color of text

--back=COLOR
    Set background color of text

--fontname=FONT
    Set text font. FONT must be in a Pango font description format.

--wrap
    Enable text wrapping.

--justify=TYPE
    Set justification. TYPE may be left, right, center or fill. Default is left.

--margins=SIZE
    Set text margins to SIZE.

--tail
    Autoscroll to end when new text appears. Works only when text is read from stdin.

--show-uri
    Make URI in text clickable. Links opens with xdg-open command.

Scale options

--value=VALUE
    Set initial value.

--min-value=VALUE
    Set minimum value.

--max-value=VALUE
    Set maximum value.

--step=VALUE
    Set step size.

--print-partial
    Print partial values.

--hide-value
    Hide value.

--vertical
    Show vertical scale.

--invert
    Invert scale direction.

Miscellaneous options

-?, --help
    Show summary of options.

--about
    Display an about dialog.

--version
    Show version of program.

Also the standard GTK+ options are accepted.

NOTIFICATION
Allows commands to be sent to yad in the form command:args. Possible commands are icon, tooltip, visible, action, menu and quit.

icon:ICONNAME
    Set notification icon to ICONNAME.

tooltip:STRING
    Set notification tooltip.

visible:[true|false|blink]
    Set notification icon to visible, invisible or blinking states.

action:COMMAND
    Specify the command running when double-clicked on the icon. Special string "quit" exit the program.

menu:STRING
    Set popup menu for notification icon. STRING must be in form name1!action1|name2!action2.... Empty name add separator to menu. Separator character for values (e.g. `|') sets with --separator argument. Separator character for menu items (e.g. `!') sets with --item-separator argument.

quit
    Exit the program. Middle click on icon also send quit command.

USER DEFINED SIGNALS

SIGUSR1
    Close dialog with 0 exit code.

SIGUSR2
    Close dialog with 1 exit code.

EXIT STATUS

0   The user has pressed OK button

1   The user has pressed Cancel button

70  The dialog has been closed because the timeout has been reached.

252 The dialog has been closed by pressing Esc or used the window functions to close the dialog

Exit codes for user-specified buttons must be specified in command line. Even exit code mean to print result, odd just return exit code.

EXAMPLES
Display a file selector with the title Select a file to remove. The file selected is returned on standard output.

    yad --title="Select a file to remove" --file-selection

Display a text entry dialog with the title Select Host and the text Select the host you would like to flood-ping. The entered text is returned on standard output.

    yad --title "Select Host" --entry --text "Select the host you would like to flood-ping"

Display a dialog, asking Microsoft Windows has been found! Would you like to remove it?. The return code will be 0 (true in shell) if YES is selected, and 1 (false) if NO is selected.

    yad --image "dialog-question" --title "Alert" --button=gtk-yes:0 --button=gtk-no:1 --text "Microsoft Windows has been found! Would you like to remove it?"

Show the search results in a list dialog with the title Search Results and the text Finding all header files....

    find . -name '*.h' | yad --list --title "Search Results" --text "Finding all header files.." --column "Files"

Show an icon in the notification area

    yad --notification --image=update.png --text "System update necessary!" --command "xterm -e apt-get upgrade"

Display a weekly shopping list in a check list dialog with Apples and Oranges pre selected

    yad --list --checklist --column "Buy" --column "Item" TRUE Apples TRUE Oranges FALSE Pears FALSE Toothpaste

Display a progress dialog while searching for all the postscript files in your home directory

    find $HOME -name '*.ps' | yad --progress --pulsate

Display a box with all of the installed desktop applications

    yad --icons --read-dir=/usr/share/applications

DEVELOPMENT
There are some developers features providing with YAD.

YAD icon browser is a graphical tool for discover icons in current or user-specifies GTK+ icon theme. Launch it as

    yad-icon-browser [theme]

When using autoconf you may use special m4 macro AM_PATH_YAD for fooking for yad and check it version. Usage of this mnacro is

    AM_PATH_YAD([MINIMUM-VERSION],[ACTION-IF-FOUND],[ACTION-IF-NOT-FOUND])

AUTHOR
Yad was written by Victor Ananjevsky <ananasik@gmail.com>.

SEE ALSO
gdialog(1), dialog(1), zenity(1)