.TH YAD 1 "Marth 24, 2011"
.SH NAME
yad \- display GTK+ dialogs

.SH SYNOPSIS
.B yad
.RI [ options ]

.SH DESCRIPTION
\fBYAD\fP 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.
.PP
\fBYAD\fP is the fork of \fBZenity\fP program.

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

.PP
Dialog options
.TP
.B \-\-calendar
Display calendar dialog.
.TP
.B \-\-color
Display color selection dialog.
.TP
.B \-\-dnd
Display drag-and-drop box.
.TP
.B \-\-entry
Display text entry dialog.
.TP
.B \-\-icons
Display box with shortcut icons.
.TP
.B \-\-file
Display file selection dialog.
.TP
.B \-\-font
Display font selection dialog.
.TP
.B \-\-form
Display form dialog
.TP
.B \-\-list
Display list dialog
.TP
.B \-\-notification
Display notification icon.
.TP
.B \-\-progress
Display progress indication dialog.
.TP
.B \-\-text-info
Display text information dialog.
.TP
.B \-\-scale
Display scale dialog.

.PP
General options
.TP
.B \-\-title=TITLE
Set the dialog title.
.TP
.B \-\-window-icon=ICONPATH
Set the window icon.
.TP
.B \-\-width=WIDTH
Set the dialog width.
.TP
.B \-\-height=HEIGHT
Set the dialog height.
.TP
.B \-\-timeout=TIMEOUT
Set the dialog timeout in seconds.
.TP
.B \-\-timeout-indicator=POSITION
Show timeout indicator in given position. Positions are \fItop\fP, \fIbottom\fP, \fIleft\fP or \fIright\fP.
Style of indicator may be set through the gtkrc file. 
See \fIhttp://code.google.com/p/yad/wiki/TimeoutIndicator\fP for details.
.TP
.B \-\-kill-parent
Send SIGTERM to parent process.
.TP
.B \-\-text=STRING
Set the dialog text.
.TP
.B \-\-image=IMAGE
Set the dialog image which appears on the left side of dialog.
\fIIMAGE\fP might be file name or icon name from current icon theme.
.TP
.B \-\-image-on-top
Show image above main widget instead of left.
.TP
.B \-\-icon-theme=THEME
Use specified GTK icon theme instead of default.
.TP
.B \-\-button=BUTTON:ID
Add the dialog button. May be used several times. \fIID\fP is an exit code.
\fIBUTTON\fP 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 \fI"Stock Items and Icon Browser"\fP. 
If no buttons specified \fIOK\fP and \fICancel\fP buttons used. See \fBEXIT STATUS\fP section for more.
.TP
.B \-\-no-buttons
Don't show buttons.
.TP
.B \-\-no-markup
Don't use pango markup in dialog's text.
.TP
.B \-\-always-print-result
Always print result. 
.TP
.B \-\-dialog-sep
Show separator between dialog and buttons.
.TP
.B \-\-sticky
Make window visible on all desktops.
.TP
.B \-\-fixed
Make window fixed width and height.
.TP
.B \-\-center
Place window on center of screen.
.TP
.B \-\-mouse
Place window under mouse position.
.TP
.B \-\-on-top
Place window over other windows.
.TP
.B \-\-undecorated
Make window undecorated (remove title and window borders).
.TP
.B \-\-skip-taskbar
Don't show window in taskbar and pager.
.TP
.B \-\-geometry=WIDTHxHEIGHT+X+Y
Use standard X Window geometry notation for placing dialog.
When this option is used, \fIwidth\fP, \fIheight\fP, \fImouse\fP and \fIcenter\fP options are
ignored.

