luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-11-05 00:46:16 +01:00
Code Issues Packages Projects Releases Wiki Activity
330c6c116e
glib/gio/gsettings.h

283 lines
18 KiB
C
Raw Normal View History

merge GSettings
2010-04-17 05:17:01 +02:00
/*
* Copyright © 2009, 2010 Codethink Limited
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2 of the licence, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA.
*
* Author: Ryan Lortie <desrt@desrt.ca>
*/
Move single-include guards inside include guards gcc has optimizations for include guards that only work if they are outermost in the the header. https://bugzilla.gnome.org/show_bug.cgi?id=689810
2012-12-28 05:43:14 +01:00
#ifndef __G_SETTINGS_H__
#define __G_SETTINGS_H__
Add single-include guards to new headers As pointed out by Christian Persch in bug 620173, all the new gdbus and gsettings headers were missing these.
2010-06-06 22:20:21 +02:00
#if !defined (__GIO_GIO_H_INSIDE__) && !defined (GIO_COMPILATION)
#error "Only <gio/gio.h> can be included directly."
#endif
Add g_settings_new_full() taking GSettingsSchema
2011-11-15 13:38:01 +01:00
#include <gio/gsettingsschema.h>
move GSettings(Backend) to giotypes.h
2010-06-17 00:49:20 +02:00
#include <gio/giotypes.h>
merge GSettings
2010-04-17 05:17:01 +02:00
G_BEGIN_DECLS
#define G_TYPE_SETTINGS (g_settings_get_type ())
#define G_SETTINGS(inst) (G_TYPE_CHECK_INSTANCE_CAST ((inst), \
G_TYPE_SETTINGS, GSettings))
#define G_SETTINGS_CLASS(class) (G_TYPE_CHECK_CLASS_CAST ((class), \
G_TYPE_SETTINGS, GSettingsClass))
#define G_IS_SETTINGS(inst) (G_TYPE_CHECK_INSTANCE_TYPE ((inst), G_TYPE_SETTINGS))
#define G_IS_SETTINGS_CLASS(class) (G_TYPE_CHECK_CLASS_TYPE ((class), G_TYPE_SETTINGS))
#define G_SETTINGS_GET_CLASS(inst) (G_TYPE_INSTANCE_GET_CLASS ((inst), \
G_TYPE_SETTINGS, GSettingsClass))
typedef struct _GSettingsPrivate GSettingsPrivate;
typedef struct _GSettingsClass GSettingsClass;
struct _GSettingsClass
{
GObjectClass parent_class;
/* Signals */
void (*writable_changed) (GSettings *settings,
const gchar *key);
void (*changed) (GSettings *settings,
const gchar *key);
gboolean (*writable_change_event) (GSettings *settings,
GQuark key);
gboolean (*change_event) (GSettings *settings,
const GQuark *keys,
gint n_keys);
gpointer padding[20];
};
struct _GSettings
{
GObject parent_instance;
GSettingsPrivate *priv;
};
GType g_settings_get_type (void);
Tweak GSettings key/schema listing APIs
2010-06-24 18:25:48 +02:00
const gchar * const * g_settings_list_schemas (void);
Clean up g_settings_list_schemas() In its previous form, g_settings_list_schemas() was not useful as a tool to prevent aborts due to using g_settings_new() with an invalid schema name. This is because g_settings_list_scheams() also listed relocatable schemas, and calling g_settings_new() for those would abort just the same as if you called it for a non-existent schema. Modify g_settings_list_schemas() so that it only returns schemas for which it is safe to call g_settings_new(). Add another call for sake of completeness: g_settings_list_relocatable_schemas().
2010-10-03 04:42:02 +02:00
const gchar * const * g_settings_list_relocatable_schemas (void);
Clarify docs/params for 'schema' vs 'schema id' Clean up our parameter naming and documentation to draw a clearer line between a schema and its identifier.
2011-11-15 13:42:02 +01:00
GSettings * g_settings_new (const gchar *schema_id);
GSettings * g_settings_new_with_path (const gchar *schema_id,
merge GSettings
2010-04-17 05:17:01 +02:00
const gchar *path);
Clarify docs/params for 'schema' vs 'schema id' Clean up our parameter naming and documentation to draw a clearer line between a schema and its identifier.
2011-11-15 13:42:02 +01:00
GSettings * g_settings_new_with_backend (const gchar *schema_id,
Bug 621266 - GSettings "context" clarification Remove the concept of "context" in favour of dealing with GSettingsBackend directly.
2010-06-17 20:05:40 +02:00
GSettingsBackend *backend);
Clarify docs/params for 'schema' vs 'schema id' Clean up our parameter naming and documentation to draw a clearer line between a schema and its identifier.
2011-11-15 13:42:02 +01:00
GSettings * g_settings_new_with_backend_and_path (const gchar *schema_id,
Bug 621266 - GSettings "context" clarification Remove the concept of "context" in favour of dealing with GSettingsBackend directly.
2010-06-17 20:05:40 +02:00
GSettingsBackend *backend,
merge GSettings
2010-04-17 05:17:01 +02:00
const gchar *path);
Annotate API introduced for 2.32 with GLIB_AVAILABLE_IN_2_32 https://bugzilla.gnome.org/show_bug.cgi?id=676816
2012-05-25 14:59:09 +02:00
GLIB_AVAILABLE_IN_2_32
Add g_settings_new_full() taking GSettingsSchema
2011-11-15 13:38:01 +01:00
GSettings * g_settings_new_full (GSettingsSchema *schema,
GSettingsBackend *backend,
const gchar *path);
split GSettings.list_items => list_{children,keys} This is an incompatible public API/ABI change.
2010-09-06 18:47:37 +02:00
gchar ** g_settings_list_children (GSettings *settings);
gchar ** g_settings_list_keys (GSettings *settings);
Bug 631263 - GSettings needs range/choice APIs Add g_settings_get_range() to describe the possible values that may be provided to g_settings_set_value() without causing an error. Add a test case.
2010-10-04 08:58:46 +02:00
GVariant * g_settings_get_range (GSettings *settings,
const gchar *key);
GSettings: add g_settings_range_check() API Checks if a given value is within the correct range for a key.
2010-10-04 09:33:06 +02:00
gboolean g_settings_range_check (GSettings *settings,
const gchar *key,
GVariant *value);
split GSettings.list_items => list_{children,keys} This is an incompatible public API/ABI change.
2010-09-06 18:47:37 +02:00
merge GSettings
2010-04-17 05:17:01 +02:00
gboolean g_settings_set_value (GSettings *settings,
const gchar *key,
GVariant *value);
GVariant * g_settings_get_value (GSettings *settings,
const gchar *key);
gboolean g_settings_set (GSettings *settings,
const gchar *key,
const gchar *format,
...);
void g_settings_get (GSettings *settings,
const gchar *key,
const gchar *format,
...);
GSettings: add g_settings_reset() Resets a key to its default value.
2010-07-22 23:49:40 +02:00
void g_settings_reset (GSettings *settings,
const gchar *key);
merge GSettings
2010-04-17 05:17:01 +02:00
gint g_settings_get_int (GSettings *settings,
const gchar *key);
gboolean g_settings_set_int (GSettings *settings,
const gchar *key,
gint value);
Add 'uint' convenience functions for GSettings Without getting into a debate about the reasons why you may or may not want to use unsigned integers, it's sufficient to note that people have been using them and requesting this functionality. Bug #641755.
2011-03-31 09:14:40 +02:00
guint g_settings_get_uint (GSettings *settings,
const gchar *key);
gboolean g_settings_set_uint (GSettings *settings,
const gchar *key,
guint value);
merge GSettings
2010-04-17 05:17:01 +02:00
gchar * g_settings_get_string (GSettings *settings,
const gchar *key);
gboolean g_settings_set_string (GSettings *settings,
const gchar *key,
const gchar *value);
gboolean g_settings_get_boolean (GSettings *settings,
const gchar *key);
gboolean g_settings_set_boolean (GSettings *settings,
const gchar *key,
gboolean value);
gdouble g_settings_get_double (GSettings *settings,
const gchar *key);
gboolean g_settings_set_double (GSettings *settings,
const gchar *key,
gdouble value);
gchar ** g_settings_get_strv (GSettings *settings,
Remove length parameter for g_settings_[gs]et_strv Length of the array is redundant since it's NULL-terminated. This is not consistent with many GLib and GTK+ functions, and adds complexity with no real gain, while these convenience functions should be kept simple. Closes bug #620312
2010-06-01 23:16:19 +02:00
const gchar *key);
merge GSettings
2010-04-17 05:17:01 +02:00
gboolean g_settings_set_strv (GSettings *settings,
const gchar *key,
Remove length parameter for g_settings_[gs]et_strv Length of the array is redundant since it's NULL-terminated. This is not consistent with many GLib and GTK+ functions, and adds complexity with no real gain, while these convenience functions should be kept simple. Closes bug #620312
2010-06-01 23:16:19 +02:00
const gchar *const *value);
GSettings: major refactor. Add enums, range.
2010-06-14 23:29:41 +02:00
gint g_settings_get_enum (GSettings *settings,
const gchar *key);
gboolean g_settings_set_enum (GSettings *settings,
const gchar *key,
gint value);
Bug 622124 - implement flags for GSettings Add a <flags> tag to the schema file format and a flags='' attribute to go along with. Add some extra test cases for those. Add new g_settings_{get,set}_flags() calls and support binding to GParamSpecFlags properties. Add test cases.
2010-07-02 00:58:56 +02:00
guint g_settings_get_flags (GSettings *settings,
const gchar *key);
gboolean g_settings_set_flags (GSettings *settings,
const gchar *key,
guint value);
merge GSettings
2010-04-17 05:17:01 +02:00
GSettings * g_settings_get_child (GSettings *settings,
const gchar *name);
gboolean g_settings_is_writable (GSettings *settings,
const gchar *name);
void g_settings_delay (GSettings *settings);
void g_settings_apply (GSettings *settings);
void g_settings_revert (GSettings *settings);
gboolean g_settings_get_has_unapplied (GSettings *settings);
Make g_settings_sync() a proper prototype.
2010-06-17 22:56:09 +02:00
void g_settings_sync (void);
merge GSettings
2010-04-17 05:17:01 +02:00
/**
* GSettingsBindSetMapping:
* @value: a #GValue containing the property value to map
* @expected_type: the #GVariantType to create
* @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
* value to a #GVariant for storing it in #GSettings.
Drop last uses of @returns:
2011-11-21 18:02:02 +01:00
*
* Returns: a new #GVariant holding the data from @value,
* or %NULL in case of an error
merge GSettings
2010-04-17 05:17:01 +02:00
*/
typedef GVariant * (*GSettingsBindSetMapping) (const GValue *value,
const GVariantType *expected_type,
gpointer user_data);
/**
* GSettingsBindGetMapping:
* @value: return location for the property value
* @variant: the #GVariant
* @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
* an object property. The @value is already initialized to hold values
* of the appropriate type.
Drop last uses of @returns:
2011-11-21 18:02:02 +01:00
*
* Returns: %TRUE if the conversion succeeded, %FALSE in case of an error
merge GSettings
2010-04-17 05:17:01 +02:00
*/
typedef gboolean (*GSettingsBindGetMapping) (GValue *value,
GVariant *variant,
gpointer user_data);
Bug 622127 - GSettings extended key validation First shot at attempting to implement this in a reasonable way. See the bug for more information about why this is needed.
2010-06-28 16:18:45 +02:00
/**
* GSettingsGetMapping:
* @value: the #GVariant to map, or %NULL
Add and update GI annotations in 'Settings' 'Settings' GIO group contains GSettings and GSettingsBackend.
2011-01-07 09:38:35 +01:00
* @result: (out): the result of the mapping
* @user_data: (closure): the user data that was passed to
* g_settings_get_mapped()
Bug 622127 - GSettings extended key validation First shot at attempting to implement this in a reasonable way. See the bug for more information about why this is needed.
2010-06-28 16:18:45 +02:00
*
* 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.
*
* If the value is successfully mapped, the result should be stored at
* @result and %TRUE returned. If mapping fails (for example, if @value
* is not in the right format) then %FALSE should be returned.
*
* If @value is %NULL then it means that the mapping function is being
* given a "last chance" to successfully return a valid value. %TRUE
* must be returned in this case.
Drop last uses of @returns:
2011-11-21 18:02:02 +01:00
*
* Returns: %TRUE if the conversion succeeded, %FALSE in case of an error
Bug 622127 - GSettings extended key validation First shot at attempting to implement this in a reasonable way. See the bug for more information about why this is needed.
2010-06-28 16:18:45 +02:00
**/
typedef gboolean (*GSettingsGetMapping) (GVariant *value,
gpointer *result,
gpointer user_data);
merge GSettings
2010-04-17 05:17:01 +02:00
/**
* GSettingsBindFlags:
* @G_SETTINGS_BIND_DEFAULT: Equivalent to <literal>G_SETTINGS_BIND_GET|G_SETTINGS_BIND_SET</literal>
Handle non-readable/-writable properties when binding And document readability/writability requirements for binding flags.
2010-04-21 18:31:33 +02:00
* @G_SETTINGS_BIND_GET: Update the #GObject property when the setting changes.
* 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.
* It is an error to use this flag if the property is not readable.
Document G_SETTINGS_BIND_GET_NO_CHANGES
2010-04-17 06:16:01 +02:00
* @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
* value initially from the setting, but do not listen for changes of the setting
GSettings: add G_SETTINGS_BIND_INVERT_BOOLEAN flag When binding a boolean setting to a boolean property, invert the values. This avoids the requirement for writing a pair of mapping functions for this extremely common case. Add a test. https://bugzilla.gnome.org/show_bug.cgi?id=625833
2010-08-03 08:08:03 +02:00
* @G_SETTINGS_BIND_INVERT_BOOLEAN: When passed to g_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
Docs: Changed can not to cannot.
2011-03-24 09:33:55 +01:00
* be booleans. You cannot pass this flag to g_settings_bind_with_mapping().
merge GSettings
2010-04-17 05:17:01 +02:00
*
* Flags used when creating a binding. These flags determine in which
* direction the binding works. The default is to synchronize in both
* directions.
*/
typedef enum
{
G_SETTINGS_BIND_DEFAULT,
G_SETTINGS_BIND_GET = (1<<0),
G_SETTINGS_BIND_SET = (1<<1),
G_SETTINGS_BIND_NO_SENSITIVITY = (1<<2),
GSettings: add G_SETTINGS_BIND_INVERT_BOOLEAN flag When binding a boolean setting to a boolean property, invert the values. This avoids the requirement for writing a pair of mapping functions for this extremely common case. Add a test. https://bugzilla.gnome.org/show_bug.cgi?id=625833
2010-08-03 08:08:03 +02:00
G_SETTINGS_BIND_GET_NO_CHANGES = (1<<3),
G_SETTINGS_BIND_INVERT_BOOLEAN = (1<<4)
merge GSettings
2010-04-17 05:17:01 +02:00
} GSettingsBindFlags;
void g_settings_bind (GSettings *settings,
const gchar *key,
gpointer object,
const gchar *property,
GSettingsBindFlags flags);
void g_settings_bind_with_mapping (GSettings *settings,
const gchar *key,
gpointer object,
const gchar *property,
GSettingsBindFlags flags,
GSettingsBindGetMapping get_mapping,
GSettingsBindSetMapping set_mapping,
gpointer user_data,
GDestroyNotify destroy);
GSettings: bind to writablity of a key
2010-04-20 18:30:12 +02:00
void g_settings_bind_writable (GSettings *settings,
const gchar *key,
gpointer object,
const gchar *property,
gboolean inverted);
merge GSettings
2010-04-17 05:17:01 +02:00
void g_settings_unbind (gpointer object,
const gchar *property);
Annotate API introduced for 2.32 with GLIB_AVAILABLE_IN_2_32 https://bugzilla.gnome.org/show_bug.cgi?id=676816
2012-05-25 14:59:09 +02:00
GLIB_AVAILABLE_IN_2_32
add a way to create a GAction from GSettings g_settings_create_action() will create a GAction for the named key, allowing it to be added to the action group of the application (so that the setting can be directly manipulated from menus, for example). https://bugzilla.gnome.org/show_bug.cgi?id=668279
2012-01-19 15:40:24 +01:00
GAction * g_settings_create_action (GSettings *settings,
const gchar *key);
Bug 622127 - GSettings extended key validation First shot at attempting to implement this in a reasonable way. See the bug for more information about why this is needed.
2010-06-28 16:18:45 +02:00
gpointer g_settings_get_mapped (GSettings *settings,
const gchar *key,
GSettingsGetMapping mapping,
gpointer user_data);
merge GSettings
2010-04-17 05:17:01 +02:00
G_END_DECLS
#endif /* __G_SETTINGS_H__ */
Reference in New Issue Copy Permalink