Class KeyFile

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.glib.KeyFile
All Implemented Interfaces:
Proxy
@Generated("org.javagi.JavaGI") public class KeyFile extends ProxyInstance

GKeyFile parses .ini-like config files.

GKeyFile lets you parse, edit or create files containing groups of key-value pairs, which we call ‘key files’ for lack of a better name. Several freedesktop.org specifications use key files. For example, the Desktop Entry Specification and the Icon Theme Specification.

The syntax of key files is described in detail in the Desktop Entry Specification, here is a quick summary: Key files consists of groups of key-value pairs, interspersed with comments.

# this is just an example
# there can be comments before the first group

[First Group]

Name=Key File Example\\tthis value shows\\nescaping

# localized strings are stored in multiple key-value pairs
Welcome=Hello
Welcome[de]=Hallo
Welcome[fr_FR]=Bonjour
Welcome[it]=Ciao

[Another Group]

Numbers=2;20;-200;0

Booleans=true;false;true;true

Lines beginning with a # and blank lines are considered comments.

Groups are started by a header line containing the group name enclosed in [ and ], and ended implicitly by the start of the next group or the end of the file. Each key-value pair must be contained in a group.

Key-value pairs generally have the form key=value, with the exception of localized strings, which have the form key[locale]=value, with a locale identifier of the form lang_COUNTRY@MODIFIER where COUNTRY and MODIFIER are optional. As a special case, the locale C is associated with the untranslated pair key=value (since GLib 2.84). Space before and after the = character is ignored. Newline, tab, carriage return and backslash characters in value are escaped as \\n, \\t, \\r, and \\\\\\\\, respectively. To preserve leading spaces in values, these can also be escaped as \\s.

Key files can store strings (possibly with localized variants), integers, booleans and lists of these. Lists are separated by a separator character, typically ; or ,. To use the list separator character in a value in a list, it has to be escaped by prefixing it with a backslash.

This syntax is obviously inspired by the .ini files commonly met on Windows, but there are some important differences:

  • .ini files use the ; character to begin comments, key files use the # character.

  • Key files do not allow for ungrouped keys meaning only comments can precede the first group.

  • Key files are always encoded in UTF-8.

  • Key and Group names are case-sensitive. For example, a group called [GROUP] is a different from [group].

  • .ini files don’t have a strongly typed boolean entry type, they only have GetProfileInt(). In key files, only true and false (in lower case) are allowed.

Note that in contrast to the Desktop Entry Specification, groups in key files may contain the same key multiple times; the last entry wins. Key files may also contain multiple groups with the same name; they are merged together. Another difference is that keys and group names in key files are not restricted to ASCII characters.

Here is an example of loading a key file and reading a value:

g_autoptr(GError) error = NULL;
g_autoptr(GKeyFile) key_file = g_key_file_new ();

if (!g_key_file_load_from_file (key_file, "key-file.ini", flags, &error))
  {
    if (!g_error_matches (error, G_FILE_ERROR, G_FILE_ERROR_NOENT))
      g_warning ("Error loading key file: %s", error->message);
    return;
  }

g_autofree gchar *val = g_key_file_get_string (key_file, "Group Name", "SomeKey", &error);
if (val == NULL &&
    !g_error_matches (error, G_KEY_FILE_ERROR, G_KEY_FILE_ERROR_KEY_NOT_FOUND))
  {
    g_warning ("Error finding key in key file: %s", error->message);
    return;
  }
else if (val == NULL)
  {
    // Fall back to a default value.
    val = g_strdup ("default-value");
  }

Here is an example of creating and saving a key file:

g_autoptr(GKeyFile) key_file = g_key_file_new ();
const gchar *val = …;
g_autoptr(GError) error = NULL;

g_key_file_set_string (key_file, "Group Name", "SomeKey", val);

// Save as a file.
if (!g_key_file_save_to_file (key_file, "key-file.ini", &error))
  {
    g_warning ("Error saving key file: %s", error->message);
    return;
  }

