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

--multi-progress

Display multi progress bars dialog.

--notebook

Display notebook dialog.

--notification

Display notification icon.

--print

Display print dialog.

--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[=SIGNAL]

Send SIGNAL to parent process. Default value of SIGNAL is a SIGTERM. SIGNAL may be specified by it's number or symbolic name with or without SIG prefix. See signal(7) for details about signals.

--plug=KEY

Run dialog in plug mode for swallow as a notebook tab. See NOTEBOOK section for more.

--tabnum=NUM

Set the tab number for plugged dialog. See NOTEBOOK section for more.

--print-xid

Print X Window Id of a dialog window to the stderr.

--text=STRING

Set the dialog text.

--text-align=TYPE

Set type of dialog text justification. TYPE may be left, right, center or fill.

--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. This option is always on for print dialog.

--icon-theme=THEME

Use specified GTK icon theme instead of default.

--expander=TEXT

Hide main widget with expander. TEXT is an optional argument with expander's label.

--button=BUTTON:ID

Add the dialog button. May be used multiply times. ID is an exit code or a command. BUTTON may be gtk stock item name for predefined buttons (like gtk-close or gtk-ok) or text in a form LABEL[!ICON[!TOOLTIP]] where `!' is an item separator. 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. See EXIT STATUS section for more. If ID have a non-numeric value it treats like a command and click on such button doesn't close the dialog.

--no-buttons

Don't show buttons.

--buttons-layout=TYPE

Set buttons layout type. Possible types are: spread, edge, start, end or center. Default is end.

--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. Works only with gtk+-2.0.

--borders=NUM

Set dialog window borders.

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

--skip-taskbar

Don't show window in taskbar and pager.

--maximized

Run dialog window maximized.

--fullscreen

Run dialog in fullscreen mode. This option may not work on all window managers.

--geometry=WIDTHxHEIGHT+X+Y

Use standard X Window geometry notation for placing dialog. When this option is used, width, height, mouse and center options are ignored.

--selectable-labels

If set, user can select dialog's text and copy it to clipboard. This option also affects on label fields in form dialog.

--image-path=PATH

Add specified path to the standard list of directories for looking for icons. This option can be used multiply times.

--rest=FILENAME

Read extra arguments from given file instead of command line. Each line of a file treats as a single argument.

--gtkrc=FILENAME

Read and parse additional GTK+ settings from given file.

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. By default is `%x'. See strftime(3) for more details.

--details=FILENAME

Read days description from FILENAME.

File with days details must be in following format:

<date> <description>

date field is date in format, specified with --date-format option. description is a string with date details, which may include Pango markup.

Color selection options

--init-color=COLOR

Set initial color value.

--extra

Show extra information about color in returned string.

--palette[=FILENAME]

Show palette and set predefined colors from given filename. By default used /etc/X11/rgb.txt.

Drag-and-Drop box options

--tooltip

Use dialog text as a tooltip for Drag-and-Drop box.

--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 or default item in combo-box.

--hide-text

Hide the entry text.

--completion

Use completion instead of combo-box.

--editable

Allow make 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, step value and precisions (in that order). All this values are optional. Default range is from 0 to 65535 with step 1.

--licon=IMAGE

Set an icon on a left side of entry.

--licon-action=CMD

Specify a command which will be run when the left icon clicked. Output of command will be set as entry text.

--ricon=IMAGE

Set an icon on a right side of entry.

--ricon-action=CMD

Specify a command which will be run when the right icon clicked. Output of command will be set as entry text.

Any extra data specified in command line adds as an items of combo-box entry, except of numeric mode.

If icon specified and icon action is not given, click on icon just clear the entry. Numeric fields will ignore the icons.

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.

--listen

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.

--compact

Use compact mode. Icon and name of each item is placed in a single row.

--single-click

Activate items by single mouse click. This option may not works properly in case of compact mode.

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

--file-filter=NAME | PATTERN1 PATTERN2 ...

Add a filename filter. NAME is a displayed filter name, PATTERN is a shell-style filename pattern (for example *.txt). This option may be used multiply times.

--add-preview

