<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
  <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
  %gtkdocentities;
]>

<part>
  <title>Libfeedback Overview</title>

  <chapter>
    <title>Introduction</title>

    <para>
      The purpose of libfeedback is to make it simple to supply
      audible, haptic and visual feedback to the user. This is done
      by notifying a &feedback_daemon; over DBus that a certain event
      happened and the daemon selects the appropriate feedbacks (such as
      a buzzing haptic motor or playing an audio file) based
      on the user session's current feedback profile, feedback theme and available
      hardware. Events are identified by strings like
      <literal>message-new-sms</literal> or
      <literal>message-new-sms</literal>. The available event names are
      described in the &event_naming_spec;.
    </para>
    <para>
      &package; provides synchronous and asynchronous APIs to trigger
      and stop feedback for these events and is usable from other languages
      than C by GObject introspection.
    </para>
  </chapter>

  <chapter>
    <title>Compiling libfeedback applications</title>
    <simplesect>
      <title>Using pkg-config</title>

      <para> Like other GNOME libraries,
      <application>&package_string;</application> uses
      <application>pkg-config</application> to provide compiler options. The
      package name is
      "<literal>&package_ver_str;</literal>". So in
      your <literal>configure.ac</literal> script, you might specify something
      like: </para>

      <informalexample><programlisting>
	PKG_CHECK_MODULES(LIBFEEDBACK, [&package_string;-&package_api_version;])
	AC_SUBST(LIBFEEDBACK_CFLAGS)
	AC_SUBST(LIBFEEDBACK_LIBS)
      </programlisting></informalexample>
    </simplesect>

    <simplesect>
      <title>Using Meson/Ninja</title>
      <para>
	If using Meson/Ninja use a <literal>dependency('&package_string;-&package_api_version;')
	</literal> dependency.
      </para>

      <para>
	The "<literal>&package_api_version;</literal>" in the package name is the "API version"
	(indicating "the version of the <application>&package_string;</application> API
	that first appeared in version &package_api_version;") and is essentially just part of
	the package name.
      </para>

      <para>
	When using the Meson build system you can declare a dependency like
      </para>
      <informalexample><programlisting>
	dependency(libfeedback-0.0')
      </programlisting></informalexample>

    </simplesect>

    <simplesect>
      <title>Acknowledge the Instability</title>

      <para>
	Since the library is young and is still changing a lot, in order to use it you are required to acknowledge that your are using an unstable API.
	To do so, <literal>LIBFEEDBACK_USE_UNSTABLE_API</literal> must be defined for compilation to succeed.
      </para>

      <para>
	From C code or any compatible language, you can prefix your inclusion of the &package_string; header like so:
      </para>

      <informalexample><programlisting>
	#define LIBFEEDBACK_USE_UNSTABLE_API
	#include &lt;libfeedback.h&gt;
      </programlisting></informalexample>

      <para>
	Including individual headers rather than <literal>libfeedback.h</literal> is not
	recommended.
      </para>
      <para>
	You can also acknoledge this with the definition option of your C compiler, like <literal>-DFEEDBACK_USE_UNSTABLE_API</literal>.
	This is required from Vala.
      </para>

      <para>
	To use &package_name; from Vala, you must define the acknowledgment in C via <literal>-X -DFEEDBACK_USE_UNSTABLE_API</literal>.
	If your build system uses a two pass compilation and hence your Vala compiler outputs C (Meson, Automake, or using the <literal>--ccode</literal> Vala compiler option trigger that) then you must add <literal>-DLIBFEEDBACK_USE_UNSTABLE_API</literal> to your C compiler argments instead.
      </para>
    </simplesect>

  </chapter>
  
</part>
