Actually, users aren't supposed to see the private gimp directory. The fact that they sometimes will need to access it is what should be addressed.

Are you sure that it is the private gimp directory that is in question here.

For example, a user downloads a pattern that they wish to add to GIMP.  Which directory do you suggest they put it in?:

C:\Documents and Settings\%user%\.gimp-2.2\patterns   --or
C:\Program Files\GIMP-2.0\share\gimp\2.0\patterns

Which is the private directory?  Which is the user directory?  Are they the same?  Placement in either directory will work but the correct answer (for now) is clearly:

C:\Documents and Settings\%user%\.gimp-2.2\patterns

...which I propose be changed to:

C:\My Documents\GIMP 2.2\patterns   --or possibly, simply
C:\My Documents\GIMP\patterns

(a.k.a. C:\Documents and Settings\%user%\My Documents\GIMP\patterns)

Yes, there do seem to be a few files in the directory in question that the user should not "fiddle" with but even moving those files to My Documents would not be considered bad behavior (ouch! a double negative).  You could maintain three directory structures, but who really wants to do that.

You are only looking at the Windows platform. On other platforms it is clear which directory is writable by the user and which isn't. We need to look at this from a platform-neutral point of view if we want to improve the situation.

See also bug 164075.

OK, I've looked into this quite a bit more and will answer the questions in the other bug reports (and correct some assumptions of my own) when I get time to prepare the info.  Right now the weekend is upon me.

}}}
First, I must clear up my outdated use of "C:\My Documents".  "My Documents" disappeared from the root directory of the hard drive after Windows 9x.  It is now a virtual object and it has no real path since Win2K and WinXP (or something like that).  It can now only be addressed by what Microsoft calls a PIDL (pointer to an item identifier list).

It came up in another GIMP report, Bug 164075, as to which environment variable or which registry entry should be used to find the path to My Documents and/or Application Data.  The short answer is none of them.  This is demonstrated by KB 329409 which shows that the %HOME...% variables are not always correct.  (Which, by the way, is the answer to the grief that was reported in Bug 164075.)

True, the My Documents folder of many users will be located at %USERPROFILE%\%USERNAME%\My Documents (likewise, Application Data will be located at %APPDATA%) but network users under group policies may instead locate it at %HOMEDRIVE%%HOMEPATH%\My Documents.

Similarly, the following registry entries are quite likely to reveal the real paths to My Documents and Application Data.  Yet, after browsing through several articles in the MS KB, it appears that their use may not be consistent throughout all flavors of Windows.

HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders
HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\User Shell Folders
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Explorer\DocFolderPaths