Add preview widget to file dialog. Preview images loads from large or normal thumbnails according to XDG Thumbnails specification v0.8.0 (http://standards.freedesktop.org/thumbnail-spec/latest/) or creates by yad for image files and saves as large thumbnails.

--quoted-output

Output values will be shell-style quoted.

Font selection options

--fontname=FONTNAME

Set the initial font. FONTNAME is a string with font representation in the form "[FAMILY-LIST] [STYLE-OPTIONS] [SIZE]".

--preview

Set the preview text.

Form options

--field=LABEL[:TYPE]

Add field to form. Type may be H, RO, NUM, CHK, CB, CBE, FL, SFL, DIR, CDIR, FN, MFL, MDIR, DT, SCL, CLR, BTN, FBTN, LBL or TXT.
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![PREC]]], where RANGE must be in form MIN..MAX. `!' is a default item separator. PREC is a precision for decimals.
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. Value started with `^' threats as default for combo-box.
CBE - editable combo-box field. Initial value same as for combo-box.
FL - file selection button.
SFL - field for create file.
DIR - directory selection button.
CDIR - field for create folder.
FN - font selection button. Initial value same as in font dialog.
MFL - select multiple files. Value of this field is a list of files separated by item-separator.
MFL - select multiple folders. Value of this field is a list of folders separated by item-separator.
DT - date field.
SCL - scale field. Value of this field in a range 0..100.
CLR - color selection button.
BTN - button field. Label may be in form text in a form LABEL[!ICON[!TOOLTIP]] where `!' is an item separator. LABEL is a text of button label or gtk stock id. ICON is a buttons icon (stock id or file name). TOOLTIP is an optional text for popup help string. Initial value is a command which is running when button is clicked. A special sympols %N in command are replaced by value of field N. If command starts with @, the output of command will be parsed and lines started with numbers will be treats as a new field values.
FBTN - same as button field, but with full relief of a button.
LBL - text label. If field name is empty, horizontal separator line will be shown.
TXT - multiline text entry. This field is always occupy all of form width.

Without type field will be a simple text entry.

--align=TYPE

Set alignment of field labels. Possible types are left, center or right. Default is left.

--columns=NUMBER

Set number of columns in form. Fields will be placed from top to bottom.

--separator=STRING

Set output separator character. Default is `|'.

--item-separator=STRING

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

--date-format=PATTERN

Set the format for the date fields (same as in calendar dialog).

--scroll

Make form scrollable.

--quoted-output

Output values will be shell-style quoted.

Additional data in command line interprets as a default values for form fields. A special value @disabled makes proper field inactive.

List options

--column=STRING[:TYPE]

Set the column header. Types are TEXT, NUM, FLT, CHK, RD, IMG, HD or TIP. TEXT type is default. Use NUM for integers and FLT for double values. TIP is used for define tooltip column. CHK (checkboxes) and RD (radio toggle) are a boolean columns. HD type means a hidden column. Such columns are not displayes in the list, only in output. 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.

--radiolist

Use radio toggle 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.

--no-click

Disable sorting of column content by clicking on its header.

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

--search-column=NUMBER

Set the quick search column. 0 mean to disable searching. By default search mades on first column.

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

--ellipsize=TYPE

Set ellipsize mode for text columns. TYPE may be NONE, START, MIDDLE or END.

--dclick-action=CMD

Set the CMD as a double-click command. When user double-clicked on row, CMD will be launched with values of all columns as an arguments. By default double-click selects row and act as OK button for simple lists, set the checkbox if --checklist specified and do nothing when list run with --multiple option. When double-click specified Enter acts as a double-click and Ctrl+Enter acts as an OK button. CMD may contain a special character `%s' for setting a position for arguments. By default arguments will be concatenated to the end of CMD. If CMD starts with @, its output will replace values of current row. This option doesn't work with --editable.

--regex-search

Use regular expressions in search for text fields.

--listen

Listen data from stdin even if command-line values was specified.

--quoted-output

Output values will be shell-style quoted.

Sending FormFeed character to list clears it. This symbol may be sent as echo -e '\f'.

Multi progress bars dialog options

--bar=LABEL[:TYPE]

Add progress bar. LABEL is a text label for progress bar. TYPE is a progress bar type. Types are: NORM for normal progress bar, RTL for inverted progress bar and PULSE for pulsate progress bar.

--vertical

Set vertical orientation of progress bars.

--align=TYPE

Set alignment of bar labels. Possible types are left, center or right. Default is left.

Initial values for bars set as extra arguments. Each lines with progress data passed to stdin must be started from N: where N is a number of progress bar. Rest is the same as in progress dialog.

Notebook options

--key=KEY

Set the key of this notebook.

--tab=TEXT

Add tab with specified label to notebook. TEXT may be in a form LABEL[!ICON[!TOOLTIP]] where `!' is an item separator.

--tab-pos=TYPE

Set the tabs position. Value may be top, bottom, left, or right. Default is top.

--tab-borders=NUMBER

Set the borders width around widget in tabs.

See NOTEBOOK section for more about notebook dialog.

Notification options

--command=CMD

Set the command running when clicked on the icon. Default action is quit if --listen not specified.

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

--menu=STRING

Set initial menu for right-click.

--no-middle

Disable exit on middle click.

--hidden

Doesn't show icon at startup.

See NOTIFICATION section for more about separators.

Print options

--type=TYPE

Set source file type. TYPE may be a TEXT for text files, IMAGE for image files or RAW for files in postscript or pdf formats.

--filename=FILENAME

Set name or path to the source file.

--headers

Add headers to the top of page with filename and page number. This option doesn't work for RAW type.

--add-preview

