Livecode Wiki
Advertisement

Returns the names and locations of system-related folders.

Syntax:

the specialFolderPath of folderIdentifier
specialFolderPath(folderIdentifier)

Examples:

specialFolderPath("Preferences")
set the defaultFolder to specialFolderPath("desktop")
put specialFolderPath("asup") into appSupportFolder 
put url ("file:" & specialFolderPath("engine") & slash & "foo.txt") into tFileContents
set the folder to specialFolderPath("engine") & slash & "myimages"
put the files into tMyImages

Use the specialFolderPath function to place preferences in the Preferences folder, save files to the Documents folder, find out which files are installed in the System or Fonts folders, and so on.

The folderIdentifier can be one of the items below. For Windows systems, you can also specify a CSIDL number that identifies a special folder. You can find a complete list of available CDISL values on the Microsoft web site. Not all CSIDL numbers work on all Windows versions, refer to the link above to find out more about CSIDLs. . For Mac OS X systems:

  • Home - The current user's home directory (e.g. "/Users/Fred").
  • Desktop - The user's Desktop folder.
  • System - The Apple Menu Items folder inside the System Folder.
  • Fonts - The system Fonts folder.
  • Preferences - The Preferences folder inside the user's Library folder.
  • Temporary - For storage of temporary files.
  • Documents - For user documents.
  • Support - For application data.
  • Engine - The folder containing the engine and the executable files copied in the standalone application.
  • Resources - In development mode, the current stack folder. In a standalone, the resources folder where non-executable files, or folders specified from the Standalone Builder, are copied.

For Windows systems:

  • Home - The current user's home directory (e.g. "C:/Documents and Settings/Fred").
  • Desktop - The user's desktop folder.
  • System - For system components.
  • Start - For items in the Start menu.
  • Documents - The user's documents folder.
  • Fonts - For font storage.
  • Temporary - For storage of temporary files.
  • Support - For CSIDL 0x1a (appdata folder) data.
  • Engine - The folder containing the engine.
  • Resources - In development mode, the current stack folder. In a standalone, the resources folder where files or folders specified from the Standalone Builder are copied.

Windows CSIDL numbers:

  • 0x001a - The user application data folder (e.g. "C:/Documents and settings/Fred/Application Data").
  • 0x0023 - The "all users" application data folder (e.g. "C:/Documents and settings/all users/Application Data").
  • 0x000d - The "My Music" folder.
  • 0x000e - The "My Videos" folder.
  • 0x0027 - The "My Pictures" folder.
  • 0x000a - The recycle bin.
  • Engine - The folder containing the engine.
  • Resources - In development mode, the current stack folder. In a standalone, the resources folder where files or folders specified from the Standalone Builder are copied.

For Unix systems:

  • Home - The current user's home directory (e.g. "/home/fred").
  • Desktop - The current user's desktop (e.g. "/home/fred/Desktop").
  • Temporary - For storage of temporary files (typically "/tmp").
  • Engine - The folder containing the engine.
  • Resources - In development mode, the current stack folder. In a standalone, the resources folder where files or folders specified from the Standalone Builder are copied.

For iOS systems:

  • home - The (unique) folder containing the application bundle and its associated data and folders.
  • documents - The folder in which the application should store any document data (this folder is backed up by iTunes on sync).
  • cache - The folder in which the application should store any transient data that needs to be preserved between launches (this folder is not backed up by iTunes on sync).
  • library - The folder in which the application can store data of various types. In particular, data private to the application should be stored in a folder named with the app's bundle identifier inside library (this folder is backed up by iTunes on sync).
  • temporary - The folder in which the application should store any temporary data that is not needed between launches (this folder is not backed up by iTunes on sync).
  • engine - The folder containing the built standalone engine (i.e. the bundle). This is useful for constructing paths to resources that have been copied into the bundle at build time.
  • resources - The path to the folder where the files and folders are copied in the standalone application (same as the engine folder).

For Android systems:

  • engine - The (virtual) path to the engine and its assets.
  • documents - The path to a folder that can be used for per-application data files.
  • cache - The path to a folder that can be used for transient per-application data files.
  • resources - The path to the folder where files and folders are copied in the standalone application (same as the engine folder).
  • "external documents" - It's the external SD card.


The specialFolderPath function returns a folder name and location.

If the folder is not found, the specialFolderPath function returns empty. If the folderIdentifier is either not supported on the current platform or doesn't exist on the current system, the result is set to "folder not found". Some of the special folders you can specify with the specialFolderPath function need not have the standard names. (For example, the System Folder on Mac OS systems is not necessarily named "System Folder".) For this reason, the specialFolderPath function returns the full path to the folder, including the name of the folder.

