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