'\" t .\" Title: gapplication .\" Author: Ryan Lortie .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 03/20/2021 .\" 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