kanberra-ctk: libkanberra Reference Manual

## kanberra-ctk kanberra-ctk — Ctk+ libkanberra Bindings |

## Functions

ka_context * | ka_ctk_context_get ()
int | ka_ctk_proplist_set_for_widget ()
int | ka_ctk_play_for_widget ()
int | ka_ctk_proplist_set_for_event ()
int | ka_ctk_play_for_event ()
void | ka_ctk_widget_disable_sounds ()

## Description

libkanberra-ctk provides a few functions that simplify libkanberra usage from Ctk+ programs. It maintains a single ka_context object per CdkScreen that is made accessible via `ka_ctk_context_get_for_screen()`, with a shortcut `ka_ctk_context_get()` to get the context for the default screen. More importantly, it provides a few functions to compile event sound property lists based on CtkWidget objects or CdkEvent events.

## Functions

### ka_ctk_context_get ()

    ka_context *
    ka_ctk_context_get (void);

Gets the single ka_context object for the default screen. See `ka_ctk_context_get_for_screen()`.

#### Returns

a ka_context object. The object is owned by libkanberra-ctk and must not be destroyed

### ka_ctk_proplist_set_for_widget ()

    int
    ka_ctk_proplist_set_for_widget (ka_proplist *p,
                                    CtkWidget *w);

Fill in a ka_proplist object for a sound event that shall originate from the specified Ctk Widget. This will fill in properties like `KA_PROP_WINDOW_NAME` or `KA_PROP_WINDOW_X11_DISPLAY` for you.

#### Parameters

p | The proplist to store these sound event properties in |
w | The Ctk widget to base these sound event properties on |

#### Returns

0 on success, negative error code on error.

### ka_ctk_play_for_widget ()

    int
    ka_ctk_play_for_widget (CtkWidget *w,
                            uint32_t id,
                            ...);

Play a sound event for the specified widget. This will internally call `ka_ctk_proplist_set_for_widget()` and then merge them with the properties passed in via the NULL terminated argument list. Finally, it will call `ka_context_play_full()` to actually play the event sound.

#### Parameters

w | The Ctk widget to base these sound event properties on |
id | The event id that can later be used to cancel this event sound using `ka_context_cancel()`. This can be any integer and shall be chosen be the client program. It is a good idea to pass 0 here if cancelling the sound later is not needed. If the same id is passed to multiple sounds they can be canceled with a single `ka_context_cancel()` call. |
... | additional event properties as pairs of strings, terminated by NULL. |

#### Returns

0 on success, negative error code on error.

### ka_ctk_proplist_set_for_event ()

    int
    ka_ctk_proplist_set_for_event (ka_proplist *p,
                                   CdkEvent *e);

Fill in a ka_proplist object for a sound event that is being triggered by the specified Cdk Event. This will fill in properties like `KA_PROP_EVENT_MOUSE_X` or `KA_PROP_EVENT_MOUSE_BUTTON` for you. This will internally also cal `ka_ctk_proplist_set_for_widget()` on the widget this event belongs to.

#### Parameters

p | The proplist to store these sound event properties in |
e | The Cdk event to base these sound event properties on |

#### Returns

0 on success, negative error code on error.

### ka_ctk_play_for_event ()

    int
    ka_ctk_play_for_event (CdkEvent *e,
                           uint32_t id,
                           ...);

Play a sound event for the specified event. This will internally call `ka_ctk_proplist_set_for_event()` and then merge them with the properties passed in via the NULL terminated argument list. Finally, it will call `ka_context_play_full()` to actually play the event sound.

#### Parameters

e | The Cdk event to base these sound event properties on |
id | The event id that can later be used to cancel this event sound using `ka_context_cancel()`. This can be any integer and shall be chosen be the client program. It is a good idea to pass 0 here if cancelling the sound later is not needed. If the same id is passed to multiple sounds they can be canceled with a single `ka_context_cancel()` call. |
... | additional event properties as pairs of strings, terminated by NULL. |

#### Returns

0 on success, negative error code on error.

### ka_ctk_widget_disable_sounds ()

    void
    ka_ctk_widget_disable_sounds (CtkWidget *w,
                                  gboolean enable);

By default sound events are automatically generated for all kinds of input events. Use this function to disable this. This is intended to be used for widgets which directly generate sound events.

#### Parameters

w | The Ctk widget to disable automatic event sounds for. |
enable | Boolean specifying whether sound events shall be enabled or disabled for this widget. |