&appname; Desktop Application Manual V&manrevision; 2003 2004 &publisher; &publisher; &legal; &author1; &author2; &publisher; Glynn Foster GNOME Documentation Project Nicholas Curran GNOME Documentation Project &appname; Desktop Application Manual V&manrevision; &date; &author1; &author2; &publisher; Zenity Manual V1.0 January 2003 Glynn Foster GNOME Documentation Project This manual describes version &appversion; of &appname;. To send feedback, follow the directions in the Feedback Page. zenity command dialog creator &app; enables you to create the following types of simple dialog: Calendar File selection List Notification Message Error Information Question Warning Progress Text entry Text information When you write scripts, you can use &app; to create simple dialogs that interact graphically with the user, as follows: You can create a dialog to obtain information from the user. For example, you can prompt the user to select a date from a calendar dialog, or to select a file from a file selection dialog. You can create a dialog to provide the user with information. For example, you can use a progress dialog to indicate the current status of an operation, or use a warning message dialog to alert the user. When the user closes the dialog, &app; prints the text produced by the dialog to standard error. When you write &app; commands, ensure that you place quotation marks around each argument. For example, use: zenity --calendar --title="Holiday Planner" Do not use: zenity --calendar --title=Holiday Planner If you do not use quotation marks, you might get unexpected results. An access key is a key that enables you to perform an action from the keyboard rather than use the mouse to choose a command from a menu or dialog. Each access key is identified by an underlined letter on a menu or dialog option. Some &app; dialogs support the use of access keys. To specify the character to use as the access key, place an underscore before that character in the text of the dialog. The following example shows how to specify the letter 'C' as the access key: "_Choose a name". &app; returns the following exit codes: Exit Code Description 0 The user has pressed either OK or Close. 1 The user has either pressed Cancel, or used the window functions to close the dialog. -1 An unexpected error has occurred. All &app; dialogs support the following general options: --title=title Specifies the title of a dialog. --window-icon=icon_path Specifies the icon that is displayed in the window frame of the dialog. There are 4 stock icons also available by providing the following keywords - 'info', 'warning', 'question' and 'error'. --width=width Specifies the width of the dialog. --height=height Specifies the height of the dialog. &app; provides the following help options: --help Displays help text. You can also use -? to specify this option. --usage Displays brief usage text. &app; also provides the following miscellaneous options: --about Displays the About &appname; dialog, which contains &app; version information, copyright information, and developer information. --version Displays the version number of &app;. &app; supports the standard GTK+ options. For more information about the GTK+ options, execute the zenity -? command. Use the --calendar option to create a calendar dialog. &app; returns the selected date to standard error. If no date is specified on the command line, the dialog uses the current date. The calendar dialog supports the following options: --text=text Specifies the text that is displayed in the calendar dialog. --day=day Specifies the day that is selected in the calendar dialog. day must be a number between 1 and 31 inclusive. --month=month Specifies the month that is selected in the calendar dialog. month must be a number between 1 and 12 inclusive. --year=year Specifies the year that is selected in the calendar dialog. --date-format=format Specifies the format that is returned from the calendar dialog after date selection. The default format depends on your locale. format must be a format that is acceptable to the strftime function, for example %A %d/%m/%y. The following example script shows how to create a calendar dialog: #!/bin/sh if zenity --calendar \ --title="Select a Date" \ --text="Click on a date to select that date." \ --day=10 --month=8 --year=2004 then echo $? else echo "No date selected" fi

&app; calendar dialog example

Use the --file-selection option to create a file selection dialog. &app; returns the selected files or directories to standard error. The default mode of the file selection dialog is open. The file selection dialog supports the following options: --filename=filename Specifies the file or directory that is selected in the file selection dialog when the dialog is first shown. --multiple Allows the selection of multiple filenames in the file selection dialog. --directory Allows only selection of directories in the file selection dialog. --save Set the file selection dialog into save mode. --separator=separator Specifies the string that is used to divide the returned list of filenames. The following example script shows how to create a file selection dialog: #!/bin/sh FILE=`zenity --file-selection --title="Select a File"` case $? in 0) echo "\"$FILE\" selected.";; 1) echo "No file selected.";; -1) echo "No file selected.";; esac

