glib/docs/reference/gio/gapplication.1

'\" t
.\"     Title: gapplication
.\"    Author: Ryan Lortie
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 07/20/2016
.\"    Manual: User Commands
.\"    Source: GIO
.\"  Language: English
.\"
.TH "GAPPLICATION" "1" "" "GIO" "User Commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
gapplication \- D\-Bus application launcher
.SH "SYNOPSIS"
.HP \w'\fBgapplication\fR\ 'u
\fBgapplication\fR help [\fICOMMAND\fR]
.HP \w'\fBgapplication\fR\ 'u
\fBgapplication\fR version
.HP \w'\fBgapplication\fR\ 'u
\fBgapplication\fR list\-apps
.HP \w'\fBgapplication\fR\ 'u
\fBgapplication\fR launch \fIAPPID\fR
.HP \w'\fBgapplication\fR\ 'u
\fBgapplication\fR launch \fIAPPID\fR [\fIFILE\fR...]
.HP \w'\fBgapplication\fR\ 'u
\fBgapplication\fR list\-actions \fIAPPID\fR
.HP \w'\fBgapplication\fR\ 'u
\fBgapplication\fR action \fIAPPID\fR \fIACTION\fR [\fIPARAMETER\fR]
.SH "DESCRIPTION"
.PP
\fBgapplication\fR
is a commandline implementation of the client\-side of the
org\&.freedesktop\&.Application
interface as specified by the freedesktop\&.org Desktop Entry Specification\&.
.PP
\fBgapplication\fR
can be used to start applications that have
\fIDBusActivatable\fR
set to
true
in their
\&.desktop
files and can be used to send messages to already\-running instances of other applications\&.
.PP
It is possible for applications to refer to
\fBgapplication\fR
in the
\fIExec\fR
line of their
\&.desktop
file to maintain backwards compatibility with implementations that do not directly support
\fIDBusActivatable\fR\&.
.PP
\fBgapplication\fR
ships as part of
GLib\&.
.SH "COMMANDS"
.SS "Global commands"
.PP
\fBhelp\fR [\fICOMMAND\fR]
.RS 4
Displays a short synopsis of the available commands or provides detailed help on a specific command\&.
.RE
.PP
\fBversion\fR
.RS 4
Prints the GLib version whence
\fBgapplication\fR
came\&.
.RE
.PP
\fBlist\-apps\fR
.RS 4
Prints a list of all application IDs that are known to support D\-Bus activation\&. This list is generated by scanning
\&.desktop
files as per the current
\fBXDG_DATA_DIRS\fR\&.
.RE
.PP
\fBlaunch\fR \fIAPPID\fR [\fIFILE\fR...]
.RS 4
Launches an application\&.
.sp
The first parameter is the application ID in the familiar "reverse DNS" style (eg: \*(Aqorg\&.gnome\&.app\*(Aq) without the
\&.desktop
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\&.
.RE
.PP
\fBlist\-actions\fR \fIAPPID\fR
.RS 4
List the actions declared in the application\*(Aqs
\&.desktop
file\&. The parameter is the application ID, as above\&.
.RE
.PP
\fBaction\fR \fIAPPID\fR \fIACTION\fR [\fIPARAMETER\fR]
.RS 4
Invokes the named action (in the same way as would occur when activating an action specified in the
\&.desktop
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\&.
.RE
.SH "EXAMPLES"
.SS "From the commandline"
.PP
Launching an application:
.sp
.if n \{\
.RS 4
.\}
.nf
        gapplication launch org\&.example\&.fooview
      
.fi
.if n \{\
.RE
.\}
.PP
Opening a file with an application:
.sp
.if n \{\
.RS 4
.\}
.nf
        gapplication launch org\&.example\&.fooview ~/file\&.foo
      
.fi
.if n \{\
.RE
.\}
.PP
Opening many files with an application:
.sp
.if n \{\
.RS 4
.\}
.nf
        gapplication launch org\&.example\&.fooview ~/foos/*\&.foo
      
.fi
.if n \{\
.RE
.\}
.PP
Invoking an action on an application:
.sp
.if n \{\
.RS 4
.\}
.nf
        gapplication action org\&.example\&.fooview create
      
.fi
.if n \{\
.RE
.\}
.PP
Invoking an action on an application, with an action:
.sp
.if n \{\
.RS 4
.\}
.nf
        gapplication action org\&.example\&.fooview show\-item \*(Aq"item_id_828739"\*(Aq
      
.fi
.if n \{\
.RE
.\}
.SS "From the \fIExec\fR lines of a \&.desktop file"
.PP
The commandline interface of
\fBgapplication\fR
was designed so that it could be used directly from the
\fIExec\fR
line of a
\&.desktop
file\&.
.PP
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\&.
.PP
Consider the following example:
.sp
.if n \{\
.RS 4
.\}
.nf
        [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
      
.fi
.if n \{\
.RE
.\}
.SS "From a script"
.PP
If installing an application that supports D\-Bus activation you may still want to put a file in
/usr/bin
so that your program can be started from a terminal\&.
.PP
It is possible for this file to be a shell script\&. The script can handle arguments such as \-\-help and \-\-version directly\&. It can also parse other command line arguments and convert them to uses of
\fBgapplication\fR
to activate the application, open files, or invoke actions\&.
.PP
Here is a simplified example, as may be installed in
/usr/bin/fooview:
.sp
.if n \{\
.RS 4
.\}
.nf
        #!/bin/sh

        case "$1" in
          \-\-help)
            echo "see \*(Aqman fooview\*(Aq for more information"
            ;;

          \-\-version)
            echo "fooview 1\&.2"
            ;;

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

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

          \-*)
            echo "unrecognised commandline argument"
            exit 1
            ;;

          *)
            gapplication launch org\&.example\&.fooview "$@"
            ;;
        esac
      
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.PP
\m[blue]\fBDesktop Entry Specification\fR\m[]\&\s-2\u[1]\d\s+2,
\fBgdbus\fR(1),
\fBxdg-open\fR(1),
\fBdesktop-file-validate\fR(1)
.SH "NOTES"
.IP " 1." 4
Desktop Entry Specification
.RS 4
\%http://standards.freedesktop.org/desktop-entry-spec/latest/
.RE