gsettings.h 19 KB
Newer Older
Allison Karlitskaya's avatar
Allison Karlitskaya committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
/*
 * 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>
 */

22 23 24
#ifndef __G_SETTINGS_H__
#define __G_SETTINGS_H__

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

29
#include <gio/gsettingsschema.h>
30
#include <gio/giotypes.h>
Allison Karlitskaya's avatar
Allison Karlitskaya committed
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 70 71

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


72
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
73 74
GType                   g_settings_get_type                             (void);

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

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

115
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
116 117 118 119
gboolean                g_settings_set                                  (GSettings          *settings,
                                                                         const gchar        *key,
                                                                         const gchar        *format,
                                                                         ...);
120
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
121 122 123 124
void                    g_settings_get                                  (GSettings          *settings,
                                                                         const gchar        *key,
                                                                         const gchar        *format,
                                                                         ...);
125
GLIB_AVAILABLE_IN_ALL
126 127
void                    g_settings_reset                                (GSettings          *settings,
                                                                         const gchar        *key);
Allison Karlitskaya's avatar
Allison Karlitskaya committed
128

129
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
130 131
gint                    g_settings_get_int                              (GSettings          *settings,
                                                                         const gchar        *key);
132
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
133 134 135
gboolean                g_settings_set_int                              (GSettings          *settings,
                                                                         const gchar        *key,
                                                                         gint                value);
136
GLIB_AVAILABLE_IN_2_32
137 138
guint                   g_settings_get_uint                             (GSettings          *settings,
                                                                         const gchar        *key);
139
GLIB_AVAILABLE_IN_2_32
140 141 142
gboolean                g_settings_set_uint                             (GSettings          *settings,
                                                                         const gchar        *key,
                                                                         guint               value);
143
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
144 145
gchar *                 g_settings_get_string                           (GSettings          *settings,
                                                                         const gchar        *key);
146
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
147 148 149
gboolean                g_settings_set_string                           (GSettings          *settings,
                                                                         const gchar        *key,
                                                                         const gchar        *value);
150
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
151 152
gboolean                g_settings_get_boolean                          (GSettings          *settings,
                                                                         const gchar        *key);
153
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
154 155 156
gboolean                g_settings_set_boolean                          (GSettings          *settings,
                                                                         const gchar        *key,
                                                                         gboolean            value);
157
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
158 159
gdouble                 g_settings_get_double                           (GSettings          *settings,
                                                                         const gchar        *key);
160
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
161 162 163
gboolean                g_settings_set_double                           (GSettings          *settings,
                                                                         const gchar        *key,
                                                                         gdouble             value);
164
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
165
gchar **                g_settings_get_strv                             (GSettings          *settings,
166
                                                                         const gchar        *key);
167
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
168 169
gboolean                g_settings_set_strv                             (GSettings          *settings,
                                                                         const gchar        *key,
170
                                                                         const gchar *const *value);
171
GLIB_AVAILABLE_IN_ALL
172 173
gint                    g_settings_get_enum                             (GSettings          *settings,
                                                                         const gchar        *key);
174
GLIB_AVAILABLE_IN_ALL
175 176 177
gboolean                g_settings_set_enum                             (GSettings          *settings,
                                                                         const gchar        *key,
                                                                         gint                value);
178
GLIB_AVAILABLE_IN_ALL
179 180
guint                   g_settings_get_flags                            (GSettings          *settings,
                                                                         const gchar        *key);
181
GLIB_AVAILABLE_IN_ALL
182 183 184
gboolean                g_settings_set_flags                            (GSettings          *settings,
                                                                         const gchar        *key,
                                                                         guint               value);
185
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
186 187 188
GSettings *             g_settings_get_child                            (GSettings          *settings,
                                                                         const gchar        *name);

189
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
190 191 192
gboolean                g_settings_is_writable                          (GSettings          *settings,
                                                                         const gchar        *name);

