gimpenv: GIMP Base Library Reference Manual

+ + +

gimpenv

gimpenv — Functions to access the GIMP environment.

Functions

++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+void +	+gimp_env_init () +
const gchar * +	+gimp_directory () +
const gchar * +	+gimp_installation_directory () +
const gchar * +	+gimp_data_directory () +
const gchar * +	+gimp_locale_directory () +
const gchar * +	+gimp_plug_in_directory () +
const gchar * +	+gimp_sysconf_directory () +
const gchar * +	+gimp_cache_directory () +
const gchar * +	+gimp_temp_directory () +
+GFile * +	+gimp_directory_file () +
+GFile * +	+gimp_installation_directory_file () +
+GFile * +	+gimp_data_directory_file () +
+GFile * +	+gimp_locale_directory_file () +
+GFile * +	+gimp_sysconf_directory_file () +
+GFile * +	+gimp_plug_in_directory_file () +
const gchar * +	+gimp_user_directory () +
+gchar * +	+gimp_personal_rc_file () +
const gchar * +	+gimp_gtkrc () +
+GList * +	+gimp_path_parse () +
+gchar * +	+gimp_path_to_str () +
+void +	+gimp_path_free () +
+gchar * +	+gimp_path_get_user_writable_dir () +

Description

A set of functions to find the locations of GIMP's data directories +and configuration files.

Functions

gimp_env_init ()

void
+gimp_env_init (gboolean plug_in);

You don't need to care about this function. It is being called for +you automatically (by means of the MAIN() macro that every plug-in +runs). Calling it again will cause a fatal error.

Parameters

+++++ + + + + + +

plug_in

must be TRUE if this function is called from a plug-in

Since: 2.4

gimp_directory ()

const gchar *
+gimp_directory (void);

Returns the user-specific GIMP settings directory. If the +environment variable GIMP2_DIRECTORY exists, it is used. If it is +an absolute path, it is used as is. If it is a relative path, it +is taken to be a subdirectory of the home directory. If it is a +relative path, and no home directory can be determined, it is taken +to be a subdirectory of gimp_data_directory().

The usual case is that no GIMP2_DIRECTORY environment variable +exists, and then we use the GIMPDIR subdirectory of the local +configuration directory:

UNIX: $XDG_CONFIG_HOME (defaults to $HOME/.config/)
Windows: CSIDL_APPDATA
OSX (UNIX exception): the Application Support Directory.

If neither the configuration nor home directory exist, +g_get_user_config_dir() will return {tmp}/{user_name}/.config/ where +the temporary directory {tmp} and the {user_name} are determined +according to platform rules.

In any case, we always return some non-empty string, whether it +corresponds to an existing directory or not.

In config files such as gimprc, the string ${gimp_dir} expands to +this directory.

The returned string is owned by GIMP and must not be modified or +freed. The returned string is in the encoding used for filenames by +GLib, which isn't necessarily UTF-8 (on Windows it is always +UTF-8.)

Returns

The user-specific GIMP settings directory.

gimp_installation_directory ()

const gchar *
+gimp_installation_directory (void);

Returns the top installation directory of GIMP. On Unix the +compile-time defined installation prefix is used. On Windows, the +installation directory as deduced from the executable's full +filename is used. On OSX we ask [NSBundle mainBundle] for the +resource path to check if GIMP is part of a relocatable bundle.

In config files such as gimprc, the string ${gimp_installation_dir} +expands to this directory.

The returned string is owned by GIMP and must not be modified or +freed. The returned string is in the encoding used for filenames by +GLib, which isn't necessarily UTF-8. (On Windows it always is +UTF-8.)

Returns

The toplevel installation directory of GIMP.

Since: 2.8

gimp_data_directory ()

const gchar *
+gimp_data_directory (void);

Returns the default top directory for GIMP data. If the environment +variable GIMP2_DATADIR exists, that is used. It should be an +absolute pathname. Otherwise, on Unix the compile-time defined +directory is used. On Windows, the installation directory as +deduced from the executable's full filename is used.

Note that the actual directories used for GIMP data files can be +overridden by the user in the preferences dialog.

In config files such as gimprc, the string ${gimp_data_dir} expands +to this directory.

