1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
|
<?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 <libfeedback.h>
</programlisting></informalexample>
<para>
Including individual headers rather than <literal>libfeedback.h</literal> is not
recommended.
</para>
<para>
You can also acknowledge 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 arguments instead.
</para>
</simplesect>
</chapter>
</part>
|