Add Preview button to the print dialog. This option doesn't work for RAW type.

--fontname=FONTNAME

Set the font for printing text. FONTNAME is a string with font representation in the form "[FAMILY-LIST] [STYLE-OPTIONS] [SIZE]". This option works only for TEXT type.

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

Set text in progress bar to TEXT.

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

--enable-log[=TEXT]

Show log window. This window gathers all of lines from stdin, started from # instead of setting appropriate progress labels. Optional argument TEXT is a text label for window expander.

--log-on-top

Place log window above progress bar.

--log-expanded

Start with expanded log window.

--log-height

Set the height of log window.

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.

--listen

Listen data from stdin even if filename was specified.

Sending FormFeed character to text dialog clears it. This symbol may be sent as echo -e '\f'. Pressing Ctrl+S popups the search entry in text dialog.

Scale options

--value=VALUE

Set initial value.

--min-value=VALUE

Set minimum value.

--max-value=VALUE

Set maximum value.

--step=VALUE

Set step size.

--page=VALUE

Set paging size. By default page value is STEP*10.

--print-partial

Print partial values.

--hide-value

Hide value.

--vertical

Show vertical scale.

--invert

Invert scale direction.

--mark=[NAME]:VALUE

Add a mark to scale. May be used multiply times. NAME is an optional arguments for set label to mark.

Miscellaneous options

-?, --help

Show summary of options.

--about

Display an about dialog.

--version

Show version of program.

Also the standard GTK+ options are accepted.

NOTEBOOK

Notebook is a complex dialog which swallow other dialogs in his tabs. Dialogs identifies by unique key (integer) and must be runs in a special plug mode (--plug option). Following example runs notebook dialog with two tabs, first has a simple text and second is an entry dialog.

#! /bin/sh

yad --plug=12345 --tabnum=1 --text="first tab with text" &> res1 &
yad --plug=12345 --tabnum=2 --text="second tab" --entry &> res2 &
yad --notebook --key=12345 --tab="Tab 1" --tab="Tab 2"

The order of output results for tabs is undefined!

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 click on the icon. Special string "quit" exit the program.

menu:STRING

Set popup menu for notification icon. STRING must be in form name1[!action1[!icon1]]|name2[!action2[!icon2]].... 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.

WIDGETS NAMES

The look and feel of yad's dialogs can be customized through gtkrc file. Here is the names of yad's widgets:

Widget name	Widget type	Description
yad-dialog-window	GtkDialog	Dialog window
yad-dialog-image	GtkImage	Dialog image
yad-dialog-label	GtkLabel	Dialog text
yad-calendar-widget	GtkCalendar	Calendar widget
yad-color-widget	GtkColorChooser	Color selection widget
yad-color-palette	GtkTreeView	Predefined colors list
yad-entry-label	GtkLabel	Entry label
yad-entry-widget	GtkEntry	Entry widget
yad-entry-spin	GtkSpinButton	Entry widget for numeric values
yad-entry-combo	GtkComboBox	Entry widget with combo
yad-entry-edit-combo	GtkComboBoxEntry	Entry widget with editable combo
yad-file-widget	GtkFileChooser	File selection widget
yad-font-widget	GtkFontChooser	Font selection widget
yad-form-flabel	GtkLabel	Field label in form
yad-form-button	GtkButton	Button field in form
yad-form-entry	GtkEntrfy	Entry field in form
yad-form-spin	GtkSpinButton	Numeric entry field in form
yad-form-check	GtkCheckButton	Checkbox field in form
yad-form-combo	GtkComboBox	Combo field in form
yad-form-edit-combo	GtkComboBoxEntry	Editable combo field in form
yad-form-file	GtkFileChooserButton	File or directory field in form
yad-form-font	GtkFontChooserButton	Font field in form
yad-form-color	GtkColorChooserButton	Color field in form
yad-form-label	GtkLabel	Label field in form
yad-form-scale	GtkScale	Scale widget in form
yad-form-separator	GtkSeparator	Separator in form
yad-form-text	GtkTextView	Multiline text field in form
yad-icons-full	GtkIconView	Icons widget for normal mode
yad-icons-compact	GtkTreeView	Icons widget for compact mode
yad-list-widget	GtkTreeView	List widget
yad-progress-widget	GtkProgressBar	Progressbar widget
yad-scale-widget	GtkScale	Scale widget
yad-text-widget	GtkTextView	Text info widget
yad-timeout-indicator	GtkProgreeBar	Timeout indicator

FILES

yad.conf

YAD default settings. yad.conf placed in $XDG_CONFIG_HOME or $HOME/.config directory. This file contain comments on every settings and will be automatically recreated on yad'd start if it doesn't exists.

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-specified GTK+ icon theme. Launch it as

yad-icon-browser [theme]

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

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

AUTHORS

Yad was written by Victor Ananjevsky <[email protected]>. Yad icon created by Bogdan Lisovich.