Returns

The top directory for GIMP data.

gimp_locale_directory ()

const gchar *
+gimp_locale_directory (void);

Returns the top directory for GIMP locale files. If the environment +variable GIMP2_LOCALEDIR exists, that is used. It should be an +absolute pathname. Otherwise, on Unix the compile-time defined +directory is used. On Windows, the installation directory as deduced +from the executable's full filename is used.

The returned string is owned by GIMP and must not be modified or +freed. The returned string is in the encoding used for filenames by +the C library, which isn't necessarily UTF-8. (On Windows, unlike +the other similar functions here, the return value from this +function is in the system codepage, never in UTF-8. It can thus be +passed directly to the bindtextdomain() function from libintl which +does not handle UTF-8.)

Returns

The top directory for GIMP locale files.

gimp_plug_in_directory ()

const gchar *
+gimp_plug_in_directory (void);

Returns the default top directory for GIMP plug-ins and modules. If +the environment variable GIMP2_PLUGINDIR exists, that is used. It +should be an absolute pathname. Otherwise, on Unix the compile-time +defined directory is used. On Windows, the installation directory +as deduced from the executable's full filename is used.

Note that the actual directories used for GIMP plug-ins and modules +can be overridden by the user in the preferences dialog.

In config files such as gimprc, the string ${gimp_plug_in_dir} +expands to this directory.

Returns

The top directory for GIMP plug_ins and modules.

gimp_sysconf_directory ()

const gchar *
+gimp_sysconf_directory (void);

Returns the top directory for GIMP config files. If the environment +variable GIMP2_SYSCONFDIR exists, that is used. It should be an +absolute pathname. Otherwise, on Unix the compile-time defined +directory is used. On Windows, the installation directory as deduced +from the executable's full filename is used.

In config files such as gimprc, the string ${gimp_sysconf_dir} +expands to this directory.

Returns

The top directory for GIMP config files.

gimp_cache_directory ()

const gchar *
+gimp_cache_directory (void);

Returns the default top directory for GIMP cached files. If the +environment variable GIMP2_CACHEDIR exists, that is used. It +should be an absolute pathname. Otherwise, a subdirectory of the +directory returned by g_get_user_cache_dir() is used.

Note that the actual directories used for GIMP caches files can +be overridden by the user in the preferences dialog.

In config files such as gimprc, the string ${gimp_cache_dir} +expands to this directory.

Returns

The default top directory for GIMP cached files.

Since: 2.10.10

gimp_temp_directory ()

const gchar *
+gimp_temp_directory (void);

Returns the default top directory for GIMP temporary files. If the +environment variable GIMP2_TEMPDIR exists, that is used. It +should be an absolute pathname. Otherwise, a subdirectory of the +directory returned by g_get_tmp_dir() is used.

In config files such as gimprc, the string ${gimp_temp_dir} expands +to this directory.

Note that the actual directories used for GIMP temporary files can +be overridden by the user in the preferences dialog.

Returns

The default top directory for GIMP temporary files.

Since: 2.10.10

gimp_directory_file ()

GFile *
+gimp_directory_file (const gchar *first_element,
+                     ...);

Returns a GFile in the user's GIMP directory, or the data +directory itself if first_element + is NULL.

Parameters

+++++ + + + + + + + + + + + + +

first_element	the first element of a path to a file in the +user's GIMP directory, or `NULL`.
...	a `NULL` terminated list of the remaining elements of the path +to the file.

Returns

a new GFile +for the path, Free with g_object_unref().

Since: 2.10

gimp_installation_directory_file ()

GFile *
+gimp_installation_directory_file (const gchar *first_element,
+                                  ...);

Returns a GFile in the installation directory, or the installation +directory itself if first_element + is NULL.

Parameters

+++++ + + + + + + + + + + + + +

first_element	the first element of a path to a file in the +top installation directory, or `NULL`.
...	a `NULL` terminated list of the remaining elements of the path +to the file.

Returns

a new GFile +for the path, Free with g_object_unref().

Since: 2.10.10

gimp_data_directory_file ()

GFile *
+gimp_data_directory_file (const gchar *first_element,
+                          ...);

