nexmon – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 office 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>