FolderItem.Constructor(path as String, pathMode as FolderItem.PathModes, followAlias as Boolean = true)

From Xojo Documentation


FolderItem.Constructor(path As String , pathMode As PathModes[, followAlias As Boolean = True])

New in 2019r2

Creates a new FolderItem. When you create a FolderItem with the New command, you can pass the full or relative path to the new FolderItem as an optional parameter.


If the path points to an alias or shortcut, the file will resolve to the file pointed to by the alias or shortcut when followAlias is True. If you need to point to the alias/shortcut itself, use False for the followAlias parameter.

The optional PathMode parameter allows you to specify the type of path: Native, Shell, or URL. If Path cannot be resolved to a FolderItem, an UnsupportedFormatException is raised. This is notably the case when a folder does not exist within the given Path or when you do not have the correct access permissions for something in the path. Only the last component of the path is allowed not to exist.

Shell Path

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 "file:///" or "file://localhost/".

Shell paths can contain escaped characters, so:

 New FolderItem("/home/path/with\ space", Folderitem.pathModes.Shell)

is the same as:

 New FolderItem("/home/path/with space", FolderItem.pathModes.Native)

Notes for Mac

The FolderItem.ShellPath function is useful when invoking a command through a Shell object but UNIX commands invoked with a Declare statement require a POSIX path (i.e. a NativePath), not a Shell path (the difference is that some characters are escaped in a ShellPath, while they are not in a POSIX path).

Notes for iOS

Due to sandboxing, you cannot access arbitrary files on iOS. To get files on iOS, you should use SpecialFolder to get at the locations your app is allowed to use.


This code passes the path to the new FolderItem.

Var f As FolderItem
f = New FolderItem("myDoc.txt")

It specifies the name of the new FolderItem and it is located in the default folder.

In this code, a FolderItem is created from a shell path.

Var f As New FolderItem("/Users/geoff", FolderItem.pathModes.Shell)

The following code uses the Parent property of the FolderItem class to get the parent directory for the directory that contains the application:

Dim f As New FolderItem("")
f = f.Parent

The following code opens a PNG file in the current folder and uses it as the background image ("backdrop") for a Canvas control:

Dim f As New FolderItem("Zippy.png")
If f.Exists Then
Canvas1.BackDrop = Picture.Open(f)
End If

The following code uses the URL path to the user's "Documents" folder on Windows:

Dim f As New FolderItem("file:///C:/Documents%20and%20Settings/Joe%20User/My%20Documents/", _
If f.Exists Then
MessageBox("The folderitem does not exist.")
End If

The following code uses the shell path to the Documents folder on macOS:

Dim f As New FolderItem("/Users/Joe/Documents", FolderItem.PathModes.Shell)
If f.Exists Then
TextField1.Value = f.NativePath
MessageBox("The FolderItem does not exist.")
End If

See Also