1 // Generated by gmmproc 2.64.2 -- DO NOT MODIFY! 2 #ifndef _GLIBMM_KEYFILE_H 3 #define _GLIBMM_KEYFILE_H 4 5 6 /* Copyright(C) 2006 The gtkmm Development Team 7 * 8 * This library is free software; you can redistribute it and/or 9 * modify it under the terms of the GNU Lesser General Public 10 * License as published by the Free Software Foundation; either 11 * version 2.1 of the License, or(at your option) any later version. 12 * 13 * This library is distributed in the hope that it will be useful, 14 * but WITHOUT ANY WARRANTY; without even the implied warranty of 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16 * Lesser General Public License for more details. 17 * 18 * You should have received a copy of the GNU Lesser General Public 19 * License along with this library. If not, see <http://www.gnu.org/licenses/>. 20 */ 21 22 23 #include <glibmmconfig.h> 24 #include <glibmm/ustring.h> 25 #include <glibmm/arrayhandle.h> 26 #include <glibmm/error.h> 27 #include <glibmm/utility.h> 28 #include <glib.h> 29 30 #ifndef DOXYGEN_SHOULD_SKIP_THIS 31 extern "C" { typedef struct _GKeyFile GKeyFile; } 32 #endif 33 34 namespace Glib 35 { 36 37 /** @addtogroup glibmmEnums glibmm Enums and Flags */ 38 39 /** 40 * @var KeyFileFlags KEY_FILE_NONE 41 * No flags, default behaviour. 42 * 43 * @var KeyFileFlags KEY_FILE_KEEP_COMMENTS 44 * Use this flag if you plan to write the 45 * (possibly modified) contents of the key file back to a file; 46 * otherwise all comments will be lost when the key file is 47 * written back. 48 * 49 * @var KeyFileFlags KEY_FILE_KEEP_TRANSLATIONS 50 * Use this flag if you plan to write the 51 * (possibly modified) contents of the key file back to a file; 52 * otherwise only the translations for the current language will be 53 * written back. 54 * 55 * @enum KeyFileFlags 56 * 57 * Flags which influence the parsing. 58 * 59 * @ingroup glibmmEnums 60 * @par Bitwise operators: 61 * <tt>%KeyFileFlags operator|(KeyFileFlags, KeyFileFlags)</tt><br> 62 * <tt>%KeyFileFlags operator&(KeyFileFlags, KeyFileFlags)</tt><br> 63 * <tt>%KeyFileFlags operator^(KeyFileFlags, KeyFileFlags)</tt><br> 64 * <tt>%KeyFileFlags operator~(KeyFileFlags)</tt><br> 65 * <tt>%KeyFileFlags& operator|=(KeyFileFlags&, KeyFileFlags)</tt><br> 66 * <tt>%KeyFileFlags& operator&=(KeyFileFlags&, KeyFileFlags)</tt><br> 67 * <tt>%KeyFileFlags& operator^=(KeyFileFlags&, KeyFileFlags)</tt><br> 68 */ 69 enum KeyFileFlags 70 { 71 KEY_FILE_NONE = 0x0, 72 KEY_FILE_KEEP_COMMENTS = 1 << 0, 73 KEY_FILE_KEEP_TRANSLATIONS = 1 << 1 74 }; 75 76 /** @ingroup glibmmEnums */ 77 inline KeyFileFlags operator|(KeyFileFlags lhs, KeyFileFlags rhs) 78 { return static_cast<KeyFileFlags>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs)); } 79 80 /** @ingroup glibmmEnums */ 81 inline KeyFileFlags operator&(KeyFileFlags lhs, KeyFileFlags rhs) 82 { return static_cast<KeyFileFlags>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs)); } 83 84 /** @ingroup glibmmEnums */ 85 inline KeyFileFlags operator^(KeyFileFlags lhs, KeyFileFlags rhs) 86 { return static_cast<KeyFileFlags>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs)); } 87 88 /** @ingroup glibmmEnums */ 89 inline KeyFileFlags operator~(KeyFileFlags flags) 90 { return static_cast<KeyFileFlags>(~static_cast<unsigned>(flags)); } 91 92 /** @ingroup glibmmEnums */ 93 inline KeyFileFlags& operator|=(KeyFileFlags& lhs, KeyFileFlags rhs) 94 { return (lhs = static_cast<KeyFileFlags>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs))); } 95 96 /** @ingroup glibmmEnums */ 97 inline KeyFileFlags& operator&=(KeyFileFlags& lhs, KeyFileFlags rhs) 98 { return (lhs = static_cast<KeyFileFlags>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs))); } 99 100 /** @ingroup glibmmEnums */ 101 inline KeyFileFlags& operator^=(KeyFileFlags& lhs, KeyFileFlags rhs) 102 { return (lhs = static_cast<KeyFileFlags>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs))); } 103 104 105 /** %Exception class for KeyFile errors. 106 */ 107 class GLIBMM_API KeyFileError : public Glib::Error 108 { 109 public: 110 /** @var Code UNKNOWN_ENCODING 111 * The text being parsed was in 112 * an unknown encoding. 113 * 114 * @var Code PARSE 115 * Document was ill-formed. 116 * 117 * @var Code NOT_FOUND 118 * The file was not found. 119 * 120 * @var Code KEY_NOT_FOUND 121 * A requested key was not found. 122 * 123 * @var Code GROUP_NOT_FOUND 124 * A requested group was not found. 125 * 126 * @var Code INVALID_VALUE 127 * A value could not be parsed. 128 * 129 * @enum Code 130 * 131 * %Error codes returned by key file parsing. 132 */ 133 enum Code 134 { 135 UNKNOWN_ENCODING, 136 PARSE, 137 NOT_FOUND, 138 KEY_NOT_FOUND, 139 GROUP_NOT_FOUND, 140 INVALID_VALUE 141 }; 142 143 KeyFileError(Code error_code, const Glib::ustring& error_message); 144 explicit KeyFileError(GError* gobject); 145 Code code() const; 146 147 #ifndef DOXYGEN_SHOULD_SKIP_THIS 148 private: 149 150 static void throw_func(GError* gobject); 151 152 friend GLIBMM_API void wrap_init(); // uses throw_func() 153 154 #endif //DOXYGEN_SHOULD_SKIP_THIS 155 }; 156 157 158 /** This class lets you parse, edit or create files containing groups of key-value pairs, which we call key files 159 * for lack of a better name. Several freedesktop.org specifications use key files now, e.g the Desktop Entry 160 * Specification and the Icon Theme Specification. 161 * 162 * The syntax of key files is described in detail in the Desktop Entry Specification, here is a quick summary: Key 163 * files consists of groups of key-value pairs, interspersed with comments. 164 * 165 * @code 166 * # this is just an example 167 * # there can be comments before the first group 168 * 169 * [First Group] 170 * 171 * Name=Key File Example\tthis value shows\nescaping 172 * 173 * # localized strings are stored in multiple key-value pairs 174 * Welcome=Hello 175 * Welcome[de]=Hallo 176 * Welcome[fr]=Bonjour 177 * Welcome[it]=Ciao 178 * 179 * [Another Group] 180 * 181 * Numbers=2;20;-200;0 182 * 183 * Booleans=true;false;true;true 184 * @endcode 185 * 186 * Lines beginning with a '#' and blank lines are considered comments. 187 * 188 * Groups are started by a header line containing the group name enclosed in '[' and ']', and ended implicitly by 189 * the start of the next group or the end of the file. Each key-value pair must be contained in a group. 190 * 191 * Key-value pairs generally have the form key=value, with the exception of localized strings, which have the form 192 * key[locale]=value. Space before and after the '=' character are ignored. Newline, tab, carriage return and 193 * backslash characters in value are escaped as \\n, \\t, \\r, and \\\\, respectively. To preserve leading spaces in 194 * values, these can also be escaped as \\s. 195 * 196 * Key files can store strings (possibly with localized variants), integers, booleans and lists of these. Lists are 197 * separated by a separator character, typically ';' or ','. To use the list separator character in a value in a 198 * list, it has to be escaped by prefixing it with a backslash. 199 * 200 * This syntax is obviously inspired by the .ini files commonly met on Windows, but there are some important 201 * differences: 202 * - .ini files use the ';' character to begin comments, key files use the '#' character. 203 * - Key files allow only comments before the first group. 204 * - Key files are always encoded in UTF-8. 205 * - Key and Group names are case-sensitive, for example a group called [GROUP] is a different group from [group]. 206 * 207 * Note that in contrast to the Desktop Entry Specification, groups in key files may contain the same key multiple 208 * times; the last entry wins. Key files may also contain multiple groups with the same name; they are merged 209 * together. Another difference is that keys and group names in key files are not restricted to ASCII characters. 210 * 211 * @newin{2,14} 212 */ 213 class GLIBMM_API KeyFile 214 { 215 public: 216 #ifndef DOXYGEN_SHOULD_SKIP_THIS 217 using CppObjectType = KeyFile; 218 using BaseObjectType = GKeyFile; 219 #endif /* DOXYGEN_SHOULD_SKIP_THIS */ 220 221 private: 222 223 public: 224 225 //TODO: GKeyFile now seems to be a reference-counted type. 226 227 //TODO: Maybe replace all the get_*/set_* methods with some generic get/set 228 //methods when it is possible. 229 230 /** Creates a new, empty KeyFile object. 231 */ 232 KeyFile(); 233 234 KeyFile(const KeyFile&) = delete; 235 KeyFile& operator=(const KeyFile&) = delete; 236 237 KeyFile(KeyFile&& other) noexcept; 238 KeyFile& operator=(KeyFile&& other) noexcept; 239 240 /** Destructor 241 */ 242 ~KeyFile(); 243 244 245 /** Creates a glibmm KeyFile wrapper for a GKeyFile object. 246 * Note, when using this that when the wrapper is deleted, 247 * it will not automatically delete the GKeyFile unless you 248 * set the @a takes_ownership boolean to <tt>true</tt>. 249 * @param castitem The C instance to wrap. 250 * @param takes_ownership If the C instance should be deleted when 251 * the wrapper is deleted. 252 */ 253 KeyFile(GKeyFile* castitem, bool takes_ownership = false); 254 255 public: 256 257 /** Loads a key file into an empty KeyFile instance. 258 * If the file could not be loaded then a FileError or KeyFileError exception is thrown. 259 * 260 * @newin{2,6} 261 * 262 * \throw Glib::FileError 263 * \throw Glib::KeyFileError 264 * 265 * @param file The path of a filename to load, in the GLib filename encoding. 266 * @param flags Flags from KeyFileFlags. 267 * @return <tt>true</tt> if a key file could be loaded, <tt>false</tt> otherwise. 268 */ 269 bool load_from_file(const std::string& file, KeyFileFlags flags = Glib::KEY_FILE_NONE); 270 271 /** Loads a KeyFile from memory 272 * @param data The data to use as a KeyFile 273 * @param flags Bitwise combination of the flags to use for the KeyFile 274 * @return true if the KeyFile was successfully loaded, false otherwise 275 * @throw Glib::KeyFileError 276 */ 277 bool load_from_data(const Glib::ustring& data, KeyFileFlags flags = Glib::KEY_FILE_NONE); 278 279 280 #ifndef GLIBMM_DISABLE_DEPRECATED 281 282 /** This function looks for a key file named @a file in the paths 283 * specified in @a search_dirs, loads the file into @a key_file and 284 * returns the file's full path in @a full_path. 285 * 286 * If the file could not be found in any of the @a search_dirs, 287 * KEY_FILE_ERROR_NOT_FOUND is returned. If 288 * the file is found but the OS returns an error when opening or reading the 289 * file, a FILE_ERROR is returned. If there is a problem parsing the file, a 290 * KEY_FILE_ERROR is returned. 291 * 292 * @newin{2,14} 293 * 294 * @deprecated Use the load_from_dirs() method that takes a std::string& full_path. 295 * 296 * @param file A relative path to a filename to open and parse. 297 * @param search_dirs <tt>nullptr</tt>-terminated array of directories to search. 298 * @param full_path Return location for a string containing the full path 299 * of the file, or <tt>nullptr</tt>. 300 * @param flags Flags from KeyFileFlags. 301 * @return <tt>true</tt> if a key file could be loaded, <tt>false</tt> otherwise. 302 * 303 * @throws Glib::KeyFileError 304 * @throws Glib::FileError 305 */ 306 bool load_from_dirs(const std::string& file, const Glib::ArrayHandle<std::string>& search_dirs, Glib::ArrayHandle<std::string>& full_path, KeyFileFlags flags = Glib::KEY_FILE_NONE); 307 #endif // GLIBMM_DISABLE_DEPRECATED 308 309 310 /** This function looks for a key file named @a file in the paths 311 * specified in @a search_dirs, loads the file into @a key_file and 312 * returns the file's full path in @a full_path. 313 * 314 * If the file could not be found in any of the @a search_dirs, 315 * KEY_FILE_ERROR_NOT_FOUND is returned. If 316 * the file is found but the OS returns an error when opening or reading the 317 * file, a FILE_ERROR is returned. If there is a problem parsing the file, a 318 * KEY_FILE_ERROR is returned. 319 * 320 * @newin{2,14} 321 * 322 * @param file A relative path to a filename to open and parse. 323 * @param search_dirs <tt>nullptr</tt>-terminated array of directories to search. 324 * @param full_path Return location for a string containing the full path 325 * of the file, or <tt>nullptr</tt>. 326 * @param flags Flags from KeyFileFlags. 327 * @return <tt>true</tt> if a key file could be loaded, <tt>false</tt> otherwise. 328 * 329 * @throws Glib::KeyFileError 330 * @throws Glib::FileError 331 */ 332 333 bool load_from_dirs(const std::string& file, const Glib::ArrayHandle<std::string>& search_dirs, std::string& full_path, KeyFileFlags flags = Glib::KEY_FILE_NONE); 334 335 /** Looks for a KeyFile named @a file in the paths returned from 336 * g_get_user_data_dir() and g_get_system_data_dirs() and loads them 337 * into the keyfile object, placing the full path to the file in 338 * @a full_path. 339 * @param file The file to search for 340 * @param[out] full_path Return location for a string containing the full path of the file 341 * @param flags Bitwise combination of the flags to use for the KeyFile 342 * @return true if the KeyFile was successfully loaded, false otherwise 343 * @throw Glib::KeyFileError 344 * @throw Glib::FileError 345 */ 346 bool load_from_data_dirs(const std::string& file, std::string& full_path, KeyFileFlags flags = Glib::KEY_FILE_NONE); 347 348 349 /** Outputs the KeyFile as a string 350 * @return A string object holding the contents of KeyFile 351 * @throw Glib::KeyFileError 352 */ 353 Glib::ustring to_data(); 354 355 356 /** Writes the contents of @a key_file to @a filename using 357 * g_file_set_contents(). 358 * 359 * This function can fail for any of the reasons that 360 * g_file_set_contents() may fail. 361 * 362 * @newin{2,40} 363 * 364 * @param filename The name of the file to write to. 365 * @return <tt>true</tt> if successful, else <tt>false</tt> with @a error set. 366 * 367 * @throws Glib::FileError 368 */ 369 bool save_to_file(const std::string& filename); 370 371 372 /** Returns the name of the start group of the file. 373 * 374 * @newin{2,6} 375 * 376 * @return The start group of the key file. 377 */ 378 Glib::ustring get_start_group() const; 379 380 /** Gets a list of all groups in the KeyFile 381 * @returns A list containing the names of the groups 382 */ 383 Glib::ArrayHandle<Glib::ustring> get_groups() const; 384 385 386 /** Gets a list of all keys from the group @a group_name. 387 * @param group_name The name of a group 388 * @returns A list containing the names of the keys in @a group_name 389 * @throw Glib::KeyFileError 390 */ 391 Glib::ArrayHandle<Glib::ustring> get_keys(const Glib::ustring& group_name) const; 392 393 394 /** Looks whether the key file has the group @a group_name. 395 * 396 * @newin{2,6} 397 * 398 * @param group_name A group name. 399 * @return <tt>true</tt> if @a group_name is a part of @a key_file, <tt>false</tt> 400 * otherwise. 401 */ 402 bool has_group(const Glib::ustring& group_name) const; 403 404 /** Looks whether the key file has the key @a key in the group 405 * @a group_name. 406 * 407 * @newin{2,6} 408 * 409 * \throw Glib::KeyFileError 410 * 411 * @param group_name A group name. 412 * @param key A key name. 413 * @return <tt>true</tt> if @a key is a part of @a group_name, <tt>false</tt> otherwise. 414 */ 415 bool has_key(const Glib::ustring& group_name, const Glib::ustring& key) const; 416 417 418 /** Returns the value associated with @a key under @a group_name. 419 * 420 * @newin{2,6} 421 * 422 * \throw Glib::KeyFileError in the event the key cannot be found (with the Glib::KeyFileError::KEY_NOT_FOUND code). 423 * \throw Glib::KeyFileError in the event that the @a group_name cannot be found (with the Glib::KeyFileError::GROUP_NOT_FOUND code). 424 * 425 * @param group_name A group name. 426 * @param key A key. 427 * @return The value as a string. 428 */ 429 Glib::ustring get_value(const Glib::ustring& group_name, const Glib::ustring& key) const; 430 431 /** Return value: a newly allocated string or <tt>nullptr</tt>. 432 * 433 * @newin{2,6} 434 * 435 * \throw Glib::KeyFileError 436 * 437 * @param group_name A group name. 438 * @param key A key. 439 * @return A newly allocated string or <tt>nullptr</tt> if the specified 440 * key cannot be found. 441 */ 442 Glib::ustring get_string(const Glib::ustring& group_name, const Glib::ustring& key) const; 443 444 445 /** Returns the actual locale which the result of 446 * g_key_file_get_locale_string() or g_key_file_get_locale_string_list() 447 * came from. 448 * 449 * If calling g_key_file_get_locale_string() or 450 * g_key_file_get_locale_string_list() with exactly the same @a key_file, 451 * @a group_name, @a key and @a locale, the result of those functions will 452 * have originally been tagged with the locale that is the result of 453 * this function. 454 * 455 * @newin{2,60} 456 * 457 * @param group_name A group name. 458 * @param key A key. 459 * @param locale A locale identifier or <tt>nullptr</tt>. 460 * @return The locale from the file, or <tt>nullptr</tt> if the key was not 461 * found or the entry in the file was was untranslated. 462 */ 463 Glib::ustring get_locale_for_key(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ustring& locale = {}) const; 464 465 /** Gets the value associated with @a key under @a group_name translated 466 * into the current locale. 467 * @return the value as a Glib::ustring 468 * @throw Glib::KeyFileError 469 */ 470 Glib::ustring get_locale_string(const Glib::ustring& group_name, const Glib::ustring& key) const; 471 472 473 /** Return value: a newly allocated string or <tt>nullptr</tt>. 474 * 475 * @newin{2,6} 476 * 477 * \throw Glib::KeyFileError 478 * 479 * @param group_name A group name. 480 * @param key A key. 481 * @param locale A locale identifier or <tt>nullptr</tt>. 482 * @return A newly allocated string or <tt>nullptr</tt> if the specified 483 * key cannot be found. 484 */ 485 Glib::ustring get_locale_string(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ustring& locale) const; 486 487 /** Gets the value in the first group, under @a key, interpreting it as 488 * a boolean. 489 * @param key The name of the key. 490 * @return The value of @a key as a boolean. 491 * @throw Glib::KeyFileError. 492 * @newin{2,6} 493 */ 494 bool get_boolean(const Glib::ustring& key) const; 495 496 497 /** Return value: the value associated with the key as a boolean. 498 * 499 * @newin{2,6} 500 * 501 * \throw Glib::KeyFileError 502 * 503 * @param group_name A group name. 504 * @param key A key. 505 * @return The value associated with the key as a boolean, 506 * or <tt>false</tt> if the key was not found or could not be parsed. 507 */ 508 bool get_boolean(const Glib::ustring& group_name, const Glib::ustring& key) const; 509 510 /** Gets the value in the first group, under @a key, interpreting it as 511 * an integer. 512 * @param key The name of the key 513 * @return The value of @a key as an integer 514 * @throw Glib::KeyFileError 515 * @newin{2,6} 516 */ 517 int get_integer(const Glib::ustring& key) const; 518 519 520 /** Return value: the value associated with the key as an integer. 521 * 522 * @newin{2,6} 523 * 524 * \throw Glib::KeyFileError 525 * 526 * @param group_name A group name. 527 * @param key A key. 528 * @return The value associated with the key as an integer, or 529 * 0 if the key was not found or could not be parsed. 530 */ 531 int get_integer(const Glib::ustring& group_name, const Glib::ustring& key) const; 532 533 /** Gets the value in the first group, under @a key, interpreting it as 534 * a signed 64-bit integer. This is similar to get_integer() but can return 535 * 64-bit results without truncation. 536 * @param key The name of the key. 537 * @return The value of @a key as a signed 64-bit integer, or <tt>0</tt> if 538 * the key was not found or could not be parsed. 539 * @throw Glib::KeyFileError. 540 * @newin{2,28} 541 */ 542 gint64 get_int64(const Glib::ustring& key) const; 543 544 545 /** Returns the value associated with @a key under @a group_name as a signed 546 * 64-bit integer. This is similar to g_key_file_get_integer() but can return 547 * 64-bit results without truncation. 548 * 549 * @newin{2,26} 550 * 551 * @param group_name A non-<tt>nullptr</tt> group name. 552 * @param key A non-<tt>nullptr</tt> key. 553 * @return The value associated with the key as a signed 64-bit integer, or 554 * 0 if the key was not found or could not be parsed. 555 * 556 * @throws Glib::KeyFileError 557 */ 558 gint64 get_int64(const Glib::ustring& group_name, const Glib::ustring& key) const; 559 560 /** Gets the value in the first group, under @a key, interpreting it as 561 * an unsigned 64-bit integer. This is similar to get_integer() but can 562 * return large positive results without truncation. 563 * @param key The name of the key. 564 * @return The value of @a key as an unsigned 64-bit integer, or <tt>0</tt> 565 * if the key was not found or could not be parsed. 566 * @throw Glib::KeyFileError. 567 * @newin{2,28} 568 */ 569 guint64 get_uint64(const Glib::ustring& key) const; 570 571 572 /** Returns the value associated with @a key under @a group_name as an unsigned 573 * 64-bit integer. This is similar to g_key_file_get_integer() but can return 574 * large positive results without truncation. 575 * 576 * @newin{2,26} 577 * 578 * @param group_name A non-<tt>nullptr</tt> group name. 579 * @param key A non-<tt>nullptr</tt> key. 580 * @return The value associated with the key as an unsigned 64-bit integer, 581 * or 0 if the key was not found or could not be parsed. 582 * 583 * @throws Glib::KeyFileError 584 */ 585 guint64 get_uint64(const Glib::ustring& group_name, const Glib::ustring& key) const; 586 587 /** Gets the value in the first group, under @a key, interpreting it as 588 * a double. 589 * @param key The name of the key 590 * @return The value of @a key as an double 591 * @throw Glib::KeyFileError 592 * 593 * @newin{2,14} 594 */ 595 double get_double(const Glib::ustring& key) const; 596 597 598 /** Return value: the value associated with the key as a double. 599 * 600 * @newin{2,14} 601 * 602 * \throw Glib::KeyFileError 603 * 604 * @param group_name A group name. 605 * @param key A key. 606 * @return The value associated with the key as a double, or 607 * 0.0 if the key was not found or could not be parsed. 608 */ 609 double get_double(const Glib::ustring& group_name, const Glib::ustring& key) const; 610 611 612 /** Associates a new double value with @a key under @a group_name. 613 * If @a key cannot be found then it is created. 614 * 615 * @newin{2,12} 616 * 617 * @param group_name A group name. 618 * @param key A key. 619 * @param value A double value. 620 */ 621 void set_double(const Glib::ustring& group_name, const Glib::ustring& key, double value); 622 623 /** Associates a new double value with @a key under the start group. 624 * If @a key cannot be found then it is created. 625 * 626 * @newin{2,12} 627 * 628 * @param key A key. 629 * @param value An double value. 630 */ 631 void set_double(const Glib::ustring& key, double value); 632 633 /** Returns the values associated with @a key under @a group_name 634 * @param group_name The name of a group 635 * @param key The name of a key 636 * @return A list containing the values requested 637 * @throw Glib::KeyFileError 638 */ 639 Glib::ArrayHandle<Glib::ustring> get_string_list(const Glib::ustring& group_name, const Glib::ustring& key) const; 640 641 642 /** Returns the values associated with @a key under @a group_name 643 * translated into the current locale, if available. 644 * @param group_name The name of a group 645 * @param key The name of a key 646 * @return A list containing the values requested 647 * @throw Glib::KeyFileError 648 */ 649 Glib::ArrayHandle<Glib::ustring> get_locale_string_list(const Glib::ustring& group_name, const Glib::ustring& key) const; 650 651 /** Returns the values associated with @a key under @a group_name 652 * translated into @a locale, if available. 653 * @param group_name The name of a group 654 * @param key The name of a key 655 * @param locale The name of a locale 656 * @return A list containing the values requested 657 * @throw Glib::KeyFileError 658 */ 659 Glib::ArrayHandle<Glib::ustring> get_locale_string_list(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ustring& locale) const; 660 661 662 /** Returns the values associated with @a key under @a group_name 663 * @param group_name The name of a group 664 * @param key The name of a key 665 * @return A list of booleans 666 * @throw Glib::KeyFileError 667 */ 668 Glib::ArrayHandle<bool> get_boolean_list(const Glib::ustring& group_name, const Glib::ustring& key) const; 669 670 671 /** Returns the values associated with @a key under @a group_name 672 * @param group_name The name of a group 673 * @param key The name of a key 674 * @return A list of integers 675 * @throw Glib::KeyFileError 676 */ 677 Glib::ArrayHandle<int> get_integer_list(const Glib::ustring& group_name, const Glib::ustring& key) const; 678 679 680 /** Returns the values associated with @a key under @a group_name 681 * @param group_name The name of a group 682 * @param key The name of a key 683 * @return A list of doubles 684 * @throw Glib::KeyFileError 685 */ 686 Glib::ArrayHandle<double> get_double_list(const Glib::ustring& group_name, const Glib::ustring& key) const; 687 688 689 /** Get comment from top of file 690 * @return The comment 691 * @throw Glib::KeyFileError 692 */ 693 Glib::ustring get_comment() const; 694 695 /** Get comment from above a group 696 * @param group_name The group 697 * @return The comment 698 * @throw Glib::KeyFileError 699 */ 700 Glib::ustring get_comment(const Glib::ustring& group_name) const; 701 702 703 /** Retrieves a comment above @a key from @a group_name. 704 * If @a key is <tt>nullptr</tt> then @a comment will be read from above 705 * @a group_name. If both @a key and @a group_name are <tt>nullptr</tt>, then 706 * @a comment will be read from above the first group in the file. 707 * Use the overrides for a <tt>nullptr</tt> @a key or @a group. 708 * 709 * @newin{2,6} 710 * 711 * \throw Glib::KeyFileError 712 * 713 * @param group_name A group name. 714 * @param key A key. 715 * @return The comment. 716 */ 717 Glib::ustring get_comment(const Glib::ustring& group_name, const Glib::ustring& key) const; 718 719 720 /** Sets the character which is used to separate 721 * values in lists. Typically ';' or ',' are used 722 * as separators. The default list separator is ';'. 723 * 724 * @newin{2,6} 725 * 726 * @param separator The separator. 727 */ 728 void set_list_separator(gchar separator); 729 730 /** Associates a new value with @a key under @a group_name. 731 * 732 * If @a key cannot be found then it is created. If @a group_name cannot 733 * be found then it is created. To set an UTF-8 string which may contain 734 * characters that need escaping (such as newlines or spaces), use 735 * g_key_file_set_string(). 736 * 737 * @newin{2,6} 738 * 739 * @param group_name A group name. 740 * @param key A key. 741 * @param value A string. 742 */ 743 void set_value(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ustring& value); 744 745 /** Associates a new string value with @a key under @a group_name. 746 * If @a key cannot be found then it is created. 747 * If @a group_name cannot be found then it is created. 748 * Unlike g_key_file_set_value(), this function handles characters 749 * that need escaping, such as newlines. 750 * 751 * @newin{2,6} 752 * 753 * @param group_name A group name. 754 * @param key A key. 755 * @param string A string. 756 */ 757 void set_string(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ustring& string); 758 759 /** Associates a string value for @a key and @a locale under @a group_name. 760 * If the translation for @a key cannot be found then it is created. 761 * 762 * @newin{2,6} 763 * 764 * @param group_name A group name. 765 * @param key A key. 766 * @param locale A locale identifier. 767 * @param string A string. 768 */ 769 void set_locale_string(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ustring& locale, const Glib::ustring& string); 770 771 /** Associates a new boolean value with @a key under @a group_name. 772 * If @a key cannot be found then it is created. 773 * 774 * @newin{2,6} 775 * 776 * @param group_name A group name. 777 * @param key A key. 778 * @param value <tt>true</tt> or <tt>false</tt>. 779 */ 780 void set_boolean(const Glib::ustring& group_name, const Glib::ustring& key, bool value); 781 782 /** Associates a new integer value with @a key under @a group_name. 783 * If @a key cannot be found then it is created. 784 * 785 * @newin{2,6} 786 * 787 * @param group_name A group name. 788 * @param key A key. 789 * @param value An integer value. 790 */ 791 void set_integer(const Glib::ustring& group_name, const Glib::ustring& key, int value); 792 793 /** Associates a new integer value with @a key under @a group_name. 794 * If @a key cannot be found then it is created. 795 * 796 * @newin{2,26} 797 * 798 * @param group_name A group name. 799 * @param key A key. 800 * @param value An integer value. 801 */ 802 void set_int64(const Glib::ustring& group_name, const Glib::ustring& key, gint64 value); 803 804 /** Associates a new integer value with @a key under @a group_name. 805 * If @a key cannot be found then it is created. 806 * 807 * @newin{2,26} 808 * 809 * @param group_name A group name. 810 * @param key A key. 811 * @param value An integer value. 812 */ 813 void set_uint64(const Glib::ustring& group_name, const Glib::ustring& key, guint64 value); 814 815 /** Sets a list of string values for @a key under @a group_name. If 816 * key cannot be found it is created. If @a group_name cannot be found 817 * it is created. 818 * @param group_name The name of a group 819 * @param key The name of a key 820 * @param list A list holding objects of type Glib::ustring 821 */ 822 void set_string_list(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ArrayHandle<Glib::ustring>& list); 823 824 825 /** Sets a list of string values for the @a key under @a group_name and marks 826 * them as being for @a locale. If the @a key or @a group_name cannot be 827 * found, they are created. 828 * @param group_name The name of a group 829 * @param key The name of a key 830 * @param locale A locale 831 * @param list A list holding objects of type Glib::ustring 832 */ 833 void set_locale_string_list(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ustring& locale, const Glib::ArrayHandle<Glib::ustring>& list); 834 835 836 /** Sets a list of booleans for the @a key under @a group_name. 837 * If either the @a key or @a group_name cannot be found they are created. 838 * @param group_name The name of a group 839 * @param key The name of a key 840 * @param list A list holding object of type bool 841 */ 842 void set_boolean_list(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ArrayHandle<bool>& list); 843 844 845 /** Sets a list of integers for the @a key under @a group_name. 846 * If either the @a key or @a group_name cannot be found they are created. 847 * @param group_name The name of a group 848 * @param key The name of a key 849 * @param list A list holding object of type int 850 */ 851 void set_integer_list(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ArrayHandle<int>& list); 852 853 854 /** Sets a list of doubles for the @a key under @a group_name. 855 * If either the @a key or @a group_name cannot be found they are created. 856 * @param group_name The name of a group 857 * @param key The name of a key 858 * @param list A list holding object of type int 859 * 860 * @newin{2,14} 861 */ 862 void set_double_list(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ArrayHandle<double>& list); 863 864 865 /** Places @a comment at the start of the file, before the first group. 866 * @param comment The Comment 867 * @throw Glib::KeyFileError 868 */ 869 void set_comment(const Glib::ustring& comment); 870 871 /** Places @a comment above @a group_name. 872 * @param group_name The Group the comment should be above 873 * @param comment The comment 874 * @throw Glib::KeyFileError 875 */ 876 void set_comment(const Glib::ustring& group_name, const Glib::ustring& comment); 877 878 879 /** Places a comment above @a key from @a group_name. 880 * If @a key is <tt>nullptr</tt> then @a comment will be written above @a group_name. 881 * If both @a key and @a group_name are <tt>nullptr</tt>, then @a comment will be 882 * written above the first group in the file. 883 * 884 * \throw Glib::KeyFileError 885 * 886 * @param group_name A group name, or <tt>nullptr</tt>. 887 * @param key A key. 888 * @param comment A comment. 889 */ 890 void set_comment(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ustring& comment); 891 892 893 /** Removes a comment above @a key from @a group_name. 894 * If @a key is <tt>nullptr</tt> then @a comment will be removed above @a group_name. 895 * If both @a key and @a group_name are <tt>nullptr</tt>, then @a comment will 896 * be removed above the first group in the file. 897 * 898 * \throw Glib::KeyFileError 899 * 900 * @param group_name A group name, or <tt>nullptr</tt>. 901 * @param key A key. 902 */ 903 void remove_comment(const Glib::ustring& group_name, const Glib::ustring& key); 904 905 /** Removes @a key in @a group_name from the key file. 906 * 907 * \throw Glib::KeyFileError 908 * 909 * @param group_name A group name. 910 * @param key A key name to remove. 911 */ 912 void remove_key(const Glib::ustring& group_name, const Glib::ustring& key); 913 914 /** Removes the specified group, @a group_name, 915 * from the key file. 916 * 917 * \throw Glib::KeyFileError 918 * 919 * @param group_name A group name. 920 */ 921 void remove_group(const Glib::ustring& group_name); 922 gobj()923 GKeyFile* gobj() { return gobject_; } gobj()924 const GKeyFile* gobj() const { return gobject_; } 925 926 protected: 927 GKeyFile* gobject_; 928 bool owns_gobject_; 929 930 931 }; 932 933 } // namespace Glib 934 935 936 #endif /* _GLIBMM_KEYFILE_H */ 937 938