LfbEvent: libfeedback Reference Manual

LfbEvent

LfbEvent — An event triggering feedback to the user

Functions

LfbEvent *	lfb_event_new ()
gboolean	lfb_event_trigger_feedback ()
void	lfb_event_trigger_feedback_async ()
gboolean	lfb_event_trigger_feedback_finish ()
gboolean	lfb_event_end_feedback ()
void	lfb_event_end_feedback_async ()
gboolean	lfb_event_end_feedback_finish ()
void	lfb_event_set_timeout ()
gint	lfb_event_get_timeout ()
void	lfb_event_set_feedback_profile ()
char *	lfb_event_get_feedback_profile ()
const char *	lfb_event_get_event ()
LfbEventState	lfb_event_get_state ()
LfbEventEndReason	lfb_event_get_end_reason ()

Properties

LfbEventEndReason	end-reason	Read
char *	event	Read / Write / Construct Only
char *	feedback-profile	Read / Write
LfbEventState	state	Read
int	timeout	Read / Write

Signals

void

feedback-ended

Run Last

Types and Values

enum	LfbEventState
enum	LfbEventEndReason
#define	LFB_TYPE_EVENT
	LfbEvent

Object Hierarchy

    GEnum
    ├── LfbEventEndReason
    ╰── LfbEventState
    GObject
    ╰── LfbEvent

Description

LfbEvent represents an event that should trigger audio, haptic and/or visual feedback to the user by triggering feedback on a feedback daemon. Valid event names are specified in the Event naming specification.

