Class # SpecialFolder --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ## Description Used to get a `FolderItem` for a specific folder or directory managed by the host operating system. ## Usage ``` xojo 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
table-centered_column_4
| Name | Parameters | Returns | Shared | |------------------------------------|------------------------------------------|-------------------------------------|--------| | `Resource` | name As `String` | `FolderItem` | | ## Method descriptions
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SpecialFolder.Resource **Resource**(name As `String`) As `FolderItem` > Returns a FolderItem to the specified file in the app's Resource folder. > > The provided *name* should be a file name, not a file path. > > ``` xojo > 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 | \Users\UserName\AppData\Roaming\\ | /Users/UserName/Library/Application Support | /home/UserName/ | | Applications | \Program Files\\ or \Program Files (x86)\\ | /Applications | Nil | | Bin | Nil | /bin | /bin/ | | Caches | C:\Users\UserName\AppData\Local\Microsoft\Windows\INetCache\\ | /Users/UserName/Library/Caches | /home/UserName/.cache/ | | Cookies | \Users\UserName\AppData\Local\Microsoft\Windows\INetCookies\\ | /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](http://linux.die.net/man/3/getcwd)). | | Desktop | \Users\UserName\Desktop\\ | /Users/UserName/Desktop | /home/UserName/Desktop/ | | Documents | \Users\UserName\Documents\\ | /Users/UserName/Documents | /home/UserName/Documents/ | | Etc | Nil | /private/etc | /etc/ | | Extensions | \Windows\System32\\ | Nil | Nil | | Favorites | \Users\UserName\Favorites\\ | /Users/UserName/Library/Favorites | Nil | | Fonts | \Windows\Fonts\\ | /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 | \Users\UserName\AppData\Local\Microsoft\Windows\History\\ | /Users/UserName/Sites | Nil | | Home | Nil | /Users | /home/ | | InternetCache | \Users\UserName\AppData\Local\Microsoft\Windows\INetCache\\ | /Users/UserName/Library/Caches | /home/UserName/.cache | | Library | Nil | /Library | /lib/ | | Mount | Nil | /Volumes | /mnt/ | | Movies | \Users\UserName\Videos\\ | /Users/UserName/Movies | /home/UserName/Videos/ | | Music | \Users\UserName\Music\\ | /Users/UserName/Music | /home/UserName/Music/ | | NetworkPlaces | \Users\UserName\AppData\Roaming\Microsoft\Windows\Network Shortcuts\\ | Nil | Nil | | Pictures | \Users\UserName\Pictures\\ | /Users/UserName/Pictures | /home/UserName/Pictures/ | | Preferences | \Users\UserName\AppData\Roaming\\ | /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 | \Users\UserName\AppData\Roaming\Microsoft\Windows\Printer Shortcuts\\ | /System/Library/Printers | Nil | | RecentItems | \Users\UserName\AppData\Roaming\Microsoft\Windows\Recent\\ | /Users/UserName/Library/Recent Documents | Nil | | Resources | MyApp Folder\Resources | MyApp.app/Contents/Resources | MyApp Folder/Resources | | SBin | Nil | /sbin | /sbin/ | | SendTo | \Users\UserName\AppData\Roaming\Microsoft\Windows\SendTo\\ | Nil | Nil | | SharedApplicationData | \ProgramData\\ | /Library/Application Support | Nil | | SharedApplications | \Program Files\Common Files\\ or \Program Files (x86)\Common Files\\ | Nil | Nil | | SharedDesktop | \Users\Public\Desktop\\ | Nil | Nil | | SharedDocuments | \Users\Public\Documents\\ | /Users/Shared | Nil | | SharedFavorites | \Users\UserName\Favorites\\ | Nil | Nil | | SharedPreferences | \ProgramData\\ | /Library/Preferences | Nil | | SharedStartupItems | \ProgramData\Microsoft\Windows\Start Menu\Programs\StartUp\\ | Nil | Nil | | SharedTemplates | \ProgramData\Microsoft\Windows\Templates\\ | Nil | Nil | | StartupItems | \Users\UserName\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup\\ | Nil | Nil | | System | \Windows\System32\\ | /System | Nil | | Templates | \Users\UserName\AppData\Roaming\Microsoft\Windows\Templates\\ | Nil | Nil | | Temporary | \Users\UserName\AppData\Local\Temp\\ | /private/var/folders/gp/.../T/TemporaryItems (varies) | /tmp/ | | Trash(relativeToVolume As FolderItem=Nil) | \Users\UserName\Desktop\Recycle Bin\\ | /Users/UserName/.Trash | Nil | | UserBin | Nil | /usr/bin | /usr/bin/ | | UserHome | \Users\UserName\\ (Points to OneDrive if activated) | /Users/UserName | /home/UserName/ | | UserLibrary | Nil | /Users/UserName/Library | /usr/lib/ | | UserSBin | Nil | /usr/sbin | /usr/sbin/ | | 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: ``` xojo 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 - ExternalStorage (This property is supported for Android only.) - Resources (This property is supported for Android only.) - 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. ``` xojo 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. ``` xojo 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 | | | |-----------------------|-----| | **Project Types** | All | | **Operating Systems** | All |
`Object` parent class; `FolderItem` class.