.PP 
Calendar options
.TP
.B \-\-day=INT
Set the calendar day.
.TP
.B \-\-month=INT
Set the calendar month.
.TP
.B \-\-year=INT
Set the calendar year.
.TP
.B \-\-date-format=PATTERN
Set the format for the returned date. By default is `%x'. See \fIstrftime(3)\fP for more details.
.TP
.B \-\-details=FILENAME
Read days description from \IFILENAME\P. 
.PP
File with days details must be in following format:
.IP
<date> <description>
.PP
\fIdate\fP field is date in format, specified with \fI\-\-date-format\fP option. \fIdescription\fP
is a string with date details, which may include Pango markup.

.PP 
Color selection options
.TP
.B \-\-init\-color=COLOR
Set initial color value.
.TP
.B \-\-extra
Show extra information about color in returned string.
.TP
.B \-\-palette[=FILENAME]
Show palette ans set predefined colors from given filename.
By default used \fI/etc/X11/rgb.txt\fP.

.PP
Drag-and-Drop box options
.TP
.B \-\-command=CMD
Run command when data received. Data strings pass to command as an agrument. 
By default data just prints to stdout.

.PP
Text entry options
.TP
.B \-\-entry-label=STRING
Set the entry label text.
.TP
.B \-\-entry-text=STRING
Set the initial entry text.
.TP
.B \-\-hide-text
Hide the entry text.
.TP
.B \-\-completion
Use completion instead of combo-box.
.TP
.B \-\-editable
Allow changes to text in combo-box.
.TP
.B \-\-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.
.TP
.B \-\-licon
Set an icon on a left side of entry.
.TP
.B \-\-licon-action
Specify a command which will be run when the left icon clicked. Output of command will be set as entry text.
.TP
.B \-\-ricon
Set an icon on a right side of entry.
.TP
.B \-\-ricon-action
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. 
Icons are available only for entry field. Numeric field or combo-boxes will ignore the icons.

.PP
Iconbox options
.TP
.B \-\-read-dir=DIRECTORY
Read .desktop files from specified directory.
.TP
.B \-\-generic
Use field GenericName instead of Name for shortcut label.
.TP
.B \-\-sort-by-name
Use field Name instead of filename for sorting items.
.TP
.B \-\-descend
Sort items in descending order. If data reads from stdin this option is useless without \fI\-\-sort-by-name\fP.
.TP
.B \-\-stdin
Read data from stdin. Data must be in order - \fIName\fP, \fITooltip\fP, \fIIcon\fP, \fICommand\fP, \fIInTerm\fP
separated by newline. \fIInTerm\fP is a case insensitive boolean constant (\fITRUE\fP or \fIFALSE\fP).
.TP
.B \-\-item-width
Set items width.
.TP
.B \-\-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.

.PP
File selection options
.TP
.B \-\-filename=FILENAME
Set the filename.
.TP
.B \-\-multiple
Allow selection of multiple filenames in file selection dialog.
.TP
.B \-\-directory
Activate directory-only selection.
.TP
.B \-\-save
Activate save mode.
.TP
.B \-\-separator=STRING
Specify separator character when returning multiple filenames.
.TP
.B \-\-confirm\-overwrite[=TEXT]
Confirm file selection if filename already exists. 
Optional argument is a text for confirmation dialog.

.PP
Font selection options
.TP
.B \-\-fontname=FILENAME
Set the initial font.
.TP
.B \-\-preview
Set the preview text.

.PP
Form options
.TP
.B \-\-field=LABEL[:TYPE]
Add field to form. Type may be \fIH\fP, \fIRO\fP, \fINUM\fP, \fICHK\fP, \fICB\fP, \fICBE\fP, \fIFL\fP, \fIDIR\fP, \fIFN\fP, \fIMFL\fP, \fIDT\fP or \fICLR\fP.
\fIH\fP - hidden field type. All characters are displayed as the invisible char.
\fIRO\fP - field is in read-only mode.
\fINUM\fP - field is a numeric. Initial value format for this field is \fIVALUE[!RANGE[!STEP]]\fP,
where \fIRANGE\fP must be in form \fIMIN..MAX\fP. `!' is a default item separator.
\fICHK\fP - checkbox field. Initial value is a case insensitive boolean constant (\fITRUE\fP or \fIFALSE\fP).
\fICB\fP - combo-box field. Initial value is a list \fIVAL1!VAL2!...\fP. The separator is the same as in \fINUM\fP field.
\fICBE\fP - editable combo-box field. Initial value same as for combo-box.
\fIFL\fP - file selection button.
\fIDIR\fP - directory selection button.
\fIFN\fP - font selection button.
\fIMFL\fP - select multiple files. Value of this field is a list of files separated by \fIitem-separator\fP.
\fIDT\fP - date field.
\fICLR\fP - color selection button.
.TP
.B \-\-align=TYPE
Set alignment of fields labels. Possible types are \fIleft\fP, \fIcenter\fP or \fIright\fP. Default is left.
.TP
.B \-\-separator=STRING
Set output separator character. Default is `|'.
.TP
.B \-\-item-separator=STRING
Set separator character for combo-box or scale values. Default is `!'.
.TP
.B \-\-date-format=PATTERN
Set the format for the date fields (same as in calendar dialog).
.PP
Additional data in command line interprets as a default values for form fields.

