Class

SpecialFolder

Description

Used to get a FolderItem for a specific folder or directory managed by the host operating system.

Usage

result = SpecialFolder.FolderName

Part	Type	Description
result	FolderItem	If successful, a FolderItem for the specified folder/directory.
FolderName	String literal	The requested folder or directory.

Methods

Name	Parameters	Returns	Shared
Resource	name As String	FolderItem

Method descriptions

SpecialFolder.Resource

Resource(name As String) As FolderItem

Returns a FolderItem to the specified file in the app’s SpecialFolder folder.

The provided name should be a file name, not a file path.

Var file As FolderItem = SpecialFolder.Resource("MyDb.sqlite")

Notes

These are the properties that are available on Desktop, Web and Console projects.

These names and paths are from Windows 10 (64-bit), macOS 10.12.5 and Mint 18.1 (64-bit). The paths may differ slightly on other operating systems and versions.

FolderName	Windows	macOS	Linux
ApplicationData	UsersUserNameAppDataRoaming	/Users/UserName/Library/Application Support	/home/UserName/
Applications	Program Filesor Program Files (x86)	/Applications	Nil
Bin	Nil	/bin	/bin/
Caches	C:UsersUserNameAppDataLocalMicrosoftWindowsINetCache	/Users/UserName/Library/Caches	/home/UserName/.cache/
Cookies	UsersUserNameAppDataLocalMicrosoftWindowsINetCookies	/Users/UserName/Library/Cookies	Nil
CurrentWorkingDirectory	Current working directory (depends on the location of the application). When run from Xojo, it is the path to Xojo. In a built app, it is the path to the built app.	Current working directory (depends on the location of the application). Usually “/”.	\|Current working directory at the time the application was launched (uses getcwd).
Desktop	UsersUserNameDesktop	/Users/UserName/Desktop	/home/UserName/Desktop/
Documents	UsersUserNameDocuments	/Users/UserName/Documents	/home/UserName/Documents/
Etc	Nil	/private/etc	/etc/
Extensions	WindowsSystem32	Nil	Nil
Favorites	UsersUserNameFavorites	/Users/UserName/Library/Favorites	Nil
Fonts	WindowsFonts	/System/Library/Fonts	Nil
GetFromDomainAndCode (domain as Integer, fourCharCode as String)	Raises PlatformNotSupportedException	Pass a class constant for the domain and a four-character code of a specific FolderItem. The constants are: DomainSystem (currently folders inside ‘/System’), DomainLocal (currently folders inside ‘/Library’), DomainUser (currently folders inside the user’s home folder)	Raises PlatformNotSupportedException
History	UsersUserNameAppDataLocalMicrosoftWindowsHistory	/Users/UserName/Sites	Nil
Home	Nil	/Users	/home/
InternetCache	UsersUserNameAppDataLocalMicrosoftWindowsINetCache	/Users/UserName/Library/Caches	/home/UserName/.cache
Library	Nil	/Library	/lib/
Mount	Nil	/Volumes	/mnt/
Movies	UsersUserNameVideos	/Users/UserName/Movies	/home/UserName/Videos/
Music	UsersUserNameMusic	/Users/UserName/Music	/home/UserName/Music/
NetworkPlaces	UsersUserNameAppDataRoamingMicrosoftWindowsNetwork Shortcuts	Nil	Nil
Pictures	UsersUserNamePictures	/Users/UserName/Pictures	/home/UserName/Pictures/
Preferences	UsersUserNameAppDataRoaming	/Users/UserName/Library/Preferences - On macOS, use SpecialFolder.ApplicationData to save your own files or directly call CFPreferences to save preferences files here.	/home/UserName/
Printers	UsersUserNameAppDataRoamingMicrosoftWindowsPrinter Shortcuts	/System/Library/Printers	Nil
RecentItems	UsersUserNameAppDataRoamingMicrosoftWindowsRecent	/Users/UserName/Library/Recent Documents	Nil
Resources	MyApp FolderResources	MyApp.app/Contents/Resources	MyApp Folder/Resources
SBin	Nil	/sbin	/sbin/
SendTo	UsersUserNameAppDataRoamingMicrosoftWindowsSendTo	Nil	Nil
SharedApplicationData	ProgramData	/Library/Application Support	Nil
SharedApplications	Program FilesCommon Filesor Program Files (x86)Common Files	Nil	Nil
SharedDesktop	UsersPublicDesktop	Nil	Nil
SharedDocuments	UsersPublicDocuments	/Users/Shared	Nil
SharedFavorites	UsersUserNameFavorites	Nil	Nil
SharedPreferences	ProgramData	/Library/Preferences	Nil
SharedStartupItems	ProgramDataMicrosoftWindowsStart MenuProgramsStartUp	Nil	Nil
SharedTemplates	ProgramDataMicrosoftWindowsTemplates	Nil	Nil
StartupItems	UsersUserNameAppDataRoamingMicrosoftWindowsStart MenuProgramsStartup	Nil	Nil
System	WindowsSystem32	/System	Nil
Templates	UsersUserNameAppDataRoamingMicrosoftWindowsTemplates	Nil	Nil
Temporary	UsersUserNameAppDataLocalTemp	/private/var/folders/gp/…/T/TemporaryItems (varies)	/tmp/
Trash(relativeToVolume As FolderItem=Nil)	UsersUserNameDesktopRecycle Bin	/Users/UserName/.Trash	Nil
UserBin	Nil	/usr/bin	/usr/bin/
UserHome	UsersUserName(Points to OneDrive if activated)	/Users/UserName	/home/UserName/
UserLibrary	Nil	/Users/UserName/Library	/usr/lib/
UserSBin	Nil	/usr/sbin	/usr/sbin/
Var (Removed in 2019r1 - Use Variable instead)	n/a	n/a	n/a
Variable	Nil	/private/var	/var/
VariableLog	Nil	/private/var/log	/var/log/
Windows	Windows	Nil	Nil

