summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--docs/reference/libmatemixer-sections.txt20
-rw-r--r--libmatemixer/matemixer-context.c60
-rw-r--r--libmatemixer/matemixer-device.c19
-rw-r--r--libmatemixer/matemixer-enums.h33
-rw-r--r--libmatemixer/matemixer-switch-option.c35
-rw-r--r--libmatemixer/matemixer-switch.c43
-rw-r--r--libmatemixer/matemixer-toggle.c43
-rw-r--r--libmatemixer/matemixer.c30
8 files changed, 246 insertions, 37 deletions
diff --git a/docs/reference/libmatemixer-sections.txt b/docs/reference/libmatemixer-sections.txt
index 2b901e5..d3545f6 100644
--- a/docs/reference/libmatemixer-sections.txt
+++ b/docs/reference/libmatemixer-sections.txt
@@ -59,9 +59,9 @@ MATE_MIXER_CONTEXT_GET_CLASS
MATE_MIXER_IS_CONTEXT
MATE_MIXER_IS_CONTEXT_CLASS
MATE_MIXER_TYPE_CONTEXT
-mate_mixer_context_get_type
<SUBSECTION Private>
MateMixerContextPrivate
+mate_mixer_context_get_type
</SECTION>
<SECTION>
@@ -83,9 +83,9 @@ MATE_MIXER_DEVICE_GET_CLASS
MATE_MIXER_IS_DEVICE
MATE_MIXER_IS_DEVICE_CLASS
MATE_MIXER_TYPE_DEVICE
-mate_mixer_device_get_type
<SUBSECTION Private>
MateMixerDevicePrivate
+mate_mixer_device_get_type
</SECTION>
<SECTION>
@@ -98,6 +98,7 @@ MATE_MIXER_IS_STORED_CONTROL
MATE_MIXER_STORED_CONTROL
MATE_MIXER_STORED_CONTROL_GET_INTERFACE
MATE_MIXER_TYPE_STORED_CONTROL
+<SUBSECTION Private>
mate_mixer_stored_control_get_type
</SECTION>
@@ -116,7 +117,6 @@ mate_mixer_stream_get_switch
mate_mixer_stream_get_default_control
mate_mixer_stream_list_controls
mate_mixer_stream_list_switches
-MateMixerStreamPrivate
<SUBSECTION Standard>
MATE_MIXER_IS_STREAM
MATE_MIXER_IS_STREAM_CLASS
@@ -124,6 +124,8 @@ MATE_MIXER_STREAM
MATE_MIXER_STREAM_CLASS
MATE_MIXER_STREAM_GET_CLASS
MATE_MIXER_TYPE_STREAM
+<SUBSECTION Private>
+MateMixerStreamPrivate
mate_mixer_stream_get_type
</SECTION>
@@ -168,7 +170,6 @@ mate_mixer_stream_control_get_min_volume
mate_mixer_stream_control_get_max_volume
mate_mixer_stream_control_get_normal_volume
mate_mixer_stream_control_get_base_volume
-MateMixerStreamControlPrivate
<SUBSECTION Standard>
MATE_MIXER_IS_STREAM_CONTROL
MATE_MIXER_IS_STREAM_CONTROL_CLASS
@@ -176,6 +177,8 @@ MATE_MIXER_STREAM_CONTROL
MATE_MIXER_STREAM_CONTROL_CLASS
MATE_MIXER_STREAM_CONTROL_GET_CLASS
MATE_MIXER_TYPE_STREAM_CONTROL
+<SUBSECTION Private>
+MateMixerStreamControlPrivate
mate_mixer_stream_control_get_type
</SECTION>
@@ -194,7 +197,6 @@ mate_mixer_switch_get_option
mate_mixer_switch_list_options
mate_mixer_switch_get_active_option
mate_mixer_switch_set_active_option
-MateMixerSwitchPrivate
<SUBSECTION Standard>
MATE_MIXER_IS_SWITCH
MATE_MIXER_IS_SWITCH_CLASS
@@ -202,6 +204,8 @@ MATE_MIXER_SWITCH
MATE_MIXER_SWITCH_CLASS
MATE_MIXER_SWITCH_GET_CLASS
MATE_MIXER_TYPE_SWITCH
+<SUBSECTION Private>
+MateMixerSwitchPrivate
mate_mixer_switch_get_type
</SECTION>
@@ -213,7 +217,6 @@ MateMixerSwitchOptionClass
mate_mixer_switch_option_get_name
mate_mixer_switch_option_get_label
mate_mixer_switch_option_get_icon
-MateMixerSwitchOptionPrivate
<SUBSECTION Standard>
MATE_MIXER_IS_SWITCH_OPTION
MATE_MIXER_IS_SWITCH_OPTION_CLASS
@@ -221,6 +224,8 @@ MATE_MIXER_SWITCH_OPTION
MATE_MIXER_SWITCH_OPTION_CLASS
MATE_MIXER_SWITCH_OPTION_GET_CLASS
MATE_MIXER_TYPE_SWITCH_OPTION
+<SUBSECTION Private>
+MateMixerSwitchOptionPrivate
mate_mixer_switch_option_get_type
</SECTION>
@@ -232,7 +237,6 @@ MateMixerToggleClass
mate_mixer_toggle_get_state
mate_mixer_toggle_set_state
mate_mixer_toggle_get_state_option
-MateMixerTogglePrivate
<SUBSECTION Standard>
MATE_MIXER_IS_TOGGLE
MATE_MIXER_IS_TOGGLE_CLASS
@@ -240,5 +244,7 @@ MATE_MIXER_TOGGLE
MATE_MIXER_TOGGLE_CLASS
MATE_MIXER_TOGGLE_GET_CLASS
MATE_MIXER_TYPE_TOGGLE
+<SUBSECTION Private>
+MateMixerTogglePrivate
mate_mixer_toggle_get_type
</SECTION>
diff --git a/libmatemixer/matemixer-context.c b/libmatemixer/matemixer-context.c
index bb24416..0251d97 100644
--- a/libmatemixer/matemixer-context.c
+++ b/libmatemixer/matemixer-context.c
@@ -32,6 +32,43 @@
* SECTION:matemixer-context
* @short_description:The main class for interfacing with the library
* @include: libmatemixer/matemixer.h
+ *
+ * After the library is initialized, a context should be created to gain
+ * access to a sound system.
+ *
+ * To create a new context, use the mate_mixer_context_new() function.
+ *
+ * The mate_mixer_context_set_backend_type() function can be used to associate
+ * the context with a particular type of sound system. Using this function is
+ * not necessary, by default the context will select a working sound system
+ * backend automatically.
+ *
+ * To connect to a sound system, use mate_mixer_context_open().
+ *
+ * When the connection is established, it is possible to query a list of sound
+ * devices with mate_mixer_context_list_devices() and streams with
+ * mate_mixer_context_list_streams().
+ *
+ * A device represents a hardware or software sound device in the system,
+ * typically a sound card.
+ *
+ * A stream is an input or output channel that may exist either as a part of a
+ * sound device, or independently. Streams essentially serve as containers for
+ * volume controls and switches, for example a sound card with microphone and
+ * line-in connectors may have an input stream containing volume controls for
+ * each of these connectors and possibly a switch allowing to change the active
+ * connector.
+ *
+ * Streams may also exist independently as the sound system may for example
+ * allow audio streaming over a network.
+ *
+ * For a more thorough description of devices and streams, see #MateMixerDevice
+ * and #MateMixerStream.
+ *
+ * Devices and streams (as almost all other elements in the library) may appear
+ * and disappear at any time, for example when external sound cards are plugged
+ * and unplugged. The application should connect to the appropriate signals to
+ * handle these events.
*/
struct _MateMixerContextPrivate
@@ -545,11 +582,15 @@ mate_mixer_context_new (void)
* be used to alter this behavior and make the @context use the selected sound
* system.
*
+ * Setting the sound system backend only succeeds if the selected backend module
+ * is available in the target system.
+ *
* This function must be used before opening a connection to a sound system with
* mate_mixer_context_open(), otherwise it will fail.
*
* Returns: %TRUE on success or %FALSE on failure.
*/
+// XXX handle UNKNOWN
gboolean
mate_mixer_context_set_backend_type (MateMixerContext *context,
MateMixerBackendType backend_type)
@@ -747,9 +788,9 @@ mate_mixer_context_set_server_address (MateMixerContext *context, const gchar *a
* If this function returns %TRUE, the connection has either been established, or
* it hasn't been established yet and the result will be determined asynchronously.
* You can differentiate between these two possibilities by checking the connection
- * #MateMixerContext:state.
+ * #MateMixerContext:state after this function returns.
*
- * The %MATE_MIXER_STATE_READY state indicates, that the connection has been
+ * The %MATE_MIXER_STATE_READY state indicates that the connection has been
* established successfully.
*
* The %MATE_MIXER_STATE_CONNECTING state is reached when the connection has not been
@@ -1130,8 +1171,9 @@ mate_mixer_context_set_default_output_stream (MateMixerContext *context,
* mate_mixer_context_get_backend_name:
* @context: a #MateMixerContext
*
- * Gets the name of the currently used sound system backend. This function will
- * not work until connected to a sound system.
+ * Gets the name of the currently used sound system backend.
+ *
+ * This function will not work until the @context is connected to a sound system.
*
* Returns: the name or %NULL on error.
*/
@@ -1150,8 +1192,9 @@ mate_mixer_context_get_backend_name (MateMixerContext *context)
* mate_mixer_context_get_backend_type:
* @context: a #MateMixerContext
*
- * Gets the type of the currently used sound system backend. This function will
- * not work until connected to a sound system.
+ * Gets the type of the currently used sound system backend.
+ *
+ * This function will not work until the @context is connected to a sound system.
*
* Returns: the backend type or %MATE_MIXER_BACKEND_UNKNOWN on error.
*/
@@ -1170,8 +1213,9 @@ mate_mixer_context_get_backend_type (MateMixerContext *context)
* mate_mixer_context_get_backend_flags:
* @context: a #MateMixerContext
*
- * Gets the capability flags of the currently used sound system backend. This
- * function will not work until connected to a sound system.
+ * Gets the capability flags of the currently used sound system backend.
+ *
+ * This function will not work until the @context is connected to a sound system.
*
* Returns: the capability flags.
*/
diff --git a/libmatemixer/matemixer-device.c b/libmatemixer/matemixer-device.c
index 9206833..f45f9b9 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
@@ -95,7 +99,6 @@ mate_mixer_device_class_init (MateMixerDeviceClass *klass)
*
* 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",
@@ -311,8 +314,10 @@ 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.
+ * 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
@@ -332,8 +337,10 @@ 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.
+ * 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.
*/
@@ -351,7 +358,7 @@ mate_mixer_device_get_label (MateMixerDevice *device)
*
* Gets the XDG icon name of the device.
*
- * Returns: the icon name.
+ * Returns: the icon name or %NULL.
*/
const gchar *
mate_mixer_device_get_icon (MateMixerDevice *device)
diff --git a/libmatemixer/matemixer-enums.h b/libmatemixer/matemixer-enums.h
index 601dc86..96176fa 100644
--- a/libmatemixer/matemixer-enums.h
+++ b/libmatemixer/matemixer-enums.h
@@ -30,7 +30,7 @@
* @MATE_MIXER_STATE_CONNECTING:
* Connection is in progress.
* @MATE_MIXER_STATE_READY:
- * Connected successfully.
+ * Connected.
* @MATE_MIXER_STATE_FAILED:
* Connection has failed.
* @MATE_MIXER_STATE_UNKNOWN:
@@ -49,7 +49,7 @@ typedef enum {
/**
* MateMixerBackendType:
* @MATE_MIXER_BACKEND_UNKNOWN:
- * Unknown or undefined backend type.
+ * Unknown or undefined sound system backend type.
* @MATE_MIXER_BACKEND_PULSEAUDIO:
* PulseAudio sound system backend. It has the highest priority and
* will be the first one to try when you call mate_mixer_context_open(),
@@ -79,11 +79,13 @@ typedef enum {
* @MATE_MIXER_BACKEND_NO_FLAGS:
* No flags.
* @MATE_MIXER_BACKEND_HAS_APPLICATION_CONTROLS:
- * The sound system backend includes support for application stream controls.
+ * The sound system backend includes support for application stream controls,
+ * allowing per-application volume control.
* @MATE_MIXER_BACKEND_HAS_STORED_CONTROLS:
- * The sound system backend includes support for stored controls. The presence
- * of this flag does not guarantee that this feature is enabled in the sound
- * system's configuration.
+ * The sound system backend includes support for stored controls. See the
+ * #MateMixerStoredControl description for more information.
+ * The presence of this flag does not guarantee that this feature is enabled
+ * in the sound system's configuration.
* @MATE_MIXER_BACKEND_CAN_SET_DEFAULT_INPUT_STREAM:
* The sound system backend is able to change the current default input stream
* using the mate_mixer_context_set_default_input_stream() function.
@@ -214,8 +216,11 @@ typedef enum {
* @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_UNKNOWN:
* Unknown media role.
* @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_VIDEO:
+ * Video role.
* @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_MUSIC:
+ * Music role.
* @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_GAME:
+ * Game role.
* @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_EVENT:
* Event sounds.
* @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_PHONE:
@@ -227,13 +232,16 @@ typedef enum {
* @MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_FILTER:
*
* Constants describing a media role of a control. These constants are mapped
- * to PulseAudio media role property and therefore only available when using the
- * PulseAudio sound system.
+ * to PulseAudio media role property and therefore are only available when using
+ * the PulseAudio sound system.
*
* Media roles are commonly set by applications to indicate what kind of sound
* input/output they provide and may be the defining property of stored controls
* (for example an event role stored control can be used to provide a volume
* slider for event sounds).
+ *
+ * See the PulseAudio documentation for more detailed information about media
+ * roles.
*/
typedef enum {
MATE_MIXER_STREAM_CONTROL_MEDIA_ROLE_UNKNOWN,
@@ -302,18 +310,27 @@ typedef enum {
* @MATE_MIXER_CHANNEL_BACK_CENTER:
* Back (rear) center channel.
* @MATE_MIXER_CHANNEL_FRONT_LEFT_CENTER:
+ * Front left of center channel.
* @MATE_MIXER_CHANNEL_FRONT_RIGHT_CENTER:
+ * Front right of center channel.
* @MATE_MIXER_CHANNEL_SIDE_LEFT:
* Side left channel.
* @MATE_MIXER_CHANNEL_SIDE_RIGHT:
* Side right channel.
* @MATE_MIXER_CHANNEL_TOP_FRONT_LEFT:
+ * Top front left channel.
* @MATE_MIXER_CHANNEL_TOP_FRONT_RIGHT:
+ * Top front right channel.
* @MATE_MIXER_CHANNEL_TOP_FRONT_CENTER:
+ * Top front center channel.
* @MATE_MIXER_CHANNEL_TOP_CENTER:
+ * Top center channel.
* @MATE_MIXER_CHANNEL_TOP_BACK_LEFT:
+ * Top back (rear) left channel.
* @MATE_MIXER_CHANNEL_TOP_BACK_RIGHT:
+ * Top back (rear) right channel.
* @MATE_MIXER_CHANNEL_TOP_BACK_CENTER:
+ * Top back (rear) center channel.
*/
typedef enum {
MATE_MIXER_CHANNEL_UNKNOWN = 0,
diff --git a/libmatemixer/matemixer-switch-option.c b/libmatemixer/matemixer-switch-option.c
index b20f92b..4c0e0fa 100644
--- a/libmatemixer/matemixer-switch-option.c
+++ b/libmatemixer/matemixer-switch-option.c
@@ -69,6 +69,12 @@ mate_mixer_switch_option_class_init (MateMixerSwitchOptionClass *klass)
object_class->get_property = mate_mixer_switch_option_get_property;
object_class->set_property = mate_mixer_switch_option_set_property;
+ /**
+ * MateMixerSwitchOption:name:
+ *
+ * The name of the switch option. 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",
@@ -78,6 +84,12 @@ mate_mixer_switch_option_class_init (MateMixerSwitchOptionClass *klass)
G_PARAM_CONSTRUCT_ONLY |
G_PARAM_STATIC_STRINGS);
+ /**
+ * MateMixerSwitchOption:label:
+ *
+ * The label of the switch option. 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",
@@ -87,6 +99,11 @@ mate_mixer_switch_option_class_init (MateMixerSwitchOptionClass *klass)
G_PARAM_CONSTRUCT_ONLY |
G_PARAM_STATIC_STRINGS);
+ /**
+ * MateMixerSwitchOption:icon:
+ *
+ * The XDG icon name of the switch option.
+ */
properties[PROP_ICON] =
g_param_spec_string ("icon",
"Icon",
@@ -183,6 +200,15 @@ mate_mixer_switch_option_finalize (GObject *object)
/**
* mate_mixer_switch_option_get_name:
* @option: a #MateMixerSwitchOption
+ *
+ * Gets the name of the switch option. 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 switch options
+ * of a particular #MateMixerSwitch and may be used to get the #MateMixerSwitchOption
+ * using mate_mixer_switch_get_option().
+ *
+ * Returns: the name of the switch option.
*/
const gchar *
mate_mixer_switch_option_get_name (MateMixerSwitchOption *option)
@@ -195,6 +221,11 @@ mate_mixer_switch_option_get_name (MateMixerSwitchOption *option)
/**
* mate_mixer_switch_option_get_label:
* @option: a #MateMixerSwitchOption
+ *
+ * Gets the label of the switch option. This is a potentially translated string
+ * that should be presented to users in the user interface.
+ *
+ * Returns: the label of the switch option.
*/
const gchar *
mate_mixer_switch_option_get_label (MateMixerSwitchOption *option)
@@ -207,6 +238,10 @@ mate_mixer_switch_option_get_label (MateMixerSwitchOption *option)
/**
* mate_mixer_switch_option_get_icon:
* @option: a #MateMixerSwitchOption
+ *
+ * Gets the XDG icon name of the switch option.
+ *
+ * Returns: the icon name or %NULL.
*/
const gchar *
mate_mixer_switch_option_get_icon (MateMixerSwitchOption *option)
diff --git a/libmatemixer/matemixer-switch.c b/libmatemixer/matemixer-switch.c
index a262e88..926c9a6 100644
--- a/libmatemixer/matemixer-switch.c
+++ b/libmatemixer/matemixer-switch.c
@@ -241,6 +241,13 @@ mate_mixer_switch_finalize (GObject *object)
/**
* mate_mixer_switch_get_name:
* @swtch: a #MateMixerSwitch
+ *
+ * Gets the name of the switch.
+ *
+ * The name serves as a unique identifier and in most cases it is not in a
+ * user-readable form.
+ *
+ * Returns: the name of the switch.
*/
const gchar *
mate_mixer_switch_get_name (MateMixerSwitch *swtch)
@@ -253,6 +260,13 @@ mate_mixer_switch_get_name (MateMixerSwitch *swtch)
/**
* mate_mixer_switch_get_label:
* @swtch: a #MateMixerSwitch
+ *
+ * Gets the label of the switch.
+ *
+ * This is a potentially translated string that should be presented to users
+ * in the user interface.
+ *
+ * Returns: the label of the switch option.
*/
const gchar *
mate_mixer_switch_get_label (MateMixerSwitch *swtch)
@@ -265,6 +279,11 @@ mate_mixer_switch_get_label (MateMixerSwitch *swtch)
/**
* mate_mixer_switch_get_flags:
* @swtch: a #MateMixerSwitch
+ *
+ * Gets the flags of the switch. See #MateMixerSwitchFlags for information about
+ * the meaning of the individual flags.
+ *
+ * Returns: the flags of the switch.
*/
MateMixerSwitchFlags
mate_mixer_switch_get_flags (MateMixerSwitch *swtch)
@@ -277,6 +296,11 @@ mate_mixer_switch_get_flags (MateMixerSwitch *swtch)
/**
* mate_mixer_switch_get_role:
* @swtch: a #MateMixerSwitch
+ *
+ * Gets the role of the switch. The role identifies the purpose of the switch.
+
+ * Note that while the role identification should be reliable, it may be based on
+ * looking for well-known switch names on some sound systems.
*/
MateMixerSwitchRole
mate_mixer_switch_get_role (MateMixerSwitch *swtch)
@@ -290,6 +314,10 @@ mate_mixer_switch_get_role (MateMixerSwitch *swtch)
* mate_mixer_switch_get_option:
* @swtch: a #MateMixerSwitch
* @name: the name of an option
+ *
+ * Gets the #MateMixerSwitchOption with the given name.
+ *
+ * Returns: a #MateMixerSwitchOption or %NULL if there is no such switch option.
*/
MateMixerSwitchOption *
mate_mixer_switch_get_option (MateMixerSwitch *swtch, const gchar *name)
@@ -302,6 +330,10 @@ mate_mixer_switch_get_option (MateMixerSwitch *swtch, const gchar *name)
/**
* mate_mixer_switch_get_active_option:
* @swtch: a #MateMixerSwitch
+ *
+ * Gets the #MateMixerSwitchOption which is currently active.
+ *
+ * Returns: a #MateMixerSwitchOption.
*/
MateMixerSwitchOption *
mate_mixer_switch_get_active_option (MateMixerSwitch *swtch)
@@ -315,6 +347,10 @@ mate_mixer_switch_get_active_option (MateMixerSwitch *swtch)
* mate_mixer_switch_set_active_option:
* @swtch: a #MateMixerSwitch
* @option: the #MateMixerSwitchOption to set as the active option
+ *
+ * Changes the currently active switch option.
+ *
+ * Returns: %TRUE on success or %FALSE on failure.
*/
gboolean
mate_mixer_switch_set_active_option (MateMixerSwitch *swtch,
@@ -338,6 +374,13 @@ mate_mixer_switch_set_active_option (MateMixerSwitch *swtch,
/**
* mate_mixer_switch_list_options:
* @swtch: a #MateMixerSwitch
+ *
+ * Gets the list of switch options that belong to the switch.
+ *
+ * The returned #GList is owned by the #MateMixerSwitch and may be invalidated
+ * at any time.
+ *
+ * Returns: a #GList of the switch options.
*/
const GList *
mate_mixer_switch_list_options (MateMixerSwitch *swtch)
diff --git a/libmatemixer/matemixer-toggle.c b/libmatemixer/matemixer-toggle.c
index 869807a..5a85076 100644
--- a/libmatemixer/matemixer-toggle.c
+++ b/libmatemixer/matemixer-toggle.c
@@ -24,6 +24,7 @@
/**
* SECTION:matemixer-toggle
+ * @short_description: On/Off switch
* @include: libmatemixer/matemixer.h
*/
@@ -80,6 +81,12 @@ mate_mixer_toggle_class_init (MateMixerToggleClass *klass)
switch_class->get_option = mate_mixer_toggle_get_option;
switch_class->list_options = mate_mixer_toggle_list_options;
+ /**
+ * MateMixerToggle:state:
+ *
+ * The current state of the toggle. %TRUE corresponds to the 'on' state and
+ * %FALSE to the 'off' state.
+ */
properties[PROP_STATE] =
g_param_spec_boolean ("state",
"State",
@@ -88,19 +95,29 @@ mate_mixer_toggle_class_init (MateMixerToggleClass *klass)
G_PARAM_READABLE |
G_PARAM_STATIC_STRINGS);
+ /**
+ * MateMixerToggle:on-state-option:
+ *
+ * The #MateMixerSwitchOption representing the 'on' value of the toggle.
+ */
properties[PROP_ON_STATE_OPTION] =
g_param_spec_object ("on-state-option",
- "State option for on",
- "Option corresponding to the 'on' value of the toggle",
+ "On state option",
+ "On state option",
MATE_MIXER_TYPE_SWITCH_OPTION,
G_PARAM_READWRITE |
G_PARAM_CONSTRUCT_ONLY |
G_PARAM_STATIC_STRINGS);
+ /**
+ * MateMixerToggle:off-state-option:
+ *
+ * The #MateMixerSwitchOption representing the 'off' value of the toggle.
+ */
properties[PROP_OFF_STATE_OPTION] =
g_param_spec_object ("off-state-option",
- "State option for off",
- "Option corresponding to the 'off' value of the toggle",
+ "Off state option",
+ "Off state option",
MATE_MIXER_TYPE_SWITCH_OPTION,
G_PARAM_READWRITE |
G_PARAM_CONSTRUCT_ONLY |
@@ -193,6 +210,11 @@ mate_mixer_toggle_dispose (GObject *object)
/**
* mate_mixer_toggle_get_state:
* @toggle: a #MateMixerToggle
+ *
+ * Gets the current state of the toggle. %TRUE corresponds to the 'on' state and
+ * %FALSE to the 'off' state.
+ *
+ * Returns: %TRUE or %FALSE.
*/
gboolean
mate_mixer_toggle_get_state (MateMixerToggle *toggle)
@@ -214,7 +236,11 @@ mate_mixer_toggle_get_state (MateMixerToggle *toggle)
/**
* mate_mixer_toggle_get_state_option:
* @toggle: a #MateMixerToggle
- * @state: the state to retrieve
+ * @state: the state to get the #MateMixerSwitchOption for
+ *
+ * Gets the #MateMixerSwitchOption representing the selected state.
+ *
+ * Returns: a #MateMixerSwitchOption.
*/
MateMixerSwitchOption *
mate_mixer_toggle_get_state_option (MateMixerToggle *toggle, gboolean state)
@@ -231,6 +257,13 @@ mate_mixer_toggle_get_state_option (MateMixerToggle *toggle, gboolean state)
* mate_mixer_toggle_set_state:
* @toggle: a #MateMixerToggle
* @state: the state to set
+ *
+ * Sets the @toggle to the selected state.
+ *
+ * This function is equivalent to using mate_mixer_switch_set_active_option()
+ * with a #MateMixerSwitchOption representing the selected state.
+ *
+ * Returns: %TRUE on success or %FALSE on failure.
*/
gboolean
mate_mixer_toggle_set_state (MateMixerToggle *toggle, gboolean state)
diff --git a/libmatemixer/matemixer.c b/libmatemixer/matemixer.c
index ce39ccc..51dc029 100644
--- a/libmatemixer/matemixer.c
+++ b/libmatemixer/matemixer.c
@@ -30,6 +30,15 @@
* @short_description: Library initialization and support functions
* @include: libmatemixer/matemixer.h
* @see_also: #MateMixerContext
+ *
+ * The libmatemixer library must be initialized before it is used by an
+ * application. The initialization function loads dynamic modules which provide
+ * access to sound systems (also called backends) and it only succeeds if there
+ * is at least one usable module present on the target system.
+ *
+ * To connect to a sound system and access the mixer functionality after the
+ * library is initialized, create a #MateMixerContext using the
+ * mate_mixer_context_new() function.
*/
static void load_modules (void);
@@ -100,14 +109,28 @@ mate_mixer_is_initialized (void)
return initialized;
}
-/* Internal: return a list of loaded backend modules */
+/**
+ * _mate_mixer_list_modules:
+ *
+ * Gets a list of loaded backend modules.
+ *
+ * Returns: a #GList.
+ */
const GList *
_mate_mixer_list_modules (void)
{
return (const GList *) modules;
}
-/* Internal: create a channel mask using the given list of channel positions */
+/**
+ * _mate_mixer_create_channel_mask:
+ * @positions: an array of channel positions
+ * @n: number of channel positions in the array
+ *
+ * Creates a channel mask using the given list of channel positions.
+ *
+ * Returns: a channel mask.
+ */
guint32
_mate_mixer_create_channel_mask (MateMixerChannelPosition *positions, guint n)
{
@@ -164,7 +187,8 @@ load_modules (void)
loaded = TRUE;
}
-/* Backend modules sorting function, higher priority number means higher priority */
+/* Backend modules sorting function, higher priority number means higher priority
+ * of the backend module */
static gint
compare_modules (gconstpointer a, gconstpointer b)
{