6d06f132d3
2003-01-18 Glynn Foster <glynn.foster@sun.com> * Makefile.am, configure.in, omf.make, xmldocs.make: Enable help documentation in the build. * help/C/zenity-C.omf, help/C/zenity.xml: Fix up silly errors.
725 lines
19 KiB
XML
725 lines
19 KiB
XML
<?xml version="1.0"?>
|
|
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
|
|
<!ENTITY legal SYSTEM "legal.xml">
|
|
<!ENTITY version "1.0">
|
|
<!ENTITY app "<application>zenity</application>">
|
|
]>
|
|
|
|
<!-- ================ Document Header ================= -->
|
|
|
|
<article id="index" lang="en">
|
|
|
|
<articleinfo>
|
|
<title>Zenity Manual</title>
|
|
<copyright>
|
|
<year>2003</year>
|
|
<holder>Sun Microsystems</holder>
|
|
</copyright>
|
|
|
|
<!-- Translators: uncomment this
|
|
<copyright>
|
|
<year>2003</year>
|
|
<holder>ME_THE_TRANSLATOR</holder>
|
|
</copyright>
|
|
-->
|
|
|
|
<publisher>
|
|
<publishername>GNOME Documentation Project</publishername>
|
|
</publisher>
|
|
|
|
<releaseinfo>Version 1.0 of Zenity Manual</releaseinfo>
|
|
|
|
<legalnotice id="feedback">
|
|
<title>Feedback Information</title>
|
|
<para>
|
|
To report a bug or make a suggestion regarding this
|
|
application or this documentation, please see the
|
|
<ulink type="help" url="ghelp:gnome-feedback">
|
|
GNOME Feedback Page
|
|
</ulink>
|
|
</para>
|
|
</legalnotice>
|
|
|
|
<authorgroup>
|
|
<author>
|
|
<firstname>Glynn</firstname>
|
|
<surname>Foster</surname>
|
|
<affiliation>
|
|
<orgname>GNOME Documentation Project</orgname>
|
|
</affiliation>
|
|
</author>
|
|
</authorgroup>
|
|
|
|
<revhistory>
|
|
<revision>
|
|
<revnumber>1.0</revnumber>
|
|
<date>18-01-2003</date>
|
|
<revdescription>
|
|
<para role="author">Glynn Foster</para>
|
|
<para role="publisher">
|
|
GNOME Documentation Project
|
|
</para>
|
|
</revdescription>
|
|
</revision>
|
|
</revhistory>
|
|
</articleinfo>
|
|
|
|
<!-- ================ Document Body ================= -->
|
|
|
|
<!-- ==== Introduction ====== -->
|
|
|
|
<sect1 id="zenity-introduction">
|
|
<title>Introduction</title>
|
|
|
|
<para>
|
|
&app; allows allows you to display simple dialogs from the
|
|
command line or from shell scripts.
|
|
</para>
|
|
|
|
<para>
|
|
The following list of dialogs are available with &app;:
|
|
</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term><varname>--calendar</varname></term>
|
|
<listitem>
|
|
<para>Display a Calendar dialog.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>--entry</varname></term>
|
|
<listitem>
|
|
<para>Display a Text Entry dialog.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>--error</varname></term>
|
|
<listitem>
|
|
<para>Display an Error dialog.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>--info</varname></term>
|
|
<listitem>
|
|
<para>Display an Informational dialog.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>--file-selection</varname></term>
|
|
<listitem>
|
|
<para>Display a File Selection dialog.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>--list</varname></term>
|
|
<listitem>
|
|
<para>Display a List dialog.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>--progress</varname></term>
|
|
<listitem>
|
|
<para>Display a Progress dialog.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>--question</varname></term>
|
|
<listitem>
|
|
<para>Display a Question dialog.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>--text-info</varname></term>
|
|
<listitem>
|
|
<para>Display a Text Information dialog.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>--warning</varname></term>
|
|
<listitem>
|
|
<para>Display a Warning dialog.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</sect1>
|
|
|
|
<!-- ==== General Options ====== -->
|
|
<sect1 id="zenity-basic-use">
|
|
<title>Basic Use</title>
|
|
|
|
<para>
|
|
&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.
|
|
</para>
|
|
|
|
<para>
|
|
The following exit codes are observed by &app;:
|
|
</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term><varname>0</varname></term>
|
|
<listitem>
|
|
<para>The user has pressed either 'OK' or 'Close'.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>1</varname></term>
|
|
<listitem>
|
|
<para>The user has pressed either 'Cancel' or closed the dialog through the window functions.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>-1</varname></term>
|
|
<listitem>
|
|
<para>An unexpected error has occurred.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</sect1>
|
|
|
|
<!-- ==== General Options ====== -->
|
|
|
|
<sect1 id="zenity-general-options">
|
|
<title>General Options</title>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
The following list of general options are available:
|
|
</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term><varname>--title</varname>=TITLE</term>
|
|
<listitem>
|
|
<para>Specify the title of a dialog.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>--window-icon</varname>=ICON_PATH</term>
|
|
<listitem>
|
|
<para>Specify the icon that should appear in the window frame of the dialog.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</sect1>
|
|
|
|
<!-- ==== Calendar Options ====== -->
|
|
|
|
<sect1 id="zenity-calendar-options">
|
|
<title>Calendar</title>
|
|
|
|
<para>
|
|
To create a Calendar dialog, use <command>--calendar</command>. &app; will return the
|
|
date selected to standard error. The following list of options are also available for
|
|
the Calendar dialog:
|
|
</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term><varname>--text</varname>=TEXT</term>
|
|
<listitem>
|
|
<para>Specify the text to appear in the Calendar dialog.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>--day</varname>=DAY</term>
|
|
<listitem>
|
|
<para>Specify the day to be pre-selected in the Calendar dialog. This must be a
|
|
number between 1 and 31.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>--month</varname>=MONTH</term>
|
|
<listitem>
|
|
<para>Specify the day to be pre-selected in the Calendar dialog. This must be
|
|
a number between 1 and 12.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>--year</varname>=YEAR</term>
|
|
<listitem>
|
|
<para>Specify the year to be pre-selected in the Calendar dialog.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>--data-format</varname>=FORMAT</term>
|
|
<listitem>
|
|
<para>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 <command>strftime</command>
|
|
style eg. "%A %d/%m%y"</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
<figure id="zenity-calendar-screenshot">
|
|
<title>Calendar dialog example</title>
|
|
<screenshot>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="figures/zenity-calendar-screenshot.png" format="PNG"/>
|
|
</imageobject>
|
|
<textobject>
|
|
<phrase>&app; Calendar dialog example</phrase>
|
|
</textobject>
|
|
</mediaobject>
|
|
</screenshot>
|
|
</figure>
|
|
|
|
<!-- FIXME: Add an example of a script -->
|
|
|
|
</sect1>
|
|
|
|
<!-- ==== Text Entry Options ====== -->
|
|
|
|
<sect1 id="zenity-text-entry-options">
|
|
<title>Text Entry</title>
|
|
|
|
<para>
|
|
To create a Text Entry dialog, use <command>--text-entry</command>. &app; returns the
|
|
contents of the text entry to standard error. The following list of options are also
|
|
available for the Text Entry dialog:
|
|
</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term><varname>--text</varname>=TEXT</term>
|
|
<listitem>
|
|
<para>Specify the text to appear in the Text Entry dialog.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>--entry-text</varname>=TEXT</term>
|
|
<listitem>
|
|
<para>Specify the text to appear in the entry field of the Text Entry dialog.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>--hide-text</varname></term>
|
|
<listitem>
|
|
<para>Specify that the text in the entry field of the Text Entry dialog be hidden.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
<figure id="zenity-entry-screenshot">
|
|
<title>Text Entry dialog example</title>
|
|
<screenshot>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="figures/zenity-entry-screenshot.png" format="PNG"/>
|
|
</imageobject>
|
|
<textobject>
|
|
<phrase>&app; Text Entry dialog example</phrase>
|
|
</textobject>
|
|
</mediaobject>
|
|
</screenshot>
|
|
</figure>
|
|
|
|
<!-- FIXME: Add an example of a script -->
|
|
|
|
</sect1>
|
|
|
|
<!-- ==== Message Options ====== -->
|
|
|
|
<sect1 id="zenity-message-options">
|
|
<title>Messages</title>
|
|
|
|
<para>
|
|
There are 4 types of message dialogs in &app; - Error, Informational, Question and Warning. To
|
|
create an Error dialog, use <command>--error</command>. To create an Informational dialog, use
|
|
<command>--info</command>. To create a Question dialog, use <command>--question</command>. To
|
|
create a Warning dialog, use <command>--question</command>. The following list of options is
|
|
available for the message dialogs.
|
|
</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term><varname>--text</varname>=TEXT</term>
|
|
<listitem>
|
|
<para>Specify the text to appear in the message dialog.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
<figure id="zenity-error-screenshot">
|
|
<title>Error dialog example</title>
|
|
<screenshot>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="figures/zenity-error-screenshot.png" format="PNG"/>
|
|
</imageobject>
|
|
<textobject>
|
|
<phrase>&app; Error dialog example</phrase>
|
|
</textobject>
|
|
</mediaobject>
|
|
</screenshot>
|
|
</figure>
|
|
|
|
<figure id="zenity-information-screenshot">
|
|
<title>Informational dialog example</title>
|
|
<screenshot>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="figures/zenity-information-screenshot.png" format="PNG"/>
|
|
</imageobject>
|
|
<textobject>
|
|
<phrase>&app; Informational dialog example</phrase>
|
|
</textobject>
|
|
</mediaobject>
|
|
</screenshot>
|
|
</figure>
|
|
|
|
<figure id="zenity-question-screenshot">
|
|
<title>Question dialog example</title>
|
|
<screenshot>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="figures/zenity-question-screenshot.png" format="PNG"/>
|
|
</imageobject>
|
|
<textobject>
|
|
<phrase>&app; Question dialog example</phrase>
|
|
</textobject>
|
|
</mediaobject>
|
|
</screenshot>
|
|
</figure>
|
|
|
|
<figure id="zenity-warning-screenshot">
|
|
<title>Warning dialog example</title>
|
|
<screenshot>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="figures/zenity-warning-screenshot.png" format="PNG"/>
|
|
</imageobject>
|
|
<textobject>
|
|
<phrase>&app; Warning dialog example</phrase>
|
|
</textobject>
|
|
</mediaobject>
|
|
</screenshot>
|
|
</figure>
|
|
|
|
<!-- FIXME: Add an example of a script -->
|
|
|
|
</sect1>
|
|
|
|
<!-- ==== File Selection Options ====== -->
|
|
|
|
<sect1 id="zenity-file-selection-options">
|
|
<title>File Selection</title>
|
|
|
|
<para>
|
|
To create a File Selection dialog, use <command>--file-selection</command>. &app; returns
|
|
the file or directory selected to standard error. The following list of options are also
|
|
available for the File Selection dialog:
|
|
</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term><varname>--filename</varname>=FILENAME</term>
|
|
<listitem>
|
|
<para>Specify the file or directory to be pre-selected in the File Selection dialog.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
<figure id="zenity-fileselection-screenshot">
|
|
<title>File Selection dialog example</title>
|
|
<screenshot>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="figures/zenity-fileselection-screenshot.png" format="PNG"/>
|
|
</imageobject>
|
|
<textobject>
|
|
<phrase>&app; File Selection dialog example</phrase>
|
|
</textobject>
|
|
</mediaobject>
|
|
</screenshot>
|
|
</figure>
|
|
|
|
<!-- FIXME: Add an example of a script -->
|
|
|
|
</sect1>
|
|
|
|
<!-- ==== List Options ====== -->
|
|
|
|
<sect1 id="zenity-list-options">
|
|
<title>Lists</title>
|
|
|
|
<para>
|
|
To create a List dialog, use <command>--list</command>. &app; returns the entries of
|
|
the first columns selected to standard error. If <command>--checklist</command> or
|
|
<command>--radiolist</command> is used, then &app; will return the entries of the
|
|
second columns selected to standard error. The following list of options are also
|
|
available for the File Selection dialog:
|
|
</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term><varname>--column</varname>=COLUMN</term>
|
|
<listitem>
|
|
<para>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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>--checklist</varname></term>
|
|
<listitem>
|
|
<para>Specify if the first column should contain check boxes in the List dialog.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>--radiolist</varname></term>
|
|
<listitem>
|
|
<para>Specify if the first column should contain radio boxes in the List dialog.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>--seperator</varname>=SEPERATOR</term>
|
|
<listitem>
|
|
<para>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'.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
<figure id="zenity-list-screenshot">
|
|
<title>List Selection dialog example</title>
|
|
<screenshot>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="figures/zenity-list-screenshot.png" format="PNG"/>
|
|
</imageobject>
|
|
<textobject>
|
|
<phrase>&app; List dialog example</phrase>
|
|
</textobject>
|
|
</mediaobject>
|
|
</screenshot>
|
|
</figure>
|
|
|
|
<!-- FIXME: Add an example of a script -->
|
|
|
|
</sect1>
|
|
|
|
<!-- ==== Progress Options ====== -->
|
|
|
|
<sect1 id="zenity-progress-options">
|
|
<title>Progress</title>
|
|
|
|
<para>
|
|
To create a Progress dialog, use <command>--progress</command>. The following list
|
|
of options are also available for the Progress dialog:
|
|
</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term><varname>--text</varname>=TEXT</term>
|
|
<listitem>
|
|
<para>Specify the text to appear in the Progress dialog.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>--percentage</varname>=PERCENTAGE</term>
|
|
<listitem>
|
|
<para>Specify the initial percentage that should be set in the Progress dialog.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>--pulsate</varname></term>
|
|
<listitem>
|
|
<para>Specify if the Progress dialog should pulsate until an EOF character is read
|
|
from standard input.</para>
|
|
</listitem>
|
|
|
|
</variablelist>
|
|
|
|
<figure id="zenity-progress-screenshot">
|
|
<title>Progress dialog example</title>
|
|
<screenshot>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="figures/zenity-progress-screenshot.png" format="PNG"/>
|
|
</imageobject>
|
|
<textobject>
|
|
<phrase>&app; Progress dialog example</phrase>
|
|
</textobject>
|
|
</mediaobject>
|
|
</screenshot>
|
|
</figure>
|
|
|
|
<!-- FIXME: Add an example of a script -->
|
|
|
|
</sect1>
|
|
|
|
<!-- ==== Text Information Options ====== -->
|
|
|
|
<sect1 id="zenity-text-options">
|
|
<title>Text Information</title>
|
|
|
|
<para>
|
|
To create a Text Information dialog, use <command>--text-info</command>. The following list
|
|
of options are also available for the Text Information dialog:
|
|
</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term><varname>--filename</varname>=FILENAME</term>
|
|
<listitem>
|
|
<para>Specify the file to be loaded in the Text Information dialog.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
<figure id="zenity-text-screenshot">
|
|
<title>Text Information dialog example</title>
|
|
<screenshot>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="figures/zenity-text-screenshot.png" format="PNG"/>
|
|
</imageobject>
|
|
<textobject>
|
|
<phrase>&app; Text Information dialog example</phrase>
|
|
</textobject>
|
|
</mediaobject>
|
|
</screenshot>
|
|
</figure>
|
|
|
|
<!-- FIXME: Add an example of a script -->
|
|
|
|
</sect1>
|
|
|
|
<!-- ==== Miscellaneous Options ====== -->
|
|
|
|
<sect1 id="zenity-miscellaneous-options">
|
|
<title>Miscellaneous</title>
|
|
|
|
<para>
|
|
The following list of options are also available for &app;:
|
|
</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term><varname>--about</varname></term>
|
|
<listitem>
|
|
<para>Display some information about &app;.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><varname>--version</varname></term>
|
|
<listitem>
|
|
<para>Print the version number of &app;.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</sect1>
|
|
|
|
<!-- ================ Application License ================= -->
|
|
<sect1 id="license">
|
|
<title>License</title>
|
|
<para>
|
|
This program is free software; you can redistribute
|
|
it and/or modify it under the terms of the
|
|
<ulink type="help" url="gnome-help:gpl">
|
|
<citetitle>GNU General Public License</citetitle>
|
|
</ulink>
|
|
as published by the Free Software Foundation; either
|
|
version 2 of the License, of (at your option) any later
|
|
version.
|
|
</para>
|
|
<para>
|
|
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
|
|
<citetitle>GNU General Public License</citetitle>
|
|
for more details.
|
|
</para>
|
|
<para>
|
|
A copy of the
|
|
<citetitle>GNU General Public License</citetitle>
|
|
is included as an appendix to the
|
|
<citetitle>GNOME Users Guide</citetitle>
|
|
. You may also obtain a copy of the
|
|
<citetitle>GNU General Public License</citetitle>
|
|
from the Free Software Foundation by visiting
|
|
<ulink type="http" url="http://www.fsf.org">
|
|
their Web site
|
|
</ulink>
|
|
or by writing to
|
|
<address>Free Software Foundation, Inc.
|
|
<street>59 Temple Place</street> - Suite 330
|
|
<city>Boston</city>,
|
|
<state>MA</state>
|
|
<postcode>02111-1307</postcode>
|
|
<country>USA</country>
|
|
</address>
|
|
</para>
|
|
</sect1>
|
|
|
|
</article>
|