<?xml version="1.0"?>
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
                      'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
  <bookinfo>
    <title>libportal Reference Manual</title>
    <releaseinfo>
      This document is for the libportal library, version &version;.
    </releaseinfo>
  </bookinfo>

  <chapter id="libportal">
    <title>Portals</title>
    <para>
      libportal is a library that provides GIO-style async API wrappers
      for the D-Bus portal APIs in xdg-desktop-portal.
    </para>
    <para>
      Where possible, applications should prefer to use existing library
      APIs that have portal support. For example, a GTK+ application should
      use GtkFileChooserNative instead of xdp_portal_open_file().
    </para>
    <para>
      Some portal interfaces are not covered in libportal, since
      they already have perfectly adequate APIs in GLib (which
      libportal depends on anyway).
    </para>

      <variablelist>
        <varlistentry>
          <term>NetworkMonitor</term>
          <listitem><para>
            Use GNetworkMonitor
          </para></listitem>
        </varlistentry>
        <varlistentry>
          <term>ProxyResolver</term>
          <listitem><para>
            Use GProxyResolver
          </para></listitem>
        </varlistentry>
        <varlistentry>
          <term>Settings</term>
          <listitem><para>
            Use a plain GDBusProxy
          </para></listitem>
        </varlistentry>
        <varlistentry>
          <term>GameMode</term>
          <listitem><para>
            Not currently covered
          </para></listitem>
        </varlistentry>
        <varlistentry>
          <term>Secrets</term>
          <listitem><para>
            Not currently covered
          </para></listitem>
        </varlistentry>
      </variablelist>

    <xi:include href="xml/account.xml" />
    <xi:include href="xml/email.xml" />
    <xi:include href="xml/inhibit.xml" />
    <xi:include href="xml/open.xml" />
    <xi:include href="xml/filechooser.xml" />
    <xi:include href="xml/trash.xml" />
    <xi:include href="xml/notification.xml" />
    <xi:include href="xml/print.xml" />
    <xi:include href="xml/screenshot.xml" />
    <xi:include href="xml/screencast.xml" />
    <xi:include href="xml/remote.xml" />
    <xi:include href="xml/background.xml" />
    <xi:include href="xml/camera.xml" />
    <xi:include href="xml/location.xml" />
    <xi:include href="xml/spawn.xml" />
    <xi:include href="xml/updates.xml" />
    <xi:include href="xml/wallpaper.xml" />

  </chapter>

  <chapter id="aux">
    <title>Helpers</title>
    <para>
      Auxiliary objects that are used in the portal API wrappers.
    </para>

    <xi:include href="xml/portal.xml" />
    <xi:include href="xml/parent.xml" />
    <xi:include href="xml/session.xml" />

  </chapter>

</book>
