2003 Sun Microsystems GNOME Documentation Project Version 1.0 of Zenity Manual To report a bug or make a suggestion regarding this application or this documentation, please see the GNOME Feedback Page Glynn Foster GNOME Documentation Project 1.0 18-01-2003 Glynn Foster GNOME Documentation Project &app; allows allows you to display simple dialogs from the command line or from shell scripts. The following list of dialogs are available with &app;: --calendar Display a Calendar dialog. --entry Display a Text Entry dialog. --error Display an Error dialog. --info Display an Informational dialog. --file-selection Display a File Selection dialog. --list Display a List dialog. --progress Display a Progress dialog. --question Display a Question dialog. --text-info Display a Text Information dialog. --warning Display a Warning dialog. &app; can only be used to create relatively simple dialogs, but is especially useful when used in scripts. When a user has completed an action requested of them, and the dialog closes, &app; prints any text specific to the dialog to standard error and an exit code is returned. Information about what text is printed to standard error will be detailed in the individual dialog sections. When using &app;, make sure that any arguments to the command line options are surrounded by a set of quotes ' ' or " " as in &app; --calendar --dialog-title="Holiday Planner" , for example. If you do not use quotes, then it is likely that you will get unexpected results. For some of the dialogs, &app; supports the use of keyboard mnemonics. This allows you to use an '_' before the letter you want the mnemonic for, as in "_Please choose a name:", for example. The following exit codes are observed by &app;: 0 The user has pressed either 'OK' or 'Close'. 1 The user has pressed either 'Cancel' or closed the dialog through the window functions. -1 An unexpected error has occurred. Each dialog shares some general command line options. If these are not provided, there are some default values that depend on the type of dialog being displayed. The following list of general options are available: --title=TITLE Specify the title of a dialog. --window-icon=ICON_PATH Specify the icon that should appear in the window frame of the dialog. --width=WIDTH Specify the width of the dialog. --height=HEIGHT Specify the height of the dialog. To create a Calendar dialog, use --calendar. &app; will return the date selected to standard error. If the day, month and year are not specified at the command line, &app; will pre-select the current date in the Calendar dialog. The following list of options are available for the Calendar dialog: --text=TEXT Specify the text to appear in the Calendar dialog. --day=DAY Specify the day to be pre-selected in the Calendar dialog. This must be a number between 1 and 31. --month=MONTH Specify the day to be pre-selected in the Calendar dialog. This must be a number between 1 and 12. --year=YEAR Specify the year to be pre-selected in the Calendar dialog. --date-format=FORMAT Specify the format to be returned from the Calendar dialog after the selection has been made. This defaults to a format depending on your locale. The format must be of strftime style eg. "%A %d/%m%y"

&app; Calendar dialog example

The following script shows an example of how to use the Calendar dialog: #!/bin/sh if zenity --calendar --dialog-title="Calendar selection" --text="Select a date from below" --day=18 --month=1 --year=2003 then echo $? else echo "No date selected" fi To create a Text Entry dialog, use --text-entry. &app; returns the contents of the text entry to standard error. The following list of options are available for the Text Entry dialog: --text=TEXT Specify the text to appear in the Text Entry dialog. --entry-text=TEXT Specify the text to appear in the entry field of the Text Entry dialog. --hide-text Specify that the text in the entry field of the Text Entry dialog be hidden.

&app; Text Entry dialog example

The following script shows an example of how to use the Text Entry dialog: #!/bin/sh if zenity --entry --dialog-title="Add a new entry" --text="Enter your _Password" --hide-text then echo $? else echo "No password entered" fi There are 4 types of message dialogs in &app; - Error, Informational, Question and Warning. To create an Error dialog, use --error. To create an Informational dialog, use --info. To create a Question dialog, use --question. To create a Warning dialog, use --question. The following list of options are available for the message dialogs. --text=TEXT Specify the text to appear in the message dialog.

&app; Error dialog example

&app; Informational dialog example

&app; Question dialog example

&app; Warning dialog example

