gsettings.h 20.7 KB
Newer Older
Allison Karlitskaya's avatar
Allison Karlitskaya committed
1 2 3 4 5 6
/*
 * 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
7
 * version 2.1 of the License, or (at your option) any later version.
Allison Karlitskaya's avatar
Allison Karlitskaya committed
8 9 10 11 12 13 14
 *
 * 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
15
 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
Allison Karlitskaya's avatar
Allison Karlitskaya committed
16 17 18 19
 *
 * Author: Ryan Lortie <desrt@desrt.ca>
 */

20 21 22
#ifndef __G_SETTINGS_H__
#define __G_SETTINGS_H__

23 24 25 26
#if !defined (__GIO_GIO_H_INSIDE__) && !defined (GIO_COMPILATION)
#error "Only <gio/gio.h> can be included directly."
#endif

27
#include <gio/gsettingsschema.h>
28
#include <gio/giotypes.h>
Allison Karlitskaya's avatar
Allison Karlitskaya committed
29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69

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;
};


70
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
71 72
GType                   g_settings_get_type                             (void);

73
GLIB_DEPRECATED_IN_2_40_FOR(g_settings_schema_source_list_schemas)
74
const gchar * const *   g_settings_list_schemas                         (void);
75
GLIB_DEPRECATED_IN_2_40_FOR(g_settings_schema_source_list_schemas)
76
const gchar * const *   g_settings_list_relocatable_schemas             (void);
77
GLIB_AVAILABLE_IN_ALL
78
GSettings *             g_settings_new                                  (const gchar        *schema_id);
79
GLIB_AVAILABLE_IN_ALL
80
GSettings *             g_settings_new_with_path                        (const gchar        *schema_id,
Allison Karlitskaya's avatar
Allison Karlitskaya committed
81
                                                                         const gchar        *path);
82
GLIB_AVAILABLE_IN_ALL
83
GSettings *             g_settings_new_with_backend                     (const gchar        *schema_id,
84
                                                                         GSettingsBackend   *backend);
85
GLIB_AVAILABLE_IN_ALL
86
GSettings *             g_settings_new_with_backend_and_path            (const gchar        *schema_id,
87
                                                                         GSettingsBackend   *backend,
Allison Karlitskaya's avatar
Allison Karlitskaya committed
88
                                                                         const gchar        *path);
89
GLIB_AVAILABLE_IN_2_32
90 91 92
GSettings *             g_settings_new_full                             (GSettingsSchema    *schema,
                                                                         GSettingsBackend   *backend,
                                                                         const gchar        *path);
93
GLIB_AVAILABLE_IN_ALL
94
gchar **                g_settings_list_children                        (GSettings          *settings);
95
GLIB_DEPRECATED_IN_2_46_FOR(g_settings_schema_list_keys)
96
gchar **                g_settings_list_keys                            (GSettings          *settings);
97
GLIB_DEPRECATED_IN_2_40_FOR(g_settings_schema_key_get_range)
98 99
GVariant *              g_settings_get_range                            (GSettings          *settings,
                                                                         const gchar        *key);
100
GLIB_DEPRECATED_IN_2_40_FOR(g_settings_schema_key_range_check)
101 102 103
gboolean                g_settings_range_check                          (GSettings          *settings,
                                                                         const gchar        *key,
                                                                         GVariant           *value);
104

105
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
106 107 108
gboolean                g_settings_set_value                            (GSettings          *settings,
                                                                         const gchar        *key,
                                                                         GVariant           *value);
109
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
110 111 112
GVariant *              g_settings_get_value                            (GSettings          *settings,
                                                                         const gchar        *key);

113 114 115 116 117 118 119
GLIB_AVAILABLE_IN_2_40
GVariant *              g_settings_get_user_value                       (GSettings          *settings,
                                                                         const gchar        *key);
GLIB_AVAILABLE_IN_2_40
GVariant *              g_settings_get_default_value                    (GSettings          *settings,
                                                                         const gchar        *key);

