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.
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.
On Windows systems, the folderIdentifier can alternatively be a
Constant Special Item ID List (CSIDL) value that identifies a
special folder. Note that not all CSIDL values work on all versions of
Windows.
The following folderIdentifier values are supported:
Windows folder names:
- "home":
The current user's profile folder
- "desktop":
The current user's desktop folder
- "documents":
The current user's "My Documents" folder
- "support":
The current user's application-specific data ("AppData")
folder
- "system":
The Windows System folder
- "start":
The folder that contains Start Menu items
- "fonts":
The folder that contains fonts
- "temporary":
The folder where temporary files can be placed
- "engine":
The folder containing the LiveCode engine and the
executable files copied in the standalone application
- "resources":
In development mode, the current stack's folder. In a
standalone, the resources folder where files or folders specified
in the Standalone Builder are located. Note: A valid resources path
is only returned after a stack has been saved.
Examples of common Windows CSIDL numbers:
- 0x001a:
Same as "support"
0x0023: The application-specific data folder shared by all users
0x000d: The current user's "My Music" folder
0x000e: The current user's "My Videos" folder
0x0027: The current user's "My Pictures" folder
0x000a: The "Recycle Bin".
On Mac OS systems, the following folderIdentifier values
are supported:
- "home":
The current user's home folder
- "desktop":
The current user's desktop folder
- "preferences":
The current user's preferences folder
- "documents":
The current user's documents folder
- "support":
The current user's application-specific data folder
- "system":
The System Folder (usually /System )
- "fonts":
The folder that contains fonts
- "temporary":
The folder where temporary files can be placed
- "engine":
The folder containing the LiveCode engine and the executable
files copied in the standalone application
- "resources":
In development mode, the current stack's folder. In
a standalone, the resources folder where files
or folders specified in the Standalone Builder are located. Note: a
valid resources path is only returned after a stack has been saved.
On iOS systems, only create files in 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.
iOS imposes strict controls over what you can and cannot access. Each
application in iOS is stored in its own "sandbox" folder
(specialFolderPath("home") ). An application is free to read and
write files anywhere beneath this folder, but it is not allowed to
access anything outside of the "sandbox".
Note: iOS devices have case-sensitive file systems, but the iOS
simulator's file system has the same case-sensitivity
as the host system (i.e. usually case-insensitive).
The following folderIdentifier values are supported:
- "home":
The (unique) folder containing the application bundle and
its associated data and folders
- "documents":
The folder in which document data should be stored
(backed up by iTunes on sync)
- "library":
The folder in which to store data of various types (backed
up by iTunes on sync). In particular, data private to the
application should be stored in a folder named with the
app's bundle identifier inside the "library" folder
- "cache":
The folder where transient data that needs to be preserved
between launches should be stored (*not* backed up by iTunes)
- "temporary":
The folder where temporary data that is not preserved
between launches should be stored (*not* backed up by iTunes)
- "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":
Same as "engine".
On Android systems, note that the file system is case-sensitive.
An Android application is installed on the device as a ZIP package.
This means that any assets that are included are not available as
separate files in the device's native file system. In order to manage
this, LiveCode "virtualizes" the asset files you include, allowing
read-only access with all the standard LiveCode file and folder handling
commands and functions. To access the assets you have included with your
application, use file names relative to specialFolderPath("engine") .
The following folderIdentifier values are supported:
- "documents":
The folder where application-specific data can be placed
(typically valuable)
- "cache":
The folder where transient application-specific data can be
placed (typically not valuable)
- "temporary":
Same as "cache"
- "engine":
The (virtual) folder containing the
application's LiveCode engine and other resources
that were copied into the application at build time
- "resources":
Same as "engine".
- "external documents": The folder on the primary shared/external
storage device where application-specific data can be placed
- "external cache": The folder on the primary shared/external
storage device where transient application-specific data can be placed
- "external temporary": same as "external cache"
Note: If using any external folderIdentifier values, ensure you
have the 'Write External Storage' permission checked in the
application standalone settings
On Linux systems, the following folderIdentifier values
are supported:
- "home":
The current user's home folder
- "desktop":
The current user's desktop folder
- "temporary":
The folder where temporary files can be placed
- "engine":
The folder containing the LiveCode engine and the executable
files copied in the standalone application
- "resources":
In development mode, the current stack's folder. In a
standalone, the resources folder where files or folders specified
in the Standalone Builder are located. Note: A valid resources path
is only returned after a stack has been saved.
In Web standalones, you can read and write files from anywhere,
since the whole file system is virtual and temporary. For compatibility
purposes, the following folderIdentifier values are supported:
- "home":
Always /livecode
- "fonts":
The folder that contains fonts
- "temporary":
A folder where temporary files can be placed
- "engine":
The folder where the standalone initial file system is
extracted
- "resources":
The resources folder where files or folders specified in
the Standalone Builder are located.
|