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
gchar * event Read / Write / Construct Only
gchar * feedback-profile Read / Write
LfbEventState state Read
gint 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:

1
2
3
4
5
 
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():

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
 
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.

Flags: Read

Default value: LFB_EVENT_END_REASON_NATURAL

The “event” property

  “event”                    gchar *

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

Flags: Read / Write / Construct Only

Default value: NULL

The “feedback-profile” property

  “feedback-profile”         gchar *

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

Flags: Read / Write

Default value: NULL

The “state” property

  “state”                    LfbEventState

The event's state.

Flags: Read

Default value: LFB_EVENT_STATE_NONE

The “timeout” property

  “timeout”                  gint

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().

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

Generated by GTK-Doc V1.28