120
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
121 122 123 124
gboolean                g_settings_set                                  (GSettings          *settings,
                                                                         const gchar        *key,
                                                                         const gchar        *format,
                                                                         ...);
125
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
126 127 128 129
void                    g_settings_get                                  (GSettings          *settings,
                                                                         const gchar        *key,
                                                                         const gchar        *format,
                                                                         ...);
130
GLIB_AVAILABLE_IN_ALL
131 132
void                    g_settings_reset                                (GSettings          *settings,
                                                                         const gchar        *key);
Allison Karlitskaya's avatar
Allison Karlitskaya committed
133

134
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
135 136
gint                    g_settings_get_int                              (GSettings          *settings,
                                                                         const gchar        *key);
137
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
138 139 140
gboolean                g_settings_set_int                              (GSettings          *settings,
                                                                         const gchar        *key,
                                                                         gint                value);
141 142 143 144 145 146 147
GLIB_AVAILABLE_IN_2_50
gint64                  g_settings_get_int64                            (GSettings          *settings,
                                                                         const gchar        *key);
GLIB_AVAILABLE_IN_2_50
gboolean                g_settings_set_int64                            (GSettings          *settings,
                                                                         const gchar        *key,
                                                                         gint64              value);
148
GLIB_AVAILABLE_IN_2_32
149 150
guint                   g_settings_get_uint                             (GSettings          *settings,
                                                                         const gchar        *key);
151
GLIB_AVAILABLE_IN_2_32
152 153 154
gboolean                g_settings_set_uint                             (GSettings          *settings,
                                                                         const gchar        *key,
                                                                         guint               value);
155 156 157 158 159 160 161
GLIB_AVAILABLE_IN_2_50
guint64                 g_settings_get_uint64                           (GSettings          *settings,
                                                                         const gchar        *key);
GLIB_AVAILABLE_IN_2_50
gboolean                g_settings_set_uint64                           (GSettings          *settings,
                                                                         const gchar        *key,
                                                                         guint64             value);
162
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
163 164
gchar *                 g_settings_get_string                           (GSettings          *settings,
                                                                         const gchar        *key);
165
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
166 167 168
gboolean                g_settings_set_string                           (GSettings          *settings,
                                                                         const gchar        *key,
                                                                         const gchar        *value);
169
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
170 171
gboolean                g_settings_get_boolean                          (GSettings          *settings,
                                                                         const gchar        *key);
172
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
173 174 175
gboolean                g_settings_set_boolean                          (GSettings          *settings,
                                                                         const gchar        *key,
                                                                         gboolean            value);
176
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
177 178
gdouble                 g_settings_get_double                           (GSettings          *settings,
                                                                         const gchar        *key);
179
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
180 181 182
gboolean                g_settings_set_double                           (GSettings          *settings,
                                                                         const gchar        *key,
                                                                         gdouble             value);
183
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
184
gchar **                g_settings_get_strv                             (GSettings          *settings,
185
                                                                         const gchar        *key);
186
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
187 188
gboolean                g_settings_set_strv                             (GSettings          *settings,
                                                                         const gchar        *key,
189
                                                                         const gchar *const *value);
190
GLIB_AVAILABLE_IN_ALL
191 192
gint                    g_settings_get_enum                             (GSettings          *settings,
                                                                         const gchar        *key);
193
GLIB_AVAILABLE_IN_ALL
194 195 196
gboolean                g_settings_set_enum                             (GSettings          *settings,
                                                                         const gchar        *key,
                                                                         gint                value);
197
GLIB_AVAILABLE_IN_ALL
198 199
guint                   g_settings_get_flags                            (GSettings          *settings,
                                                                         const gchar        *key);
200
GLIB_AVAILABLE_IN_ALL
201 202 203
gboolean                g_settings_set_flags                            (GSettings          *settings,
                                                                         const gchar        *key,
                                                                         guint               value);
204
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
205 206 207
GSettings *             g_settings_get_child                            (GSettings          *settings,
                                                                         const gchar        *name);

208
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
209 210 211
gboolean                g_settings_is_writable                          (GSettings          *settings,
                                                                         const gchar        *name);

