1
<?xml version="1.0" encoding="UTF-8" ?>
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
5
<refentry id="libgimpbase-gimpenv">
7
<refentrytitle role="top_of_page" id="libgimpbase-gimpenv.top_of_page">gimpenv</refentrytitle>
8
<manvolnum>3</manvolnum>
9
<refmiscinfo>LIBGIMPBASE Library</refmiscinfo>
13
<refname>gimpenv</refname>
14
<refpurpose>Functions to access the GIMP environment.</refpurpose>
17
<refsynopsisdiv id="libgimpbase-gimpenv.synopsis" role="synopsis">
18
<title role="synopsis.title">Synopsis</title>
21
<link linkend="void">void</link> <link linkend="gimp-env-init">gimp_env_init</link> (<link linkend="gboolean">gboolean</link> plug_in);
22
const <link linkend="gchar">gchar</link> * <link linkend="gimp-directory">gimp_directory</link> (void);
23
const <link linkend="gchar">gchar</link> * <link linkend="gimp-data-directory">gimp_data_directory</link> (void);
24
const <link linkend="gchar">gchar</link> * <link linkend="gimp-locale-directory">gimp_locale_directory</link> (void);
25
const <link linkend="gchar">gchar</link> * <link linkend="gimp-plug-in-directory">gimp_plug_in_directory</link> (void);
26
const <link linkend="gchar">gchar</link> * <link linkend="gimp-sysconf-directory">gimp_sysconf_directory</link> (void);
27
const <link linkend="gchar">gchar</link> * <link linkend="gimp-user-directory">gimp_user_directory</link> (<link linkend="GimpUserDirectory">GimpUserDirectory</link> type);
28
<link linkend="gchar">gchar</link> * <link linkend="gimp-personal-rc-file">gimp_personal_rc_file</link> (const <link linkend="gchar">gchar</link> *basename);
29
const <link linkend="gchar">gchar</link> * <link linkend="gimp-gtkrc">gimp_gtkrc</link> (void);
30
<link linkend="GList">GList</link> * <link linkend="gimp-path-parse">gimp_path_parse</link> (const <link linkend="gchar">gchar</link> *path,
31
<link linkend="gint">gint</link> max_paths,
32
<link linkend="gboolean">gboolean</link> check,
33
<link linkend="GList">GList</link> **check_failed);
34
<link linkend="gchar">gchar</link> * <link linkend="gimp-path-to-str">gimp_path_to_str</link> (<link linkend="GList">GList</link> *path);
35
<link linkend="void">void</link> <link linkend="gimp-path-free">gimp_path_free</link> (<link linkend="GList">GList</link> *path);
36
<link linkend="gchar">gchar</link> * <link linkend="gimp-path-get-user-writable-dir">gimp_path_get_user_writable_dir</link> (<link linkend="GList">GList</link> *path);
48
<refsect1 id="libgimpbase-gimpenv.description" role="desc">
49
<title role="desc.title">Description</title>
51
A set of functions to find the locations of GIMP's data directories and
56
<refsect1 id="libgimpbase-gimpenv.details" role="details">
57
<title role="details.title">Details</title>
58
<refsect2 id="gimp-env-init" role="function" condition="since:GIMP 2.4">
59
<title>gimp_env_init ()</title>
60
<indexterm zone="gimp-env-init" role="GIMP 2.4"><primary sortas="gimp_env_init">gimp_env_init</primary></indexterm><programlisting><link linkend="void">void</link> gimp_env_init (<link linkend="gboolean">gboolean</link> plug_in);</programlisting>
62
You don't need to care about this function. It is being called for
63
you automatically (by means of the <link linkend="MAIN--CAPS"><function>MAIN()</function></link> macro that every plug-in
64
runs). Calling it again will cause a fatal error.</para>
66
</para><variablelist role="params">
67
<varlistentry><term><parameter>plug_in</parameter> :</term>
68
<listitem><simpara> must be <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if this function is called from a plug-in
69
</simpara></listitem></varlistentry>
70
</variablelist><para role="since">Since GIMP 2.4</para></refsect2>
71
<refsect2 id="gimp-directory" role="function">
72
<title>gimp_directory ()</title>
73
<indexterm zone="gimp-directory"><primary sortas="gimp_directory">gimp_directory</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link> * gimp_directory (void);</programlisting>
75
Returns the user-specific GIMP settings directory. If the
76
environment variable GIMP2_DIRECTORY exists, it is used. If it is
77
an absolute path, it is used as is. If it is a relative path, it
78
is taken to be a subdirectory of the home directory. If it is a
79
relative path, and no home directory can be determined, it is taken
80
to be a subdirectory of <link linkend="gimp-data-directory"><function>gimp_data_directory()</function></link>.
83
The usual case is that no GIMP2_DIRECTORY environment variable
84
exists, and then we use the GIMPDIR subdirectory of the home
85
directory. If no home directory exists, we use a per-user
86
subdirectory of <link linkend="gimp-data-directory"><function>gimp_data_directory()</function></link>. In any case, we always
87
return some non-empty string, whether it corresponds to an existing
91
The returned string is owned by GIMP and must not be modified or
92
freed. The returned string is in the encoding used for filenames by
93
GLib, which isn't necessarily UTF-8. (On Windows it always is
96
</para><variablelist role="params">
97
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The user-specific GIMP settings directory.
98
</simpara></listitem></varlistentry>
99
</variablelist></refsect2>
100
<refsect2 id="gimp-data-directory" role="function">
101
<title>gimp_data_directory ()</title>
102
<indexterm zone="gimp-data-directory"><primary sortas="gimp_data_directory">gimp_data_directory</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link> * gimp_data_directory (void);</programlisting>
104
Returns the top directory for GIMP data. If the environment
105
variable GIMP2_DATADIR exists, that is used. It should be an
106
absolute pathname. Otherwise, on Unix the compile-time defined
107
directory is used. On Windows, the installation directory as deduced
108
from the executable's full filename is used.
111
The returned string is owned by GIMP and must not be modified or
112
freed. The returned string is in the encoding used for filenames by
113
GLib, which isn't necessarily UTF-8. (On Windows it always is
116
</para><variablelist role="params">
117
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The top directory for GIMP data.
118
</simpara></listitem></varlistentry>
119
</variablelist></refsect2>
120
<refsect2 id="gimp-locale-directory" role="function">
121
<title>gimp_locale_directory ()</title>
122
<indexterm zone="gimp-locale-directory"><primary sortas="gimp_locale_directory">gimp_locale_directory</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link> * gimp_locale_directory (void);</programlisting>
124
Returns the top directory for GIMP locale files. If the environment
125
variable GIMP2_LOCALEDIR exists, that is used. It should be an
126
absolute pathname. Otherwise, on Unix the compile-time defined
127
directory is used. On Windows, the installation directory as deduced
128
from the executable's full filename is used.
131
The returned string is owned by GIMP and must not be modified or
132
freed. The returned string is in the encoding used for filenames by
133
the C library, which isn't necessarily UTF-8. (On Windows, unlike
134
the other similar functions here, the return value from this
135
function is in the system codepage, never in UTF-8. It can thus be
136
passed directly to the <link linkend="bindtextdomain"><function>bindtextdomain()</function></link> function from libintl which
137
does not handle UTF-8.)</para>
139
</para><variablelist role="params">
140
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The top directory for GIMP locale files.
141
</simpara></listitem></varlistentry>
142
</variablelist></refsect2>
143
<refsect2 id="gimp-plug-in-directory" role="function">
144
<title>gimp_plug_in_directory ()</title>
145
<indexterm zone="gimp-plug-in-directory"><primary sortas="gimp_plug_in_directory">gimp_plug_in_directory</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link> * gimp_plug_in_directory (void);</programlisting>
147
Returns the top directory for GIMP plug_ins and modules. If the
148
environment variable GIMP2_PLUGINDIR exists, that is used. It
149
should be an absolute pathname. Otherwise, on Unix the compile-time
150
defined directory is used. On Windows, the installation directory as
151
deduced from the executable's full filename is used.
154
The returned string is owned by GIMP and must not be modified or
155
freed. The returned string is in the encoding used for filenames by
156
GLib, which isn't necessarily UTF-8. (On Windows it always is
159
</para><variablelist role="params">
160
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The top directory for GIMP plug_ins and modules.
161
</simpara></listitem></varlistentry>
162
</variablelist></refsect2>
163
<refsect2 id="gimp-sysconf-directory" role="function">
164
<title>gimp_sysconf_directory ()</title>
165
<indexterm zone="gimp-sysconf-directory"><primary sortas="gimp_sysconf_directory">gimp_sysconf_directory</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link> * gimp_sysconf_directory (void);</programlisting>
167
Returns the top directory for GIMP config files. If the environment
168
variable GIMP2_SYSCONFDIR exists, that is used. It should be an
169
absolute pathname. Otherwise, on Unix the compile-time defined
170
directory is used. On Windows, the installation directory as deduced
171
from the executable's full filename is used.
174
The returned string is owned by GIMP and must not be modified or
175
freed. The returned string is in the encoding used for filenames by
176
GLib, which isn't necessarily UTF-8. (On Windows it always is
179
</para><variablelist role="params">
180
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The top directory for GIMP config files.
181
</simpara></listitem></varlistentry>
182
</variablelist></refsect2>
183
<refsect2 id="gimp-user-directory" role="function" condition="deprecated:|since:GIMP 2.4">
184
<title>gimp_user_directory ()</title>
185
<indexterm zone="gimp-user-directory" role="deprecated"><primary sortas="gimp_user_directory">gimp_user_directory</primary></indexterm><indexterm zone="gimp-user-directory" role="GIMP 2.4"><primary sortas="gimp_user_directory">gimp_user_directory</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link> * gimp_user_directory (<link linkend="GimpUserDirectory">GimpUserDirectory</link> type);</programlisting>
186
<warning><para><literal>gimp_user_directory</literal> is deprecated and should not be used in newly-written code.</para></warning>
188
This procedure is deprecated! Use <link linkend="g-get-user-special-dir"><function>g_get_user_special_dir()</function></link> instead.</para>
190
</para><variablelist role="params">
191
<varlistentry><term><parameter>type</parameter> :</term>
192
<listitem><simpara> the type of user directory to retrieve
193
</simpara></listitem></varlistentry>
194
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The path to the specified user directory, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if the
195
logical ID was not found.
197
</simpara></listitem></varlistentry>
198
</variablelist><para role="since">Since GIMP 2.4</para></refsect2>
199
<refsect2 id="gimp-personal-rc-file" role="function">
200
<title>gimp_personal_rc_file ()</title>
201
<indexterm zone="gimp-personal-rc-file"><primary sortas="gimp_personal_rc_file">gimp_personal_rc_file</primary></indexterm><programlisting><link linkend="gchar">gchar</link> * gimp_personal_rc_file (const <link linkend="gchar">gchar</link> *basename);</programlisting>
203
Returns the name of a file in the user-specific GIMP settings directory.
206
The returned string is allocated dynamically and *SHOULD* be freed
207
with <link linkend="g-free"><function>g_free()</function></link> after use. The returned string is in the encoding
208
used for filenames by GLib, which isn't necessarily
209
UTF-8. (On Windows it always is UTF-8.)</para>
211
</para><variablelist role="params">
212
<varlistentry><term><parameter>basename</parameter> :</term>
213
<listitem><simpara> The basename of a rc_file.
214
</simpara></listitem></varlistentry>
215
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The name of a file in the user-specific GIMP settings directory.
216
</simpara></listitem></varlistentry>
217
</variablelist></refsect2>
218
<refsect2 id="gimp-gtkrc" role="function">
219
<title>gimp_gtkrc ()</title>
220
<indexterm zone="gimp-gtkrc"><primary sortas="gimp_gtkrc">gimp_gtkrc</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link> * gimp_gtkrc (void);</programlisting>
222
Returns the name of GIMP's application-specific gtkrc file.
225
The returned string is owned by GIMP and must not be modified or
226
freed. The returned string is in the encoding used for filenames by
227
GLib, which isn't necessarily UTF-8. (On Windows it always is
230
</para><variablelist role="params">
231
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The name of GIMP's application-specific gtkrc file.
232
</simpara></listitem></varlistentry>
233
</variablelist></refsect2>
234
<refsect2 id="gimp-path-parse" role="function">
235
<title>gimp_path_parse ()</title>
236
<indexterm zone="gimp-path-parse"><primary sortas="gimp_path_parse">gimp_path_parse</primary></indexterm><programlisting><link linkend="GList">GList</link> * gimp_path_parse (const <link linkend="gchar">gchar</link> *path,
237
<link linkend="gint">gint</link> max_paths,
238
<link linkend="gboolean">gboolean</link> check,
239
<link linkend="GList">GList</link> **check_failed);</programlisting>
243
</para><variablelist role="params">
244
<varlistentry><term><parameter>path</parameter> :</term>
245
<listitem><simpara> A list of directories separated by <link linkend="G-SEARCHPATH-SEPARATOR--CAPS"><type>G_SEARCHPATH_SEPARATOR</type></link>.
246
</simpara></listitem></varlistentry>
247
<varlistentry><term><parameter>max_paths</parameter> :</term>
248
<listitem><simpara> The maximum number of directories to return.
249
</simpara></listitem></varlistentry>
250
<varlistentry><term><parameter>check</parameter> :</term>
251
<listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if you want the directories to be checked.
252
</simpara></listitem></varlistentry>
253
<varlistentry><term><parameter>check_failed</parameter> :</term>
254
<listitem><simpara> Returns a <link linkend="GList"><type>GList</type></link> of path elements for which the
256
</simpara></listitem></varlistentry>
257
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A <link linkend="GList"><type>GList</type></link> of all directories in <parameter>path</parameter>.
258
</simpara></listitem></varlistentry>
259
</variablelist></refsect2>
260
<refsect2 id="gimp-path-to-str" role="function">
261
<title>gimp_path_to_str ()</title>
262
<indexterm zone="gimp-path-to-str"><primary sortas="gimp_path_to_str">gimp_path_to_str</primary></indexterm><programlisting><link linkend="gchar">gchar</link> * gimp_path_to_str (<link linkend="GList">GList</link> *path);</programlisting>
266
</para><variablelist role="params">
267
<varlistentry><term><parameter>path</parameter> :</term>
268
<listitem><simpara> A list of directories as returned by <link linkend="gimp-path-parse"><function>gimp_path_parse()</function></link>.
269
</simpara></listitem></varlistentry>
270
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A searchpath string separated by <link linkend="G-SEARCHPATH-SEPARATOR--CAPS"><type>G_SEARCHPATH_SEPARATOR</type></link>.
271
</simpara></listitem></varlistentry>
272
</variablelist></refsect2>
273
<refsect2 id="gimp-path-free" role="function">
274
<title>gimp_path_free ()</title>
275
<indexterm zone="gimp-path-free"><primary sortas="gimp_path_free">gimp_path_free</primary></indexterm><programlisting><link linkend="void">void</link> gimp_path_free (<link linkend="GList">GList</link> *path);</programlisting>
277
This function frees the memory allocated for the list and the strings
280
</para><variablelist role="params">
281
<varlistentry><term><parameter>path</parameter> :</term>
282
<listitem><simpara> A list of directories as returned by <link linkend="gimp-path-parse"><function>gimp_path_parse()</function></link>.
283
</simpara></listitem></varlistentry>
284
</variablelist></refsect2>
285
<refsect2 id="gimp-path-get-user-writable-dir" role="function">
286
<title>gimp_path_get_user_writable_dir ()</title>
287
<indexterm zone="gimp-path-get-user-writable-dir"><primary sortas="gimp_path_get_user_writable_dir">gimp_path_get_user_writable_dir</primary></indexterm><programlisting><link linkend="gchar">gchar</link> * gimp_path_get_user_writable_dir (<link linkend="GList">GList</link> *path);</programlisting>
289
Note that you have to <link linkend="g-free"><function>g_free()</function></link> the returned string.</para>
291
</para><variablelist role="params">
292
<varlistentry><term><parameter>path</parameter> :</term>
293
<listitem><simpara> A list of directories as returned by <link linkend="gimp-path-parse"><function>gimp_path_parse()</function></link>.
294
</simpara></listitem></varlistentry>
295
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The first directory in <parameter>path</parameter> where the user has write permission.
296
</simpara></listitem></varlistentry>
297
</variablelist></refsect2>
added
removed
devel-docs/libgimpbase/xml/gimpenv.xml
