|
Packit |
ae235b |
<refentry id="gapplication-tool" lang="en">
|
|
Packit |
ae235b |
<refentryinfo>
|
|
Packit |
ae235b |
<title>gapplication</title>
|
|
Packit |
ae235b |
<productname>GIO</productname>
|
|
Packit |
ae235b |
<authorgroup>
|
|
Packit |
ae235b |
<author>
|
|
Packit |
ae235b |
<contrib>Developer</contrib>
|
|
Packit |
ae235b |
<firstname>Ryan</firstname>
|
|
Packit |
ae235b |
<surname>Lortie</surname>
|
|
Packit |
ae235b |
</author>
|
|
Packit |
ae235b |
</authorgroup>
|
|
Packit |
ae235b |
</refentryinfo>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<refmeta>
|
|
Packit |
ae235b |
<refentrytitle>gapplication</refentrytitle>
|
|
Packit |
ae235b |
<manvolnum>1</manvolnum>
|
|
Packit |
ae235b |
<refmiscinfo class="manual">User Commands</refmiscinfo>
|
|
Packit |
ae235b |
</refmeta>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<refnamediv>
|
|
Packit |
ae235b |
<refname>gapplication</refname>
|
|
Packit |
ae235b |
<refpurpose>D-Bus application launcher</refpurpose>
|
|
Packit |
ae235b |
</refnamediv>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<refsynopsisdiv>
|
|
Packit |
ae235b |
<cmdsynopsis>
|
|
Packit |
ae235b |
<command>gapplication</command>
|
|
Packit |
ae235b |
<arg choice="plain">help</arg>
|
|
Packit |
ae235b |
<arg choice="opt"><replaceable>COMMAND</replaceable></arg>
|
|
Packit |
ae235b |
</cmdsynopsis>
|
|
Packit |
ae235b |
<cmdsynopsis>
|
|
Packit |
ae235b |
<command>gapplication</command>
|
|
Packit |
ae235b |
<arg choice="plain">version</arg>
|
|
Packit |
ae235b |
</cmdsynopsis>
|
|
Packit |
ae235b |
<cmdsynopsis>
|
|
Packit |
ae235b |
<command>gapplication</command>
|
|
Packit |
ae235b |
<arg choice="plain">list-apps</arg>
|
|
Packit |
ae235b |
</cmdsynopsis>
|
|
Packit |
ae235b |
<cmdsynopsis>
|
|
Packit |
ae235b |
<command>gapplication</command>
|
|
Packit |
ae235b |
<arg choice="plain">launch</arg>
|
|
Packit |
ae235b |
<arg choice="plain"><replaceable>APPID</replaceable></arg>
|
|
Packit |
ae235b |
</cmdsynopsis>
|
|
Packit |
ae235b |
<cmdsynopsis>
|
|
Packit |
ae235b |
<command>gapplication</command>
|
|
Packit |
ae235b |
<arg choice="plain">launch</arg>
|
|
Packit |
ae235b |
<arg choice="plain"><replaceable>APPID</replaceable></arg>
|
|
Packit |
ae235b |
<arg choice="opt" rep="repeat"><replaceable>FILE</replaceable></arg>
|
|
Packit |
ae235b |
</cmdsynopsis>
|
|
Packit |
ae235b |
<cmdsynopsis>
|
|
Packit |
ae235b |
<command>gapplication</command>
|
|
Packit |
ae235b |
<arg choice="plain">list-actions</arg>
|
|
Packit |
ae235b |
<arg choice="plain"><replaceable>APPID</replaceable></arg>
|
|
Packit |
ae235b |
</cmdsynopsis>
|
|
Packit |
ae235b |
<cmdsynopsis>
|
|
Packit |
ae235b |
<command>gapplication</command>
|
|
Packit |
ae235b |
<arg choice="plain">action</arg>
|
|
Packit |
ae235b |
<arg choice="plain"><replaceable>APPID</replaceable></arg>
|
|
Packit |
ae235b |
<arg choice="plain"><replaceable>ACTION</replaceable></arg>
|
|
Packit |
ae235b |
<arg choice="opt"><replaceable>PARAMETER</replaceable></arg>
|
|
Packit |
ae235b |
</cmdsynopsis>
|
|
Packit |
ae235b |
</refsynopsisdiv>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<refsect1>
|
|
Packit |
ae235b |
<title>Description</title>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<para>
|
|
Packit |
ae235b |
<command>gapplication</command> is a commandline implementation of the client-side of the
|
|
Packit |
ae235b |
<interfacename>org.freedesktop.Application</interfacename> interface as specified by the freedesktop.org
|
|
Packit |
ae235b |
Desktop Entry Specification.
|
|
Packit |
ae235b |
</para>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<para>
|
|
Packit |
ae235b |
<command>gapplication</command> can be used to start applications that have
|
|
Packit |
ae235b |
<varname>DBusActivatable</varname> set to <literal>true</literal> in their <filename>.desktop</filename>
|
|
Packit |
ae235b |
files and can be used to send messages to already-running instances of other applications.
|
|
Packit |
ae235b |
</para>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<para>
|
|
Packit |
ae235b |
It is possible for applications to refer to <command>gapplication</command> in the <varname>Exec</varname>
|
|
Packit |
ae235b |
line of their <filename class='extension'>.desktop</filename> file to maintain backwards compatibility
|
|
Packit |
ae235b |
with implementations that do not directly support <varname>DBusActivatable</varname>.
|
|
Packit |
ae235b |
</para>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<para>
|
|
Packit |
ae235b |
<command>gapplication</command> ships as part of <application>GLib</application>.
|
|
Packit |
ae235b |
</para>
|
|
Packit |
ae235b |
</refsect1>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<refsect1>
|
|
Packit |
ae235b |
<title>Commands</title>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<refsect2>
|
|
Packit |
ae235b |
<title>Global commands</title>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<variablelist>
|
|
Packit |
ae235b |
<varlistentry>
|
|
Packit |
ae235b |
<term>
|
|
Packit |
ae235b |
<command>help</command>
|
|
Packit |
ae235b |
<arg choice="opt"><replaceable>COMMAND</replaceable></arg>
|
|
Packit |
ae235b |
</term>
|
|
Packit |
ae235b |
<listitem>
|
|
Packit |
ae235b |
<para>
|
|
Packit |
ae235b |
Displays a short synopsis of the available commands or provides detailed help on a specific
|
|
Packit |
ae235b |
command.
|
|
Packit |
ae235b |
</para>
|
|
Packit |
ae235b |
</listitem>
|
|
Packit |
ae235b |
</varlistentry>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<varlistentry>
|
|
Packit |
ae235b |
<term>
|
|
Packit |
ae235b |
<command>version</command>
|
|
Packit |
ae235b |
</term>
|
|
Packit |
ae235b |
<listitem>
|
|
Packit |
ae235b |
<para>
|
|
Packit |
ae235b |
Prints the GLib version whence <command>gapplication</command> came.
|
|
Packit |
ae235b |
</para>
|
|
Packit |
ae235b |
</listitem>
|
|
Packit |
ae235b |
</varlistentry>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<varlistentry>
|
|
Packit |
ae235b |
<term>
|
|
Packit |
ae235b |
<command>list-apps</command>
|
|
Packit |
ae235b |
</term>
|
|
Packit |
ae235b |
<listitem>
|
|
Packit |
ae235b |
<para>
|
|
Packit |
ae235b |
Prints a list of all application IDs that are known to support D-Bus activation. This list is
|
|
Packit |
ae235b |
generated by scanning <filename class='extension'>.desktop</filename> files as per the current
|
|
Packit |
ae235b |
<envar>XDG_DATA_DIRS</envar>.
|
|
Packit |
ae235b |
</para>
|
|
Packit |
ae235b |
</listitem>
|
|
Packit |
ae235b |
</varlistentry>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<varlistentry>
|
|
Packit |
ae235b |
<term>
|
|
Packit |
ae235b |
<command>launch</command>
|
|
Packit |
ae235b |
<arg choice="plain"><replaceable>APPID</replaceable></arg>
|
|
Packit |
ae235b |
<arg choice="opt" rep="repeat"><replaceable>FILE</replaceable></arg>
|
|
Packit |
ae235b |
</term>
|
|
Packit |
ae235b |
<listitem>
|
|
Packit |
ae235b |
<para>
|
|
Packit |
ae235b |
Launches an application.
|
|
Packit |
ae235b |
</para>
|
|
Packit |
ae235b |
<para>
|
|
Packit |
ae235b |
The first parameter is the application ID in the familiar "reverse DNS" style (eg:
|
|
Packit |
ae235b |
'<literal>org.gnome.app</literal>') without the <filename class='extension'>.desktop</filename>
|
|
Packit |
ae235b |
suffix.
|
|
Packit |
ae235b |
</para>
|
|
Packit |
ae235b |
<para>
|
|
Packit |
ae235b |
Optionally, if additional parameters are given, they are treated as the names of files to open and
|
|
Packit |
ae235b |
may be filenames or URIs. If no files are given then the application is simply activated.
|
|
Packit |
ae235b |
</para>
|
|
Packit |
ae235b |
</listitem>
|
|
Packit |
ae235b |
</varlistentry>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<varlistentry>
|
|
Packit |
ae235b |
<term>
|
|
Packit |
ae235b |
<command>list-actions</command>
|
|
Packit |
ae235b |
<arg choice="plain"><replaceable>APPID</replaceable></arg>
|
|
Packit |
ae235b |
</term>
|
|
Packit |
ae235b |
<listitem>
|
|
Packit |
ae235b |
<para>
|
|
Packit |
ae235b |
List the actions declared in the application's <filename class='extension'>.desktop</filename>
|
|
Packit |
ae235b |
file. The parameter is the application ID, as above.
|
|
Packit |
ae235b |
</para>
|
|
Packit |
ae235b |
</listitem>
|
|
Packit |
ae235b |
</varlistentry>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<varlistentry>
|
|
Packit |
ae235b |
<term>
|
|
Packit |
ae235b |
<command>action</command>
|
|
Packit |
ae235b |
<arg choice="plain"><replaceable>APPID</replaceable></arg>
|
|
Packit |
ae235b |
<arg choice="plain"><replaceable>ACTION</replaceable></arg>
|
|
Packit |
ae235b |
<arg choice="opt"><replaceable>PARAMETER</replaceable></arg>
|
|
Packit |
ae235b |
</term>
|
|
Packit |
ae235b |
<listitem>
|
|
Packit |
ae235b |
<para>
|
|
Packit |
ae235b |
Invokes the named action (in the same way as would occur when activating an action specified in
|
|
Packit |
ae235b |
the <filename class='extension'>.desktop</filename> file).
|
|
Packit |
ae235b |
</para>
|
|
Packit |
ae235b |
<para>
|
|
Packit |
ae235b |
The application ID (as above) is the first parameter. The action name follows.
|
|
Packit |
ae235b |
</para>
|
|
Packit |
ae235b |
<para>
|
|
Packit |
ae235b |
Optionally, following the action name can be one parameter, in GVariant format, given as a single
|
|
Packit |
ae235b |
argument. Make sure to use sufficient quoting.
|
|
Packit |
ae235b |
</para>
|
|
Packit |
ae235b |
</listitem>
|
|
Packit |
ae235b |
</varlistentry>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
</variablelist>
|
|
Packit |
ae235b |
</refsect2>
|
|
Packit |
ae235b |
</refsect1>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<refsect1>
|
|
Packit |
ae235b |
<title>Examples</title>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<refsect2>
|
|
Packit |
ae235b |
<title>From the commandline</title>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<para>
|
|
Packit |
ae235b |
Launching an application:
|
|
Packit |
ae235b |
</para>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<programlisting>
|
|
Packit |
ae235b |
gapplication launch org.example.fooview
|
|
Packit |
ae235b |
</programlisting>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<para>
|
|
Packit |
ae235b |
Opening a file with an application:
|
|
Packit |
ae235b |
</para>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<programlisting>
|
|
Packit |
ae235b |
gapplication launch org.example.fooview ~/file.foo
|
|
Packit |
ae235b |
</programlisting>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<para>
|
|
Packit |
ae235b |
Opening many files with an application:
|
|
Packit |
ae235b |
</para>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<programlisting>
|
|
Packit |
ae235b |
gapplication launch org.example.fooview ~/foos/*.foo
|
|
Packit |
ae235b |
</programlisting>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<para>
|
|
Packit |
ae235b |
Invoking an action on an application:
|
|
Packit |
ae235b |
</para>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<programlisting>
|
|
Packit |
ae235b |
gapplication action org.example.fooview create
|
|
Packit |
ae235b |
</programlisting>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<para>
|
|
Packit |
ae235b |
Invoking an action on an application, with an action:
|
|
Packit |
ae235b |
</para>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<programlisting>
|
|
Packit |
ae235b |
gapplication action org.example.fooview show-item '"item_id_828739"'
|
|
Packit |
ae235b |
</programlisting>
|
|
Packit |
ae235b |
</refsect2>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<refsect2>
|
|
Packit |
ae235b |
<title>
|
|
Packit |
ae235b |
From the <varname>Exec</varname> lines of a <filename class='extension'>.desktop</filename> file
|
|
Packit |
ae235b |
</title>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<para>
|
|
Packit |
ae235b |
The commandline interface of <command>gapplication</command> was designed so that it could be used
|
|
Packit |
ae235b |
directly from the <varname>Exec</varname> line of a <filename class='extension'>.desktop</filename>
|
|
Packit |
ae235b |
file.
|
|
Packit |
ae235b |
</para>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<para>
|
|
Packit |
ae235b |
You might want to do this to allow for backwards compatibility with implementations of the specification
|
|
Packit |
ae235b |
that do not understand how to do D-Bus activation, without having to install a separate utility program.
|
|
Packit |
ae235b |
</para>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<para>
|
|
Packit |
ae235b |
Consider the following example:
|
|
Packit |
ae235b |
</para>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<programlisting>
|
|
Packit |
ae235b |
[Desktop Entry]
|
|
Packit |
ae235b |
Version=1.1
|
|
Packit |
ae235b |
Type=Application
|
|
Packit |
ae235b |
Name=Foo Viewer
|
|
Packit |
ae235b |
DBusActivatable=true
|
|
Packit |
ae235b |
MimeType=image/x-foo;
|
|
Packit |
ae235b |
Exec=gapplication launch org.example.fooview %F
|
|
Packit |
ae235b |
Actions=gallery;create;
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
[Desktop Action gallery]
|
|
Packit |
ae235b |
Name=Browse Gallery
|
|
Packit |
ae235b |
Exec=gapplication action org.example.fooview gallery
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
[Desktop Action create]
|
|
Packit |
ae235b |
Name=Create a new Foo!
|
|
Packit |
ae235b |
Exec=gapplication action org.example.fooview create
|
|
Packit |
ae235b |
</programlisting>
|
|
Packit |
ae235b |
</refsect2>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<refsect2>
|
|
Packit |
ae235b |
<title>From a script</title>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<para>
|
|
Packit |
ae235b |
If installing an application that supports D-Bus activation you may still want to put a file in
|
|
Packit |
ae235b |
<filename class='directory'>/usr/bin</filename> so that your program can be started from a terminal.
|
|
Packit |
ae235b |
</para>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<para>
|
|
Packit |
ae235b |
It is possible for this file to be a shell script. The script can handle arguments such as --help and
|
|
Packit |
ae235b |
--version directly. It can also parse other command line arguments and convert them to uses of
|
|
Packit |
ae235b |
<command>gapplication</command> to activate the application, open files, or invoke actions.
|
|
Packit |
ae235b |
</para>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<para>
|
|
Packit |
ae235b |
Here is a simplified example, as may be installed in <filename>/usr/bin/fooview</filename>:
|
|
Packit |
ae235b |
</para>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<programlisting>
|
|
Packit |
ae235b |
#!/bin/sh
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
case "$1" in
|
|
Packit |
ae235b |
--help)
|
|
Packit |
ae235b |
echo "see 'man fooview' for more information"
|
|
Packit |
ae235b |
;;
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
--version)
|
|
Packit |
ae235b |
echo "fooview 1.2"
|
|
Packit |
ae235b |
;;
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
--gallery)
|
|
Packit |
ae235b |
gapplication action org.example.fooview gallery
|
|
Packit |
ae235b |
;;
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
--create)
|
|
Packit |
ae235b |
gapplication action org.example.fooview create
|
|
Packit |
ae235b |
;;
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
-*)
|
|
Packit |
ae235b |
echo "unrecognised commandline argument"
|
|
Packit |
ae235b |
exit 1
|
|
Packit |
ae235b |
;;
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
*)
|
|
Packit |
ae235b |
gapplication launch org.example.fooview "$@"
|
|
Packit |
ae235b |
;;
|
|
Packit |
ae235b |
esac
|
|
Packit |
ae235b |
</programlisting>
|
|
Packit |
ae235b |
</refsect2>
|
|
Packit |
ae235b |
</refsect1>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<refsect1>
|
|
Packit |
ae235b |
<title>See also</title>
|
|
Packit |
ae235b |
<para>
|
|
Packit |
ae235b |
<ulink url='http://standards.freedesktop.org/desktop-entry-spec/latest/'>Desktop Entry Specification</ulink>,
|
|
Packit |
ae235b |
<citerefentry>
|
|
Packit |
ae235b |
<refentrytitle>gdbus</refentrytitle>
|
|
Packit |
ae235b |
<manvolnum>1</manvolnum>
|
|
Packit |
ae235b |
</citerefentry>,
|
|
Packit |
ae235b |
<citerefentry>
|
|
Packit |
ae235b |
<refentrytitle>xdg-open</refentrytitle>
|
|
Packit |
ae235b |
<manvolnum>1</manvolnum>
|
|
Packit |
ae235b |
</citerefentry>,
|
|
Packit |
ae235b |
<citerefentry>
|
|
Packit |
ae235b |
<refentrytitle>desktop-file-validate</refentrytitle>
|
|
Packit |
ae235b |
<manvolnum>1</manvolnum>
|
|
Packit |
ae235b |
</citerefentry>
|
|
Packit |
ae235b |
</para>
|
|
Packit |
ae235b |
</refsect1>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
</refentry>
|