.PP
List options
.TP
.B \-\-column=STRING[:TYPE]
Set the column header. Types are \fITEXT\fP, \fINUM\fP, \fIFLT\fP, \fICHK\fP, \fIIMG\fP or \fITIP\fP. 
\fITEXT\fP type is default. Use \fINUM\fP for integers and \fIFTL\fP for double values. \fITIP\fP is used for define tooltip column.
\fIIMG\fP 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 \fI@fore@\fP, \fI@back@\fP and \fI@font@\fP sets corresponding rows attributes.
Values of those columns don't show in results.
.TP
.B \-\-checklist
Use check boxes for first column.
.TP
.B \-\-separator=STRING
Set output separator characters.
.TP
.B \-\-multiple
Allow multiple rows to be selected.
.TP
.B \-\-editable
Allow changes to text.
.TP
.B \-\-no-headers
Do not show column headers
.TP
.B \-\-print-all
Print all data from the list. 
.TP
.B \-\-print-column=NUM
Specify what column will be printed to standard output. \fI0\fP may be used to print all columns (this is default).
.TP
.B \-\-hide\-column=NUMBER
Hide a specific column.
.TP
.B \-\-expand\-column=NUMBER
Set the column expandable by default. \fI0\fP sets all columns expandable.
.TP
.B \-\-search\-column=NUMBER
Set the quick search column. \fI0\fP mean to disable searching. By default search mades on first column.
.TP
.B \-\-limit=NUMBER
Set the number of rows in list dialog. Will be shown only the last \fINUMBER\fP rows. This option will take effect only when data reading from stdin.
.TP
.B \-\-ellipsize=TYPE
Set ellipsize mode for text columns. \fITYPE\fP may be \fINONE\fP, \fISTART\fP, \fIMIDDLE\fP or \fIEND\fP.
.TP
.B \-\-dclick-action=CMD
Set the \fICMD\fP as a double-click command. When user double-clicked on row, CMD will be launched with values of all columns as an arguments.

.PP
Notification options
.TP
.B \-\-command=CMD
Set the command running when clicked on the icon.
.TP
.B \-\-listen
Listen for commands on stdin. See \fBNOTIFICATION\fP section.
.TP
.B \-\-separator=STRING
Set separator character for menu values. Default is `|'.
.TP
.B \-\-item-separator=STRING
Set separator character for menu items. Default is `!'.
.PP
See \fBNOTIFICATION\fP section for more about separators. 

.PP
Progress options
.PP
When the \-\-progress option is used, yad reads lines of progress data from stdin.
When the lines begin with \fI#\fP the text after \fI#\fP is displayed in the progress
bar label. Numeric values treats like a persents for progress bar.
.TP
.B \-\-progress-text=STRING
Set text in progress bar to STRING.
.TP
.B \-\-percentage=INT
Set initial percentage.
.TP
.B \-\-rtl
Set Right-To-Left progress bar direction.
.TP
.B \-\-auto\-close
Close dialog when 100% has been reached.
.TP
.B \-\-auto\-kill
Kill parent process if cancel button is pressed.
.TP
.B \-\-pulsate
Pulsate progress bar.

.PP
Text options
.TP
.B \-\-filename=FILENAME
Open specified file.
.TP
.B \-\-editable
Allow changes to text.
.TP
.B \-\-fore=COLOR
Set foreground color of text
.TP
.B \-\-back=COLOR
Set background color of text
.TP
.B \-\-fontname=FONT
Set text font. \fIFONT\fP must be in a Pango font description format.
.TP
.B \-\-wrap
Enable text wrapping.
.TP
.B \-\-justify=TYPE
Set justification. \fITYPE\fP may be \fIleft\fP, \fIright\fP, \fIcenter\fP or \fIfill\fP.
Default is \fIleft\fP.
.TP
.B \-\-margins=SIZE
Set text margins to SIZE.
.TP
.B \-\-tail
Autoscroll to end when new text appears. Works only when text is read from stdin.
.TP
.B \-\-show-uri
Make URI in text clickable. Links opens with \fIxdg-open\fP command. 

.PP
Scale options
.TP
.B \-\-value=VALUE
Set initial value.
.TP
.B \-\-min\-value=VALUE
Set minimum value.
.TP
.B \-\-max\-value=VALUE
Set maximum value.
.TP
.B \-\-step=VALUE
Set step size.
.TP
.B \-\-print\-partial
Print partial values.
.TP
.B \-\-hide\-value
Hide value.
.TP
.B \-\-vertical
Show vertical scale.
.TP
.B \-\-invert
Invert scale direction.

