Merge branch 'after-gsoc'

author: Stefano Karapetsas <[email protected]> 2014-10-09 15:59:09 +0200
committer: Stefano Karapetsas <[email protected]> 2014-10-09 15:59:09 +0200
commit: 526fdf477edc40452c18b51e13cbdffaa69de52b (patch)
tree: dd73763b097fca2a86288bcb55881a96f3e5faaf /libmatemixer/matemixer-device.c
parent: b4695e82ae0cc3183e9d3be4fca191394292609f (diff)
parent: 0ab66491e3847f6de92fc5358e9687c6d2f458ce (diff)
download: libmatemixer-526fdf477edc40452c18b51e13cbdffaa69de52b.tar.bz2
libmatemixer-526fdf477edc40452c18b51e13cbdffaa69de52b.tar.xz
1 files changed, 137 insertions, 14 deletions
diff --git a/libmatemixer/matemixer-device.c b/libmatemixer/matemixer-device.c
index 8144388..f9d368b 100644
--- a/libmatemixer/matemixer-device.c
+++ b/libmatemixer/matemixer-device.c
@@ -27,6 +27,10 @@
 * SECTION:matemixer-device
 * @short_description: Hardware or software device in the sound system
 * @include: libmatemixer/matemixer.h
+ *
+ * A #MateMixerDevice represents a sound device, most typically a sound card.
+ *
+ * Each device may contain an arbitrary number of streams.
 */
 
 struct _MateMixerDevicePrivate
@@ -72,24 +76,30 @@ static void mate_mixer_device_finalize (GObject *object);
 
 G_DEFINE_ABSTRACT_TYPE (MateMixerDevice, mate_mixer_device, G_TYPE_OBJECT)
 
-static MateMixerStream *mate_mixer_device_real_get_stream (MateMixerDevice *device,
- const gchar *name);
-static MateMixerSwitch *mate_mixer_device_real_get_switch (MateMixerDevice *device,
- const gchar *name);
+static MateMixerStream *mate_mixer_device_real_get_stream (MateMixerDevice *device,
+ const gchar *name);
+static MateMixerSwitch *mate_mixer_device_real_get_switch (MateMixerDevice *device,
+ const gchar *name);
 
 static void
 mate_mixer_device_class_init (MateMixerDeviceClass *klass)
 {
 GObjectClass *object_class;
 
- klass->get_stream = mate_mixer_device_real_get_stream;
- klass->get_switch = mate_mixer_device_real_get_switch;
+ klass->get_stream = mate_mixer_device_real_get_stream;
+ klass->get_switch = mate_mixer_device_real_get_switch;
 
 object_class = G_OBJECT_CLASS (klass);
 object_class->finalize = mate_mixer_device_finalize;
 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 +109,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 +124,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,10 +140,20 @@ 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),
- G_SIGNAL_RUN_LAST,
+ G_SIGNAL_RUN_FIRST,
 G_STRUCT_OFFSET (MateMixerDeviceClass, stream_added),
 NULL,
 NULL,
@@ -131,10 +162,22 @@ 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),
- G_SIGNAL_RUN_LAST,
+ G_SIGNAL_RUN_FIRST,
 G_STRUCT_OFFSET (MateMixerDeviceClass, stream_removed),
 NULL,
 NULL,
@@ -143,10 +186,17 @@ 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),
- G_SIGNAL_RUN_LAST,
+ G_SIGNAL_RUN_FIRST,
 G_STRUCT_OFFSET (MateMixerDeviceClass, switch_added),
 NULL,
 NULL,
@@ -155,10 +205,22 @@ 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),
- G_SIGNAL_RUN_LAST,
+ G_SIGNAL_RUN_FIRST,
 G_STRUCT_OFFSET (MateMixerDeviceClass, switch_removed),
 NULL,
 NULL,
@@ -190,6 +252,7 @@ mate_mixer_device_get_property (GObject *object,
 case PROP_ICON:
 g_value_set_string (value, device->priv->icon);
 break;
+
 default:
 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, param_id, pspec);
 break;
@@ -209,15 +272,15 @@ mate_mixer_device_set_property (GObject *object,
 switch (param_id) {
 case PROP_NAME:
 /* Construct-only string */
- device->priv->name = g_strdup (g_value_get_string (value));
+ device->priv->name = g_value_dup_string (value);
 break;
 case PROP_LABEL:
 /* Construct-only string */
- device->priv->label = g_strdup (g_value_get_string (value));
+ device->priv->label = g_value_dup_string (value);
 break;
 case PROP_ICON:
 /* Construct-only string */
- device->priv->icon = g_strdup (g_value_get_string (value));
+ device->priv->icon = g_value_dup_string (value);
 break;
 
 default:
@@ -251,6 +314,17 @@ 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 +337,13 @@ 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 +356,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 or %NULL.
 */
 const gchar *
 mate_mixer_device_get_icon (MateMixerDevice *device)
@@ -288,6 +373,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 +388,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 +409,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 +436,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)
author	Stefano Karapetsas <[email protected]>	2014-10-09 15:59:09 +0200
committer	Stefano Karapetsas <[email protected]>	2014-10-09 15:59:09 +0200
commit	526fdf477edc40452c18b51e13cbdffaa69de52b (patch)
tree	dd73763b097fca2a86288bcb55881a96f3e5faaf /libmatemixer/matemixer-device.c
parent	b4695e82ae0cc3183e9d3be4fca191394292609f (diff)
parent	0ab66491e3847f6de92fc5358e9687c6d2f458ce (diff)
download	libmatemixer-526fdf477edc40452c18b51e13cbdffaa69de52b.tar.bz2 libmatemixer-526fdf477edc40452c18b51e13cbdffaa69de52b.tar.xz