diff options
| -rw-r--r-- | docs/reference/libmatemixer-sections.txt | 20 | ||||
| -rw-r--r-- | libmatemixer/matemixer-context.c | 60 | ||||
| -rw-r--r-- | libmatemixer/matemixer-device.c | 19 | ||||
| -rw-r--r-- | libmatemixer/matemixer-enums.h | 33 | ||||
| -rw-r--r-- | libmatemixer/matemixer-switch-option.c | 35 | ||||
| -rw-r--r-- | libmatemixer/matemixer-switch.c | 43 | ||||
| -rw-r--r-- | libmatemixer/matemixer-toggle.c | 43 | ||||
| -rw-r--r-- | libmatemixer/matemixer.c | 30 |
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) { |