diff options
Diffstat (limited to 'libmatemixer/matemixer-device.c')
| -rw-r--r-- | libmatemixer/matemixer-device.c | 117 |
1 files changed, 116 insertions, 1 deletions
diff --git a/libmatemixer/matemixer-device.c b/libmatemixer/matemixer-device.c index 8144388..3944af5 100644 --- a/libmatemixer/matemixer-device.c +++ b/libmatemixer/matemixer-device.c @@ -90,6 +90,13 @@ mate_mixer_device_class_init (MateMixerDeviceClass *klass) object_class->get_property = mate_mixer_device_get_property; object_class->set_property = mate_mixer_device_set_property; + /** + * MateMixerDevice:name: + * + * The name of the device. The name serves as a unique identifier and + * in most cases it is not in a user-readable form. + * + */ properties[PROP_NAME] = g_param_spec_string ("name", "Name", @@ -99,6 +106,12 @@ mate_mixer_device_class_init (MateMixerDeviceClass *klass) G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS); + /** + * MateMixerDevice:label: + * + * The label of the device. This is a potentially translated string + * that should be presented to users in the user interface. + */ properties[PROP_LABEL] = g_param_spec_string ("label", "Label", @@ -108,10 +121,15 @@ mate_mixer_device_class_init (MateMixerDeviceClass *klass) G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS); + /** + * MateMixerDevice:icon: + * + * The XDG icon name of the device. + */ properties[PROP_ICON] = g_param_spec_string ("icon", "Icon", - "Name of the sound device icon", + "XDG icon name of the device", NULL, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | @@ -119,6 +137,16 @@ mate_mixer_device_class_init (MateMixerDeviceClass *klass) g_object_class_install_properties (object_class, N_PROPERTIES, properties); + /** + * MateMixerDevice::stream-added: + * @device: a #MateMixerDevice + * @name: name of the added stream + * + * The signal is emitted each time a device stream is added. + * + * Note that at the time this signal is emitted, the controls and switches + * of the stream may not yet be known. + */ signals[STREAM_ADDED] = g_signal_new ("stream-added", G_TYPE_FROM_CLASS (object_class), @@ -131,6 +159,18 @@ mate_mixer_device_class_init (MateMixerDeviceClass *klass) 1, G_TYPE_STRING); + /** + * MateMixerDevice::stream-removed: + * @device: a #MateMixerDevice + * @name: name of the removed stream + * + * The signal is emitted each time a device stream is removed. + * + * When this signal is emitted, the stream is no longer known to the library, + * it will not be included in the stream list provided by the + * mate_mixer_device_list_streams() function and it is not possible to get + * the stream with mate_mixer_device_get_stream(). + */ signals[STREAM_REMOVED] = g_signal_new ("stream-removed", G_TYPE_FROM_CLASS (object_class), @@ -143,6 +183,13 @@ mate_mixer_device_class_init (MateMixerDeviceClass *klass) 1, G_TYPE_STRING); + /** + * MateMixerDevice::switch-added: + * @device: a #MateMixerDevice + * @name: name of the added switch + * + * The signal is emitted each time a device switch is added. + */ signals[SWITCH_ADDED] = g_signal_new ("switch-added", G_TYPE_FROM_CLASS (object_class), @@ -155,6 +202,18 @@ mate_mixer_device_class_init (MateMixerDeviceClass *klass) 1, G_TYPE_STRING); + /** + * MateMixerDevice::switch-removed: + * @device: a #MateMixerDevice + * @name: name of the removed switch + * + * The signal is emitted each time a device switch is removed. + * + * When this signal is emitted, the switch is no longer known to the library, + * it will not be included in the switch list provided by the + * mate_mixer_device_list_switches() function and it is not possible to get + * the switch with mate_mixer_device_get_switch(). + */ signals[SWITCH_REMOVED] = g_signal_new ("switch-removed", G_TYPE_FROM_CLASS (object_class), @@ -251,6 +310,15 @@ mate_mixer_device_finalize (GObject *object) /** * mate_mixer_device_get_name: * @device: a #MateMixerDevice + * + * Gets the name of the device. The name serves as a unique identifier and + * in most cases it is not in a user-readable form. + * + * The returned name is guaranteed to be unique across all the known devices + * and may be used to get the #MateMixerDevice using + * mate_mixer_context_get_device(). + * + * Returns: the name of the device. */ const gchar * mate_mixer_device_get_name (MateMixerDevice *device) @@ -263,6 +331,11 @@ mate_mixer_device_get_name (MateMixerDevice *device) /** * mate_mixer_device_get_label: * @device: a #MateMixerDevice + * + * Gets the label of the device. This is a potentially translated string + * that should be presented to users in the user interface. + * + * Returns: the label of the device. */ const gchar * mate_mixer_device_get_label (MateMixerDevice *device) @@ -275,6 +348,10 @@ mate_mixer_device_get_label (MateMixerDevice *device) /** * mate_mixer_device_get_icon: * @device: a #MateMixerDevice + * + * Gets the XDG icon name of the device. + * + * Returns: the icon name. */ const gchar * mate_mixer_device_get_icon (MateMixerDevice *device) @@ -288,6 +365,10 @@ mate_mixer_device_get_icon (MateMixerDevice *device) * mate_mixer_device_get_stream: * @device: a #MateMixerDevice * @name: a stream name + * + * Gets the device stream with the given name. + * + * Returns: a #MateMixerStream or %NULL if there is no such stream. */ MateMixerStream * mate_mixer_device_get_stream (MateMixerDevice *device, const gchar *name) @@ -299,6 +380,17 @@ mate_mixer_device_get_stream (MateMixerDevice *device, const gchar *name) * mate_mixer_device_get_switch: * @device: a #MateMixerDevice * @name: a switch name + * + * Gets the device switch with the given name. + * + * Note that this function will only return a switch that belongs to the device + * and not to a stream of the device. See mate_mixer_device_list_switches() for + * information about the difference between device and stream switches. + * + * To get a stream switch, rather than a device switch, use + * mate_mixer_stream_get_switch(). + * + * Returns: a #MateMixerSwitch or %NULL if there is no such device switch. */ MateMixerSwitch * mate_mixer_device_get_switch (MateMixerDevice *device, const gchar *name) @@ -309,6 +401,14 @@ mate_mixer_device_get_switch (MateMixerDevice *device, const gchar *name) /** * mate_mixer_device_list_streams: * @device: a #MateMixerDevice + * + * Gets the list of streams that belong to the device. + * + * The returned #GList is owned by the #MateMixerDevice and may be invalidated + * at any time. + * + * Returns: a #GList of the device streams or %NULL if the device does not have + * any streams. */ const GList * mate_mixer_device_list_streams (MateMixerDevice *device) @@ -328,6 +428,21 @@ mate_mixer_device_list_streams (MateMixerDevice *device) /** * mate_mixer_device_list_switches: * @device: a #MateMixerDevice + * + * Gets the list of switches the belong to the device. + * + * Note that a switch may belong either to a device, or to a stream. Unlike + * stream switches, device switches returned by this function are not classified + * as input or output (as streams are), but they operate on the whole device. + * + * Use mate_mixer_stream_list_switches() to get a list of switches that belong + * to a stream. + * + * The returned #GList is owned by the #MateMixerDevice and may be invalidated + * at any time. + * + * Returns: a #GList of the device switches or %NULL if the device does not have + * any switches. */ const GList * mate_mixer_device_list_switches (MateMixerDevice *device) |