Mobile notes[]

The Android and iOS filesystems are case-sensitive.

iOS Note: iOS imposes strict controls over what you can and cannot access. Each application in iOS is stored in its own 'sandbox' folder (referred to as the home folder). An application is free to read and write files within this folder and its descendants, but it is not allowed to access anything outside of the 'sandbox'.

The iOS simulator has the 'same' case-sensitivity as the host system and not the device.

If you are using the specialFolderPath on iOS, the you should only create files within the documents, cache and temporary folders. Be careful not to change or add any files within the application bundle. The application bundle is digitally signed when it is built, and any changes after this point will invalidate the signature and prevent it from launching.

Android Note: An Android application is installed on the phone in the form of its zip package. This means that any assets that are included are not available as discrete files in the native filesystem. In order to manage this the engine essentially 'virtualizes' the asset files you include, allowing (read-only) manipulation with all the standard LiveCode file and folder handling syntax. To access the assets you have included within your application, use filenames relative to specialFolderPath ("engine").

== Further Macintosh Special Folders == Note that the last character of the first item in the list (for the Apple Menu Items Folder) is the ƒ symbol, which is typed in on the Mac using Option-F. It may or may not be visible this way in your browser.

(Testing was done under OS 9.2.2 and OS X 10.2.3 in a standalone (non-networked) environment. Note that some codes supplied by Apple did not return any values during my testing, even though they were supposed to. Although an entry may say "folder not found", that doesn't mean that it may not work for you; it just didn't work for me (perhaps my configuration is not set up properly).)

Assuming the name of the hard disk is "HD" and the user is "kenray" (under OS X), the following values are returned:

Folder Code Reference:

http://developer.apple.com/documentation/Carbon/Reference/Folder_Manager/Reference/reference.html#//apple_ref/doc/uid/TP30000238-CH4g-C006668

Use the entry under the Code heading with specialFolderPath:

Code Description Returned Value (MacOS 9) Returned Value (MacOS X)
aexƒ Apple Extras Folder /HD/Applications (Mac OS 9)/Apple Extras --
aexƒ Apple Menu Items Folder /HD/System Folder/Apple Menu Items --
appr Appearance Folder /HD/System Folder/Appearance --
apps Applications Folder /HD/Applications (Mac OS 9) --
astƒ Assistants Folder /HD/Applications (Mac OS 9)/Utilities/Assistants --
asup Application Support Folder /HD/System Folder/Application Support /Library/Application Support
cmnu Contextual Menu Items Folder /HD/System Folder/Contextual Menu Items --
ctrD Control Panels Disabled Folder /HD/System Folder/Control Panels (Disabled) --
ctrl Control Panels Folder /HD/System Folder/Control Panels --
desk Desktop Folder /HD/Desktop Folder /Users/kenray/Desktop
docs Documents Folder /HD/Documents /Users/kenray/Documents
empt Empty Trash Folder /HD/Trash /Users/kenray/.Trash
extD Extensions Disabled Folder /HD/System Folder/Extensions (Disabled) --
extn Extensions Folder /HD/System Folder/Extensions --
favs Favorites Folder /HD/System Folder/Favorites /Users/kenray/Library/Favorites
font Fonts Folder /HD/System Folder/Fonts /System/Library/Fonts
fvoc Voices Folder /HD/System Folder/Extensions/Voices /System/Library/Speech/Voices
intƒ Internet Folder /HD/Applications (Mac OS 9) --
isst Internet Search Sites Folder /HD/System Folder/Internet Search Sites --
macD System Extensions Disabled Folder /HD/System Folder/System Extensions (Disabled) --
macs System Folder /HD/System Folder /System
morƒ MacOS Read Me Folder -- --
ppdf Printer Descriptions Folder /HD/System Folder/Extensions/Printer Descriptions /System/Library/Printers/PPDs
pref Preferences Folder /HD/System Folder/Preferences /Users/kenray/Library/Preferences
prfƒ Preferences Folder (alternate?) -- --
prnt PrintMonitor Documents Folder /HD/System Folder/PrintMonitor Documents --
prof ColorSync Profiles Folder /HD/System Folder/ColorSync Profiles /System/Library/ColorSync/Profiles
rapp Recent Applications Folder /HD/System Folder/Apple Menu Items/Recent Applications --
rdoc Recent Documents Folder /HD/System Folder/Apple Menu Items/Recent Documents --
rsrv Recent Servers Folder /HD/System Folder/Apple Menu Items/Recent Servers --
scrƒ Scripts Folder /HD/System Folder/Scripts /Users/kenray/Library/Scripts
sctl System Control Panels Folder* /HD/System Folder/Control Panels --
sdsk System Desktop Folder** /HD/System Folder/Control Panels --
sdvƒ Control Strip Modules Folder -- --
shdD Shutdown Items Disabled Folder /HD/System Folder/Shutdown Items (Disabled) --
shdf Shutdown Items Folder /HD/System Folder/Shutdown Items --
spki Speakable Items Folder /HD/System Folder/Apple Menu Items/Speakable Items --
sprf System Preferences Folder*** /HD/System Folder/Preferences /System/Library/PreferencePanels
strD Startup Items Disabled Folder /HD/System Folder/Startup Items (Disabled) --
strs System Trash Folder**** /HD/Trash --
strt Startup Items Folder /HD/System Folder/Startup Items --
temp Temporary Items Folder /HD/Temporary Items /private/tmp/501/Temporary Items
trsh Trash Folder /HD/Trash /Users/kenray/.Trash
usrs Users Folder -- /Users
utiƒ Utilities Folder /HD/Applications (Mac OS 9)/Utilities /Applications/Utilities
ƒhlp Help Folder /HD/System Folder/Help /Library/Documentation/Help
ƒlib Shared Libraries Folder /HD/System Folder/Extensions /System/Library/CFMSupport
ƒloc Locales Folder /HD/System Folder/Language & Region Support --
ƒnet Internet Plugin Folder /HD/System Folder/Internet Plug-Ins --
ƒprd Printer Driver Folder -- --
ƒscr Scripting Additions Folder /HD/System Folder/Scripting Additions /System/Library/ScriptingAdditions
ƒtex Text Encodings Folder /HD/System Folder/Text Encodings --

