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:

    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 when it is submitted. 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 seconds. 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