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).
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:
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