luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-07-06 10:47:00 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'settings-docs' into 'main'

Browse Source 
gsettings: Port docs to gi-docgen format, add missing annotations and make various improvements

See merge request GNOME/glib!4541
This commit is contained in:
Philip Withnall 2025-03-19 20:18:34 +00:00
commit 88e8ee515c
2 changed files with 398 additions and 354 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

676
gio/gsettings.c
View File

File diff suppressed because it is too large Load Diff

58
gio/gsettings.h
View File

@ -224,15 +224,15 @@ void g_settings_sync (void);
/** /**
* GSettingsBindSetMapping: * GSettingsBindSetMapping:
* @value: a #GValue containing the property value to map * @value: the property value to map
* @expected_type: the #GVariantType to create * @expected_type: expected type of the result
* @user_data: user data that was specified when the binding was created * @user_data: user data that was specified when the binding was created
* *
* The type for the function that is used to convert an object property * The type for the function that is used to convert an object property
* value to a #GVariant for storing it in #GSettings. * value to a [struct@GLib.Variant] for storing it in [class@Gio.Settings].
* *
* Returns: a new #GVariant holding the data from @value, * Returns: (nullable): a new [struct@GLib.Variant] holding the data from @value,
* or %NULL in case of an error * or `NULL` in case of an error
*/ */
typedef GVariant * (*GSettingsBindSetMapping) (const GValue *value, typedef GVariant * (*GSettingsBindSetMapping) (const GValue *value,
const GVariantType *expected_type, const GVariantType *expected_type,
@ -241,14 +241,15 @@ typedef GVariant * (*GSettingsBindSetMapping) (const G
/** /**
* GSettingsBindGetMapping: * GSettingsBindGetMapping:
* @value: return location for the property value * @value: return location for the property value
* @variant: the #GVariant * @variant: variant to map to the property value
* @user_data: user data that was specified when the binding was created * @user_data: user data that was specified when the binding was created
* *
* The type for the function that is used to convert from #GSettings to * The type for the function that is used to convert from [class@Gio.Settings]
* an object property. The @value is already initialized to hold values * to an object property.
* of the appropriate type.
* *
* Returns: %TRUE if the conversion succeeded, %FALSE in case of an error * The @value is already initialized to hold values of the appropriate type.
*
* Returns: true if the conversion succeeded, false in case of an error
*/ */
typedef gboolean (*GSettingsBindGetMapping) (GValue *value, typedef gboolean (*GSettingsBindGetMapping) (GValue *value,
GVariant *variant, GVariant *variant,
@ -256,23 +257,23 @@ typedef gboolean (*GSettingsBindGetMapping) (GValue
/** /**
* GSettingsGetMapping: * GSettingsGetMapping:
* @value: the #GVariant to map, or %NULL * @value: (nullable): variant to map to the application value
* @result: (out): the result of the mapping * @result: (out): the result of the mapping
* @user_data: (closure): the user data that was passed to * @user_data: (closure): the user data that was passed to
* g_settings_get_mapped() * [method@Gio.Settings.get_mapped]
* *
* The type of the function that is used to convert from a value stored * The type of the function that is used to convert from a value stored
* in a #GSettings to a value that is useful to the application. * in a [class@Gio.Settings] to a value that is useful to the application.
* *
* If the value is successfully mapped, the result should be stored at * If the value is successfully mapped, the result should be stored at
* @result and %TRUE returned. If mapping fails (for example, if @value * @result and true returned. If mapping fails (for example, if @value
* is not in the right format) then %FALSE should be returned. * is not in the right format) then false should be returned.
* *
* If @value is %NULL then it means that the mapping function is being * If @value is `NULL` then it means that the mapping function is being
* given a "last chance" to successfully return a valid value. %TRUE * given a ‘last chance’ to successfully return a valid value. True
* must be returned in this case. * must be returned in this case.
* *
* Returns: %TRUE if the conversion succeeded, %FALSE in case of an error * Returns: true if the conversion succeeded, false in case of an error
**/ **/
typedef gboolean (*GSettingsGetMapping) (GVariant *value, typedef gboolean (*GSettingsGetMapping) (GVariant *value,
gpointer *result, gpointer *result,
@ -281,20 +282,23 @@ typedef gboolean (*GSettingsGetMapping) (GVarian
/** /**
* GSettingsBindFlags: * GSettingsBindFlags:
* @G_SETTINGS_BIND_DEFAULT: Equivalent to `G_SETTINGS_BIND_GET|G_SETTINGS_BIND_SET` * @G_SETTINGS_BIND_DEFAULT: Equivalent to `G_SETTINGS_BIND_GET|G_SETTINGS_BIND_SET`
* @G_SETTINGS_BIND_GET: Update the #GObject property when the setting changes. * @G_SETTINGS_BIND_GET: Update the [class@GObject.Object] property when the setting changes.
* It is an error to use this flag if the property is not writable. * It is an error to use this flag if the property is not writable.
* @G_SETTINGS_BIND_SET: Update the setting when the #GObject property changes. * @G_SETTINGS_BIND_SET: Update the setting when the [class@GObject.Object] property changes.
* It is an error to use this flag if the property is not readable. * It is an error to use this flag if the property is not readable.
* @G_SETTINGS_BIND_NO_SENSITIVITY: Do not try to bind a "sensitivity" property to the writability of the setting * @G_SETTINGS_BIND_NO_SENSITIVITY: Do not try to bind a ‘sensitivity’ property to the writability of the setting
* @G_SETTINGS_BIND_GET_NO_CHANGES: When set in addition to %G_SETTINGS_BIND_GET, set the #GObject property * @G_SETTINGS_BIND_GET_NO_CHANGES: When set in addition to [flags@Gio.SettingsBindFlags.GET],
* set the [class@GObject.Object] property
* value initially from the setting, but do not listen for changes of the setting * value initially from the setting, but do not listen for changes of the setting
* @G_SETTINGS_BIND_INVERT_BOOLEAN: When passed to g_settings_bind(), uses a pair of mapping functions that invert * @G_SETTINGS_BIND_INVERT_BOOLEAN: When passed to [method@Gio.Settings.bind],
* uses a pair of mapping functions that invert
* the boolean value when mapping between the setting and the property. The setting and property must both * the boolean value when mapping between the setting and the property. The setting and property must both
* be booleans. You cannot pass this flag to g_settings_bind_with_mapping(). * be booleans. You cannot pass this flag to [method@Gio.Settings.bind_with_mapping].
* *
* Flags used when creating a binding. These flags determine in which * Flags used when creating a binding.
* direction the binding works. The default is to synchronize in both *
* directions. * These flags determine in which direction the binding works. The default is to
* synchronize in both directions.
*/ */
typedef enum typedef enum
{ {