path: root/docs/reference/gio/gapplication.xml

<refentry id="gapplication-tool" lang="en">
  <refentryinfo>
    <title>gapplication</title>
    <productname>GIO</productname>
    <authorgroup>
      <author>
        <contrib>Developer</contrib>
        <firstname>Ryan</firstname>
        <surname>Lortie</surname>
      </author>
    </authorgroup>
  </refentryinfo>

  <refmeta>
    <refentrytitle>gapplication</refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo class="manual">User Commands</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>gapplication</refname>
    <refpurpose>D-Bus application launcher</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>gapplication</command>
      <arg choice="plain">help</arg>
      <arg choice="opt"><replaceable>COMMAND</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>gapplication</command>
      <arg choice="plain">version</arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>gapplication</command>
      <arg choice="plain">list-apps</arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>gapplication</command>
      <arg choice="plain">launch</arg>
      <arg choice="plain"><replaceable>APPID</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>gapplication</command>
      <arg choice="plain">launch</arg>
      <arg choice="plain"><replaceable>APPID</replaceable></arg>
      <arg choice="opt" rep="repeat"><replaceable>FILE</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>gapplication</command>
      <arg choice="plain">list-actions</arg>
      <arg choice="plain"><replaceable>APPID</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>gapplication</command>
      <arg choice="plain">action</arg>
      <arg choice="plain"><replaceable>APPID</replaceable></arg>
      <arg choice="plain"><replaceable>ACTION</replaceable></arg>
      <arg choice="opt"><replaceable>PARAMETER</replaceable></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para>
      <command>gapplication</command> is a commandline implementation of the client-side of the
      <interfacename>org.freedesktop.Application</interfacename> interface as specified by the freedesktop.org
      Desktop Entry Specification.
    </para>

    <para>
      <command>gapplication</command> can be used to start applications that have
      <varname>DBusActivatable</varname> set to <literal>true</literal> in their <filename>.desktop</filename>
      files and can be used to send messages to already-running instances of other applications.
    </para>

    <para>
      It is possible for applications to refer to <command>gapplication</command> in the <varname>Exec</varname>
      line of their <filename class='extension'>.desktop</filename> file to maintain backwards compatibility
      with implementations that do not directly support <varname>DBusActivatable</varname>.
    </para>

    <para>
      <command>gapplication</command> ships as part of <application>GLib</application>.
    </para>
  </refsect1>

  <refsect1>
    <title>Commands</title>

    <refsect2>
      <title>Global commands</title>

      <variablelist>
        <varlistentry>
          <term>
            <command>help</command>
            <arg choice="opt"><replaceable>COMMAND</replaceable></arg>
          </term>
          <listitem>
            <para>
              Displays a short synopsis of the available commands or provides detailed help on a specific
              command.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <command>version</command>
          </term>
          <listitem>
            <para>
              Prints the GLib version whence <command>gapplication</command> came.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <command>list-apps</command>
          </term>
          <listitem>
            <para>
              Prints a list of all application IDs that are known to support D-Bus activation.  This list is
              generated by scanning <filename class='extension'>.desktop</filename> files as per the current
              <envar>XDG_DATA_DIRS</envar>.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <command>launch</command>
            <arg choice="plain"><replaceable>APPID</replaceable></arg>
            <arg choice="opt" rep="repeat"><replaceable>FILE</replaceable></arg>
          </term>
          <listitem>
            <para>
              Launches an application.
            </para>
            <para> 
              The first parameter is the application ID in the familiar "reverse DNS" style (eg:
              '<literal>org.gnome.app</literal>') without the <filename class='extension'>.desktop</filename>
              suffix.
            </para>
            <para>
              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.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <command>list-actions</command>
            <arg choice="plain"><replaceable>APPID</replaceable></arg>
          </term>
          <listitem>
            <para>
              List the actions declared in the application's <filename class='extension'>.desktop</filename>
              file.  The parameter is the application ID, as above.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <command>action</command>
            <arg choice="plain"><replaceable>APPID</replaceable></arg>
            <arg choice="plain"><replaceable>ACTION</replaceable></arg>
            <arg choice="opt"><replaceable>PARAMETER</replaceable></arg>
          </term>
          <listitem>
            <para>
              Invokes the named action (in the same way as would occur when activating an action specified in
              the <filename class='extension'>.desktop</filename> file).
            </para>
            <para>
              The application ID (as above) is the first parameter.  The action name follows.
            </para>
            <para>
              Optionally, following the action name can be one parameter, in GVariant format, given as a single
              argument.  Make sure to use sufficient quoting.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>
    </refsect2>
  </refsect1>

  <refsect1>
    <title>Examples</title>

    <refsect2>
      <title>From the commandline</title>

      <para>
        Launching an application:
      </para>

      <programlisting>
        gapplication launch org.example.fooview
      </programlisting>

      <para>
        Opening a file with an application:
      </para>

      <programlisting>
        gapplication launch org.example.fooview ~/file.foo
      </programlisting>

      <para>
        Opening many files with an application:
      </para>

      <programlisting>
        gapplication launch org.example.fooview ~/foos/*.foo
      </programlisting>

      <para>
        Invoking an action on an application:
      </para>

      <programlisting>
        gapplication action org.example.fooview create
      </programlisting>

      <para>
        Invoking an action on an application, with an action:
      </para>

      <programlisting>
        gapplication action org.example.fooview show-item '"item_id_828739"'
      </programlisting>
    </refsect2>

    <refsect2>
      <title>
        From the <varname>Exec</varname> lines of a <filename class='extension'>.desktop</filename> file
      </title>

      <para>
        The commandline interface of <command>gapplication</command> was designed so that it could be used
        directly from the <varname>Exec</varname> line of a <filename class='extension'>.desktop</filename>
        file.
      </para>

      <para>
        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.
      </para>

      <para>
        Consider the following example:
      </para>

      <programlisting>
        [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
      </programlisting>
    </refsect2>

    <refsect2>
      <title>From a script</title>

      <para>
        If installing an application that supports D-Bus activation you may still want to put a file in
        <filename class='directory'>/usr/bin</filename> so that your program can be started from a terminal.
      </para>

      <para>
        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
        <command>gapplication</command> to activate the application, open files, or invoke actions.
      </para>

      <para>
        Here is a simplified example, as may be installed in <filename>/usr/bin/fooview</filename>:
      </para>

      <programlisting>
        #!/bin/sh

        case "$1" in
          --help)
            echo "see 'man fooview' 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
      </programlisting>
    </refsect2>
  </refsect1>

  <refsect1>
    <title>See also</title>
    <para>
      <ulink url='http://standards.freedesktop.org/desktop-entry-spec/latest/'>Desktop Entry Specification</ulink>,
      <citerefentry>
        <refentrytitle>gdbus</refentrytitle>
        <manvolnum>1</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>xdg-open</refentrytitle>
        <manvolnum>1</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>desktop-file-validate</refentrytitle>
        <manvolnum>1</manvolnum>
      </citerefentry>
    </para>
  </refsect1>

</refentry>