.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "GAPPLICATION"  "" ""
.SH NAME
gapplication \- D-Bus application launcher
.\" This has to be duplicated from above to make it machine-readable by `reuse`:
.\" SPDX-FileCopyrightText: 2013 Allison Karlitskaya
.\" SPDX-License-Identifier: LGPL-2.1-or-later
.
.SH SYNOPSIS
.nf
\fBgapplication\fP help [COMMAND]
\fBgapplication\fP version
\fBgapplication\fP list\-apps
\fBgapplication\fP launch <APP\-ID>
\fBgapplication\fP launch <APP\-ID> [FILE…]
\fBgapplication\fP list\-actions <APP\-ID>
\fBgapplication\fP action <APP\-ID> <ACTION> [PARAMETER]
.fi
.sp
.SH DESCRIPTION
.sp
\fBgapplication\fP is a commandline implementation of the client\-side of the
\fBorg.freedesktop.Application\fP interface as specified by the freedesktop.org
Desktop Entry Specification.
.sp
\fBgapplication\fP can be used to start applications that have \fBDBusActivatable\fP
set to \fBtrue\fP in their \fB\&.desktop\fP files and can be used to send messages to
already\-running instances of other applications.
.sp
It is possible for applications to refer to \fBgapplication\fP in the \fBExec\fP
line of their \fB\&.desktop\fP file to maintain backwards compatibility with
implementations that do not directly support \fBDBusActivatable\fP\&.
.sp
\fBgapplication\fP ships as part of GLib.
.SH COMMANDS
.sp
\fBhelp [COMMAND]\fP
.INDENT 0.0
.INDENT 3.5
Displays a short synopsis of the available commands or provides detailed help
on a specific command.
.UNINDENT
.UNINDENT
.sp
\fBversion\fP
.INDENT 0.0
.INDENT 3.5
Prints the GLib version whence \fBgapplication\fP came.
.UNINDENT
.UNINDENT
.sp
\fBlist\-apps\fP
.INDENT 0.0
.INDENT 3.5
Prints a list of all application IDs that are known to support D\-Bus
activation.  This list is generated by scanning \fB\&.desktop\fP files as per the
current \fBXDG_DATA_DIRS\fP\&.
.UNINDENT
.UNINDENT
.sp
\fBlaunch <APP\-ID> [FILE…]\fP
.INDENT 0.0
.INDENT 3.5
Launches an application.
.sp
The first parameter is the application ID in the familiar ‘reverse DNS’ style
(e.g. \fBorg.gnome.app\fP) without the \fB\&.desktop\fP suffix.
.sp
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.
.UNINDENT
.UNINDENT
.sp
\fBlist\-actions <APP\-ID>\fP
.INDENT 0.0
.INDENT 3.5
List the actions declared in the application’s \fB\&.desktop\fP file.  The
parameter is the application ID, as above.
.UNINDENT
.UNINDENT
.sp
\fBaction <APP\-ID> <ACTION> [PARAMETER]\fP
.INDENT 0.0
.INDENT 3.5
Invokes the named action (in the same way as would occur when activating an
action specified in the \fB\&.desktop\fP file).
.sp
The application ID (as above) is the first parameter.  The action name
follows.
.sp
Optionally, following the action name can be one parameter, in GVariant
format, given as a single argument.  Make sure to use sufficient quoting.
.UNINDENT
.UNINDENT
.SH EXAMPLES
.SS From the commandline
.sp
Launching an application:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
gapplication launch org.example.fooview
.EE
.UNINDENT
.UNINDENT
.sp
Opening a file with an application:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
gapplication launch org.example.fooview ~/file.foo
.EE
.UNINDENT
.UNINDENT
.sp
Opening many files with an application:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
gapplication launch org.example.fooview ~/foos/*.foo
.EE
.UNINDENT
.UNINDENT
.sp
Invoking an action on an application:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
gapplication action org.example.fooview create
.EE
.UNINDENT
.UNINDENT
.sp
Invoking an action on an application, with an action:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
gapplication action org.example.fooview show\-item \(aq\(dqitem_id_828739\(dq\(aq
.EE
.UNINDENT
.UNINDENT
.SS From the \fBExec\fP lines of a \fB\&.desktop\fP file
.sp
The commandline interface of \fBgapplication\fP was designed so that it could be
used directly from the \fBExec\fP line of a \fB\&.desktop\fP file.
.sp
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.
.sp
Consider the following example:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
[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
.EE
.UNINDENT
.UNINDENT
.SS From a script
.sp
If installing an application that supports D\-Bus activation you may still want
to put a file in \fB/usr/bin\fP so that your program can be started from a
terminal.
.sp
It is possible for this file to be a shell script.  The script can handle
arguments such as \fB\-\-help\fP and \fB\-\-version\fP directly.  It can also parse
other command line arguments and convert them to uses of \fBgapplication\fP to
activate the application, open files, or invoke actions.
.sp
Here is a simplified example, as may be installed in \fB/usr/bin/fooview\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
#!/bin/sh

case \(dq$1\(dq in
  \-\-help)
    echo \(dqsee ‘man fooview’ for more information\(dq
    ;;

  \-\-version)
    echo \(dqfooview 1.2\(dq
    ;;

  \-\-gallery)
    gapplication action org.example.fooview gallery
    ;;

  \-\-create)
    gapplication action org.example.fooview create
    ;;

  \-*)
    echo \(dqunrecognised commandline argument\(dq
    exit 1
    ;;

  *)
    gapplication launch org.example.fooview \(dq$@\(dq
    ;;
esac
.EE
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
\fI\%Desktop Entry Specification\fP,
\fI\%gdbus(1)\fP,
\fI\%xdg\-open(1)\fP,
\fI\%desktop\-file\-validate(1)\fP
.\" Generated by docutils manpage writer.
.