Method # GetFolderItem ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Warning
This item was deprecated in version 2019r2. Please use `Constructor(path As String, pathMode As pathmodes, followAlias As Boolean = True)` as a replacement.
## Description Used to access an item in a folder (directory). ## Usage *result* = **GetFolderItem**(*path* \[,*pathMode*\]) | Part | Type | Description | |----------|-------------------------------------|---------------------------------------------------------------------| | result | `FolderItem` | Represents the file that was opened. | | path | `String` | The path or an empty string. | | pathMode | `Constant` | The type of path that is passed. See the Notes section for details. | ## Notes The GetFolderItem function creates a `FolderItem` object for a specific item (application, document, or folder). GetFolderItem can be passed a file name for a specific item or an empty string. If you want to access an item via an absolute path, it is safer to use the `FolderItem` function and the Child method of the `FolderItem` class. If you intend to open an existing file with GetFolderItem, you should check the `Exists` property of the `FolderItem` to be sure that the file actually exists before accessing that `FolderItem's` properties. Passing an empty string returns a `FolderItem` representing the current folder of the running app. For macOS applications, GetFolderItem returns the `FolderItem` for the directory containing the bundle. --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Specifying the type of path The PathMode is specified via a `FolderItem` class constant. The following are valid values: | Class Constant | Value | |------------------|-------| | PathTypeAbsolute | 0 | | PathTypeShell | 1 | | PathTypeURL | 2 | | PathTypeNative | 3 | Use the class constants, not the numeric values in your code. The numeric values are provided for your information only and the values associated with the constants may change in subsequent versions. The *pathtype* parameter indicates whether the path is a Shell path, an “ordinary” path, or path in the form of a URL. For example, to specify a Shell path, use the expression ``` xojo FolderItem.PathTypeShell ``` If you pass a Shell path, it must be an absolute path. If not, an `UnsupportedFormatException` will result. See the ShellPath property of the `FolderItem` class for information about shell paths. If you pass `FolderItem`.PathTypeURL, it must begin with "". --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Resolving aliases on macOS GetFolderItem automatically resolves aliases when *filename* represents an alias. To prevent this, use GetFolderItem. If necessary, macOS will mount external volumes and may present a login dialog during alias resolution. ## Sample code This code displays the name of the current folder in a message box. ``` xojo Dim currentFolder As FolderItem currentFolder = GetFolderItem("") MsgBox(currentFolder.Name) ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The following code gets an item within the current directory: ``` xojo Dim f As FolderItem f = GetFolderItem("Resources") ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The following code uses the Parent property of the `FolderItem` class to get the parent directory for the directory that contains the application: ``` xojo Dim f As FolderItem f = GetFolderItem("").Parent ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The following code opens a PNG file in the current folder and uses it as the background image ("backdrop") for a `Canvas` control: ``` xojo Dim f As FolderItem f = GetFolderItem("Zippy.png") If f.Exists Then Canvas1.BackDrop = Picture.Open(f) End If ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- To get a reference using an absolute path, construct it using the `FolderItem` function and the Child method of the `FolderItem` class:. The code uses a `Try` block to handle the exception if the path is invalid. ``` xojo Dim f As FolderItem Try f = SpecialFolder.Documents.Child("Schedule") Catch err As NilObjectException MsgBox("The path is invalid!") End Try ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The following code uses the URL path to the user's "Documents" folder on Windows: ``` xojo Dim f As FolderItem f = GetFolderItem("file:///C:/Documents%20and%20Settings/Joe%20User/My%20Documents/", _ FolderItem.PathTypeURL) If f.Exists Then MsgBox(f.NativePath) Else MsgBox("The folderitem does not exist.") End If ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The following code uses the shell path to the Documents folder on macOS: ``` xojo Dim f As FolderItem f = GetFolderItem("/Users/Joe/Documents", FolderItem.PathTypeShell) If f.Exists Then TextField1.Text = f.NativePath Else MsgBox("The FolderItem does not exist.") End If ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This code returns a `FolderItem` for the "Documents" folder in the home directory on Linux for user "Joe": ``` xojo Dim f As FolderItem f = GetFolderItem("/home/Joe/Documents", FolderItem.PathTypeShell) If f.Exists Then TextField1.Text = f.NativePath Else MsgBox("The FolderItem does not exist.") End If ``` ## Compatibility All project types on all supported operating systems. ## See also `FolderItem`, `FolderItemDialog`, `RuntimeException` classes; `NilObjectException` error; `Nil` object.