blob: 11c254233acb2c72f94e1db6703e93cab50951f6 [file] [log] [blame]
<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl"
href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
]>
<refentry id="xdg-file-dialog">
<refentryinfo>
<title>xdg-file-dialog Manual</title>
<copyright>
<year>2006</year>
</copyright>
<author>
<firstname>Kevin</firstname>
<surname>Krammer</surname>
</author>
<address><email>kevin.krammer@gmx.at</email></address>
<releaseinfo>This is release 0.5 of the xdg-mime Manual.</releaseinfo>
</refentryinfo>
<refmeta>
<refentrytitle>xdg-file-dialog</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>
<refnamediv>
<refname>xdg-file-dialog</refname>
<refpurpose>command line tool for providing file and directory selection dialogs</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>xdg-file-dialog</command>
<arg choice="plain">openfilename</arg>
<arg><option>--title <replaceable>TITLE</replaceable></option></arg>
<arg><replaceable>FILENAME</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>xdg-file-dialog</command>
<arg choice="plain">openfilenamelist</arg>
<arg><option>--title <replaceable>TITLE</replaceable></option></arg>
<arg><replaceable>FILENAME</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>xdg-file-dialog</command>
<arg choice="plain">savefilename</arg>
<arg><option>--title <replaceable>TITLE</replaceable></option></arg>
<arg><replaceable>FILENAME</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>xdg-file-dialog</command>
<arg choice="plain">directory</arg>
<arg><option>--title <replaceable>TITLE</replaceable></option></arg>
<arg><replaceable>DIRNAME</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>xdg-file-dialog</command>
<group choice="req">
<arg choice="plain"><option>--help</option></arg>
<arg choice="plain"><option>--manual</option></arg>
<arg choice="plain"><option>--version</option></arg>
</group>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1 id="description">
<title>Description</title>
<para>
The xdg-file-dialog program can be used to let the native file selection dialog
handle file and directory input.
</para>
<para>
xdg-file-dialog is for use inside a desktop session only.
It is not recommended to use xdg-file-dialog as root.
</para>
</refsect1>
<refsect1 id="commands">
<title>Commands</title>
<variablelist>
<varlistentry>
<term>openfilename</term>
<listitem>
<simpara>
Returns the filename with path for a file to read from.
<replaceable>FILENAME</replaceable> can optionally be used to
specify path and filename of a preselection.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>openfilenamelist</term>
<listitem>
<simpara>
Returns one or more filenames with path for files to read from,
each on a new line. <replaceable>FILENAME</replaceable> can optionally
be used to specify path and filename of a preselection.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>savefilename</term>
<listitem>
<simpara>
Returns the filename with path for file to write to.
<replaceable>FILENAME</replaceable> can optionally be used to
specify path and filename of a preselection.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>directory</term>
<listitem>
<simpara>
Returns the path for an exsiting directory.
<replaceable>DIRNAME</replaceable> can optionally be used to
specify a path of a preselection.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="options">
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>--title</option> <replaceable>TITLE</replaceable></term>
<listitem>
<simpara>
Sets the dialog's title (caption) to the specified text.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--help</option></term>
<listitem>
<simpara>
Show command synopsis.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--manual</option></term>
<listitem>
<simpara>
Show this manualpage.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--version</option></term>
<listitem>
<simpara>
Show the xdg-utils version information.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="exitcodes">
<title>Exit Codes</title>
<para>
An exit code of 0 indicates success while a non-zero exit code
indicates failure. The following failure codes can be returned:
</para>
<variablelist>
<varlistentry>
<term><option>1</option></term>
<listitem>
<simpara>
Error in command line syntax.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><option>2</option></term>
<listitem>
<simpara>
One of the files passed on the command line did not exist.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><option>3</option></term>
<listitem>
<simpara>
A required tool could not be found.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><option>4</option></term>
<listitem>
<simpara>
The action failed.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="examples">
<title>Examples</title>
<para>
<programlisting>
xdg-file-dialog savefilename /tmp/foobar.png
</programlisting>
Asks for a save file name starting in directory /tmp and suggesting foobar.png as the filename
</para>
<para>
<programlisting>
xdg-file-dialog directory --title "Select a target folder" /tmp
</programlisting>
Asks for a directory name starting in directory /tmp using the text "Select a target folder" as the dialog's title/caption.
</para>
</refsect1>
</refentry>