Zenity Manual

Glynn Foster
GNOME Documentation Project

Edited by

Nicholas Curran 1. Introduction

Zenity displays simple GNOME dialogs. Zenity can display the following dialogs:

Calender dialog. Text entry dialog. Various message dialogs including:

Error dialog. Information dialog. Question dialog. Warning dialog.

File selection dialog. List options dialog. Progress dialog. Text dialog.

2. Basic Use
Zenity creates simple dialogs. You can use Zenity to create a script that interacts graphically with the user. When the user closes the dialog, Zenity prints text produced by the dialog to standard error.

Zenity Manual Ensure that all arguments to Zenity are surrounded by quotes. For example, use zenity --calender --title="Holiday Planner" instead of zenity --calender --title=Holiday Planner. If you do not use quotes, you can get unexpected results.
NOTE: Some dialogs support the use of keyboard mnemonics. To specify the character to use as the mnemonic, place an underscore before that character in the text of the dialog. For example, to specify the P as the keyboard mnemonic in the following sentence, use "_Please choose a name".

Zenity returns the following exit codes:

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.

3. General Options
All dialogs have the following general options:
--title=TITLE

Species the title of a dialog.

--window-icon=ICON_PATH

Species the icon that should appear in the window frame of the dialog.
--width=WIDTH

Species the width of the dialog.

--height=HEIGHT

Species the height of the dialog.

4. Calendar Dialog
Use --calender to create a Calender dialog. Zenity returns the date selected to standad error. The current date will be used by the dialog if no date is given on the command line. The Calender dialog has the following options:

Zenity Manual
--text=TEXT

Species the text to appear in the Calendar dialog.

--day=DAY

Species the day to be pre-selected in the Calendar dialog. The day ust be a number between 1 and 31.
--month=MONTH

Species the day to be pre-selected in the Calendar dialog. The day must be a number between 1 and 12.
--year=YEAR

Species the year to be pre-selected in the Calendar dialog.

--date-format=FORMAT

Species the format to be returned from the Calendar dialog after the selection has been made. The default format depends on your locale. The format must be of strftime style, for example "%A %d/%m%y". The following script is an example of how to use the Calendar dialog:
#!/bin/sh

if zenity --calendar --title="Calendar selection" --text="Select a date from below" --day=18 --mo then echo $? else echo "No date selected" fi

Figure 1. Calendar dialog example Zenity Calendar dialog example

5. Text Entry Dialog

Use --text-entry to create a Text Entry dialog. Zenity returns the contents of the text entry to standard error. The Text Entry dialog has the following options:
--text=TEXT

Species the text to appear in the Text Entry dialog.

--entry-text=TEXT

Species the text to appear in the entry eld of the Text Entry dialog.
--hide-text

Species that the text in the entry eld of the Text Entry dialog be hidden.

Zenity Manual The following script is an example of how to use the Text Entry dialog:
#!/bin/sh if zenity --entry --title="Add a new entry" --text="Enter your _Password" --hide-text then echo $? else echo "No password entered" fi

Figure 2. Text Entry dialog example Zenity Text Entry dialog example

6. Message Dialogs
Zenity can create four types of message dialog. Use the --text option to set the text shown in the dialog.

6.1. Warning Dialog

Use --warning to create a Warning dialog. The following script is 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

Figure 3. Warning dialog example Zenity Warning dialog example

6.2. Error Dialog

Use --error to create an Error dialog.

Zenity Manual Figure 4. Error dialog example Zenity Error dialog example

6.3. Information Dialog

Use --info to create an Information dialog. Figure 5. Informational dialog example Zenity Informational dialog example

6.4. Question Dialog

Use --question to create a Question dialog. Figure 6. Question dialog example Zenity Question dialog example

7. File Selection Dialog

Use --le-selection to create a le selection dialog. Zenity returns the les or directories selected to standard error. The File Selection dialog has the following options:
--filename=FILENAME

Species the le or directory to be selected in the File Selection dialog when the dialog is rst shown.
--multiple

Allows selection of multiple lenames in the File Selection dialog.

--separator=SEPARATOR

Species the string used to divide the returned list of lenames. The following script is an example of how to use the File Selection dialog:
#!/bin/sh FILE=zenity --file-selection --title="Select a file"

Zenity Manual
case $? in 0) echo "\"$FILE\" selected.";; 1) echo "No file selected.";; -1) echo "No file selected.";; esac

Figure 7. File Selection dialog example Zenity File Selection dialog example

8. List Dialog
Use --list to create a list dialog. Zenity returns the entries in the rst column of text of selected rows to standard error. Every column must be specied by the --column option. Data for the dialog must specied column by column, row by row. Data can be provided to the dialog through standard input. Each entry must be separated by a newline. If you use the --checklist or --radiolist options, each row must start with either TRUE or FALSE. The List dialog has the following options:
--column=COLUMN

Species the column headers to appear in the List dialog. You must call the --column option for each column you want to appear in the dialog.
--checklist

Species that the rst column should contain check boxes in the List dialog.
--radiolist

Species that the rst column should contain radio boxes in the List dialog.
--editable

Allows the displayed items to be edited.

--seperator=SEPERATOR

Species what string should be used when the List dialog returns the selected entries. The following commandline is an example of how to use the List dialog:
zenity --list --title="Choose bugs you wish to view" \

Zenity Manual
--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"

Figure 8. List Selection dialog example Zenity List dialog example

9. Progress Dialog
Use --progress to create a Progress dialog. Zenity reads data from standard input line by line. If a line is prexed with a hash (#), the text is updated with the text on that line. If a line contains only a number, the percentage is updated with that number. The Progress dialog has the following options:
--text=TEXT

Species the text to appear in the Progress dialog.

--percentage=PERCENTAGE

Species the initial percentage that should be set in the Progress dialog.
--auto-close

Closes the progress dialog when 100% has been reached.

--pulsate

Species that the Progress dialog should pulsate until an EOF character is read from standard input. The following script is 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 --title="Update System Logs" --text="Scanning mail logs..." --percentage=0

Zenity Manual

if [ "$?" = -1 ] ; then zenity --error --text="Update cancelled." fi

Figure 9. Progress dialog example Zenity Progress dialog example

10. Text Information Dialog

Use --text-info to create a Text Information dialog. The Text Information dialog has the following options:
--filename=FILENAME

Species a le to be loaded in the Text Information dialog.

--editable

Allows the displayed text to be edited. The edited text is returned to standard error when the dialog is closed. The following script is an example of how to use the Text Infomation dialog:
#!/bin/sh FILE=zenity --file-selection --title="Select a file" case $? in 0) zenity --text-info --title=$FILE --editable 2>/tmp/tmp.txt 1) echo "No file selected.";; -1) echo "No file selected.";; esac

Figure 10. Text Information dialog example Zenity Text Information dialog example

Zenity Manual

11. Miscellaneous Options

Zenity has the following miscellaneous options:
--about

Displays some information about Zenity.

--version

Prints the version number of Zenity.

12. License
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License (gnome-help:gpl) 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 (http://www.fsf.org) or by writing to Free Software Foundation, Inc. 59 Temple Place - Suite 330 Boston, MA 02111-1307 USA