libs/glibmm2/glib/glibmm/keyfile.h

   1 // -*- c++ -*-
   2 // Generated by gtkmmproc -- DO NOT MODIFY!
   3 #ifndef _GLIBMM_KEYFILE_H
   4 #define _GLIBMM_KEYFILE_H
   5
   6
   7 /* Copyright(C) 2006 The gtkmm Development Team
   8  *
   9  * This library is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Library General Public
  11  * License as published by the Free Software Foundation; either
  12  * version 2 of the License, or(at your option) any later version.
  13  *
  14  * This library is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Library General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Library General Public
  20  * License along with this library; if not, write to the Free
  21  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  22  */
  23
  24
  25 #include <glibmm/ustring.h>
  26 #include <glibmm/arrayhandle.h>
  27 #include <glibmm/error.h>
  28 #include <glibmm/utility.h>
  29 #include <glib/gkeyfile.h>
  30
  31 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  32 extern "C" { typedef struct _GKeyFile GKeyFile; }
  33 #endif
  34
  35 namespace Glib
  36 {
  37
  38   /** @addtogroup glibmmEnums Enums and Flags */
  39
  40 /**
  41  * @ingroup glibmmEnums
  42  * @par Bitwise operators:
  43  * <tt>%KeyFileFlags operator|(KeyFileFlags, KeyFileFlags)</tt><br>
  44  * <tt>%KeyFileFlags operator&(KeyFileFlags, KeyFileFlags)</tt><br>
  45  * <tt>%KeyFileFlags operator^(KeyFileFlags, KeyFileFlags)</tt><br>
  46  * <tt>%KeyFileFlags operator~(KeyFileFlags)</tt><br>
  47  * <tt>%KeyFileFlags& operator|=(KeyFileFlags&, KeyFileFlags)</tt><br>
  48  * <tt>%KeyFileFlags& operator&=(KeyFileFlags&, KeyFileFlags)</tt><br>
  49  * <tt>%KeyFileFlags& operator^=(KeyFileFlags&, KeyFileFlags)</tt><br>
  50  */
  51 enum KeyFileFlags
  52 {
  53   KEY_FILE_NONE = 0,
  54   KEY_FILE_KEEP_COMMENTS = 1 << 0,
  55   KEY_FILE_KEEP_TRANSLATIONS = 1 << 1
  56 };
  57
  58 /** @ingroup glibmmEnums */
  59 inline KeyFileFlags operator|(KeyFileFlags lhs, KeyFileFlags rhs)
  60   { return static_cast<KeyFileFlags>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs)); }
  61
  62 /** @ingroup glibmmEnums */
  63 inline KeyFileFlags operator&(KeyFileFlags lhs, KeyFileFlags rhs)
  64   { return static_cast<KeyFileFlags>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs)); }
  65
  66 /** @ingroup glibmmEnums */
  67 inline KeyFileFlags operator^(KeyFileFlags lhs, KeyFileFlags rhs)
  68   { return static_cast<KeyFileFlags>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs)); }
  69
  70 /** @ingroup glibmmEnums */
  71 inline KeyFileFlags operator~(KeyFileFlags flags)
  72   { return static_cast<KeyFileFlags>(~static_cast<unsigned>(flags)); }
  73
  74 /** @ingroup glibmmEnums */
  75 inline KeyFileFlags& operator|=(KeyFileFlags& lhs, KeyFileFlags rhs)
  76   { return (lhs = static_cast<KeyFileFlags>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs))); }
  77
  78 /** @ingroup glibmmEnums */
  79 inline KeyFileFlags& operator&=(KeyFileFlags& lhs, KeyFileFlags rhs)
  80   { return (lhs = static_cast<KeyFileFlags>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs))); }
  81
  82 /** @ingroup glibmmEnums */
  83 inline KeyFileFlags& operator^=(KeyFileFlags& lhs, KeyFileFlags rhs)
  84   { return (lhs = static_cast<KeyFileFlags>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs))); }
  85
  86
  87 /** Exception class for KeyFile errors.
  88  */
  89 class KeyFileError : public Glib::Error
  90 {
  91 public:
  92   enum Code
  93   {
  94     UNKNOWN_ENCODING,
  95     PARSE,
  96     NOT_FOUND,
  97     KEY_NOT_FOUND,
  98     GROUP_NOT_FOUND,
  99     INVALID_VALUE
 100   };
 101
 102   KeyFileError(Code error_code, const Glib::ustring& error_message);
 103   explicit KeyFileError(GError* gobject);
 104   Code code() const;
 105
 106 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 107 private:
 108
 109 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 110   static void throw_func(GError* gobject);
 111 #else
 112   //When not using exceptions, we just pass the Exception object around without throwing it:
 113   static std::auto_ptr<Glib::Error> throw_func(GError* gobject);
 114 #endif //GLIBMM_EXCEPTIONS_ENABLED
 115
 116   friend void wrap_init(); // uses throw_func()
 117 #endif
 118 };
 119
 120
 121 /** This class lets you parse, edit or create files containing groups of key-value pairs, which we call key files
 122  * for lack of a better name. Several freedesktop.org specifications use key files now, e.g the Desktop Entry
 123  * Specification and the Icon Theme Specification.
 124  *
 125  * The syntax of key files is described in detail in the Desktop Entry Specification, here is a quick summary: Key
 126  * files consists of groups of key-value pairs, interspersed with comments.
 127  *
 128  * @code
 129  * # this is just an example
 130  * # there can be comments before the first group
 131  *
 132  * [First Group]
 133  *
 134  * Name=Key File Example\tthis value shows\nescaping
 135  *
 136  * # localized strings are stored in multiple key-value pairs
 137  * Welcome=Hello
 138  * Welcome[de]=Hallo
 139  * Welcome[fr]=Bonjour
 140  * Welcome[it]=Ciao
 141  *
 142  * [Another Group]
 143  *
 144  * Numbers=2;20;-200;0
 145  *
 146  * Booleans=true;false;true;true
 147  * @endcode
 148  *
 149  * Lines beginning with a '#' and blank lines are considered comments.
 150  *
 151  * Groups are started by a header line containing the group name enclosed in '[' and ']', and ended implicitly by
 152  * the start of the next group or the end of the file. Each key-value pair must be contained in a group.
 153  *
 154  * Key-value pairs generally have the form key=value, with the exception of localized strings, which have the form
 155  * key[locale]=value. Space before and after the '=' character are ignored. Newline, tab, carriage return and
 156  * backslash characters in value are escaped as \n, \t, \r, and \\, respectively. To preserve leading spaces in
 157  * values, these can also be escaped as \s.
 158  *
 159  * Key files can store strings (possibly with localized variants), integers, booleans and lists of these. Lists are
 160  * separated by a separator character, typically ';' or ','. To use the list separator character in a value in a
 161  * list, it has to be escaped by prefixing it with a backslash.
 162  *
 163  * This syntax is obviously inspired by the .ini files commonly met on Windows, but there are some important
 164  * differences:
 165  * - .ini files use the ';' character to begin comments, key files use the '#' character.
 166  * - Key files allow only comments before the first group.
 167  * - Key files are always encoded in UTF-8.
 168  * - Key and Group names are case-sensitive, for example a group called [GROUP] is a different group from [group].
 169  *
 170  * Note that in contrast to the Desktop Entry Specification, groups in key files may contain the same key multiple
 171  * times; the last entry wins. Key files may also contain multiple groups with the same name; they are merged
 172  * together. Another difference is that keys and group names in key files are not restricted to ASCII characters.
 173  *
 174  * @newin2p14
 175  */
 176 class KeyFile
 177 {
 178   public:
 179 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 180   typedef KeyFile CppObjectType;
 181   typedef GKeyFile BaseObjectType;
 182 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
 183
 184 private:
 185
 186 public:
 187
 188   /** Creates a new, empty KeyFile object.
 189    */
 190   KeyFile();
 191
 192   /** Destructor
 193    */
 194   ~KeyFile();
 195
 196
 197   /** Creates a glibmm KeyFile wrapper for a GKeyFile object.
 198    * Note, when using this that when the wrapper is deleted,
 199    * it will not automatically deleted the GKeyFile unless you
 200    * set the delete_c_instance boolean to true.
 201    * @param castitem The C instance to wrap
 202    * @param delete_c_instance If the C instance should be deleted when
 203    * the wrapper is deleted.
 204    */
 205   KeyFile(GKeyFile* castitem, bool takes_ownership = false);
 206
 207 public:
 208
 209
 210   /** Loads a key file into an empty G::KeyFile structure.
 211    * If the file could not be loaded then %error is set to
 212    * either a G::FileError or G::KeyFileError.
 213    * @param file The path of a filename to load, in the GLib file name encoding.
 214    * @param flags Flags from G::KeyFileFlags.
 215    * @param error Return location for a G::Error, or <tt>0</tt>.
 216    * @return <tt>true</tt> if a key file could be loaded, <tt>false</tt> othewise
 217    * @newin2p6.
 218    */
 219 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 220   bool load_from_file(const std::string& filename, KeyFileFlags flags = Glib::KEY_FILE_NONE);
 221 #else
 222   bool load_from_file(const std::string& filename, KeyFileFlags flags, std::auto_ptr<Glib::Error>& error);
 223 #endif //GLIBMM_EXCEPTIONS_ENABLED
 224
 225
 226   /** Loads a KeyFile from memory
 227    * @param data The data to use as a KeyFile
 228    * @param flags Bitwise combination of the flags to use for the KeyFile
 229    * @return true if the KeyFile was successfully loaded, false otherwise
 230    * @throw Glib::KeyFileError
 231    */
 232
 233   bool load_from_data(const Glib::ustring& data, KeyFileFlags flags = Glib::KEY_FILE_NONE);
 234
 235
 236   //TODO:
 237   /*
 238   gboolean g_key_file_load_from_dirs          (GKeyFile             *key_file,
 239                                              const gchar          *file,
 240                                              const gchar         **search_dirs,
 241                                              gchar               **full_path,
 242                                              GKeyFileFlags         flags,
 243                                              GError              **error);
 244   */
 245
 246   /** Looks for a KeyFile named @a file in the paths returned from
 247    * g_get_user_data_dir() and g_get_system_data_dirs() and loads them
 248    * into the keyfile object, placing the full path to the file in
 249    * @a full_path.
 250    * @param file The file to search for
 251    * @param full_path Return location for a string containing the full path of the file
 252    * @param flags Bitwise combination of the flags to use for the KeyFile
 253    * @return true if the KeyFile was successfully loaded, false otherwise
 254    * @throw Glib::KeyFileError
 255    * @throw Glib::FileError
 256    */
 257   bool load_from_data_dirs(const std::string& file, std::string& full_path, KeyFileFlags flags = Glib::KEY_FILE_NONE);
 258
 259
 260   /** Outputs the KeyFile as a string
 261    * @return A string object holding the contents of KeyFile
 262    */
 263   Glib::ustring to_data();
 264
 265
 266   /** Return value: The start group of the key file.
 267    * @return The start group of the key file.
 268    *
 269    * @newin2p6.
 270    */
 271   Glib::ustring get_start_group() const;
 272
 273   /** Gets a list of all groups in the KeyFile
 274    * @returns A list containing the names of the groups
 275    */
 276   Glib::ArrayHandle<Glib::ustring> get_groups() const;
 277
 278
 279   /** Gets a list of all keys from the group @a group_name.
 280    * @param group_name The name of a group
 281    * @returns A list containing the names of the keys in @a group_name
 282    */
 283   Glib::ArrayHandle<Glib::ustring> get_keys(const Glib::ustring& group_name) const;
 284
 285
 286   /** Looks whether the key file has the group @a group_name .
 287    * @param group_name A group name.
 288    * @return <tt>true</tt> if @a group_name  is a part of @a key_file , <tt>false</tt>
 289    * otherwise.
 290    * @newin2p6.
 291    */
 292   bool has_group(const Glib::ustring& group_name) const;
 293
 294   /** Looks whether the key file has the key @a key  in the group
 295    *  @a group_name .
 296    * @param group_name A group name.
 297    * @param key A key name.
 298    * @param error Return location for a G::Error.
 299    * @return <tt>true</tt> if @a key  is a part of @a group_name , <tt>false</tt>
 300    * otherwise.
 301    *
 302    * @newin2p6.
 303    */
 304 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 305   bool has_key(const Glib::ustring& group_name, const Glib::ustring& key) const;
 306 #else
 307   bool has_key(const Glib::ustring& group_name, const Glib::ustring& key, std::auto_ptr<Glib::Error>& error) const;
 308 #endif //GLIBMM_EXCEPTIONS_ENABLED
 309
 310
 311   /** Return value: a newly allocated string or <tt>0</tt> if the specified
 312    * @param group_name A group name.
 313    * @param key A key.
 314    * @param error Return location for a G::Error, or <tt>0</tt>.
 315    * @return A newly allocated string or <tt>0</tt> if the specified
 316    * key cannot be found.
 317    *
 318    * @newin2p6.
 319    */
 320 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 321   Glib::ustring get_value(const Glib::ustring& group_name, const Glib::ustring& key) const;
 322 #else
 323   Glib::ustring get_value(const Glib::ustring& group_name, const Glib::ustring& key, std::auto_ptr<Glib::Error>& error) const;
 324 #endif //GLIBMM_EXCEPTIONS_ENABLED
 325
 326
 327   /** Return value: a newly allocated string or <tt>0</tt> if the specified
 328    * @param group_name A group name.
 329    * @param key A key.
 330    * @param error Return location for a G::Error, or <tt>0</tt>.
 331    * @return A newly allocated string or <tt>0</tt> if the specified
 332    * key cannot be found.
 333    *
 334    * @newin2p6.
 335    */
 336 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 337   Glib::ustring get_string(const Glib::ustring& group_name, const Glib::ustring& key) const;
 338 #else
 339   Glib::ustring get_string(const Glib::ustring& group_name, const Glib::ustring& key, std::auto_ptr<Glib::Error>& error) const;
 340 #endif //GLIBMM_EXCEPTIONS_ENABLED
 341
 342
 343   /** Gets the value associated with @a key under @a group_name translated
 344   * into the current locale.
 345   */
 346   Glib::ustring get_locale_string(const Glib::ustring& group_name, const Glib::ustring& key) const;
 347
 348
 349   /** Return value: a newly allocated string or <tt>0</tt> if the specified
 350    * @param group_name A group name.
 351    * @param key A key.
 352    * @param locale A locale or <tt>0</tt>.
 353    * @param error Return location for a G::Error, or <tt>0</tt>.
 354    * @return A newly allocated string or <tt>0</tt> if the specified
 355    * key cannot be found.
 356    *
 357    * @newin2p6.
 358    */
 359 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 360   Glib::ustring get_locale_string(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ustring& locale) const;
 361 #else
 362   Glib::ustring get_locale_string(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ustring& locale, std::auto_ptr<Glib::Error>& error) const;
 363 #endif //GLIBMM_EXCEPTIONS_ENABLED
 364
 365
 366   /** Return value: the value associated with the key as a boolean, or
 367    * @param group_name A group name.
 368    * @param key A key.
 369    * @param error Return location for a G::Error.
 370    * @return The value associated with the key as a boolean, or
 371    * <tt>false</tt> if the key was not found or could not be parsed.
 372    *
 373    * @newin2p6.
 374    */
 375 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 376   bool get_boolean(const Glib::ustring& group_name, const Glib::ustring& key) const;
 377 #else
 378   bool get_boolean(const Glib::ustring& group_name, const Glib::ustring& key, std::auto_ptr<Glib::Error>& error) const;
 379 #endif //GLIBMM_EXCEPTIONS_ENABLED
 380
 381
 382   /** Gets the value in the first group, under @a key, interpreting it as
 383    * an integer.
 384    * @param key The name of the key
 385    * @return The value of @a key as an integer
 386    * @throws Glib::KeyFileError
 387    */
 388   int get_integer(const Glib::ustring& key) const;
 389
 390
 391   /** Return value: the value associated with the key as an integer, or
 392    * @param group_name A group name.
 393    * @param key A key.
 394    * @param error Return location for a G::Error.
 395    * @return The value associated with the key as an integer, or
 396    * 0 if the key was not found or could not be parsed.
 397    *
 398    * @newin2p6.
 399    */
 400 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 401   int get_integer(const Glib::ustring& group_name, const Glib::ustring& key) const;
 402 #else
 403   int get_integer(const Glib::ustring& group_name, const Glib::ustring& key, std::auto_ptr<Glib::Error>& error) const;
 404 #endif //GLIBMM_EXCEPTIONS_ENABLED
 405
 406
 407   /** Gets the value in the first group, under @a key, interpreting it as
 408    * a double.
 409    * @param key The name of the key
 410    * @return The value of @a key as an double
 411    * @throws Glib::KeyFileError
 412    *
 413    * @newin2p14
 414    */
 415    double get_double(const Glib::ustring& key) const;
 416
 417
 418   /** Return value: the value associated with the key as a double, or
 419    * @param group_name A group name.
 420    * @param key A key.
 421    * @param error Return location for a G::Error.
 422    * @return The value associated with the key as a double, or
 423    * 0.0 if the key was not found or could not be parsed.
 424    *
 425    * @newin2p14.
 426    */
 427 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 428   double get_double(const Glib::ustring& group_name, const Glib::ustring& key) const;
 429 #else
 430   double get_double(const Glib::ustring& group_name, const Glib::ustring& key, std::auto_ptr<Glib::Error>& error) const;
 431 #endif //GLIBMM_EXCEPTIONS_ENABLED
 432
 433
 434   /** Associates a new double value with @a key  under @a group_name .
 435    * If @a key  cannot be found then it is created.
 436    *
 437    * @newin2p14
 438    * @param group_name A group name.
 439    * @param key A key.
 440    * @param value An double value.
 441    */
 442   void set_double(const Glib::ustring& group_name, const Glib::ustring& key, double value);
 443
 444   /** Associates a new double value with @a key under the start group.
 445    * If @a key  cannot be found then it is created.
 446    *
 447    * @newin2p12
 448    * @param key A key.
 449    * @param value An double value.
 450    */
 451   void set_double(const Glib::ustring& key, double value);
 452
 453   /** Returns the values associated with @a key under @a group_name
 454    * @param group_name The name of a group
 455    * @param key The name of a key
 456    * @return A list containing the values requested
 457    * @throws Glib::KeyFileError
 458    */
 459   Glib::ArrayHandle<Glib::ustring> get_string_list(const Glib::ustring& group_name, const Glib::ustring& key) const;
 460
 461
 462   /** Returns the values associated with @a key under @a group_name
 463    * translated into the current locale, if available.
 464    * @param group_name The name of a group
 465    * @param key The name of a key
 466    * @return A list containing the values requested
 467    * @throws Glib::KeyFileError
 468    */
 469   Glib::ArrayHandle<Glib::ustring> get_locale_string_list(const Glib::ustring& group_name, const Glib::ustring& key) const;
 470
 471   /** Returns the values associated with @a key under @a group_name
 472    * translated into @a locale, if available.
 473    * @param group_name The name of a group
 474    * @param key The name of a key
 475    * @param locale The name of a locale
 476    * @return A list containing the values requested
 477    * @throws Glib::KeyFileError
 478    */
 479   Glib::ArrayHandle<Glib::ustring> get_locale_string_list(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ustring& locale) const;
 480
 481
 482   /** Returns the values associated with @a key under @a group_name
 483    * @param group_name The name of a group
 484    * @param key The name of a key
 485    * @return A list of booleans
 486    * @throws Glib::KeyFileError
 487    */
 488   Glib::ArrayHandle<bool> get_boolean_list(const Glib::ustring& group_name, const Glib::ustring& key) const;
 489
 490
 491   /** Returns the values associated with @a key under @a group_name
 492    * @param group_name The name of a group
 493    * @param key The name of a key
 494    * @return A list of integers
 495    * @throws Glib::KeyFileError
 496    */
 497   Glib::ArrayHandle<int> get_integer_list(const Glib::ustring& group_name, const Glib::ustring& key) const;
 498
 499
 500   /** Returns the values associated with @a key under @a group_name
 501    * @param group_name The name of a group
 502    * @param key The name of a key
 503    * @return A list of doubles
 504    * @throws Glib::KeyFileError
 505    */
 506   Glib::ArrayHandle<double> get_double_list(const Glib::ustring& group_name, const Glib::ustring& key) const;
 507
 508
 509   /** Get comment from top of file
 510    * @return The comment
 511    */
 512   Glib::ustring get_comment() const;
 513
 514   /** Get comment from above a group
 515    * @param group_name The group
 516    * @return The comment
 517    */
 518   Glib::ustring get_comment(const Glib::ustring& group_name) const;
 519
 520
 521   /** Retrieves a comment above @a key  from @a group_name .
 522    *  @a group_name . If @a key  is <tt>0</tt> then @a comment  will
 523    * be read from above @a group_name .  If both @a key
 524    * and @a group_name  are <tt>0</tt>, then @a comment  will
 525    * be read from above the first group in the file.
 526    * @param group_name A group name, or <tt>0</tt>.
 527    * @param key A key.
 528    * @param error Return location for a G::Error.
 529    * @return A comment that should be freed with g_free()
 530    *
 531    * @newin2p6.
 532    */
 533 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 534   Glib::ustring get_comment(const Glib::ustring& group_name, const Glib::ustring& key) const;
 535 #else
 536   Glib::ustring get_comment(const Glib::ustring& group_name, const Glib::ustring& key, std::auto_ptr<Glib::Error>& error) const;
 537 #endif //GLIBMM_EXCEPTIONS_ENABLED
 538
 539
 540   /** Sets the character which is used to separate
 541    * values in lists. Typically ';' or ',' are used
 542    * as separators. The default list separator is ';'.
 543    *
 544    * @newin2p6
 545    * @param separator The separator.
 546    */
 547   void set_list_separator(gchar separator);
 548
 549   /** Associates a new value with @a key  under @a group_name .  If @a key
 550    * cannot be found then it is created. If @a group_name  cannot be
 551    * found then it is created.
 552    *
 553    * @newin2p6
 554    * @param group_name A group name.
 555    * @param key A key.
 556    * @param value A string.
 557    */
 558   void set_value(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ustring& value);
 559
 560   /** Associates a new string value with @a key  under @a group_name .  If
 561    *  @a key  cannot be found then it is created.  If @a group_name
 562    * cannot be found then it is created.
 563    *
 564    * @newin2p6
 565    * @param group_name A group name.
 566    * @param key A key.
 567    * @param string A string.
 568    */
 569   void set_string(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ustring& string);
 570
 571   /** Associates a string value for @a key  and @a locale  under
 572    *  @a group_name .  If the translation for @a key  cannot be found
 573    * then it is created.
 574    *
 575    * @newin2p6
 576    * @param group_name A group name.
 577    * @param key A key.
 578    * @param locale A locale.
 579    * @param string A string.
 580    */
 581   void set_locale_string(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ustring& locale, const Glib::ustring& string);
 582
 583   /** Associates a new boolean value with @a key  under @a group_name .
 584    * If @a key  cannot be found then it is created.
 585    *
 586    * @newin2p6
 587    * @param group_name A group name.
 588    * @param key A key.
 589    * @param value <tt>true</tt> or <tt>false</tt>.
 590    */
 591   void set_boolean(const Glib::ustring& group_name, const Glib::ustring& key, bool value);
 592
 593   /** Associates a new integer value with @a key  under @a group_name .
 594    * If @a key  cannot be found then it is created.
 595    *
 596    * @newin2p6
 597    * @param group_name A group name.
 598    * @param key A key.
 599    * @param value An integer value.
 600    */
 601   void set_integer(const Glib::ustring& group_name, const Glib::ustring& key, int value);
 602
 603   /** Sets a list of string values for @a key under @a group_name. If
 604    * key cannot be found it is created. If @a group_name cannot be found
 605    * it is created.
 606    * @param group_name The name of a group
 607    * @param key The name of a key
 608    * @param list A list holding objects of type Glib::ustring
 609    */
 610   void set_string_list(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ArrayHandle<Glib::ustring>& list);
 611
 612
 613   /** Sets a list of string values for the @a key under @a group_name and marks
 614    * them as being for @a locale. If the @a key or @a group_name cannot be
 615    * found, they are created.
 616    * @param group_name The name of a group
 617    * @param key The name of a key
 618    * @param locale A locale
 619    * @param list A list holding objects of type Glib::ustring
 620    */
 621   void set_locale_string_list(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ustring& locale, const Glib::ArrayHandle<Glib::ustring>& list);
 622
 623
 624   /** Sets a list of booleans for the @a key under @a group_name.
 625    * If either the @a key or @a group_name cannot be found they are created.
 626    * @param group_name The name of a group
 627    * @param key The name of a key
 628    * @param list A list holding object of type bool
 629    */
 630   void set_boolean_list(const Glib::ustring& group_name, const Glib::ustring& key, Glib::ArrayHandle<bool>& list);
 631
 632
 633   /** Sets a list of integers for the @a key under @a group_name.
 634    * If either the @a key or @a group_name cannot be found they are created.
 635    * @param group_name The name of a group
 636    * @param key The name of a key
 637    * @param list A list holding object of type int
 638    */
 639   void set_integer_list(const Glib::ustring& group_name, const Glib::ustring& key, Glib::ArrayHandle<int>& list);
 640
 641
 642   /** Sets a list of doubles for the @a key under @a group_name.
 643    * If either the @a key or @a group_name cannot be found they are created.
 644    * @param group_name The name of a group
 645    * @param key The name of a key
 646    * @param list A list holding object of type int
 647    *
 648    * @newin2p14
 649    */
 650   void set_double_list(const Glib::ustring& group_name, const Glib::ustring& key, Glib::ArrayHandle<double>& list);
 651
 652
 653   /** Places @a comment at the start of the file, before the first group.
 654    * @param comment The Comment
 655    */
 656   void set_comment(const Glib::ustring& comment);
 657
 658   /** Places @a comment above @a group_name.
 659    * @param group_name The Group the comment should be above
 660    * @param comment The comment
 661    */
 662   void set_comment(const Glib::ustring& group_name, const Glib::ustring& comment);
 663
 664   /** Places a comment above @a key from @a group_name.
 665    * @param key Key comment should be above
 666    * @param group_name Group comment is in
 667    * @param comment The comment
 668    */
 669
 670   /** Places a comment above @a key  from @a group_name .
 671    *  @a group_name . If @a key  is <tt>0</tt> then @a comment  will
 672    * be written above @a group_name .  If both @a key
 673    * and @a group_name  are <tt>0</tt>, then @a comment  will
 674    * be written above the first group in the file.
 675    *
 676    * @newin2p6
 677    * @param group_name A group name, or <tt>0</tt>.
 678    * @param key A key.
 679    * @param comment A comment.
 680    * @param error Return location for a G::Error.
 681    */
 682 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 683   void set_comment(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ustring& comment);
 684 #else
 685   void set_comment(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ustring& comment, std::auto_ptr<Glib::Error>& error);
 686 #endif //GLIBMM_EXCEPTIONS_ENABLED
 687
 688
 689   /** Removes a comment above @a key  from @a group_name .
 690    *  @a group_name . If @a key  is <tt>0</tt> then @a comment  will
 691    * be written above @a group_name .  If both @a key
 692    * and @a group_name  are <tt>0</tt>, then @a comment  will
 693    * be written above the first group in the file.
 694    *
 695    * @newin2p6
 696    * @param group_name A group name, or <tt>0</tt>.
 697    * @param key A key.
 698    * @param error Return location for a G::Error.
 699    */
 700 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 701   void remove_comment(const Glib::ustring& group_name, const Glib::ustring& key);
 702 #else
 703   void remove_comment(const Glib::ustring& group_name, const Glib::ustring& key, std::auto_ptr<Glib::Error>& error);
 704 #endif //GLIBMM_EXCEPTIONS_ENABLED
 705
 706
 707   /** Removes @a key  in @a group_name  from the key file.
 708    *
 709    * @newin2p6
 710    * @param group_name A group name.
 711    * @param key A key name to remove.
 712    * @param error Return location for a G::Error or <tt>0</tt>.
 713    */
 714 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 715   void remove_key(const Glib::ustring& group_name, const Glib::ustring& key);
 716 #else
 717   void remove_key(const Glib::ustring& group_name, const Glib::ustring& key, std::auto_ptr<Glib::Error>& error);
 718 #endif //GLIBMM_EXCEPTIONS_ENABLED
 719
 720
 721   /** Removes the specified group, @a group_name ,
 722    * from the key file.
 723    *
 724    * @newin2p6
 725    * @param group_name A group name.
 726    * @param error Return location for a G::Error or <tt>0</tt>.
 727    */
 728 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 729   void remove_group(const Glib::ustring& group_name);
 730 #else
 731   void remove_group(const Glib::ustring& group_name, std::auto_ptr<Glib::Error>& error);
 732 #endif //GLIBMM_EXCEPTIONS_ENABLED
 733
 734
 735   GKeyFile*       gobj()       { return gobject_; }
 736   const GKeyFile* gobj() const { return gobject_; }
 737
 738 protected:
 739   GKeyFile* gobject_;
 740   bool owns_gobject_;
 741
 742 private:
 743   // noncopyable
 744   KeyFile(const KeyFile&);
 745   KeyFile& operator=(const KeyFile&);
 746
 747
 748 };
 749
 750 } // namespace Glib
 751
 752
 753 #endif /* _GLIBMM_KEYFILE_H */
 754