So how does the programmer find the My Documents folder?  The only reliable answer (ignoring GUID's) is through the use of Shell API functions and Shell CSIDL constants.  The following CSIDL's apply to this discussion:

CSIDL_PERSONAL (0x0005)
CSIDL_MYDOCUMENTS (0x000c)
CSIDL_MYPICTURES (0x0027)
CSIDL_APPDATA (0x001a)
CSIDL_COMMON_APPDATA (0x0023)
CSIDL_LOCAL_APPDATA (0x001c)

Here are some quotes from Microsoft that emphasize the issue here:

  * Some CSIDLs can be mapped to an equivalent %VariableName% environment variable. CSIDLs are more reliable, however, and should be used if possible.

  * The SHGetFolderLocation, SHGetFolderPath, SHGetSpecialFolderLocation, and SHGetSpecialFolderPath functions are the preferred ways to obtain handles to folders. Functions such as ExpandEnvironmentStrings that use the environment variable names directly, in the form %VariableName%, may not be reliable.

  * You must never hard code a path within your application because you can never guarantee its physical location. For example, an Administrator may relocate the My Documents folder to a network location. 

The use of the Shell API functions is a bit convoluted and beyond the scope of this report.  Some return PIDL's, some return paths.  Not all CSIDL's can return a path.  Some functions require shell32.dll v4.71, some require v5.0.  Should you call them through SHFolder.dll or shell32.dll?  One MS documents says SHFolder.dll will always call the correct function in shell32.dll, another says SHFolder.dll may outdate.  Blah, blah, blah...  I've included links for more information at the bottom of this report.

Now that I've said that the only answer is CSIDL and not environment variables, there is one thing that is not available through CSIDL's.  The temp folder.  It appears that the best place to find the temp folder is still through the environment variables %TMP% and %TEMP% (take your pick as to which one--they are both in use and both the same).  I am guessing this is the way it is because the use of TMP and TEMP predates Windows.  Furthermore, TMP and TEMP are set at both the system level and the user level.  For example, when a user is NOT logged in, they often return "C:\Windows\Temp"; and when a user is logged in they often return "C:\DOCUME~1\Username\LOCALS~1\Temp".  No worries here, just grab it and use whatever it gives you.

---

Now, finally!, back to the task at hand.  Where to store the user data.  Microsoft documents lay it out fairly specifically (perhaps annoyingly so):

  There is no need for users to know anything about the physical location of their file system folders. They simply access their files through the My Documents icon.

  When a user displays an application's File Save (or File Open) dialog box for the first time, the dialog box must default to the user's My Documents folder (or a descendant of My Documents, such as My Pictures for image data and My Music for audio files).

Classify Application Data

  You should not store application-specific data (such as temporary files, user preferences, application configuration files, and so on) in the My Documents folder. Instead, use either an appropriate location in the Windows Registry (for data that does not exceed 64 kilobytes) or an application-specific file that is located in a valid Application Data folder.

  It is important to store application data in the correct location to allow several people to use the same computer without corrupting or overwriting each other's data and settings.

  To determine the most appropriate location for your application data, use the following categories to classify your data:

  * For each user (roaming): This category describes application data that is specific to a particular user and should be available to the user as he or she moves between computers within a domain (for example, a custom dictionary). Note that this setting does not apply to applications that are not designed to run in a domain environment. 

    CSIDL_APPDATA - default: \Documents and Settings\%USERNAME%\Application Data

  * For each user (non-roaming): This category describes application data that is specific to a particular user but applies only to a single computer (for example, a user-specified monitor resolution). 

    CSIDL_LOCAL_APPDATA - default: \Documents and Settings\%USERNAME%\Local Settings\Application Data

  * For each computer (non-user specific and non-roaming): This category describes application data that applies to all users and to a specific computer (for example, an application dictionary, a log file, or a temporary file). 

    CSIDL_COMMON_APPDATA - default: \Documents and Settings\All Users\Application Data

---

WTF!  Should a multi-platform application really try to maintain 4, 5 or more directories?  I stand by my original recommendations.  Please keep in mind that the recommended changes apply to the Windows "GIMP User Installation" (shown on the first run of GIMP) and not the GIMP application installation.  I will now reiterate my original recommendation in terms of classifying files and CSIDL:

Application Files::  The current behavior is fine, "\Program Files\GIMP-2.0\...".  There is a CSIDL for this, but I am not concerned how GIMP finds this right now.

Application Data, Roaming User::  In the spirit of multi-platform simplicity, I would put this data with "User Data, Other."  All "User Data" is roaming.

Application Data, Non-roaming User::  There is no "simplistic" answer to this.  The only choice seems to be the Microsoft recommendation of CSIDL_LOCAL_APPDATA.  I do not know if GIMP has any such data.  Perhaps, monitor calibrations or absolute window positions or processor optimizations.  Well, even some of that could go with "Application Files."

Application Data, Non-user-specific::  In the spirit of multi-platform simplicity, I would put this data with "Application Files."

Application Temp::  Set this to the value returned by %TEMP%.

User Temp::  If a user is logged in, then set this to the value returned by %TEMP%, or just set it to the literal "%TEMP%".

User Data, Pictures::  Personally, I would not use the My Pictures folder for GIMP artwork but rather default all user data to "User Data, Other" for simplicity (much like Jasc PSP).  The user can always switch to the My Pictures folder on their own.  You may decide otherwise, in which case, use CSIDL_MYPICTURES.

User Data, Other::  For all intents and purposes of this report CSIDL_PERSONAL and CSIDL_MYDOCUMENTS are the same.  One returns either the real path or the PIDL (depending on Shell version and function used) and the other returns only the PIDL.  Changes here are the core of my recommendation.  Nearly everything currently in "C:\Documents and Settings\%USERNAME%\.gimp-2.2\..." should instead be placed in CSIDL_MYDOCUMENTS\GIMP\... (or CSIDL_PERSONAL\GIMP\...).

The following files and folders are listed in the GIMP User Installation - Personal GIMP Folder page.  According to the data types outlined above, I will classify them each as to how I understand them.  I really don't know all the correct answers here, so please feel free to correct them.

gimprc            AppDataRoam *1
gtkrc             UserDataOther
pluginrc          AppDataRoam *1
menurc            AppDataRoam
sessionrc         AppDataRoam *2
templaterc        AppDataRoam
unitrc            AppDataRoam
\brushes          UserDataOther
\fonts            UserDataOther
\gradients        UserDataOther
\pallettes        UserDataOther
\patterns         UserDataOther
\plug-ins         UserDataOther
\modules          UserDataOther *3
\environ          UserDataOther *3?
\scripts          UserDataOther
\templates        UserDataOther
\themes           UserDataOther
\tmp              UserTemp
\tool-options     AppDataRoam
\curves           AppDataRoam
\levels           AppDataRoam

The GIMP Performance Tuning page asks for the location of the swap folder:
<swap file>       AppTemp

The following files and folders are also created but not described in the GIMP User Installation:
colorrc           AppDataRoam
controllerrc      AppDataRoam
documents         AppDataRoam *1
parasiterc        AppDataRoam ?
themerc           AppDataRoam *1
toolrc            AppDataRoam
\fractalexplorer  AppDataRoam ?
\gfig             AppDataRoam ?
\gflare           AppDataRoam ?
\gimpressionist   AppDataRoam ?

(1) If file locations are hard stored as real paths, then that data would be classified as AppDataNonroam.  For example, references to resources in AppFiles (typically "C:\Program Files\GIMP-2.0\...") and any other file outside the Personal GIMP Folder directory tree.

(2) Storing window positions could be considered AppDataNonroam unless those positions are relative to the current resolution.  This is minor and probably best ignored--the user _should_ know what they did.

(3) Not sure what to do about machine- or platform-specific dll's.

---

To sum everything up, this is how I would locate everything in question (assuming all exceptions to AppDataNonroam indicated above are reconciled):

*rc.*             CSIDL_PERSONAL\GIMP\.gimprc
documents         CSIDL_PERSONAL\GIMP\.gimprc
<swap file>       %TEMP%
<image files>     CSIDL_PERSONAL\GIMP or CSIDL_MYPICTURES
\brushes          CSIDL_PERSONAL\GIMP\brushes
\fonts            CSIDL_PERSONAL\GIMP\fonts
\gradients        CSIDL_PERSONAL\GIMP\gradients
\pallettes        CSIDL_PERSONAL\GIMP\pallettes
\patterns         CSIDL_PERSONAL\GIMP\patterns
\plug-ins         CSIDL_PERSONAL\GIMP\plug-ins
\modules          CSIDL_PERSONAL\GIMP\modules
\environ          CSIDL_PERSONAL\GIMP\environ
\scripts          CSIDL_PERSONAL\GIMP\scripts
\templates        CSIDL_PERSONAL\GIMP\templates
\themes           CSIDL_PERSONAL\GIMP\themes
\tmp              %TEMP% or CSIDL_PERSONAL\GIMP\tmp
\tool-options     CSIDL_PERSONAL\GIMP\.tool-options
\curves           CSIDL_PERSONAL\GIMP\.curves
\levels           CSIDL_PERSONAL\GIMP\.levels
\fractalexplorer  CSIDL_PERSONAL\GIMP\.fractalexplorer
\gfig             CSIDL_PERSONAL\GIMP\.gfig
\gflare           CSIDL_PERSONAL\GIMP\.gflare
\gimpressionist   CSIDL_PERSONAL\GIMP\.gimpressionist

... and any other customization files mentioned in the user docs, such as:
gimp-splash.png   CSIDL_PERSONAL\GIMP\.gimprc

---

I recognize that implementing these changes may ultimately depend on functionality provided by GLib and GTK+.  It is unknown to me what the g_get_ functions currently provide.  Depending on how you read the GLib reference, I came up with two scenarios of what the g_get_ functions should provide on Windows.  The scenarios vary on interpretation of what GLib really wants for _data_dir and _home_dir.  I am not sure which is correct, but I suspect it is Scenario 2.  In Windows I fail to see the difference between application data and application configuration information (unless you want _config_dir to point to registry keys).

GLib Windows Scenario 1 ("data" actually means "doc"):
g_get_user_name            %USERNAME%
g_get_real_name            n/a?
g_get_user_cache_dir       %TMP% or %TEMP%
g_get_user_data_dir        CSIDL_PERSONAL (or CSIDL_MYDOCUMENTS)  *1
g_get_user_config_dir      CSIDL_APPDATA or CSIDL_LOCAL_APPDATA   *2
g_get_system_data_dirs     CSIDL_COMMON_DOCUMENTS                 *3
g_get_system_config_dirs   CSIDL_COMMON_APPDATA                   *3
g_get_host_name            %COMPUTERNAME%
g_get_home_dir             CSIDL_PERSONAL (or CSIDL_MYDOCUMENTS)  *4
g_get_tmp_dir              %TMP% or %TEMP%
g_get_current_dir          ?

GLib Windows Scenario 2 (duplicate functions):
g_get_user_name            %USERNAME%
g_get_real_name            n/a?
g_get_user_cache_dir       %TMP% or %TEMP%
g_get_user_data_dir        CSIDL_APPDATA or CSIDL_LOCAL_APPDATA   *2
g_get_user_config_dir      CSIDL_APPDATA or CSIDL_LOCAL_APPDATA   *2
g_get_system_data_dirs     CSIDL_COMMON_APPDATA                   *3
g_get_system_config_dirs   CSIDL_COMMON_APPDATA                   *3
g_get_host_name            %COMPUTERNAME%
g_get_home_dir             CSIDL_PERSONAL (or CSIDL_MYDOCUMENTS)  *1,4
g_get_tmp_dir              %TMP% or %TEMP%
g_get_current_dir          ?

(1) GLib does not provide an equivalent to CSIDL_MYPICTURES.

(2) GLib does not appear to distinguish between roaming and non-roaming (/usr/share/ and /usr/local/share/).

(3) g_get_user_data_dir currently returns CSIDL_COMMON_APPDATA and CSIDL_COMMON_DOCUMENTS (plus other paths).  It is probably incorrect to return both of these together (even with Scenario 2).  A typical path for CSIDL_COMMON_DOCUMENTS is C:\Documents and Settings\All Users\Documents.  This is a folder for user documents much like My Documents (and not a folder for application data).

(4) It is not advisable to use CSIDL_PROFILE in GLib even though this may be an obvious match to the desired directory.  If the intent of g_get_home_dir is to get a directory for storing application documents, then use CSIDL_PERSONAL instead.  CSIDL_PROFILE (0x0028).  Version 5.0.  The user's profile folder.  A typical path is C:\Documents and Settings\username.  Applications should not create files or folders at this level; they should put their data under the locations referred to by CSIDL_APPDATA or CSIDL_LOCAL_APPDATA.

A note from Microsoft:

  * You use the SHGetFolderPath function to retrieve the correct Application Data folder. Do not store application data directly in this folder. Instead, use the PathAppend function to append a subfolder to the path that SHGetFolderPath returns. Make sure that you use the following convention: 

    Company Name\Product Name\Product Version 

  * For example, the resultant full path may appear as follows: 

    \Documents and Settings\All Users\Application Data\My Company\My Product\1.0 

[Perhaps another solution might be in the Windows application installer: have it call the functions and create the appropriate gimprc file before the first run of GIMP.  Not my favorite idea--more of a hack.]

If done correctly, the CSIDL v4.71 method would allow support all the way back to Windows 95 with the IE 4 Desktop Update.  One may also choose to only support CSIDL v5.0 method (Windows 95 with IE 5).  Either way, support can be provided to all Win9x by providing the right shell dll's.

---

Now I need to quit goofing off with bug research and go find a job.

=== REFERENCE ===

'''How to write a Windows XP Application that stores user and application data in the correct location by using Visual C++ 2005 or Visual C++ .NET'''
    http://support.microsoft.com/kb/310294/en-us

'''CSIDL Reference'''
    http://msdn.microsoft.com/library/default.asp?url=/library/en-us/shellcc/platform/shell/reference/enums/csidl.asp

'''Managing the File System'''
    http://msdn.microsoft.com/library/default.asp?url=/library/en-us/shellcc/platform/shell/programmersguide/shell_basics/shell_basics_programming/manage.asp

'''The Shell Namespace'''
    http://msdn.microsoft.com/library/default.asp?url=/library/en-us/shellcc/platform/shell/programmersguide/shell_basics/namespace.asp

'''Shell and Common Controls Versions'''
    http://msdn.microsoft.com/library/default.asp?url=/library/en-us/shellcc/platform/shell/programmersguide/versions.asp


'''PathAppend Function'''
    http://msdn.microsoft.com/library/default.asp?url=/library/en-us/shellcc/platform/shell/reference/shlwapi/path/pathappend.asp

'''SHGetFolderLocation Function'''
    http://msdn.microsoft.com/library/default.asp?url=/library/en-us/shellcc/platform/shell/reference/functions/shgetfolderlocation.asp

'''SHGetSpecialFolderLocation Function'''
    http://msdn.microsoft.com/library/default.asp?url=/library/en-us/shellcc/platform/shell/reference/functions/shgetspecialfolderlocation.asp

'''SHGetFolderPath Function'''
    http://msdn.microsoft.com/library/default.asp?url=/library/en-us/shellcc/platform/shell/reference/functions/shgetfolderpath.asp

'''SHGetSpecialFolderPath Function'''
    http://msdn.microsoft.com/library/default.asp?url=/library/en-us/shellcc/platform/shell/reference/functions/shgetspecialfolderpath.asp


'''GLib Miscellaneous Utility Functions'''
    http://developer.gnome.org/doc/API/2.0/glib/glib-Miscellaneous-Utility-Functions.html

'''gimprc - gimp configuration file'''
    http://gimp.org/man/gimprc.html

'''XDG Base Directory Specification'''
    http://www.freedesktop.org/wiki/Standards/basedir-spec

{{{

The installer doesn't seem to allow the user to change the directory where these files get placed.  In my case it put them my emacs directory, possibly because the installer shares some things in common with the emacs installer?  Gimp seems to work now, but it is a tad irritating that I can't put the files where I want to.

You probably have set the HOME environment variable to this directory. Then this behavior is expected and correct, and anything else would be an error.

Let's just close this as a duplicate to bug 164075. In the future mj.Jernigan, please avoid 7-page comments. I'm sure that post can be condensed to a couple of paragraphs. I don't know though because I'm not going to read that 7-page comment in detail.

*** This bug has been marked as a duplicate of 164075 ***