&app; file selection dialog example

--text=text Specifies the text that is displayed in the notification area. The following example script shows how to create a notification icon: #!/bin/sh zenity --notification\ --window-icon="info" \ --text="There are system updates necessary!"

&app; notification icon example

Use the --list option to create a list dialog. &app; returns the entries in the first column of text of selected rows to standard error. Data for the dialog must specified column by column, row by row. Data can be provided to the dialog through standard input. Each entry must be separated by a newline character. If you use the --checklist or --radiolist options, each row must start with either 'TRUE' or 'FALSE'. The list dialog supports the following options: --column=column Specifies the column headers that are displayed in the list dialog. You must specify a --column option for each column that you want to display in the dialog. --checklist Specifies that the first column in the list dialog contains check boxes. --radiolist Specifies that the first column in the list dialog contains radio boxes. --editable Allows the displayed items to be edited. --separator=separator Specifies what string is used when the list dialog returns the selected entries. --print-column=column Specifies what column should be printed out upon selection. The default column is '1'. 'ALL' can be used to print out all columns in the list. The following example script shows how to create a list dialog: #!/bin/sh zenity --list \ --title="Choose the Bugs You Wish to View" \ --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"

&app; list dialog example

&app; can create four types of message dialog: Error Information Question Warning For each type, use the --text option to specify the text that is displayed in the dialog. Use the --error option to create an error dialog. The following example script shows how to create an error dialog: #!/bin/bash zenity --error \ --text="Could not find /var/log/syslog."

&app; error dialog example

Use the --info option to create an information dialog. The following example script shows how to create an information dialog: #!/bin/bash zenity --info \ --text="Merge complete. Updated 3 of 10 files."

&app; information dialog example

Use the --question option to create a question dialog. The following example script shows how to create a question dialog: #!/bin/bash zenity --question \ --text="Are you sure you wish to proceed?"

&app; question dialog example

Use the --warning option to create a warning dialog. The following example script shows how to create a warning dialog: #!/bin/bash zenity --warning \ --text="Disconnect the power cable to avoid electrical shock."

&app; warning dialog example

Use the --progress option to create a progress dialog. &app; reads data from standard input line by line. If a line is prefixed with #, 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 supports the following options: --text=text Specifies the text that is displayed in the progress dialog. --percentage=percentage Specifies the initial percentage that is set in the progress dialog. --auto-close Closes the progress dialog when 100% has been reached. --pulsate Specifies that the progress bar pulsates until an EOF character is read from standard input. The following example script shows how to create a 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 if [ "$?" = -1 ] ; then zenity --error \ --text="Update canceled." fi

&app; progress dialog example

Use the -entry option to create a text entry dialog. &app; returns the contents of the text entry to standard error. The text entry dialog supports the following options: --text=text Specifies the text that is displayed in the text entry dialog. --entry-text=text Specifies the text that is displayed in the entry field of the text entry dialog. --hide-text Hides the text in the entry field of the text entry dialog. The following example script shows how to create a text entry dialog: #!/bin/sh if zenity --entry \ --title="Add an Entry" \ --text="Enter your _password:" \ --entry-text "password" \ --hide-text then echo $? else echo "No password entered" fi

&app; text entry dialog example

Use the --text-info option to create a text information dialog. The text information dialog supports the following options: --filename=filename Specifies a file that is 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 example script shows how to create a text information dialog: #!/bin/sh FILE=`zenity --file-selection \ --title="Select a File"` case $? in 0) zenity --text-info \ --title=$FILE \ --filename=$FILE \ --editable 2>/tmp/tmp.txt;; 1) echo "No file selected.";; -1) echo "No file selected.";; esac

&app; text information dialog example