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