193
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
194
void                    g_settings_delay                                (GSettings          *settings);
195
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
196
void                    g_settings_apply                                (GSettings          *settings);
197
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
198
void                    g_settings_revert                               (GSettings          *settings);
199
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
200
gboolean                g_settings_get_has_unapplied                    (GSettings          *settings);
201
GLIB_AVAILABLE_IN_ALL
202
void                    g_settings_sync                                 (void);
Allison Karlitskaya's avatar
Allison Karlitskaya committed
203 204 205 206 207 208 209 210 211

/**
 * 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.
212 213 214
 *
 * Returns: a new #GVariant holding the data from @value,
 *     or %NULL in case of an error
Allison Karlitskaya's avatar
Allison Karlitskaya committed
215 216 217 218 219 220 221 222 223 224 225 226 227 228
 */
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.
229 230
 *
 * Returns: %TRUE if the conversion succeeded, %FALSE in case of an error
Allison Karlitskaya's avatar
Allison Karlitskaya committed
231 232 233 234 235
 */
typedef gboolean      (*GSettingsBindGetMapping)                        (GValue             *value,
                                                                         GVariant           *variant,
                                                                         gpointer            user_data);

236 237 238
/**
 * GSettingsGetMapping:
 * @value: the #GVariant to map, or %NULL
239 240 241
 * @result: (out): the result of the mapping
 * @user_data: (closure): the user data that was passed to
 * g_settings_get_mapped()
242 243 244 245 246 247 248 249 250 251 252
 *
 * 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.
253 254
 *
 * Returns: %TRUE if the conversion succeeded, %FALSE in case of an error
255 256 257 258 259
 **/
typedef gboolean      (*GSettingsGetMapping)                            (GVariant           *value,
                                                                         gpointer           *result,
                                                                         gpointer            user_data);

Allison Karlitskaya's avatar
Allison Karlitskaya committed
260 261 262
/**
 * GSettingsBindFlags:
 * @G_SETTINGS_BIND_DEFAULT: Equivalent to <literal>G_SETTINGS_BIND_GET|G_SETTINGS_BIND_SET</literal>
263 264 265 266
 * @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.
267 268 269
 * @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
270 271
 * @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
272
 *     be booleans.  You cannot pass this flag to g_settings_bind_with_mapping().
Allison Karlitskaya's avatar
Allison Karlitskaya committed
273 274 275 276 277 278 279 280 281 282 283
 *
 * 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),
284 285
  G_SETTINGS_BIND_GET_NO_CHANGES = (1<<3),
  G_SETTINGS_BIND_INVERT_BOOLEAN = (1<<4)
Allison Karlitskaya's avatar
Allison Karlitskaya committed
286 287
} GSettingsBindFlags;

288
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
289 290 291 292 293
void                    g_settings_bind                                 (GSettings               *settings,
                                                                         const gchar             *key,
                                                                         gpointer                 object,
                                                                         const gchar             *property,
                                                                         GSettingsBindFlags       flags);
294
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
295 296 297 298 299 300 301 302 303
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);
304
GLIB_AVAILABLE_IN_ALL
305 306 307 308 309
void                    g_settings_bind_writable                        (GSettings               *settings,
                                                                         const gchar             *key,
                                                                         gpointer                 object,
                                                                         const gchar             *property,
                                                                         gboolean                 inverted);
310
GLIB_AVAILABLE_IN_ALL
Allison Karlitskaya's avatar
Allison Karlitskaya committed
311 312 313
void                    g_settings_unbind                               (gpointer                 object,
                                                                         const gchar             *property);

314
GLIB_AVAILABLE_IN_2_32
315 316 317
GAction *               g_settings_create_action                        (GSettings               *settings,
                                                                         const gchar             *key);

318
GLIB_AVAILABLE_IN_ALL
319 320 321 322 323
gpointer                g_settings_get_mapped                           (GSettings               *settings,
                                                                         const gchar             *key,
                                                                         GSettingsGetMapping      mapping,
                                                                         gpointer                 user_data);

Allison Karlitskaya's avatar
Allison Karlitskaya committed
324 325 326
G_END_DECLS

#endif  /* __G_SETTINGS_H__ */