| <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> |