Returns a GFile in the data directory, or the data directory +itself if first_element + is NULL.

Parameters

+++++ + + + + + + + + + + + + +

first_element	the first element of a path to a file in the +data directory, or `NULL`.
...	a `NULL` terminated list of the remaining elements of the path +to the file.

Returns

a new GFile +for the path, Free with g_object_unref().

Since: 2.10

gimp_locale_directory_file ()

GFile *
+gimp_locale_directory_file (const gchar *first_element,
+                            ...);

Returns a GFile in the locale directory, or the locale directory +itself if first_element + is NULL.

Parameters

+++++ + + + + + + + + + + + + +

first_element	the first element of a path to a file in the +locale directory, or `NULL`.
...	a `NULL` terminated list of the remaining elements of the path +to the file.

Returns

a new GFile +for the path, Free with g_object_unref().

Since: 2.10

gimp_sysconf_directory_file ()

GFile *
+gimp_sysconf_directory_file (const gchar *first_element,
+                             ...);

Returns a GFile in the sysconf directory, or the sysconf directory +itself if first_element + is NULL.

Parameters

+++++ + + + + + + + + + + + + +

first_element	the first element of a path to a file in the +sysconf directory, or `NULL`.
...	a `NULL` terminated list of the remaining elements of the path +to the file.

Returns

a new GFile +for the path, Free with g_object_unref().

Since: 2.10

gimp_plug_in_directory_file ()

GFile *
+gimp_plug_in_directory_file (const gchar *first_element,
+                             ...);

Returns a GFile in the plug-in directory, or the plug-in directory +itself if first_element + is NULL.

Parameters

+++++ + + + + + + + + + + + + +

first_element	the first element of a path to a file in the +plug-in directory, or `NULL`.
...	a `NULL` terminated list of the remaining elements of the path +to the file.

Returns

a new GFile +for the path, Free with g_object_unref().

Since: 2.10

gimp_user_directory ()

const gchar *
+gimp_user_directory (GimpUserDirectory type);

gimp_user_directory is deprecated and should not be used in newly-written code.

This procedure is deprecated! Use g_get_user_special_dir() instead.

Parameters

+++++ + + + + + +

type

the type of user directory to retrieve

Returns

The path to the specified user directory, or NULL if the +logical ID was not found.

Since: 2.4

gimp_personal_rc_file ()

gchar *
+gimp_personal_rc_file (const gchar *basename);

Returns the name of a file in the user-specific GIMP settings directory.

The returned string is newly allocated and should be freed with +g_free() after use. The returned string is in the encoding used for +filenames by GLib, which isn't necessarily UTF-8. (On Windows it +always is UTF-8.)

Parameters

+++++ + + + + + +

basename

The basename of a rc_file.

Returns

The name of a file in the user-specific GIMP settings directory.

gimp_gtkrc ()

const gchar *
+gimp_gtkrc (void);

Returns the name of GIMP's application-specific gtkrc file.

Returns

The name of GIMP's application-specific gtkrc file.

gimp_path_parse ()

GList *
+gimp_path_parse (const gchar *path,
+                 gint max_paths,
+                 gboolean check,
+                 GList **check_failed);

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

path	A list of directories separated by G_SEARCHPATH_SEPARATOR.
max_paths	The maximum number of directories to return.
check	`TRUE` if you want the directories to be checked.
check_failed	Returns a GList of path elements for which the +check failed.

Returns

A GList of all directories in path +.

gimp_path_to_str ()

gchar *
+gimp_path_to_str (GList *path);

Parameters

+++++ + + + + + +

path

A list of directories as returned by gimp_path_parse().

Returns

A searchpath string separated by G_SEARCHPATH_SEPARATOR.

gimp_path_free ()

void
+gimp_path_free (GList *path);

This function frees the memory allocated for the list and the strings +it contains.

Parameters

+++++ + + + + + +

path

A list of directories as returned by gimp_path_parse().

gimp_path_get_user_writable_dir ()

gchar *
+gimp_path_get_user_writable_dir (GList *path);

Note that you have to g_free() the returned string.

Parameters

+++++ + + + + + +

path

A list of directories as returned by gimp_path_parse().

Returns

The first directory in path +where the user has write permission.