According to Apple:

* Always "Control Panels" inside the System Folder; never the redirected one
** The desktop folder at the root of the hard drive, never the redirected user desktop folder
*** System-type Preferences go here - this is always the system's preferences folder, never a logged in user's
**** The trash folder at the root of the drive, never the redirected user trash folder

Further Windows Special Folders[]

NOTE: The following was based on testing under Windows XP.

Keep in mind that as Windows was expanded upon (either through upgrades or by installation of DLLs or Internet Explorer), additional folders were created/accessible. Here’s the reference list:

Version Reference: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/shellcc/platform/shell/programmersguide/versions.asp

Version DLL Distributed With...
4.00 All Windows 95/Windows NT 4.0
4.70 All Internet Explorer 3.x
4.71 All Internet Explorer 4.0
4.72 All Internet Explorer 4.01 and Windows 98
5.00 shlwapi.dll Internet Explorer 5
5.00 shell32.dll Windows 2000 and Windows ME
5.80 comctl32.dll Internet Explorer 5
5.81 comctl32.dll Windows 2000 and Windows ME
6.00 comctl32.dll Windows XP and Windows Vista

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

Use the entry under the No. heading with specialFolderPath

No. Microsoft Constant Name Example Returned Value Nec. Version Comments
0 CSIDL_DESKTOP C:/Documents and Settings/Ken/Desktop      
1 n/a (empty)      
2 CSIDL_PROGRAMS C:/Documents and Settings/Ken/Start Menu/Programs      
3 n/a (empty)      
4 n/a (empty)      
5 CSIDL_PERSONAL C:/Documents and Settings/Ken/My Documents    Also "documents".
6 CSIDL_FAVORITES C:/Documents and Settings/Ken/Favorites      
7 CSIDL_STARTUP C:/Documents and Settings/Ken/Start Menu/Programs/Startup      
8 CSIDL_RECENT C:/Documents and Settings/Ken/Recent      
9 CSIDL_SENDTO C:/Documents and Settings/Ken/SendTo      
10 n/a (empty)      
11 CSIDL_STARTMENU C:/Documents and Settings/Ken/Start Menu    Also "start".
12 n/a (empty)      
13 CSIDL_MUSIC C:/Documents and Settings/Ken/My Documents/My Music 6.0   
14 n/a (empty)      
15 n/a (empty)      
16 CSIDL_DESKTOPDIRECTORY C:/Documents and Settings/Ken/Desktop    Also "desktop".
17 n/a (empty)      
18 n/a (empty)      
19 CSIDL_NETHOOD C:/Documents and Settings/Ken/NetHood      
20 CSIDL_FONTS C:/WINDOWS/Fonts    Also "fonts".
21 CSIDL_TEMPLATES C:/Documents and Settings/Ken/Templates      
22 CSIDL_COMMON_STARTMENU C:/Documents and Settings/All Users/Start Menu    Win NT/2000/XP only.
23 CSIDL_COMMON_PROGRAMS C:/Documents and Settings/All Users/Start Menu/Programs    Win NT/2000/XP only.
24 CSIDL_COMMON_STARTUP C:/Documents and Settings/All Users/Start Menu/Programs/Startup    Win NT/2000/XP only.
25 CSIDL_COMMON_DESKTOPDIRECTORY C:/Documents and Settings/All Users/Desktop    Win NT/2000/XP only.
26 CSIDL_APPDATA C:/Documents and Settings/Ken/Application Data 4.71   
27 CSIDL_PRINTHOOD C:/Documents and Settings/Ken/PrintHood      
28 CSIDL_LOCAL_APPDATA C:/Documents and Settings/Ken/Local Settings/Application Data 5.00   
29 n/a (empty)      
30 n/a (empty)      
31 CSIDL_COMMON_FAVORITES C:/Documents and Settings/All Users/Favorites    Win NT/2000/XP only.
32 CSIDL_INTERNET_CACHE* C:/Documents and Settings/Ken/Local Settings/Temporary Internet Files 4.72*   
33 CSIDL_COOKIES C:/Documents and Settings/Ken/Cookies      
34 CSIDL_HISTORY* C:/Documents and Settings/Ken/Local Settings/History      
35 CSIDL_COMMON_APPDATA C:/Documents and Settings/All Users/Application Data 5.00   
36 CSIDL_WINDOWS C:/WINDOWS 5.00 Also "system".
37 CSIDL_SYSTEM C:/WINDOWS/system32 5.00 Could also be #41.
38 CSIDL_PROGRAM_FILES C:/Program Files 5.00   
39 CSIDL_MYPICTURES C:/Documents and Settings/Ken/My Documents/My Pictures 5.00   
40 CSIDL_PROFILE C:/Documents and Settings/Ken 5.00   
41 (CSIDL_SYSTEM) C:/WINDOWS/system32 5.00 Could also be #37.
42 n/a (empty)      
43 CSIDL_PROGRAM_FILES_COMMON C:/Program Files/Common Files 5.00 Win NT/2000/XP only.
44 n/a (empty)      
45 CSIDL_COMMON_TEMPLATES C:/Documents and Settings/All Users/Templates    Win NT/2000/XP only.
46 CSIDL_COMMON_DOCUMENTS C:/Documents and Settings/All Users/Documents    Win NT/2000/XP; Win 95/98 if Shfolder.dll is installed.
47 CSIDL_COMMON_ADMINTOOLS C:/Documents and Settings/All Users/Start Menu/Programs/Administrative Tools 5.00   
48 n/a (empty)      
49 n/a (empty)      
50 n/a (empty)      
51 n/a (empty)      
52 n/a (empty)      
53 CSIDL_COMMON_MUSIC C:/Documents and Settings/All Users/Documents/My Music 6.0   
54 CSIDL_COMMON_PICTURES C:/Documents and Settings/All Users/Documents/My Pictures 6.0   
55 CSIDL_COMMON_VIDEO C:/Documents and Settings/All Users/Documents/My Videos 6.0   
56 CSIDL_RESOURCES C:/WINDOWS/Resources 6.0   
57 n/a (empty)      
58 n/a (empty)      
59 CSIDL_CDBURN_AREA C:/Documents and Settings/Ken/Local Settings/Application Data/Microsoft/CD Burning 6.0   

