docs/reference/gio/gapplication.xml

   1 <refentry id="gapplication-tool" lang="en">
   2   <refentryinfo>
   3     <title>gapplication</title>
   4     <productname>GIO</productname>
   5     <authorgroup>
   6       <author>
   7         <contrib>Developer</contrib>
   8         <firstname>Ryan</firstname>
   9         <surname>Lortie</surname>
  10       </author>
  11     </authorgroup>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>gapplication</refentrytitle>
  16     <manvolnum>1</manvolnum>
  17     <refmiscinfo class="manual">User Commands</refmiscinfo>
  18   </refmeta>
  19
  20   <refnamediv>
  21     <refname>gapplication</refname>
  22     <refpurpose>D-Bus application launcher</refpurpose>
  23   </refnamediv>
  24
  25   <refsynopsisdiv>
  26     <cmdsynopsis>
  27       <command>gapplication</command>
  28       <arg choice="plain">help</arg>
  29       <arg choice="opt"><replaceable>COMMAND</replaceable></arg>
  30     </cmdsynopsis>
  31     <cmdsynopsis>
  32       <command>gapplication</command>
  33       <arg choice="plain">version</arg>
  34     </cmdsynopsis>
  35     <cmdsynopsis>
  36       <command>gapplication</command>
  37       <arg choice="plain">list-apps</arg>
  38     </cmdsynopsis>
  39     <cmdsynopsis>
  40       <command>gapplication</command>
  41       <arg choice="plain">launch</arg>
  42       <arg choice="plain"><replaceable>APPID</replaceable></arg>
  43     </cmdsynopsis>
  44     <cmdsynopsis>
  45       <command>gapplication</command>
  46       <arg choice="plain">launch</arg>
  47       <arg choice="plain"><replaceable>APPID</replaceable></arg>
  48       <arg choice="opt" rep="repeat"><replaceable>FILE</replaceable></arg>
  49     </cmdsynopsis>
  50     <cmdsynopsis>
  51       <command>gapplication</command>
  52       <arg choice="plain">list-actions</arg>
  53       <arg choice="plain"><replaceable>APPID</replaceable></arg>
  54     </cmdsynopsis>
  55     <cmdsynopsis>
  56       <command>gapplication</command>
  57       <arg choice="plain">action</arg>
  58       <arg choice="plain"><replaceable>APPID</replaceable></arg>
  59       <arg choice="plain"><replaceable>ACTION</replaceable></arg>
  60       <arg choice="opt"><replaceable>PARAMETER</replaceable></arg>
  61     </cmdsynopsis>
  62   </refsynopsisdiv>
  63
  64   <refsect1>
  65     <title>Description</title>
  66
  67     <para>
  68       <command>gapplication</command> is a commandline implementation of the client-side of the
  69       <interfacename>org.freedesktop.Application</interfacename> interface as specified by the freedesktop.org
  70       Desktop Entry Specification.
  71     </para>
  72
  73     <para>
  74       <command>gapplication</command> can be used to start applications that have
  75       <varname>DBusActivatable</varname> set to <literal>true</literal> in their <filename>.desktop</filename>
  76       files and can be used to send messages to already-running instances of other applications.
  77     </para>
  78
  79     <para>
  80       It is possible for applications to refer to <command>gapplication</command> in the <varname>Exec</varname>
  81       line of their <filename class='extension'>.desktop</filename> file to maintain backwards compatibility
  82       with implementations that do not directly support <varname>DBusActivatable</varname>.
  83     </para>
  84
  85     <para>
  86       <command>gapplication</command> ships as part of <application>GLib</application>.
  87     </para>
  88   </refsect1>
  89
  90   <refsect1>
  91     <title>Commands</title>
  92
  93     <refsect2>
  94       <title>Global commands</title>
  95
  96       <variablelist>
  97         <varlistentry>
  98           <term>
  99             <command>help</command>
 100             <arg choice="opt"><replaceable>COMMAND</replaceable></arg>
 101           </term>
 102           <listitem>
 103             <para>
 104               Displays a short synopsis of the available commands or provides detailed help on a specific
 105               command.
 106             </para>
 107           </listitem>
 108         </varlistentry>
 109
 110         <varlistentry>
 111           <term>
 112             <command>version</command>
 113           </term>
 114           <listitem>
 115             <para>
 116               Prints the GLib version whence <command>gapplication</command> came.
 117             </para>
 118           </listitem>
 119         </varlistentry>
 120
 121         <varlistentry>
 122           <term>
 123             <command>list-apps</command>
 124           </term>
 125           <listitem>
 126             <para>
 127               Prints a list of all application IDs that are known to support D-Bus activation.  This list is
 128               generated by scanning <filename class='extension'>.desktop</filename> files as per the current
 129               <envar>XDG_DATA_DIRS</envar>.
 130             </para>
 131           </listitem>
 132         </varlistentry>
 133
 134         <varlistentry>
 135           <term>
 136             <command>launch</command>
 137             <arg choice="plain"><replaceable>APPID</replaceable></arg>
 138             <arg choice="opt" rep="repeat"><replaceable>FILE</replaceable></arg>
 139           </term>
 140           <listitem>
 141             <para>
 142               Launches an application.
 143             </para>
 144             <para>
 145               The first parameter is the application ID in the familiar "reverse DNS" style (eg:
 146               '<literal>org.gnome.app</literal>') without the <filename class='extension'>.desktop</filename>
 147               suffix.
 148             </para>
 149             <para>
 150               Optionally, if additional parameters are given, they are treated as the names of files to open and
 151               may be filenames or URIs.  If no files are given then the application is simply activated.
 152             </para>
 153           </listitem>
 154         </varlistentry>
 155
 156         <varlistentry>
 157           <term>
 158             <command>list-actions</command>
 159             <arg choice="plain"><replaceable>APPID</replaceable></arg>
 160           </term>
 161           <listitem>
 162             <para>
 163               List the actions declared in the application's <filename class='extension'>.desktop</filename>
 164               file.  The parameter is the application ID, as above.
 165             </para>
 166           </listitem>
 167         </varlistentry>
 168
 169         <varlistentry>
 170           <term>
 171             <command>action</command>
 172             <arg choice="plain"><replaceable>APPID</replaceable></arg>
 173             <arg choice="plain"><replaceable>ACTION</replaceable></arg>
 174             <arg choice="opt"><replaceable>PARAMETER</replaceable></arg>
 175           </term>
 176           <listitem>
 177             <para>
 178               Invokes the named action (in the same way as would occur when activating an action specified in
 179               the <filename class='extension'>.desktop</filename> file).
 180             </para>
 181             <para>
 182               The application ID (as above) is the first parameter.  The action name follows.
 183             </para>
 184             <para>
 185               Optionally, following the action name can be one parameter, in GVariant format, given as a single
 186               argument.  Make sure to use sufficient quoting.
 187             </para>
 188           </listitem>
 189         </varlistentry>
 190
 191       </variablelist>
 192     </refsect2>
 193   </refsect1>
 194
 195   <refsect1>
 196     <title>Examples</title>
 197
 198     <refsect2>
 199       <title>From the commandline</title>
 200
 201       <para>
 202         Launching an application:
 203       </para>
 204
 205       <programlisting>
 206         gapplication launch org.example.fooview
 207       </programlisting>
 208
 209       <para>
 210         Opening a file with an application:
 211       </para>
 212
 213       <programlisting>
 214         gapplication launch org.example.fooview ~/file.foo
 215       </programlisting>
 216
 217       <para>
 218         Opening many files with an application:
 219       </para>
 220
 221       <programlisting>
 222         gapplication launch org.example.fooview ~/foos/*.foo
 223       </programlisting>
 224
 225       <para>
 226         Invoking an action on an application:
 227       </para>
 228
 229       <programlisting>
 230         gapplication action org.example.fooview create
 231       </programlisting>
 232
 233       <para>
 234         Invoking an action on an application, with an action:
 235       </para>
 236
 237       <programlisting>
 238         gapplication action org.example.fooview show-item '"item_id_828739"'
 239       </programlisting>
 240     </refsect2>
 241
 242     <refsect2>
 243       <title>
 244         From the <varname>Exec</varname> lines of a <filename class='extension'>.desktop</filename> file
 245       </title>
 246
 247       <para>
 248         The commandline interface of <command>gapplication</command> was designed so that it could be used
 249         directly from the <varname>Exec</varname> line of a <filename class='extension'>.desktop</filename>
 250         file.
 251       </para>
 252
 253       <para>
 254         You might want to do this to allow for backwards compatibility with implementations of the specification
 255         that do not understand how to do D-Bus activation, without having to install a separate utility program.
 256       </para>
 257
 258       <para>
 259         Consider the following example:
 260       </para>
 261
 262       <programlisting>
 263         [Desktop Entry]
 264         Version=1.1
 265         Type=Application
 266         Name=Foo Viewer
 267         DBusActivatable=true
 268         MimeType=image/x-foo;
 269         Exec=gapplication launch org.example.fooview %F
 270         Actions=gallery;create;
 271
 272         [Desktop Action gallery]
 273         Name=Browse Gallery
 274         Exec=gapplication action org.example.fooview gallery
 275
 276         [Desktop Action create]
 277         Name=Create a new Foo!
 278         Exec=gapplication action org.example.fooview create
 279       </programlisting>
 280     </refsect2>
 281
 282     <refsect2>
 283       <title>From a script</title>
 284
 285       <para>
 286         If installing an application that supports D-Bus activation you may still want to put a file in
 287         <filename class='directory'>/usr/bin</filename> so that your program can be started from a terminal.
 288       </para>
 289
 290       <para>
 291         It is possible for this file to be a shell script.  The script can handle arguments such as --help and
 292         --version directly.  It can also parse other command line arguments and convert them to uses of
 293         <command>gapplication</command> to activate the application, open files, or invoke actions.
 294       </para>
 295
 296       <para>
 297         Here is a simplified example, as may be installed in <filename>/usr/bin/fooview</filename>:
 298       </para>
 299
 300       <programlisting>
 301         #!/bin/sh
 302
 303         case "$1" in
 304           --help)
 305             echo "see 'man fooview' for more information"
 306             ;;
 307
 308           --version)
 309             echo "fooview 1.2"
 310             ;;
 311
 312           --gallery)
 313             gapplication action org.example.fooview gallery
 314             ;;
 315
 316           --create)
 317             gapplication action org.example.fooview create
 318             ;;
 319
 320           -*)
 321             echo "unrecognised commandline argument"
 322             exit 1
 323             ;;
 324
 325           *)
 326             gapplication launch org.example.fooview "$@"
 327             ;;
 328         esac
 329       </programlisting>
 330     </refsect2>
 331   </refsect1>
 332
 333   <refsect1>
 334     <title>See also</title>
 335     <para>
 336       <ulink url='http://standards.freedesktop.org/desktop-entry-spec/latest/'>Desktop Entry Specification</ulink>,
 337       <citerefentry>
 338         <refentrytitle>gdbus</refentrytitle>
 339         <manvolnum>1</manvolnum>
 340       </citerefentry>,
 341       <citerefentry>
 342         <refentrytitle>xdg-open</refentrytitle>
 343         <manvolnum>1</manvolnum>
 344       </citerefentry>,
 345       <citerefentry>
 346         <refentrytitle>desktop-file-validate</refentrytitle>
 347         <manvolnum>1</manvolnum>
 348       </citerefentry>
 349     </para>
 350   </refsect1>
 351
 352 </refentry>