diff --git a/ChangeLog b/ChangeLog index a3d30a0..2777690 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2003-09-01 Glynn Foster + + * help/C/zenity.xml: Documentation updates from Nicholas Curran. + * THANKS, src/about.c: Add Nicholas. + 2003-08-27 Glynn Foster * src/tree.c: Put horizontal scrolling on automatic, otherwise diff --git a/THANKS b/THANKS index 44d2dae..2ccee8a 100644 --- a/THANKS +++ b/THANKS @@ -2,6 +2,7 @@ These are all the people that I've taken code from: Jonathan Blandford Ross Burton Anders Carlsson +Nicholas Curran John Fleck James Henstridge Mihai T. Lazarescu diff --git a/help/C/zenity.xml b/help/C/zenity.xml index 358fb81..3d7bc75 100644 --- a/help/C/zenity.xml +++ b/help/C/zenity.xml @@ -3,7 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ - zenity"> + Zenity"> ]> @@ -49,6 +49,13 @@ GNOME Documentation Project + + Nicholas + Curran + + GNOME Documentation Project + + @@ -73,87 +80,49 @@ Introduction - &app; allows allows you to display simple dialogs from the - command line or from shell scripts. + &app; displays simple GNOME dialogs. - The following list of dialogs are available with &app;: + &app; can display the following dialogs: - - - - --calendar - - Display a Calendar dialog. + + + Calender dialog. + + + Text entry dialog. + + Various message dialogs including: + + + Error dialog. + + + Information dialog. + + + Question dialog. + + + Warning 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. - - - - + + File selection dialog. + + + List options dialog. + + + Progress dialog. + + + Text dialog. + + @@ -162,28 +131,34 @@ Basic Use - &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. + &app; creates simple dialogs. You can use &app; to create a script that + interacts graphically with the user. + + + + When the user closes the dialog, + &app; prints text produced by the dialog to standard error. - 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 --title="Holiday Planner" - , for example. If you do not use quotes, then it is likely that you will get - unexpected results. + Ensure that all arguments to &app; 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. - - 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. - + + 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". + + - The following exit codes are observed by &app;: + &app; returns the following exit codes: @@ -219,13 +194,7 @@ General Options - 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: + All dialogs have the following general options: @@ -233,28 +202,28 @@ --title=TITLE - Specify the title of a dialog. + Specifies the title of a dialog. --window-icon=ICON_PATH - Specify the icon that should appear in the window frame of the dialog. + Specifies the icon that should appear in the window frame of the dialog. --width=WIDTH - Specify the width of the dialog. + Specifies the width of the dialog. --height=HEIGHT - Specify the height of the dialog. + Specifies the height of the dialog. @@ -265,15 +234,15 @@ - Calendar + Calendar 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. + Use --calender to create a Calender dialog. &app; 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 following list of options are available for the Calendar dialog: + The Calender dialog has the following options: @@ -281,15 +250,15 @@ --text=TEXT - Specify the text to appear in the Calendar dialog. + Specifies 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. + Specifies the day to be pre-selected in the Calendar dialog. The day + ust be a number between 1 and 31. @@ -297,7 +266,7 @@ --month=MONTH - Specify the day to be pre-selected in the Calendar dialog. This must be + Specifies the day to be pre-selected in the Calendar dialog. The day must be a number between 1 and 12. @@ -306,39 +275,25 @@ --year=YEAR - Specify the year to be pre-selected in the Calendar dialog. + Specifies 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 + Specifies 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 eg. "%A %d/%m%y" + style, for example "%A %d/%m%y". + -
- Calendar dialog example - - - - - - - &app; Calendar dialog example - - - -
- - - The following script shows an example of how to use the Calendar dialog: + The following script is an example of how to use the Calendar dialog: #!/bin/sh @@ -350,19 +305,34 @@ +
+ Calendar dialog example + + + + + + + &app; Calendar dialog example + + + +
+ - Text Entry + Text Entry Dialog - To create a Text Entry dialog, use --text-entry. &app; returns the + Use --text-entry to create a Text Entry dialog. + &app; returns the contents of the text entry to standard error. - The following list of options are available for the Text Entry dialog: + The Text Entry dialog has the following options: @@ -370,26 +340,39 @@ --text=TEXT - Specify the text to appear in the Text Entry dialog. + Specifies 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. + Specifies 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. + Specifies that the text in the entry field of the Text Entry dialog be hidden. + + 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 + + +
Text Entry dialog example @@ -403,106 +386,27 @@
- - - The following script shows 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 - - - - Messages + Message Dialogs - 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. + &app; can create four types of message dialog. + Use the --text option to set the text shown in the + dialog. + + Warning Dialog - + + Use --warning to create a Warning dialog. + - - --text=TEXT - - Specify the text to appear in the message dialog. - - - - - -
- Error dialog example - - - - - - - &app; Error dialog example - - - -
- -
- Informational dialog example - - - - - - - &app; Informational dialog example - - - -
- -
- Question dialog example - - - - - - - &app; Question dialog example - - - -
- -
- Warning dialog example - - - - - - - &app; Warning dialog example - - - -
- - - The following script shows an example of how to use the Warning message dialog: + + The following script is an example of how to use the Warning message dialog: #!/bin/bash @@ -513,21 +417,103 @@ zenity --warning --text="Could not rotate image :" --hide-text fi - + + +
+ Warning dialog example + + + + + + + &app; Warning dialog example + + + +
+ + + + Error Dialog + + + Use --error to create an Error dialog. + + +
+ Error dialog example + + + + + + + &app; Error dialog example + + + +
+ + + + Information Dialog + + + Use --info to create an Information dialog. + + +
+ Informational dialog example + + + + + + + &app; Informational dialog example + + + +
+ + + + Question Dialog + + + Use --question to create a Question dialog. + + +
+ Question dialog example + + + + + + + &app; Question dialog example + + + +
+ - File Selection + File Selection Dialog - To create a File Selection dialog, use --file-selection. &app; returns - the file or directory selected to standard error. + Use --file-selection to create a file selection + dialog. &app; returns + the files or directories selected to standard error. - The following list of options are available for the File Selection dialog: + The File Selection dialog has the following options: @@ -535,43 +521,29 @@ --filename=FILENAME - Specify the file or directory to be pre-selected in the File Selection dialog. + Specifies the file or directory to be selected in the File Selection dialog + when the dialog is first shown. --multiple - Allow selection of mulitple filename in the File Selection dialog. + Allows selection of multiple filenames in the File Selection dialog. --separator=SEPARATOR - Specify the character(s) which will divide between entries in the returned list of file names. The - default character is '|'. If you want to specify a newline, use '\n'. + Specifies the string used to divide the returned list of filenames. -
- File Selection dialog example - - - - - - - &app; File Selection dialog example - - - -
- - The following script shows an example of how to use the File Selection dialog: + The following script is an example of how to use the File Selection dialog: #!/bin/sh @@ -589,34 +561,45 @@ +
+ File Selection dialog example + + + + + + + &app; File Selection dialog example + + + +
+ - Lists + List Dialog - 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. + Use --list to create a list dialog. &app; returns the entries in + the first column of text of selected rows 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. + Every column must be specified by the --column option. 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. - The following list of options are available for the List dialog: + If you use the --checklist or --radiolist + options, each row must start with either 'TRUE' or 'FALSE'. + + + + The List dialog has the following options: @@ -624,8 +607,9 @@ --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. + Specifies 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. @@ -633,7 +617,7 @@ --checklist - Specify if the first column should contain check boxes in the List dialog. + Specifies that the first column should contain check boxes in the List dialog. @@ -641,7 +625,7 @@ --radiolist - Specify if the first column should contain radio boxes in the List dialog. + Specifies that the first column should contain radio boxes in the List dialog. @@ -649,7 +633,7 @@ --editable - Allow the displayed items to be edited. + Allows the displayed items to be edited. @@ -657,14 +641,25 @@ --seperator=SEPERATOR - Specify what seperator character(s) should be used when the List dialog returns the selected entries. The - default character is '|'. If you want to specify a newline, use '\n'. + Specifies 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" \ + --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" + + +
List Selection dialog example @@ -679,33 +674,26 @@
- - The following commandline shows an example of how to use the List dialog: - - zenity --list --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" - - - - Progress + Progress Dialog - 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). + Use --progress to create a Progress dialog. + + + + &app; reads data from + standard input line by line. If a line is prefixed 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 following list of options are available for the Progress dialog: + The Progress dialog has the following options: @@ -713,14 +701,14 @@ --text=TEXT - Specify the text to appear in the Progress dialog. + Specifies the text to appear in the Progress dialog. --percentage=PERCENTAGE - Specify the initial percentage that should be set in the Progress dialog. + Specifies the initial percentage that should be set in the Progress dialog. @@ -734,29 +722,15 @@ --pulsate - Specify if the Progress dialog should pulsate until an EOF character is read + Specifies that the Progress dialog should pulsate until an EOF character is read from standard input. -
- Progress dialog example - - - - - - - &app; Progress dialog example - - - -
- - The following script shows an example of how to use the Progress dialog: + The following script is an example of how to use the Progress dialog: #!/bin/sh ( @@ -778,19 +752,33 @@ +
+ Progress dialog example + + + + + + + &app; Progress dialog example + + + +
+ - Text Information + Text Information Dialog - To create a Text Information dialog, use --text-info. + Use --text-info to create a Text Information dialog. - The following list of options are available for the Text Information dialog: + The Text Information dialog has the following options: @@ -798,35 +786,22 @@ --filename=FILENAME - Specify the file to be loaded in the Text Information dialog. + Specifies a 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. + Allows the displayed text to be edited. The edited text is + returned to standard error when the dialog is closed. -
- Text Information dialog example - - - - - - - &app; Text Information dialog example - - - -
- - The following script shows an example of how to use the Text Infomation dialog: + The following script is an example of how to use the Text Infomation dialog: #!/bin/sh @@ -844,15 +819,29 @@ +
+ Text Information dialog example + + + + + + + &app; Text Information dialog example + + + +
+ - Miscellaneous + Miscellaneous Options - The following list of options are also available for &app;: + &app; has the following miscellaneous options: @@ -860,14 +849,14 @@ --about - Display some information about &app;. + Displays some information about &app;. --version - Print the version number of &app;. + Prints the version number of &app;. diff --git a/src/about.c b/src/about.c index bb67581..b59e5f1 100644 --- a/src/about.c +++ b/src/about.c @@ -53,6 +53,7 @@ static const gchar *author_credits[] = { "Jonathan Blandford ", "Ross Burton ", "Anders Carlsson ", + "Nicholas Curran ", "John Fleck ", "James Henstridge ", "Mihai T. Lazarescu ",