canberra-gtk: libcanberra Reference Manual

canberra-gtk

canberra-gtk — Gtk+ libcanberra Bindings

Functions

ca_context *	ca_gtk_context_get ()
int	ca_gtk_proplist_set_for_widget ()
int	ca_gtk_play_for_widget ()
int	ca_gtk_proplist_set_for_event ()
int	ca_gtk_play_for_event ()
void	ca_gtk_widget_disable_sounds ()

Description

libcanberra-gtk provides a few functions that simplify libcanberra usage from Gtk+ programs. It maintains a single ca_context object per GdkScreen that is made accessible via ca_gtk_context_get_for_screen(), with a shortcut ca_gtk_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 GtkWidget objects or GdkEvent events.

Functions

ca_gtk_context_get ()

ca_context *
ca_gtk_context_get (void);

Gets the single ca_context object for the default screen. See ca_gtk_context_get_for_screen().

Returns

a ca_context object. The object is owned by libcanberra-gtk and must not be destroyed

ca_gtk_proplist_set_for_widget ()

int
ca_gtk_proplist_set_for_widget (ca_proplist *p,
                                GtkWidget *w);

Fill in a ca_proplist object for a sound event that shall originate from the specified Gtk Widget. This will fill in properties like CA_PROP_WINDOW_NAME or CA_PROP_WINDOW_X11_DISPLAY for you.

Parameters

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

Returns

0 on success, negative error code on error.

ca_gtk_play_for_widget ()

int
ca_gtk_play_for_widget (GtkWidget *w,
                        uint32_t id,
                        ...);

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

Parameters

w	The Gtk widget to base these sound event properties on
id	The event id that can later be used to cancel this event sound using `ca_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 `ca_context_cancel()` call.
...	additional event properties as pairs of strings, terminated by NULL.

Returns

0 on success, negative error code on error.

ca_gtk_proplist_set_for_event ()

int
ca_gtk_proplist_set_for_event (ca_proplist *p,
                               GdkEvent *e);

Fill in a ca_proplist object for a sound event that is being triggered by the specified Gdk Event. This will fill in properties like CA_PROP_EVENT_MOUSE_X or CA_PROP_EVENT_MOUSE_BUTTON for you. This will internally also cal ca_gtk_proplist_set_for_widget() on the widget this event belongs to.

Parameters

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

Returns

0 on success, negative error code on error.

ca_gtk_play_for_event ()

int
ca_gtk_play_for_event (GdkEvent *e,
                       uint32_t id,
                       ...);

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

Parameters

e	The Gdk event to base these sound event properties on
id	The event id that can later be used to cancel this event sound using `ca_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 `ca_context_cancel()` call.
...	additional event properties as pairs of strings, terminated by NULL.

Returns

0 on success, negative error code on error.

ca_gtk_widget_disable_sounds ()

void
ca_gtk_widget_disable_sounds (GtkWidget *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 Gtk widget to disable automatic event sounds for.
enable	Boolean specifying whether sound events shall be enabled or disabled for this widget.