<doc>
	<legacy_id>1267</legacy_id>
	<name>specialFolderPath</name>
	<type>function</type>

	<syntax>
		<example>the specialFolderPath of <i>folderIdentifier</i></example>
		<example>specialFolderPath(<i>folderIdentifier</i>)</example>
	</syntax>

	<synonyms>
	</synonyms>

	<summary>Returns the names and locations of system-related <function tag="folders">folders</function>.</summary>

	<examples>
<example>specialFolderPath("Preferences")</example>
<example>set the defaultFolder to specialFolderPath("desktop")</example>
<example><p>put specialFolderPath("asup") into appSupportFolder </p></example>
<example>put url ("file:" &amp; specialFolderPath("engine") &amp; slash &amp; "foo.txt") into tFileContents</example>
<example><p>set the folder to specialFolderPath("engine") &amp; slash &amp; "myimages"</p><p>put the files into tMyImages</p></example>
	</examples>

	<history>
		<introduced version="1.1">Added.</introduced>
		<deprecated version=""></deprecated>
		<removed version=""></removed>
		<changed version="6.7.5">Added &quot;resources&quot; folder for Desktop platform</changed>
		<changed version="6.7.0">Added &quot;engine&quot; folder for Desktop platforms</changed>
		<changed version="4.6.1">Added Android Support.</changed>
		<changed version="5.5.3">5.5.3</changed>
		<changed version="4.5.2">Added iOS Support.</changed>
		<changed version="2.9">2.9</changed>
		<experimental version=""></experimental>
		<nonexperimental version=""></nonexperimental>
	</history>

	<objects>
	</objects>

	<platforms>
		<mac/>
		<windows/>
		<linux/>
		<ios/>
		<android/>
	</platforms>

	<classes>
		<desktop/>
		<server/>
		<web/>
		<mobile/>
	</classes>

	<security>
		<disk/>
	</security>


	<classification>
		<category>The System Environment</category>
		<category>Files, Folders &amp; Resources</category>
	</classification>

	<references>
		<function tag="tempName">tempName Function</function>
		<command tag="revSetDatabaseDriverPath">revSetDatabaseDriverPath Command</command>
	</references>

	<description>
	<overview>Use the <b>specialFolderPath</b> 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.</overview>

		<parameters>
  <parameter>
    <name>folderIdentifier</name>
    <description>One of the items below. 
		<p><b>Windows Note:</b> 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 <a href="http://vbnet.mvps.org/index.html?code/browse/csidlversions.htm">Microsoft web site</a>. Not all CSIDL numbers work on all Windows versions, refer to the link above to find out more about CSIDLs.</p>
		<p><b>iOS Note:</b> 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'.</p>
		<p><b>Android Note:</b> 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 <b>specialFolderPath</b> ("engine").</p>
	
	.</description>
    <options title="For Mac OS systems:">
      <option>
        <item>Desktop</item>
        <description>The Desktop folder, where files or folders on the desktop are placed.</description>
      </option>
      <option>
        <item>System</item>
        <description>The active System Folder.</description>
      </option>
      <option>
        <item>Apple</item>
        <description>The Apple Menu Items folder inside the System Folder.</description>
      </option>
      <option>
        <item>Control</item>
        <description>The Control Panels folder inside the System Folder.</description>
      </option>
      <option>
        <item>Extension</item>
        <description>The Extensions folder inside the System Folder.</description>
      </option>
      <option>
        <item>Fonts</item>
        <description>The Fonts folder inside the System Folder.</description>
      </option>
      <option>
        <item>Preferences</item>
        <description>The Preferences folder inside the System Folder.</description>
      </option>
      <option>
        <item>Temporary</item>
        <description>For storage of temporary files.</description>
      </option>
      <option>
        <item>Engine</item>
        <description>The folder containing the engine and the executable files copied in the standalone application.</description>
      </option>
      <option>
        <item>Resources</item>
        <description>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.</description>
      </option>
    </options>
    <options title="For Mac OS X systems:">
      <option>
        <item>Home</item>
        <description>The current user's home directory (e.g. "/Users/Fred").</description>
      </option>
      <option>
        <item>Desktop</item>
        <description>The user's Desktop folder.</description>
      </option>
      <option>
        <item>System</item>
        <description>The Apple Menu Items folder inside the System Folder.</description>
      </option>
      <option>
        <item>Control</item>
        <description>The active System Folder.</description>
      </option>
      <option>
        <item>Fonts</item>
        <description>The system Fonts folder.</description>
      </option>
      <option>
        <item>Preferences</item>
        <description>The Preferences folder inside the user's Library folder.</description>
      </option>
      <option>
        <item>Temporary</item>
        <description>For storage of temporary files.</description>
      </option>
      <option>
        <item>Documents</item>
        <description>For user documents.</description>
      </option>
      <option>
        <item>Support</item>
        <description>For application data.</description>
      </option>
      <option>
        <item>Engine</item>
        <description>The folder containing the engine and the executable files copied in the standalone application.</description>
      </option>
      <option>
        <item>Resources</item>
        <description>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.</description>
      </option>
    </options>
    <options title="For Windows systems:">
      <option>
        <item>Home</item>
        <description>The current user's home directory (e.g. "C:/Documents and Settings/Fred").</description>
      </option>
      <option>
        <item>Desktop</item>
        <description>The user's desktop folder.</description>
      </option>
      <option>
        <item>System</item>
        <description>For system components.</description>
      </option>
      <option>
        <item>Start</item>
        <description>For items in the Start menu.</description>
      </option>
      <option>
        <item>Documents</item>
        <description>The user's documents folder.</description>
      </option>
      <option>
        <item>Fonts</item>
        <description>For font storage.</description>
      </option>
      <option>
        <item>Temporary</item>
        <description>For storage of temporary files.</description>
      </option>
      <option>
        <item>Support</item>
        <description>For CSIDL 0x1a (appdata folder) data.</description>
      </option>
      <option>
        <item>Engine</item>
        <description>The folder containing the engine.</description>
      </option>
      <option>
        <item>Resources</item>
        <description>In development mode, the current stack folder. In a standalone, the resources folder where files or folders specified from the Standalone Builder are copied.</description>
      </option>
    </options>
    <options title="Windows CSIDL numbers:">
      <option>
        <item>0x001a</item>
        <description>The user application data folder (e.g. "C:/Documents and settings/Fred/Application Data").</description>
      </option>
      <option>
        <item>0x0023</item>
        <description>The "all users" application data folder (e.g. "C:/Documents and settings/all users/Application Data").</description>
      </option>
      <option>
        <item>0x000d</item>
        <description>The "My Music" folder.</description>
      </option>
      <option>
        <item>0x000e</item>
        <description>The "My Videos" folder.</description>
      </option>
      <option>
        <item>0x0027</item>
        <description>The "My Pictures" folder.</description>
      </option>
      <option>
        <item>0x000a</item>
        <description>The recycle bin.</description>
      </option>
      <option>
        <item>Engine</item>
        <description>The folder containing the engine.</description>
      </option>
      <option>
        <item>Resources</item>
        <description>In development mode, the current stack folder. In a standalone, the resources folder where files or folders specified from the Standalone Builder are copied.</description>
      </option>
    </options>
    <options title="For Unix systems:">
      <option>
        <item>Home</item>
        <description>The current user's home directory (e.g. "/home/fred").</description>
      </option>
      <option>
        <item>Desktop</item>
        <description>The current user's desktop (e.g. "/home/fred/Desktop").</description>
      </option>
      <option>
        <item>Temporary</item>
        <description>For storage of temporary files (typically "/tmp").</description>
      </option>
      <option>
        <item>0x000e</item>
        <description>The "My Videos" folder.</description>
      </option>
      <option>
        <item>Engine</item>
        <description>The folder containing the engine.</description>
      </option>
      <option>
        <item>Resources</item>
        <description>In development mode, the current stack folder. In a standalone, the resources folder where files or folders specified from the Standalone Builder are copied.</description>
      </option>
    </options>
    <options title="For iOS systems:">
      <option>
        <item>home</item>
        <description>The (unique) folder containing the application bundle and its associated data and folders.</description>
      </option>
      <option>
        <item>documents</item>
        <description>The folder in which the application should store any document data (this folder is backed up by iTunes on sync).</description>
      </option>
      <option>
        <item>cache</item>
        <description>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).</description>
      </option>
      <option>
        <item>library</item>
        <description>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).</description>
      </option>
      <option>
        <item>temporary</item>
        <description>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).</description>
      </option>
      <option>
        <item>engine</item>
        <description>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.</description>
      </option>
      <option>
        <item>resources</item>
        <description>The path to the folder where the files and folders are copied in the standalone application (same as the engine folder).</description>
      </option>
    </options>
    <options title="For Android systems:">
      <option>
        <item>engine</item>
        <description>The (virtual) path to the engine and its assets.</description>
      </option>
      <option>
        <item>documents</item>
        <description>The path to a folder that can be used for per-application data files.</description>
      </option>
      <option>
        <item>cache</item>
        <description>The path to a folder that can be used for transient per-application data files.</description>
      </option>
      <option>
        <item>resources</item>
        <description>The path to the folder where files and folders are copied in the standalone application (same as the engine folder).</description>
      </option>
    </options>
  </parameter>		</parameters>

	<value>The <b>specialFolderPath</b> function returns a folder name and location.</value>
	<comments>If the folder is not found, the <b>specialFolderPath</b> function returns empty. If the <i>folderIdentifier</i> is either not supported on the current platform or doesn't exist on the current system, the result is set to "folder not found".<p>Some of the special folders you can specify with the <b>specialFolderPath</b> 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 <b>specialFolderPath</b> function returns the full path to the folder, including the name of the folder.</p><p></p><p>If you are using the <b>specialFolderPath</b> 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.</p><p></p><p></p><p></p><note>Unlike (most) Mac OS X installs, the Android and iOS filesystems are case-sensitive.</note><p></p><p></p><p></p><note>The iOS simulator has the 'same' case-sensitivity as the host system and not the device.</note><p></p><p></p><p></p><change><p>Support for using the <b>specialFolderPath</b> function on Android systems was added in version 4.6.2.</change><p>Support for using the <b>specialFolderPath</b> function on iOS systems was added in version 4.5.2.</p><p>Support for using the <b>specialFolderPath</b> function on Unix systems was added in version 2.9.</p><p>Support for special folder constants (on Mac OS and OS X) and CSIDL numbers (on Windows) was added in version 2.0.</p><p>&#9;</p><p>&#9;</p></comments>
	</description>
</doc>