The following script shows an example of how to use the Warning message dialog: #!/bin/bash FILE_TYPE=$(file -b $NAUTILUS_SCRIPT_SELECTED_FILE_PATHS|awk '{ print $1}') if [ "$FILE_TYPE" != "PNG" ]; then zenity --warning --text="Could not rotate image :" --hide-text fi To create a File Selection dialog, use --file-selection. &app; returns the file or directory selected to standard error. The following list of options are available for the File Selection dialog: --filename=FILENAME Specify the file or directory to be pre-selected in the File Selection dialog.

&app; File Selection dialog example

The following script shows an example of how to use the File Selection dialog: #!/bin/sh FILE=`zenity --file-selection --dialog-title="Select a file"' case $? in 0) echo "\"$FILE\" selected.";; 1) echo "No file selected.";; -1) echo "No file selected.";; esac To create a List dialog, use --list. &app; returns the entries of the first columns selected to standard error. If --checklist or --radiolist is used, then &app; will return the entries of the second columns selected to standard error. With the List dialog, you must specify the number of columns to be displayed by specifying the column headers. To fill data into this dialog, you may specify entries column by column, row by row. If you are using a checklist or a radiolist then your first pieces of data for each row must be either 'TRUE' or 'FALSE'. See examples below for how to fill data into this dialog. The List dialog may also be filled by providing data from standard input, column by column, row by row, each seperated by a newline, however the column headers must appear with the --column option. The following list of options are available for the List dialog: --column=COLUMN Specify the column headers to appear in the List dialog. This option must be called for each column that you want to appear in the dialog. --checklist Specify if the first column should contain check boxes in the List dialog. --radiolist Specify if the first column should contain radio boxes in the List dialog. --editable Allow the displayed items to be edited. --seperator=SEPERATOR Specify what seperator character should be used when the List dialog returns the selected entries. The default character is '\'. If you want to specify a newline, use '\n'.

&app; List dialog example

The following commandline shows an example of how to use the List dialog: zenity --list --dialog-title="Choose bugs you wish to view" \ --text="Select items from the list below." \ --column="Bug Number" --column="Severity" --column="Description" \ 992383 Normal "GtkTreeView crashes on multiple selections" \ 293823 High "GNOME Dictionary does not handle proxy" \ 393823 Critical "Menu editing does not work in GNOME 2.0" To create a Progress dialog, use --progress. Zenity reads data from standard input line by line, determining whether it should update the text (if the line is prefixed with a '#') or the percentage (if the line is a digit). The following list of options are available for the Progress dialog: --text=TEXT Specify the text to appear in the Progress dialog. --percentage=PERCENTAGE Specify the initial percentage that should be set in the Progress dialog. --pulsate Specify if the Progress dialog should pulsate until an EOF character is read from standard input.

&app; Progress dialog example

The following script shows an example of how to use the Progress dialog: #!/bin/sh ( echo "10" ; sleep 1 echo "# Updating mail logs" ; sleep 1 echo "20" ; sleep 1 echo "# Resetting cron jobs" ; sleep 1 echo "50" ; sleep 1 echo "This line will just be ignored" ; sleep 1 echo "75" ; sleep 1 echo "# Rebooting system" ; sleep 1 echo "100" ; sleep 1 ) | zenity --progress --dialog-title="Update System Logs" --text="Scanning mail logs..." --percentage=0 if [ "$?" = -1 ] ; then zenity --error --text="Update cancelled." fi To create a Text Information dialog, use --text-info. The following list of options are available for the Text Information dialog: --filename=FILENAME Specify the file to be loaded in the Text Information dialog. --editable Allow the displayed text to be edited and returned to standard error when the dialog is closed.

&app; Text Information dialog example

The following script shows an example of how to use the Text Infomation dialog: #!/bin/sh FILE=`zenity --file-selection --dialog-title="Select a file"' case $? in 0) zenity --text-info --dialog-title=$FILE --editable 2>/tmp/tmp.txt 1) echo "No file selected.";; -1) echo "No file selected.";; esac The following list of options are also available for &app;: --about Display some information about &app;. --version Print the version number of &app;. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, of (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. A copy of the GNU General Public License is included as an appendix to the GNOME Users Guide . You may also obtain a copy of the GNU General Public License from the Free Software Foundation by visiting their Web site or by writing to

Free Software Foundation, Inc. 59 Temple Place - Suite 330 Boston, MA 02111-1307 USA