Windows Vista Special Folders Use the entry under the No. heading with specialFolderPath

No. Microsoft Constant Name Example Returned Value Nec. Version Comments
0 CSIDL_DESKTOP C:/Users/Ken/Desktop      
1 n/a (empty)      
2 CSIDL_PROGRAMS C:/Users/Ken/AppData/Roaming/Microsoft/Windows/Start Menu/Programs      
3 n/a (empty)      
4 n/a (empty)      
5 CSIDL_PERSONAL C:/Users/Ken/Documents    Also "documents".
6 CSIDL_FAVORITES C:/Users/Ken/Favorites      
7 CSIDL_STARTUP C:/Users/Ken/AppData/Roaming/Microsoft/Windows/Start Menu/Programs/Startup      
8 CSIDL_RECENT C:/Users/Ken/AppData/Roaming/Microsoft/Windows/Recent      
9 CSIDL_SENDTO C:/Users/Ken/AppData/Roaming/Microsoft/Windows/SendTo      
10 n/a (empty)      
11 CSIDL_STARTMENU C:/Users/Ken/AppData/Roaming/Microsoft/Windows/Start Menu    Also "start".
12 n/a (empty)      
13 CSIDL_MUSIC C:/Users/Ken/Music 6.0   
14 CSIDL_VIDEO C:/Users/Ken/Videos 6.0   
15 n/a (empty)      
16 CSIDL_DESKTOPDIRECTORY C:/Users/Ken/Desktop    Also "desktop".
17 n/a (empty)      
18 n/a (empty)      
19 CSIDL_NETHOOD C:/Users/Ken/AppData/Roaming/Microsoft/Windows/Network Shortcuts      
20 CSIDL_FONTS C:/Windows/Fonts    Also "fonts".
21 CSIDL_TEMPLATES C:/Users/Ken/AppData/Roaming/Microsoft/Windows/Templates      
22 CSIDL_COMMON_STARTMENU C:/ProgramData/Microsoft/Windows/Start Menu      
23 CSIDL_COMMON_PROGRAMS C:/ProgramData/Microsoft/Windows/Start Menu/Programs      
24 CSIDL_COMMON_STARTUP C:/ProgramData/Microsoft/Windows/Start Menu/Programs/Startup      
25 CSIDL_COMMON_DESKTOPDIRECTORY C:/Users/Public/Desktop      
26 CSIDL_APPDATA C:/Users/Ken/AppData/Roaming      
27 CSIDL_PRINTHOOD C:/Users/Ken/AppData/Roaming/Microsoft/Windows/Printer Shortcuts      
28 CSIDL_LOCAL_APPDATA C:/Users/Ken/AppData/Local      
29 n/a C:/Users/Ken/AppData/Roaming/Microsoft/Windows/Start Menu/Programs/Startup      
30 n/a C:/ProgramData/Microsoft/Windows/Start Menu/Programs/Startup      
31 CSIDL_COMMON_FAVORITES C:/Users/Ken/Favorites      
32 CSIDL_INTERNET_CACHE* C:/Users/Ken/AppData/Roaming/Microsoft/Windows/Temporary Internet Files      
33 CSIDL_COOKIES C:/Users/Ken/AppData/Roaming/Microsoft/Windows/Cookies      
34 CSIDL_HISTORY* C:/Users/Ken/AppData/Roaming/Microsoft/Windows/History      
35 CSIDL_COMMON_APPDATA C:/ProgramData      
36 CSIDL_WINDOWS C:/Windows    Also "system".
37 CSIDL_SYSTEM C:/Windows/system32    Could also be #41.
38 CSIDL_PROGRAM_FILES C:/Program Files      
39 CSIDL_MYPICTURES C:/Users/Ken/Pictures      
40 CSIDL_PROFILE C:/Users/Ken      
41 (CSIDL_SYSTEM) C:/Windows/system32    Could also be #37.
42 n/a C:/Program Files      
43 CSIDL_PROGRAM_FILES_COMMON C:/Program Files/Common Files      
44 n/a C:/Program Files/Common Files      
45 CSIDL_COMMON_TEMPLATES C:/ProgramData/Microsoft/Windows/Templates      
46 CSIDL_COMMON_DOCUMENTS C:/Users/Public/Documents      
47 CSIDL_COMMON_ADMINTOOLS C:/ProgramData/Microsoft/Windows/Start Menu/Programs/Administrative Tools      
48 n/a C:/Users/Ken/AppData/Roaming/Microsoft/Windows/Start Menu/Programs/Administrative Tools      
49 n/a (empty)      
50 n/a (empty)      
51 n/a (empty)      
52 n/a (empty)      
53 CSIDL_COMMON_MUSIC C:/Users/Public/Music 6.0   
54 CSIDL_COMMON_PICTURES C:/Users/Public/Pictures 6.0   
55 CSIDL_COMMON_VIDEO C:/Users/Public/Videos 6.0   
56 CSIDL_RESOURCES C:/Windows/Resources 6.0   
57 n/a (empty)      
58 n/a (empty)      
59 CSIDL_CDBURN_AREA C:/Users/Ken/AppData/Local/Microsoft/Windows/Burn/Burn 6.0   


* Pretty sure is right constant (not specified in MS doc).


See Also: tempName Function, revSetDatabaseDriverPath Command, engine folder Property, desktop folder Property, temporary folder Property, documents folder Property, home folder Property, create folder Command, delete folder Command

Advertisement