212
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
213
void                    g_settings_delay                                (GSettings          *settings);
214
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
215
void                    g_settings_apply                                (GSettings          *settings);
216
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
217
void                    g_settings_revert                               (GSettings          *settings);
218
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
219
gboolean                g_settings_get_has_unapplied                    (GSettings          *settings);
220
GLIB_AVAILABLE_IN_ALL
221
void                    g_settings_sync                                 (void);
Allison Karlitskaya's avatar
Allison Karlitskaya committed
222 223 224 225 226 227 228 229 230

/**
 * 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.
231 232 233
 *
 * Returns: a new #GVariant holding the data from @value,
 *     or %NULL in case of an error
Allison Karlitskaya's avatar
Allison Karlitskaya committed
234 235 236 237 238 239 240 241 242 243 244 245 246 247
 */
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.
248 249
 *
 * Returns: %TRUE if the conversion succeeded, %FALSE in case of an error
Allison Karlitskaya's avatar
Allison Karlitskaya committed
250 251 252 253 254
 */
typedef gboolean      (*GSettingsBindGetMapping)                        (GValue             *value,
                                                                         GVariant           *variant,
                                                                         gpointer            user_data);

255 256 257
/**
 * GSettingsGetMapping:
 * @value: the #GVariant to map, or %NULL
258 259 260
 * @result: (out): the result of the mapping
 * @user_data: (closure): the user data that was passed to
 * g_settings_get_mapped()
261 262 263 264 265 266 267 268 269 270 271
 *
 * 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.
272 273
 *
 * Returns: %TRUE if the conversion succeeded, %FALSE in case of an error
274 275 276 277 278
 **/
typedef gboolean      (*GSettingsGetMapping)                            (GVariant           *value,
                                                                         gpointer           *result,
                                                                         gpointer            user_data);

Allison Karlitskaya's avatar
Allison Karlitskaya committed
279 280
/**
 * GSettingsBindFlags:
281
 * @G_SETTINGS_BIND_DEFAULT: Equivalent to `G_SETTINGS_BIND_GET|G_SETTINGS_BIND_SET`
282 283 284 285
 * @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.
286 287 288
 * @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
289 290
 * @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
291
 *     be booleans.  You cannot pass this flag to g_settings_bind_with_mapping().
Allison Karlitskaya's avatar
Allison Karlitskaya committed
292 293 294 295 296 297 298 299 300 301 302
 *
 * 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),
303 304
  G_SETTINGS_BIND_GET_NO_CHANGES = (1<<3),
  G_SETTINGS_BIND_INVERT_BOOLEAN = (1<<4)
Allison Karlitskaya's avatar
Allison Karlitskaya committed
305 306
} GSettingsBindFlags;

307
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
308 309 310 311 312
void                    g_settings_bind                                 (GSettings               *settings,
                                                                         const gchar             *key,
                                                                         gpointer                 object,
                                                                         const gchar             *property,
                                                                         GSettingsBindFlags       flags);
313
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
314 315 316 317 318 319 320 321 322
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);
323
GLIB_AVAILABLE_IN_ALL
324 325 326 327 328
void                    g_settings_bind_writable                        (GSettings               *settings,
                                                                         const gchar             *key,
                                                                         gpointer                 object,
                                                                         const gchar             *property,
                                                                         gboolean                 inverted);
329
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
330 331 332
void                    g_settings_unbind                               (gpointer                 object,
                                                                         const gchar             *property);

333
GLIB_AVAILABLE_IN_2_32
334 335 336
GAction *               g_settings_create_action                        (GSettings               *settings,
                                                                         const gchar             *key);

337
GLIB_AVAILABLE_IN_ALL
338 339 340 341 342
gpointer                g_settings_get_mapped                           (GSettings               *settings,
                                                                         const gchar             *key,
                                                                         GSettingsGetMapping      mapping,
                                                                         gpointer                 user_data);

Allison Karlitskaya's avatar
Allison Karlitskaya committed
343 344 345
G_END_DECLS

#endif  /* __G_SETTINGS_H__ */