docs/reference/gio/html/gapplication-tool.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>gapplication: GIO Reference Manual</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   7 <link rel="home" href="index.html" title="GIO Reference Manual">
   8 <link rel="up" href="tools.html" title="GIO Tools">
   9 <link rel="prev" href="gresource-tool.html" title="gresource">
  10 <link rel="next" href="gio.html" title="gio">
  11 <meta name="generator" content="GTK-Doc V1.25.1 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
  16 <td width="100%" align="left" class="shortcuts"></td>
  17 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
  18 <td><a accesskey="u" href="tools.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
  19 <td><a accesskey="p" href="gresource-tool.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
  20 <td><a accesskey="n" href="gio.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
  21 </tr></table>
  22 <div lang="en" class="refentry">
  23 <a name="gapplication-tool"></a><div class="titlepage"></div>
  24 <div class="refnamediv"><table width="100%"><tr>
  25 <td valign="top">
  26 <h2><span class="refentrytitle">gapplication</span></h2>
  27 <p>gapplication — D-Bus application launcher</p>
  28 </td>
  29 <td class="gallery_image" valign="top" align="right"></td>
  30 </tr></table></div>
  31 <div class="refsynopsisdiv">
  32 <h2>Synopsis</h2>
  33 <div class="cmdsynopsis"><p><code class="command">gapplication</code>   help  [<em class="replaceable"><code>COMMAND</code></em>]</p></div>
  34 <div class="cmdsynopsis"><p><code class="command">gapplication</code>   version </p></div>
  35 <div class="cmdsynopsis"><p><code class="command">gapplication</code>   list-apps </p></div>
  36 <div class="cmdsynopsis"><p><code class="command">gapplication</code>   launch   <em class="replaceable"><code>APPID</code></em> </p></div>
  37 <div class="cmdsynopsis"><p><code class="command">gapplication</code>   launch   <em class="replaceable"><code>APPID</code></em>  [<em class="replaceable"><code>FILE</code></em>...]</p></div>
  38 <div class="cmdsynopsis"><p><code class="command">gapplication</code>   list-actions   <em class="replaceable"><code>APPID</code></em> </p></div>
  39 <div class="cmdsynopsis"><p><code class="command">gapplication</code>   action   <em class="replaceable"><code>APPID</code></em>   <em class="replaceable"><code>ACTION</code></em>  [<em class="replaceable"><code>PARAMETER</code></em>]</p></div>
  40 </div>
  41 <div class="refsect1">
  42 <a name="id-1.4.26.9.5"></a><h2>Description</h2>
  43 <p>
  44       <span class="command"><strong>gapplication</strong></span> is a commandline implementation of the client-side of the
  45       <code class="interfacename">org.freedesktop.Application</code> interface as specified by the freedesktop.org
  46       Desktop Entry Specification.
  47     </p>
  48 <p>
  49       <span class="command"><strong>gapplication</strong></span> can be used to start applications that have
  50       <code class="varname">DBusActivatable</code> set to <code class="literal">true</code> in their <code class="filename">.desktop</code>
  51       files and can be used to send messages to already-running instances of other applications.
  52     </p>
  53 <p>
  54       It is possible for applications to refer to <span class="command"><strong>gapplication</strong></span> in the <code class="varname">Exec</code>
  55       line of their <code class="filename">.desktop</code> file to maintain backwards compatibility
  56       with implementations that do not directly support <code class="varname">DBusActivatable</code>.
  57     </p>
  58 <p>
  59       <span class="command"><strong>gapplication</strong></span> ships as part of <span class="application">GLib</span>.
  60     </p>
  61 </div>
  62 <div class="refsect1">
  63 <a name="id-1.4.26.9.6"></a><h2>Commands</h2>
  64 <div class="refsect2">
  65 <a name="id-1.4.26.9.6.2"></a><h3>Global commands</h3>
  66 <div class="variablelist"><table border="0" class="variablelist">
  67 <colgroup>
  68 <col align="left" valign="top">
  69 <col>
  70 </colgroup>
  71 <tbody>
  72 <tr>
  73 <td><p><span class="term">
  74             <span class="command"><strong>help</strong></span>
  75              [<em class="replaceable"><code>COMMAND</code></em>]
  76           </span></p></td>
  77 <td><p>
  78               Displays a short synopsis of the available commands or provides detailed help on a specific
  79               command.
  80             </p></td>
  81 </tr>
  82 <tr>
  83 <td><p><span class="term">
  84             <span class="command"><strong>version</strong></span>
  85           </span></p></td>
  86 <td><p>
  87               Prints the GLib version whence <span class="command"><strong>gapplication</strong></span> came.
  88             </p></td>
  89 </tr>
  90 <tr>
  91 <td><p><span class="term">
  92             <span class="command"><strong>list-apps</strong></span>
  93           </span></p></td>
  94 <td><p>
  95               Prints a list of all application IDs that are known to support D-Bus activation.  This list is
  96               generated by scanning <code class="filename">.desktop</code> files as per the current
  97               <code class="envar">XDG_DATA_DIRS</code>.
  98             </p></td>
  99 </tr>
 100 <tr>
 101 <td><p><span class="term">
 102             <span class="command"><strong>launch</strong></span>
 103               <em class="replaceable"><code>APPID</code></em>
 104              [<em class="replaceable"><code>FILE</code></em>...]
 105           </span></p></td>
 106 <td>
 107 <p>
 108               Launches an application.
 109             </p>
 110 <p>
 111               The first parameter is the application ID in the familiar "reverse DNS" style (eg:
 112               '<code class="literal">org.gnome.app</code>') without the <code class="filename">.desktop</code>
 113               suffix.
 114             </p>
 115 <p>
 116               Optionally, if additional parameters are given, they are treated as the names of files to open and
 117               may be filenames or URIs.  If no files are given then the application is simply activated.
 118             </p>
 119 </td>
 120 </tr>
 121 <tr>
 122 <td><p><span class="term">
 123             <span class="command"><strong>list-actions</strong></span>
 124               <em class="replaceable"><code>APPID</code></em>
 125           </span></p></td>
 126 <td><p>
 127               List the actions declared in the application's <code class="filename">.desktop</code>
 128               file.  The parameter is the application ID, as above.
 129             </p></td>
 130 </tr>
 131 <tr>
 132 <td><p><span class="term">
 133             <span class="command"><strong>action</strong></span>
 134               <em class="replaceable"><code>APPID</code></em>
 135               <em class="replaceable"><code>ACTION</code></em>
 136              [<em class="replaceable"><code>PARAMETER</code></em>]
 137           </span></p></td>
 138 <td>
 139 <p>
 140               Invokes the named action (in the same way as would occur when activating an action specified in
 141               the <code class="filename">.desktop</code> file).
 142             </p>
 143 <p>
 144               The application ID (as above) is the first parameter.  The action name follows.
 145             </p>
 146 <p>
 147               Optionally, following the action name can be one parameter, in GVariant format, given as a single
 148               argument.  Make sure to use sufficient quoting.
 149             </p>
 150 </td>
 151 </tr>
 152 </tbody>
 153 </table></div>
 154 </div>
 155 </div>
 156 <div class="refsect1">
 157 <a name="id-1.4.26.9.7"></a><h2>Examples</h2>
 158 <div class="refsect2">
 159 <a name="id-1.4.26.9.7.2"></a><h3>From the commandline</h3>
 160 <p>
 161         Launching an application:
 162       </p>
 163 <pre class="programlisting">
 164         gapplication launch org.example.fooview
 165       </pre>
 166 <p>
 167         Opening a file with an application:
 168       </p>
 169 <pre class="programlisting">
 170         gapplication launch org.example.fooview ~/file.foo
 171       </pre>
 172 <p>
 173         Opening many files with an application:
 174       </p>
 175 <pre class="programlisting">
 176         gapplication launch org.example.fooview ~/foos/*.foo
 177       </pre>
 178 <p>
 179         Invoking an action on an application:
 180       </p>
 181 <pre class="programlisting">
 182         gapplication action org.example.fooview create
 183       </pre>
 184 <p>
 185         Invoking an action on an application, with an action:
 186       </p>
 187 <pre class="programlisting">
 188         gapplication action org.example.fooview show-item '"item_id_828739"'
 189       </pre>
 190 </div>
 191 <hr>
 192 <div class="refsect2">
 193 <a name="id-1.4.26.9.7.3"></a><h3>
 194         From the <code class="varname">Exec</code> lines of a <code class="filename">.desktop</code> file
 195       </h3>
 196 <p>
 197         The commandline interface of <span class="command"><strong>gapplication</strong></span> was designed so that it could be used
 198         directly from the <code class="varname">Exec</code> line of a <code class="filename">.desktop</code>
 199         file.
 200       </p>
 201 <p>
 202         You might want to do this to allow for backwards compatibility with implementations of the specification
 203         that do not understand how to do D-Bus activation, without having to install a separate utility program.
 204       </p>
 205 <p>
 206         Consider the following example:
 207       </p>
 208 <pre class="programlisting">
 209         [Desktop Entry]
 210         Version=1.1
 211         Type=Application
 212         Name=Foo Viewer
 213         DBusActivatable=true
 214         MimeType=image/x-foo;
 215         Exec=gapplication launch org.example.fooview %F
 216         Actions=gallery;create;
 217
 218         [Desktop Action gallery]
 219         Name=Browse Gallery
 220         Exec=gapplication action org.example.fooview gallery
 221
 222         [Desktop Action create]
 223         Name=Create a new Foo!
 224         Exec=gapplication action org.example.fooview create
 225       </pre>
 226 </div>
 227 <hr>
 228 <div class="refsect2">
 229 <a name="id-1.4.26.9.7.4"></a><h3>From a script</h3>
 230 <p>
 231         If installing an application that supports D-Bus activation you may still want to put a file in
 232         <code class="filename">/usr/bin</code> so that your program can be started from a terminal.
 233       </p>
 234 <p>
 235         It is possible for this file to be a shell script.  The script can handle arguments such as --help and
 236         --version directly.  It can also parse other command line arguments and convert them to uses of
 237         <span class="command"><strong>gapplication</strong></span> to activate the application, open files, or invoke actions.
 238       </p>
 239 <p>
 240         Here is a simplified example, as may be installed in <code class="filename">/usr/bin/fooview</code>:
 241       </p>
 242 <pre class="programlisting">
 243         #!/bin/sh
 244
 245         case "$1" in
 246           --help)
 247             echo "see 'man fooview' for more information"
 248             ;;
 249
 250           --version)
 251             echo "fooview 1.2"
 252             ;;
 253
 254           --gallery)
 255             gapplication action org.example.fooview gallery
 256             ;;
 257
 258           --create)
 259             gapplication action org.example.fooview create
 260             ;;
 261
 262           -*)
 263             echo "unrecognised commandline argument"
 264             exit 1
 265             ;;
 266
 267           *)
 268             gapplication launch org.example.fooview "$@"
 269             ;;
 270         esac
 271       </pre>
 272 </div>
 273 </div>
 274 <div class="refsect1">
 275 <a name="id-1.4.26.9.8"></a><h2>See also</h2>
 276 <p>
 277       <a class="ulink" href="http://standards.freedesktop.org/desktop-entry-spec/latest/" target="_top">Desktop Entry Specification</a>,
 278       <span class="citerefentry"><span class="refentrytitle">gdbus</span>(1)</span>,
 279       <span class="citerefentry"><span class="refentrytitle">xdg-open</span>(1)</span>,
 280       <span class="citerefentry"><span class="refentrytitle">desktop-file-validate</span>(1)</span>
 281     </p>
 282 </div>
 283 </div>
 284 <div class="footer">
 285 <hr>Generated by GTK-Doc V1.25.1</div>
 286 </body>
 287 </html>