.PP
Miscellaneous options
.TP
.B \-?, \-\-help
Show summary of options.
.TP
.B \-\-about
Display an about dialog.
.TP
.B \-\-version
Show version of program.

.PP
Also the standard GTK+ options are accepted.

.SH NOTIFICATION
Allows commands to be sent to yad in the form \fBcommand:args\fP.
Possible commands are \fIicon\fP, \fItooltip\fP, \fIvisible\fP, \fIaction\fP, \fImenu\fP and \fIquit\fP.
.TP
.B
icon:ICONNAME
Set notification icon to ICONNAME.
.TP
.B
tooltip:STRING
Set notification tooltip.
.TP
.B
visible:[true|false|blink]
Set notification icon to visible, invisible or blinking states.
.TP
.B
action:COMMAND
Specify the command running when double-clicked on the icon. 
Special string \fI"quit"\fP exit the program.
.TP
.B
menu:STRING
Set popup menu for notification icon.
STRING must be in form \fIname1!action1|name2!action2...\fP.
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.
.TP
.B
quit
Exit the program. Middle click on icon also send \fIquit\fP command.

.SH USER DEFINED SIGNALS
.TP
.B
SIGUSR1
Close dialog with 0 exit code.
.TP
.B
SIGUSR2
Close dialog with 1 exit code.

.SH EXIT STATUS
.TP
.B
0
The user has pressed \fIOK\fP button
.TP
.B
1
The user has pressed \fICancel\fP button
.TP
.B
70
The dialog has been closed because the timeout has been reached.
.TP
.B
252
The dialog has been closed by pressing \fIEsc\fP or used the window functions to close the dialog
.TP
Exit codes for user-specified buttons must be specified in command line. Even exit code mean to print result, odd just return exit code.

.SH EXAMPLES
Display a file selector with the title \fISelect a file to
remove\fP. The file selected is returned on standard output.
.IP
yad  \-\-title="Select a file to remove" \-\-file-selection
.PP
Display a text entry dialog with the title \fISelect Host\fP and the
text \fISelect the host you would like to flood-ping\fP. The entered
text is returned on standard output.
.IP
yad  \-\-title "Select Host" \-\-entry \-\-text "Select the host you would like to flood-ping"
.PP
Display a dialog, asking \fIMicrosoft Windows has been found! Would
you like to remove it?\fP. The return code will be 0 (true in shell)
if \fIYES\fP is selected, and 1 (false) if \fINO\fP is selected.
.IP
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?"
.PP
Show the search results in a list dialog with the title \fISearch Results\fP
and the text \fIFinding all header files...\fP.
.IP
find . \-name '*.h' | yad \-\-list \-\-title "Search Results" \-\-text "Finding all header files.." \-\-column "Files"
.PP
Show an icon in the notification area
.IP
yad \-\-notification \-\-image=update.png \-\-text "System update necessary!" \-\-command "xterm \-e apt-get upgrade"
.PP
Display a weekly shopping list in a check list dialog with \fIApples\fP and \fIOranges\fP pre selected
.IP
yad \-\-list \-\-checklist \-\-column "Buy" \-\-column "Item" TRUE Apples TRUE Oranges FALSE Pears FALSE Toothpaste
.PP
Display a progress dialog while searching for all the postscript files in your home directory
.IP
find $HOME \-name '*.ps' | yad \-\-progress \-\-pulsate
.PP
Display a box with all of the installed desktop applications
.IP
yad \-\-icons \-\-read-dir=/usr/share/applications

.SH DEVELOPMENT
There are some developers features providing with YAD.
.TP
\fIYAD icon browser\fP is a graphical tool for discover icons in current or user-specifies GTK+ icon theme. Launch it as
.IP
yad-icon-browser [theme]
.PP
When using autoconf you may use special m4 macro \fIAM_PATH_YAD\fP for fooking for yad and check it version. Usage of this mnacro is
.IP
AM_PATH_YAD([MINIMUM-VERSION],[ACTION-IF-FOUND],[ACTION-IF-NOT-FOUND])
.PP

.SH AUTHOR
\fBYad\fP was written by Victor Ananjevsky <ananasik@gmail.com>.

.SH SEE ALSO
\fBgdialog\fP(1), \fBdialog\fP(1), \fBzenity\fP(1)

.