// Or store to a GBytes for use elsewhere.
gsize data_len;
g_autofree guint8 *data = (guint8 *) g_key_file_to_data (key_file, &data_len, &error);
if (data == NULL)
  {
    g_warning ("Error saving key file: %s", error->message);
    return;
  }
g_autoptr(GBytes) bytes = g_bytes_new_take (g_steal_pointer (&data), data_len);

  • Constructor Details

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the KeyFile class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • errorQuark

      public static Quark errorQuark()

    • free

      public void free()

      Clears all keys and groups from keyFile, and decreases the reference count by 1.

      If the reference count reaches zero, frees the key file and all its allocated memory.

      Since:
      2.6

    • getBoolean

      public boolean getBoolean(String groupName, String key) throws GErrorException

      Returns the value associated with key under groupName as a boolean.

      If key cannot be found then GLib.KeyFileError.KEY_NOT_FOUND is returned. Likewise, if the value associated with key cannot be interpreted as a boolean then GLib.KeyFileError.INVALID_VALUE is returned.

      Parameters:
      groupName - a group name
      key - a key
      Returns:
      the value associated with the key as a boolean, or false if the key was not found or could not be parsed.
      Throws:
      GErrorException - see GError
      Since:
      2.6

    • getBooleanList

      public boolean[] getBooleanList(String groupName, String key) throws GErrorException

      Returns the values associated with key under groupName as booleans.

      If key cannot be found then GLib.KeyFileError.KEY_NOT_FOUND is returned. Likewise, if the values associated with key cannot be interpreted as booleans then GLib.KeyFileError.INVALID_VALUE is returned.

      Parameters:
      groupName - a group name
      key - a key
      Returns:
      the values associated with the key as a list of booleans, or NULL if the key was not found or could not be parsed. The returned list of booleans should be freed with GLib.free(MemorySegment) when no longer needed.
      Throws:
      GErrorException - see GError
      Since:
      2.6

    • getComment

      public String getComment(@Nullable String groupName, @Nullable String key) throws GErrorException

      Retrieves a comment above key from groupName.

      If key is NULL then comment will be read from above groupName. If both key and groupName are NULL, then comment will be read from above the first group in the file.

      Note that the returned string does not include the # comment markers, but does include any whitespace after them (on each line). It includes the line breaks between lines, but does not include the final line break.

      Parameters:
      groupName - a group name, or NULL to get a top-level comment
      key - a key, or NULL to get a group comment
      Returns:
      a comment that should be freed with GLib.free(MemorySegment)
      Throws:
      GErrorException - see GError
      Since:
      2.6

    • getDouble

      public double getDouble(String groupName, String key) throws GErrorException

      Returns the value associated with key under groupName as a double.

      If key cannot be found then GLib.KeyFileError.KEY_NOT_FOUND is returned. Likewise, if the value associated with key cannot be interpreted as a double then GLib.KeyFileError.INVALID_VALUE is returned.

      Parameters:
      groupName - a group name
      key - a key
      Returns:
      the value associated with the key as a double, or 0.0 if the key was not found or could not be parsed.
      Throws:
      GErrorException - see GError
      Since:
      2.12

    • getDoubleList

      public double[] getDoubleList(String groupName, String key) throws GErrorException

      Returns the values associated with key under groupName as doubles.

      If key cannot be found then GLib.KeyFileError.KEY_NOT_FOUND is returned. Likewise, if the values associated with key cannot be interpreted as doubles then GLib.KeyFileError.INVALID_VALUE is returned.

      Parameters:
      groupName - a group name
      key - a key
      Returns:
      the values associated with the key as a list of doubles, or NULL if the key was not found or could not be parsed. The returned list of doubles should be freed with GLib.free(MemorySegment) when no longer needed.
      Throws:
      GErrorException - see GError
      Since:
      2.12

    • getGroups

      public String[] getGroups(@Nullable Out<Long> length)

      Returns all groups in the key file loaded with keyFile.

      The array of returned groups will be NULL-terminated, so length may optionally be NULL.

      Parameters:
      length - return location for the number of returned groups, or NULL to ignore
      Returns:
      a newly-allocated NULL-terminated array of strings. Use GLib.strfreev(MemorySegment) to free it.
      Since:
      2.6

    • getInt64

      public long getInt64(String groupName, String key) throws GErrorException

      Returns the value associated with key under groupName as a signed 64-bit integer.

      This is similar to getInteger(String, String) but can return 64-bit results without truncation.

      Parameters:
      groupName - a group name
      key - a key
      Returns:
      the value associated with the key as a signed 64-bit integer, or 0 if the key was not found or could not be parsed.
      Throws:
      GErrorException - see GError
      Since:
      2.26

    • getInteger

      public int getInteger(String groupName, String key) throws GErrorException

      Returns the value associated with key under groupName as an integer.

      If key cannot be found then GLib.KeyFileError.KEY_NOT_FOUND is returned. Likewise, if the value associated with key cannot be interpreted as an integer, or is out of range for a gint, then GLib.KeyFileError.INVALID_VALUE is returned.

      Parameters:
      groupName - a group name
      key - a key
      Returns:
      the value associated with the key as an integer, or 0 if the key was not found or could not be parsed.
      Throws:
      GErrorException - see GError
      Since:
      2.6

    • getIntegerList

      public int[] getIntegerList(String groupName, String key) throws GErrorException

      Returns the values associated with key under groupName as integers.

      If key cannot be found then GLib.KeyFileError.KEY_NOT_FOUND is returned. Likewise, if the values associated with key cannot be interpreted as integers, or are out of range for gint, then GLib.KeyFileError.INVALID_VALUE is returned.

      Parameters:
      groupName - a group name
      key - a key
      Returns:
      the values associated with the key as a list of integers, or NULL if the key was not found or could not be parsed. The returned list of integers should be freed with GLib.free(MemorySegment) when no longer needed.
      Throws:
      GErrorException - see GError
      Since:
      2.6

    • getKeys

      public String[] getKeys(String groupName, @Nullable Out<Long> length) throws GErrorException

      Returns all keys for the group name groupName.

      The array of returned keys will be NULL-terminated, so length may optionally be NULL. If the groupName cannot be found, GLib.KeyFileError.GROUP_NOT_FOUND is returned.

      Parameters:
      groupName - a group name
      length - return location for the number of keys returned, or NULL to ignore
      Returns:
      a newly-allocated NULL-terminated array of strings. Use GLib.strfreev(MemorySegment) to free it.
      Throws:
      GErrorException - see GError
      Since:
      2.6

    • getLocaleForKey

      public @Nullable String getLocaleForKey(String groupName, String key, @Nullable String locale)

      Returns the actual locale which the result of getLocaleString(String, String, String) or getLocaleStringList(String, String, String) came from.

      If calling getLocaleString(String, String, String) or getLocaleStringList(String, String, String) with exactly the same keyFile, groupName, key and locale, the result of those functions will have originally been tagged with the locale that is the result of this function.

      Parameters:
      groupName - a group name
      key - a key
      locale - a locale identifier or NULL to use the current locale
      Returns:
      the locale from the file, or NULL if the key was not found or the entry in the file was was untranslated
      Since:
      2.56

    • getLocaleString

      public String getLocaleString(String groupName, String key, @Nullable String locale) throws GErrorException

      Returns the value associated with key under groupName translated in the given locale if available.

      If locale is C then the untranslated value is returned (since GLib 2.84).

      If locale is NULL then the current locale is assumed.

      If locale is to be non-NULL, or if the current locale will change over the lifetime of the GLib.KeyFile, it must be loaded with GLib.KeyFileFlags.KEEP_TRANSLATIONS in order to load strings for all locales.

      If key cannot be found then GLib.KeyFileError.KEY_NOT_FOUND is returned. If the value associated with key cannot be interpreted or no suitable translation can be found then the untranslated value is returned.

      Parameters:
      groupName - a group name
      key - a key
      locale - a locale identifier or NULL to use the current locale
      Returns:
      a newly allocated string or NULL if the specified key cannot be found.
      Throws:
      GErrorException - see GError
      Since:
      2.6

    • getLocaleStringList

      public String[] getLocaleStringList(String groupName, String key, @Nullable String locale) throws GErrorException

      Returns the values associated with key under groupName translated in the given locale if available.

      If locale is C then the untranslated value is returned (since GLib 2.84).

      If locale is NULL then the current locale is assumed.

      If locale is to be non-NULL, or if the current locale will change over the lifetime of the GLib.KeyFile, it must be loaded with GLib.KeyFileFlags.KEEP_TRANSLATIONS in order to load strings for all locales.

      If key cannot be found then GLib.KeyFileError.KEY_NOT_FOUND is returned. If the values associated with key cannot be interpreted or no suitable translations can be found then the untranslated values are returned. The returned array is NULL-terminated, so length may optionally be NULL.

      Parameters:
      groupName - a group name
      key - a key
      locale - a locale identifier or NULL to use the current locale
      Returns:
      a newly allocated NULL-terminated string array or NULL if the key isn’t found. The string array should be freed with GLib.strfreev(MemorySegment).
      Throws:
      GErrorException - see GError
      Since:
      2.6

    • getStartGroup

      public @Nullable String getStartGroup()
      Returns the name of the start group of the file.
      Returns:
      The start group of the key file.
      Since:
      2.6

    • getString

      public String getString(String groupName, String key) throws GErrorException

      Returns the string value associated with key under groupName.

      Unlike getValue(String, String), this function handles escape sequences like \\s.

      If the key cannot be found, GLib.KeyFileError.KEY_NOT_FOUND is returned. If the groupName cannot be found, GLib.KeyFileError.GROUP_NOT_FOUND is returned.

      Parameters:
      groupName - a group name
      key - a key
      Returns:
      a newly allocated string or NULL if the specified key cannot be found.
      Throws:
      GErrorException - see GError
      Since:
      2.6

    • getStringList

      public String[] getStringList(String groupName, String key) throws GErrorException

      Returns the values associated with key under groupName.

      If the key cannot be found, GLib.KeyFileError.KEY_NOT_FOUND is returned. If the groupName cannot be found, GLib.KeyFileError.GROUP_NOT_FOUND is returned.

      Parameters:
      groupName - a group name
      key - a key
      Returns:
      a NULL-terminated string array or NULL if the specified key cannot be found. The array should be freed with GLib.strfreev(MemorySegment).
      Throws:
      GErrorException - see GError
      Since:
      2.6

    • getUint64

      public long getUint64(String groupName, String key) throws GErrorException

      Returns the value associated with key under groupName as an unsigned 64-bit integer.

      This is similar to getInteger(String, String) but can return large positive results without truncation.

      Parameters:
      groupName - a group name
      key - a key
      Returns:
      the value associated with the key as an unsigned 64-bit integer, or 0 if the key was not found or could not be parsed.
      Throws:
      GErrorException - see GError
      Since:
      2.26

    • getValue

      public String getValue(String groupName, String key) throws GErrorException

      Returns the raw value associated with key under groupName.

      Use getString(String, String) to retrieve an unescaped UTF-8 string.

      If the key cannot be found, GLib.KeyFileError.KEY_NOT_FOUND is returned. If the groupName cannot be found, GLib.KeyFileError.GROUP_NOT_FOUND is returned.

      Parameters:
      groupName - a group name
      key - a key
      Returns:
      a newly allocated string or NULL if the specified key cannot be found.
      Throws:
      GErrorException - see GError
      Since:
      2.6

    • hasGroup

      public boolean hasGroup(String groupName)
      Looks whether the key file has the group groupName.
      Parameters:
      groupName - a group name
      Returns:
      true if groupName is a part of keyFile, false otherwise.
      Since:
      2.6

    • hasKey

      public boolean hasKey(String groupName, String key) throws GErrorException

      Looks whether the key file has the key key in the group groupName.

      Note that this function does not follow the rules for GLib.Error strictly; the return value both carries meaning and signals an error. To use this function, you must pass a GLib.Error pointer in error, and check whether it is not NULL to see if an error occurred.

      Language bindings should use getValue(String, String) to test whether a key exists.

      Parameters:
      groupName - a group name
      key - a key name
      Returns:
      true if key is a part of groupName, false otherwise
      Throws:
      GErrorException - see GError
      Since:
      2.6

    • loadFromBytes

      public boolean loadFromBytes(byte[] bytes, Set<KeyFileFlags> flags) throws GErrorException

      Loads a key file from the data in bytes into an empty GLib.KeyFile structure.

      If the object cannot be created then a GLib.KeyFileError is returned.

      Parameters:
      bytes - a GLib.Bytes
      flags - flags from GLib.KeyFileFlags
      Returns:
      true if a key file could be loaded, false otherwise
      Throws:
      GErrorException - see GError
      Since:
      2.50

    • loadFromBytes

      public boolean loadFromBytes(byte[] bytes, KeyFileFlags... flags) throws GErrorException

      Loads a key file from the data in bytes into an empty GLib.KeyFile structure.

      If the object cannot be created then a GLib.KeyFileError is returned.

      Parameters:
      bytes - a GLib.Bytes
      flags - flags from GLib.KeyFileFlags
      Returns:
      true if a key file could be loaded, false otherwise
      Throws:
      GErrorException - see GError
      Since:
      2.50

    • loadFromData

      public boolean loadFromData(String data, long length, Set<KeyFileFlags> flags) throws GErrorException

      Loads a key file from memory into an empty GLib.KeyFile structure.

      If the object cannot be created then a [errorGLib.KeyFileError is returned.

      Parameters:
      data - key file loaded in memory
      length - the length of data in bytes (or (gsize)-1 if data is nul-terminated)
      flags - flags from GLib.KeyFileFlags
      Returns:
      true if a key file could be loaded, false otherwise
      Throws:
      GErrorException - see GError
      Since:
      2.6

    • loadFromData

      public boolean loadFromData(String data, long length, KeyFileFlags... flags) throws GErrorException

      Loads a key file from memory into an empty GLib.KeyFile structure.

      If the object cannot be created then a [errorGLib.KeyFileError is returned.

      Parameters:
      data - key file loaded in memory
      length - the length of data in bytes (or (gsize)-1 if data is nul-terminated)
      flags - flags from GLib.KeyFileFlags
      Returns:
      true if a key file could be loaded, false otherwise
      Throws:
      GErrorException - see GError
      Since:
      2.6

    • loadFromDataDirs

      public boolean loadFromDataDirs(String file, @Nullable Out<String> fullPath, Set<KeyFileFlags> flags) throws GErrorException

      Looks for a key file named file in the paths returned from GLib.getUserDataDir() and GLib.getSystemDataDirs().

      The search algorithm from loadFromDirs(String, String[], Out, Set) is used. If file is found, it’s loaded into this KeyFile and its full path is returned in fullPath.

      If the file could not be loaded then either a GLib.FileError or GLib.KeyFileError is returned.

      Parameters:
      file - a relative path to a filename to open and parse
      fullPath - return location for a string containing the full path of the file, or NULL to ignore
      flags - flags from GLib.KeyFileFlags
      Returns:
      true if a key file could be loaded, false otherwise
      Throws:
      GErrorException - see GError
      Since:
      2.6

    • loadFromDataDirs

      public boolean loadFromDataDirs(String file, @Nullable Out<String> fullPath, KeyFileFlags... flags) throws GErrorException

      Looks for a key file named file in the paths returned from GLib.getUserDataDir() and GLib.getSystemDataDirs().

      The search algorithm from loadFromDirs(String, String[], Out, Set) is used. If file is found, it’s loaded into this KeyFile and its full path is returned in fullPath.

      If the file could not be loaded then either a GLib.FileError or GLib.KeyFileError is returned.

      Parameters:
      file - a relative path to a filename to open and parse
      fullPath - return location for a string containing the full path of the file, or NULL to ignore
      flags - flags from GLib.KeyFileFlags
      Returns:
      true if a key file could be loaded, false otherwise
      Throws:
      GErrorException - see GError
      Since:
      2.6

    • loadFromDirs

      public boolean loadFromDirs(String file, @Nullable String @Nullable [] searchDirs, @Nullable Out<String> fullPath, Set<KeyFileFlags> flags) throws GErrorException

      Looks for a key file named file in the paths specified in searchDirs, loads the file into this KeyFile and returns the file’s full path in fullPath.

      searchDirs are checked in the order listed in the array, with the highest priority directory listed first. Within each directory, file is looked for. If it’s not found, - characters in file are progressively replaced with directory separators to search subdirectories of the search directory. If the file has not been found after all - characters have been replaced, the next search directory in searchDirs is checked.

      If the file could not be found in any of the searchDirs, GLib.KeyFileError.NOT_FOUND is returned. If the file is found but the OS returns an error when opening or reading the file, a GLib.FileError is returned. If there is a problem parsing the file, a GLib.KeyFileError is returned.

      Parameters:
      file - a relative path to a filename to open and parse
      searchDirs - NULL-terminated array of directories to search
      fullPath - return location for a string containing the full path of the file, or NULL to ignore
      flags - flags from GLib.KeyFileFlags
      Returns:
      true if a key file could be loaded, false otherwise
      Throws:
      GErrorException - see GError
      Since:
      2.14

    • loadFromDirs

      public boolean loadFromDirs(String file, @Nullable String @Nullable [] searchDirs, @Nullable Out<String> fullPath, KeyFileFlags... flags) throws GErrorException

      Looks for a key file named file in the paths specified in searchDirs, loads the file into this KeyFile and returns the file’s full path in fullPath.

      searchDirs are checked in the order listed in the array, with the highest priority directory listed first. Within each directory, file is looked for. If it’s not found, - characters in file are progressively replaced with directory separators to search subdirectories of the search directory. If the file has not been found after all - characters have been replaced, the next search directory in searchDirs is checked.

      If the file could not be found in any of the searchDirs, GLib.KeyFileError.NOT_FOUND is returned. If the file is found but the OS returns an error when opening or reading the file, a GLib.FileError is returned. If there is a problem parsing the file, a GLib.KeyFileError is returned.

      Parameters:
      file - a relative path to a filename to open and parse
      searchDirs - NULL-terminated array of directories to search
      fullPath - return location for a string containing the full path of the file, or NULL to ignore
      flags - flags from GLib.KeyFileFlags
      Returns:
      true if a key file could be loaded, false otherwise
      Throws:
      GErrorException - see GError
      Since:
      2.14

    • loadFromFile

      public boolean loadFromFile(String file, Set<KeyFileFlags> flags) throws GErrorException

      Loads a key file into an empty GLib.KeyFile structure.

      If the OS returns an error when opening or reading the file, a GLib.FileError is returned. If there is a problem parsing the file, a GLib.KeyFileError is returned.

      This function will never return a GLib.KeyFileError.NOT_FOUND error. If the file is not found, GLib.FileError.NOENT is returned.

      Parameters:
      file - the path of a filename to load, in the GLib filename encoding
      flags - flags from GLib.KeyFileFlags
      Returns:
      true if a key file could be loaded, false otherwise
      Throws:
      GErrorException - see GError
      Since:
      2.6

    • loadFromFile

      public boolean loadFromFile(String file, KeyFileFlags... flags) throws GErrorException

      Loads a key file into an empty GLib.KeyFile structure.

      If the OS returns an error when opening or reading the file, a GLib.FileError is returned. If there is a problem parsing the file, a GLib.KeyFileError is returned.

      This function will never return a GLib.KeyFileError.NOT_FOUND error. If the file is not found, GLib.FileError.NOENT is returned.

      Parameters:
      file - the path of a filename to load, in the GLib filename encoding
      flags - flags from GLib.KeyFileFlags
      Returns:
      true if a key file could be loaded, false otherwise
      Throws:
      GErrorException - see GError
      Since:
      2.6

    • ref

      public KeyFile ref()
      Increases the reference count of keyFile.
      Returns:
      the same keyFile.
      Since:
      2.32

    • removeComment

      public boolean removeComment(@Nullable String groupName, @Nullable String key) throws GErrorException

      Removes a comment above key from groupName.

      If key is NULL then comment will be removed above groupName. If both key and groupName are NULL, then comment will be removed above the first group in the file.

      Parameters:
      groupName - a group name, or NULL to get a top-level comment
      key - a key, or NULL to get a group comment
      Returns:
      true if the comment was removed, false otherwise
      Throws:
      GErrorException - see GError
      Since:
      2.6

    • removeGroup

      public boolean removeGroup(String groupName) throws GErrorException
      Removes the specified group, groupName, from the key file.
      Parameters:
      groupName - a group name
      Returns:
      true if the group was removed, false otherwise
      Throws:
      GErrorException - see GError
      Since:
      2.6

    • removeKey

      public boolean removeKey(String groupName, String key) throws GErrorException
      Removes key in groupName from the key file.
      Parameters:
      groupName - a group name
      key - a key name to remove
      Returns:
      true if the key was removed, false otherwise
      Throws:
      GErrorException - see GError
      Since:
      2.6

    • saveToFile

      public boolean saveToFile(String filename) throws GErrorException

      Writes the contents of this KeyFile to filename using GLib.fileSetContents(String, byte[]).

      If you need stricter guarantees about durability of the written file than are provided by GLib.fileSetContents(String, byte[]), use GLib.fileSetContentsFull(String, byte[], Set, int) with the return value of toData(Out).

      This function can fail for any of the reasons that GLib.fileSetContents(String, byte[]) may fail.

      Parameters:
      filename - the name of the file to write to
      Returns:
      true if successful, false otherwise
      Throws:
      GErrorException - see GError
      Since:
      2.40

    • setBoolean

      public void setBoolean(String groupName, String key, boolean value)

      Associates a new boolean value with key under groupName.

      If key cannot be found then it is created.

      Parameters:
      groupName - a group name
      key - a key
      value - true or false
      Since:
      2.6

    • setBooleanList

      public void setBooleanList(String groupName, String key, @Nullable boolean @Nullable [] list)

      Associates a list of boolean values with key under groupName.

      If key cannot be found then it is created.

      Parameters:
      groupName - a group name
      key - a key
      list - an array of boolean values
      Since:
      2.6

    • setComment

      public boolean setComment(@Nullable String groupName, @Nullable String key, String comment) throws GErrorException

      Places a comment above key from groupName.

      If key is NULL then comment will be written above groupName. If both key and groupName are NULL, then comment will be written above the first group in the file.

      Passing a non-existent groupName or key to this function returns false and populates error. (In contrast, passing a non-existent group_name or key to setString(String, String, String) creates the associated group name and key.)

      Note that this function prepends a # comment marker to each line of comment.

      Parameters:
      groupName - a group name, or NULL to write a top-level comment
      key - a key, or NULL to write a group comment
      comment - a comment
      Returns:
      true if the comment was written, false otherwise
      Throws:
      GErrorException - see GError
      Since:
      2.6

    • setDouble

      public void setDouble(String groupName, String key, double value)

      Associates a new double value with key under groupName.

      If key cannot be found then it is created.

      Parameters:
      groupName - a group name
      key - a key
      value - a double value
      Since:
      2.12

    • setDoubleList

      public void setDoubleList(String groupName, String key, @Nullable double @Nullable [] list)

      Associates a list of double values with key under groupName.

      If key cannot be found then it is created.

      Parameters:
      groupName - a group name
      key - a key
      list - an array of double values
      Since:
      2.12

    • setInt64

      public void setInt64(String groupName, String key, long value)

      Associates a new integer value with key under groupName.

      If key cannot be found then it is created.

      Parameters:
      groupName - a group name
      key - a key
      value - an integer value
      Since:
      2.26

    • setInteger

      public void setInteger(String groupName, String key, int value)

      Associates a new integer value with key under groupName.

      If key cannot be found then it is created.

      Parameters:
      groupName - a group name
      key - a key
      value - an integer value
      Since:
      2.6

    • setIntegerList

      public void setIntegerList(String groupName, String key, @Nullable int @Nullable [] list)

      Associates a list of integer values with key under groupName.

      If key cannot be found then it is created.

      Parameters:
      groupName - a group name
      key - a key
      list - an array of integer values
      Since:
      2.6

    • setListSeparator

      public void setListSeparator(byte separator)

      Sets the character which is used to separate values in lists.

      Typically ; or , are used as separators. The default list separator is ;.

      Parameters:
      separator - the separator
      Since:
      2.6

    • setLocaleString

      public void setLocaleString(String groupName, String key, String locale, String string)

      Associates a string value for key and locale under groupName.

      If the translation for key cannot be found then it is created.

      If locale is C then the untranslated value is set (since GLib 2.84).

      Parameters:
      groupName - a group name
      key - a key
      locale - a locale identifier
      string - a string
      Since:
      2.6

    • setLocaleStringList

      public void setLocaleStringList(String groupName, String key, String locale, @Nullable String @Nullable [] list)

      Associates a list of string values for key and locale under groupName.

      If locale is C then the untranslated value is set (since GLib 2.84).

      If the translation for key cannot be found then it is created.

      Parameters:
      groupName - a group name
      key - a key
      locale - a locale identifier
      list - a NULL-terminated array of locale string values
      Since:
      2.6

    • setString

      public void setString(String groupName, String key, String string)

      Associates a new string value with key under groupName.

      If key cannot be found then it is created. If groupName cannot be found then it is created. Unlike setValue(String, String, String), this function handles characters that need escaping, such as newlines.

      Parameters:
      groupName - a group name
      key - a key
      string - a string
      Since:
      2.6

    • setStringList

      public void setStringList(String groupName, String key, @Nullable String @Nullable [] list)

      Associates a list of string values for key under groupName.

      If key cannot be found then it is created. If groupName cannot be found then it is created.

      Parameters:
      groupName - a group name
      key - a key
      list - an array of string values
      Since:
      2.6

    • setUint64

      public void setUint64(String groupName, String key, long value)

      Associates a new integer value with key under groupName.

      If key cannot be found then it is created.

      Parameters:
      groupName - a group name
      key - a key
      value - an integer value
      Since:
      2.26

    • setValue

      public void setValue(String groupName, String key, String value)

      Associates a new value with key under groupName.

      If key cannot be found then it is created. If groupName cannot be found then it is created. To set an UTF-8 string which may contain characters that need escaping (such as newlines or spaces), use setString(String, String, String).

      Parameters:
      groupName - a group name
      key - a key
      value - a string
      Since:
      2.6

    • toData

      public String toData(@Nullable Out<Long> length) throws GErrorException

      Outputs this KeyFile as a string.

      Note that this function never reports an error.

      Parameters:
      length - return location for the length of the returned string, or NULL to ignore
      Returns:
      a newly allocated string holding the contents of the key file
      Throws:
      GErrorException - see GError
      Since:
      2.6

    • unref

      public void unref()

      Decreases the reference count of this KeyFile by 1.

      If the reference count reaches zero, frees the key file and all its allocated memory.

      Since:
      2.32