mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-09-06 07:58:44 +02:00
New gapplication(1) tool
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
This commit is contained in:
Ryan Lortie
352
docs/reference/gio/gapplication.xml
Normal file
352
docs/reference/gio/gapplication.xml
Normal file
@@ -0,0 +1,352 @@
|
||||
<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>
|
||||
Reference in New Issue
Block a user