One event can trigger multiple feedbacks at once (e.g. audio and haptic feedback). This is determined by the feedback theme in use (which is not under the appliction's control) and the active feedback profile (see lfb_set_feedback_profile()).

After initializing the library via lfb_init() feedback can be triggered like:

g_autoptr (GError) err = NULL;
LpfEvent *event = lfb_event_new ("message-new-instant");
lfb_event_set_timeout (event, 0);
if (!lfb_event_trigger_feedback (event, &err))
  g_warning ("Failed to trigger feedback: %s", err->message);

When all feedback for this event has ended the “feedback-ended” signal is emitted. If you want to end the feedback ahead of time use lfb_event_end_feedback():

1 2	if (!lfb_event_end_feedback (event, &err)) g_warning ("Failed to end feedback: %s", err->message);

Since these methods involve DBus calls there are asynchronous variants available, e.g. lfb_event_trigger_feedback_async():

static void
on_feedback_triggered (LfbEvent      *event,
                       GAsyncResult  *res,
                       gpointer      unused)
{
   g_autoptr (GError) err = NULL;
   if (!lfb_event_trigger_feedback_finish (event, res, &err)) {
      g_warning ("Failed to trigger feedback for %s: %s",
                 lfb_event_get_event (event), err->message);
   }
}

static void
my_function ()
{
  LfbEvent *event = lfb_event_new ("message-new-instant");
  lfb_event_trigger_feedback_async (event, NULL,
                                   (GAsyncReadyCallback)on_feedback_triggered,
                                   NULL);
}

Functions

lfb_event_new ()

LfbEvent *
lfb_event_new (const char *event);

Creates a new LfbEvent based on the given event name. See “event” for details.

Parameters

event

The event's name.

Returns

The LfbEvent.

lfb_event_trigger_feedback ()

gboolean
lfb_event_trigger_feedback (LfbEvent *self,
                            GError **error);

Tells the feedback server to provide proper feedback for the give event to the user.

Parameters

self	The event to trigger feedback for.
error	The returned error information.

Returns

TRUE if successful. On error, this will return FALSE and set error .

lfb_event_trigger_feedback_async ()

void
lfb_event_trigger_feedback_async (LfbEvent *self,
                                  GCancellable *cancellable,
                                  GAsyncReadyCallback callback,
                                  gpointer user_data);

Tells the feedback server to provide proper feedback for the give event to the user. This is the sync version of lfb_event_trigger_feedback.

Parameters

self	The event to trigger feedback for.
cancellable	A GCancellable or `NULL`.	[nullable]
callback	A GAsyncReadyCallback to call when the request is satisfied or `NULL`.
user_data	User data to pass to `callback` .

lfb_event_trigger_feedback_finish ()

gboolean
lfb_event_trigger_feedback_finish (LfbEvent *self,
                                   GAsyncResult *res,
                                   GError **error);

Finish an async operation started by lfb_event_trigger_feedback_async. You must call this function in the callback to free memory and receive any errors which occurred.

Parameters

self	the event
res	Result object passed to the callback of lfb_event_trigger_feedback_async
error	Return location for error

Returns

TRUE if triggering the feedbacks was successful

lfb_event_end_feedback ()

gboolean
lfb_event_end_feedback (LfbEvent *self,
                        GError **error);

Tells the feedback server to end all feedback for the given event as soon as possible.

Parameters

self	The event to end feedback for.
error	The returned error information.

Returns

TRUE if successful. On error, this will return FALSE and set error .

lfb_event_end_feedback_async ()

void
lfb_event_end_feedback_async (LfbEvent *self,
                              GCancellable *cancellable,
                              GAsyncReadyCallback callback,
                              gpointer user_data);

Tells the feedback server to end all feedback for the given event as soon as possible.

Parameters

self	The event to end feedback for.
cancellable	A GCancellable or `NULL`.	[nullable]
callback	A GAsyncReadyCallback to call when the request is satisfied or `NULL`.
user_data	User data to pass to `callback` .

lfb_event_end_feedback_finish ()

gboolean
lfb_event_end_feedback_finish (LfbEvent *self,
                               GAsyncResult *res,
                               GError **error);

Finish an async operation started by lfb_event_end_feedback_async. You must call this function in the callback to free memory and receive any errors which occurred.

This does not mean that the feedbacks finished right away. Connect to the “feedback-ended” signal for this.

Parameters

self	the event
res	Result object passed to the callback of lfb_event_end_feedback_async
error	Return location for error

Returns

TRUE if ending the feedbacks was successful

lfb_event_set_timeout ()

void
lfb_event_set_timeout (LfbEvent *self,
                       gint timeout);

Tells the feedback server to end feedack after timeout seconds. The value -1 indicates to not set a timeout and let feedbacks stop on their own while 0 indicates to loop all feedbacks endlessly. They must be stopped via lfb_event_end_feedback() in this case.

It is an error to change the timeout after the feedback has been triggered via lfb_event_trigger.

Parameters

self	The event
timeout	The timeout

lfb_event_get_timeout ()

gint
lfb_event_get_timeout (LfbEvent *self);

Get the currently set timeout.

Parameters

self

The event

Returns

The event timeout in msecs

lfb_event_set_feedback_profile ()

void
lfb_event_set_feedback_profile (LfbEvent *self,
                                const char *profile);

Tells the feedback server to use the given feedback profile for this event. The server might ignore this request. Valid profile names and their 'noisiness' are specified in the Feedback theme specification.

A value of NULL (the default) lets the server pick the profile.

Parameters

self	The event
profile	The feedback profile to use

lfb_event_get_feedback_profile ()

char *
lfb_event_get_feedback_profile (LfbEvent *self);

Parameters

self

The event

Returns

The set feedback profile to use for this event or NULL.

[transfer full]

lfb_event_get_event ()

const char *
lfb_event_get_event (LfbEvent *self);

Get the event's name according to the event naming spec.

Parameters

self

The event

Returns

The event name

lfb_event_get_state ()

LfbEventState
lfb_event_get_state (LfbEvent *self);

Get the current event state (e.g. if triggered feeedback is currently running.

Parameters

self

The event

Returns

The state of the feedback triggered by event.

lfb_event_get_end_reason ()

LfbEventEndReason
lfb_event_get_end_reason (LfbEvent *self);

Get the reason why the feadback ended.

Parameters

self

The event

Returns

The reason why feedback ended.

Types and Values

enum LfbEventState

Enum values to indicate the current state of the feedbacks triggered by an event.

Members

LFB_EVENT_STATE_ERRORED	An error occurred triggering feedbacks
LFB_EVENT_STATE_NONE	No state information yet
LFB_EVENT_STATE_RUNNING	The feedbacks for this event are currently running
LFB_EVENT_STATE_ENDED	All feedbacks for this event ended

enum LfbEventEndReason

Enum values used to indicate why the feedbacks for an event ended.

Members

LFB_EVENT_END_REASON_NOT_FOUND	There was no feedback in the current theme for this event so no feedback was provided to the user.
LFB_EVENT_END_REASON_NATURAL	All feedbacks finished playing their natural length
LFB_EVENT_END_REASON_EXPIRED	Feedbacks ran until the set timeout expired
LFB_EVENT_END_REASON_EXPLICIT	The feedbacks were ended explicitly

LFB_TYPE_EVENT

#define LFB_TYPE_EVENT (lfb_event_get_type())

LfbEvent

typedef struct _LfbEvent LfbEvent;

Property Details

The `“end-reason”` property

  “end-reason”               LfbEventEndReason

The reason why the feedbacks ended.

Owner: LfbEvent

Flags: Read

Default value: LFB_EVENT_END_REASON_NATURAL

The `“event”` property

  “event”                    char *

The type of event from the Event naming spec, e.g. 'message-new-instant'.

Owner: LfbEvent

Flags: Read / Write / Construct Only

Default value: NULL

The `“feedback-profile”` property

  “feedback-profile”         char *

The name of the feedback profile to use for this event. See lfb_event_set_feedback_profile() for details.

Owner: LfbEvent

Flags: Read / Write

Default value: NULL

The `“state”` property

  “state”                    LfbEventState

The event's state.

Owner: LfbEvent

Flags: Read

Default value: LFB_EVENT_STATE_NONE

The `“timeout”` property

  “timeout”                  int

How long feedback should be provided in milliseconds. The special value -1 uses the natural length of each feedback while 0 plays each feedback in a loop until ended explicitly via e.g. lfb_event_end_feedback().

Owner: LfbEvent

Flags: Read / Write

Allowed values: >= -1

Default value: -1

Signal Details

The `“feedback-ended”` signal

void
user_function (LfbEvent *lfbevent,
               gpointer  user_data)

Emitted when all feedbacks triggered by the event have ended.

Parameters

user_data

user data set when the signal handler was connected.

Flags: Run Last

LfbEvent

Functions

Properties

Signals

Types and Values

Object Hierarchy

Description

Functions

lfb_event_new ()

Parameters

Returns

lfb_event_trigger_feedback ()

Parameters

Returns

lfb_event_trigger_feedback_async ()

Parameters

lfb_event_trigger_feedback_finish ()

Parameters

Returns

lfb_event_end_feedback ()

Parameters

Returns

lfb_event_end_feedback_async ()

Parameters

lfb_event_end_feedback_finish ()

Parameters

Returns

lfb_event_set_timeout ()

Parameters

lfb_event_get_timeout ()

Parameters

Returns

lfb_event_set_feedback_profile ()

Parameters

lfb_event_get_feedback_profile ()

Parameters

Returns

lfb_event_get_event ()

Parameters

Returns

lfb_event_get_state ()

Parameters

Returns

lfb_event_get_end_reason ()

Parameters

Returns

Types and Values

enum LfbEventState

Members

enum LfbEventEndReason

Members

LFB_TYPE_EVENT

LfbEvent

Property Details

The “end-reason” property

The “event” property

The “feedback-profile” property

The “state” property

The “timeout” property

Signal Details

The “feedback-ended” signal

Parameters

The `“end-reason”` property

The `“event”` property

The `“feedback-profile”` property

The `“state”` property

The `“timeout”` property

The `“feedback-ended”` signal