Not all types of folders are supported on all operating systems. After a call to SpecialFolder, check that the result not Nil. Please note that in a web app on a server, some folders do not exist.

macOS

SpecialFolder.Temporary returns an item in the OS’s TemporaryItems directory for the current user. The path contains a long system-defined string that cannot be specified. It looks similar to this:

private:var:folders:pX:pXijpazEF5aGY39FGy9H7k+++TI:TemporaryItems:

Windows

On 64-bit versions of Windows, 32-bit applications created with Xojo will map SpecialFolder.Applications to “Program Files (x86)” instead of “Program Files”.

If the user’s Home directory is locked, SpecialFolder.UserHome will return Nil.

Xojo cloud

For Xojo Cloud, these are the only SpecialFolder methods that are usable. All others return Nil:

Fonts
SharedDocuments: The web server Shared_Documents folder.
Documents: The Documents folder within the web app folder.
Temporary: The web server tmp folder.

Mobile

Mobile has these properties:

ApplicationSupport
Caches
Documents
Temporary

Specific paths do not matter much with sandboxing, but you can use these locations to store files that your apps can access.

If you’re using a build script to copy files your app needs into the application bundle, put them in the Contents folder then use Resource to access them. If the files are something the user will be modifying (such as a database), in the Opening event, look in the appropriate special folder (ApplicationSupport, Caches, Documents or Temporary) and if the file is not there, copy it from Contents using FolderItem.CopyTo and Resource.

It’s a good idea to create a folder with the name of your application bundle identifier and then store your files inside that. Files in the Documents folder will be visible to the user via iCloud.

Sample code

The following code gets a FolderItem for the Application Data folder and displays its native path.

Var f As FolderItem
f = SpecialFolder.ApplicationData
If f <> Nil Then
  MessageBox(f.NativePath)
Else
  MessageBox("There is no Application Data folder on this computer.")
End If

The following example returns a FolderItem for the Documents directory on Windows and macOS and the Home directory on Linux.

Var f As FolderItem
If Not TargetLinux Then
  f = SpecialFolder.Documents
Else
  f = SpecialFolder.Home
End If

If f <> Nil Then
  // proceed normally
Else
  MessageBox("FolderItem does not exist!")
End If

Compatibility

All projects types on all supported operating systems.