How do I get the path to common folders on my computer or device?

When creating apps you will often need to save data outside your app. You might want to store preferences, settings and state between uses of the app or export data to an accessible location on disk.

This lesson will explain how to use the specialFolderPath function to specify read from/write to common paths on the different operating systems.

Differences between platforms

The specialFolderPath function is especially useful in cross-platform development work in which your stack will need, for example, to keep track of a user's performance, preferences, etc.   

Consider, for example, the pathing differences between Mac OS X and Windows with respect to writing files to "the desktop": 

Operating System Path to "the Desktop" . 

  • Mac OS X: /Users/username/Desktop 
  • Windows: C:/Users/username/Desktop
  • Linux: /home/username/Desktop

While, for the sake of making the written files obvious so that you won't forget to delete them later because they are buried down deep in some obscure folder, we will be writing our files to the desktop, you should be aware that LiveCode allows you to write them to a number of places using the specialFolderPath function; check the LiveCode Dictionary for more details.  

The syntax of the specialFolderPath function

The syntax of the specialFolderPath function is as follows:

specialFolderPath(folderIdentifier)

Values for folderIdentifier on Mac OS

  • "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. 

Values for folderIdentifier on Windows

  • "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.

In addition, CSIDL numbers maybe used to identify certain Windows directories; from the documentation, these are:

  • 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".

More information on obtaining CSIDL values can be found at http://vbnet.mvps.org/index.html?code/browse/csidlversions.htm

Values for folderIdentifier on Linux

  • "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.")

Values for folderIdentifier on iOS

  • "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 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".

Values for folderIdentifier on Android

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"

If using any external folderIdentifier values, ensure you have the 'Write External Storage' permission checked in the application standalone settings

Values for folderIdentifier in HTML5

In HTML5 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.

Example of using the specialFolderPath function to write a file to disk using the URL keyword

This code snippet puts the contents of a LiveCode field into a text file on the desktop of a Mac or Windows system, referring to the file by a file URL. If the file does not exist it is created.

on mouseUp
   put field "Rotten Wood" into url ("file:" & specialFolderPath("desktop") & "/myData.txt")
end mouseUp

Example of using the specialFolderPath function to write a file to disk using file commands

The below code snippet, which writes data from a LiveCode field to a text file on the desktop of a Mac or Windows system, serves as an example of using the specialFolderPath function using 

on mouseUp 
   open file specialFolderPath("desktop") & "/myData.txt" for write  -- creates a file  on a Mac or Windows "desktop" for LiveCode to write to
   put field "Rotten Wood" into myText  -- places the text from the field "Rotten Wood" into a local variable
   write myText to file specialFolderPath("desktop") & "/myData.txt"  -- writes the text placed in the local variable into the open text file we created
   close file specialFolderPath("desktop") & "/myData.txt"  -- closes/saves the text file containing the text form the field/local variable into a text file on the desktop
end mouseUp

Example of using the specialFolderPath function to delete a file from disk

Below is an example of using the specialFolderPath function in conjunction with the delete file command to delete a file from the desktop of a Mac or Windows system when a stack is closed (perhaps a temporary file that the stack created but no longer needs):

on closeStack
  delete file specialFolderPath("desktop") & "/Temp.txt"  
end closeStack

References

The original version of this lesson was based on the stack "How to work with Files" by Ken Ray.

Supplemental materials:

http://www.sonsothunder.com/devres/revolution/tips/file010.htm

http://www.sonsothunder.com/devres/revolution/revolution.htm

4 Comments

Warren

This is especially handy for working with directories within your user's "home" directory. Two notes; Apple has available a long list of four-letter shortcuts to standard directory locations which may be usable and this does NOT work to navigate to the Applications directory in OS X. For example, using 'answer file "somePrompt" with specialFolderPath(Applications)' or 'answer file "somePrompt" with specialFolderPath('apps')' will open the dialog in whatever directory the application issuing this command is in, be it the Revolution IDE or your standalone. This would have to be considered a bug, IMO, and it demands that one use the actual path to 'Applications', which of course is not likely to be changed by a user ;)

Matthew Turney

on mouseUp
    
ask "What is the name of your file?"
put "/" & it & ".txt" into mynameholder
open file specialFolderPath("desktop") & mynameholder for write  
put field "Shakespeare" into myText   
write myText to file specialFolderPath("desktop") & mynameholder 
close file specialFolderPath("desktop") & mynameholder
end mouseUp

trevix

Is there a way to get the path to the download folder, on iOS and Android? And write read to it?

Panos Merakos

Hello trevix,

There is an enhancement request about this:

https://quality.livecode.com/show_bug.cgi?id=23526

On Android, the location of the Downloads folder is *usually* in /storage/emulated/0/Download/

Also, make sure you have checked the WRITE_EXTERNAL_STORAGE permission in the standalone application settings for Android.

Kind regards,
Panos

Add your comment

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.