From Xojo Documentation

You are currently browsing the old Xojo documentation site. Please visit the new Xojo documentation site!

Class (inherits from Object)

FolderItem class objects represent files, applications, or folders. Common ways to create FolderItems are by using the Constructor, SpecialFolder along with the FolderItem.Child method or using the various FolderItem shared methods for selecting files.

Count fa-lock-32.png IsReadable fa-lock-32.png Parent fa-lock-32.png
CreationDateTime IsWriteable fa-lock-32.png Permissions
DisplayName fa-lock-32.png Length fa-lock-32.png ShellPath fa-lock-32.png
Exists fa-lock-32.png Locked Type fa-lock-32.png
ExtensionVisible ModificationDateTime URLPath fa-lock-32.png
Group Name Visible
IsAlias fa-lock-32.png NativePath fa-lock-32.png
IsFolder fa-lock-32.png Owner
Child CopyTo Open
ChildAt CreateFolder Remove
Children MoveTo SaveInfo
PathModes SaveInfoModes
Shared Properties
DriveCount fa-lock-32.png LastDriveIndex fa-lock-32.png
Shared Methods
DriveAt ShowSaveFileDialog
FromSaveInfo ShowSelectFolderDialog
ShowOpenFileDialog TemporaryFile


Constructor(f as FolderItem)

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


Case Sensitivity

Be aware that file systems on macOS and Windows are generally not case-sensitive, while file systems on Linux usually are case-sensitive. This means that if you are creating apps to deploy on Linux (including web apps deployed to Linux servers), you need to ensure that your filenames correctly match case. If you do not, you may find that files cannot be found when your app is running on Linux.

Xojo Cloud

Xojo Cloud's file system is case sensitive.

Performance Considerations

Avoid invoking functions such as Count, Child and IgnoreAlias multiple times for the same target because these functions are time-intensive (especially on macOS).

If you walk directory contents, follow these rules:

  • Always iterate forward, starting at index 0 and ending with the index that matches the folder's Count. If you iterate backward, it may get very slow if the directory contains a few hundred or even more items.
  • If you want to recurse into subfolders, do not go depth-first. Instead, first collect all items into an array of FolderItems, then walk the array items and enter any folders you encounter.
  • To delete items from a folder, follow the above rules as well. Do not be tempted to walk the directory items backwards (from Count downto 0), even if you see many recommendations for doing so. The proper way is to first collect all items in a loop into an array, then walk the array and delete the items accordingly.

Specifying Pathnames

Use the DriveAt function, the Parent property of the FolderItem class, and the Child method of the FolderItem class to specify pathnames. The DriveAt function returns a reference to any drive on the user's computer/device. Pass it a number that indicates the desired volume. Passing DriveAt 0 will return the boot drive. You can get the number of drives with the DriveCount function. For example, to get a FolderItem for Microsoft Word in the Program Files folder on the boot drive, you can use the following line of code (The line continuation keyword, _, is used to split the line into two printed lines).

Var f As FolderItem
f = FolderItem.DriveAt(0).Child("Program Files").Child("Microsoft Office"). _

The Folderitem.Constructor can be used to get a FolderItem for an item in the current folder by passing it the name of the item. For example, the following returns a FolderItem for the folder "MyTemplates" in the current folder:

Var f As New FolderItem("MyTemplates", FolderItem.PathModes.Native)

If the document or folder does not exist, the Exists property of the FolderItem is False.

If you pass the empty string to FolderItem.Constructor, it returns the FolderItem for the folder that contains the application.

Var f As New FolderItem("", FolderItem.PathModes.Native)

The Parent property of the FolderItem class enables you to navigate one level up in the hierarchy. For example, the following gives you the FolderItem for the folder that contains the folder that contains the application:

Var f As New FolderItem("", FolderItem.PathModes.Native)
f = f.Parent

Remember, macOS is based on BSD Unix which uses "/" as the separator.

Shell Paths and Regular Paths

If you pass the optional parameter for path, you can also pass an optional second parameter indicating whether the path is a ShellPath, a "regular" path, or a path in the form of a URL. FolderItem.PathModes has three modes that you use to indicate this, Native, Shell, and URL. For example:

Var f As FolderItem
f = New FolderItem("/home/shr/mytextdoc.txt", FolderItem.PathModes.Shell)

You cannot pass a non-absolute Shell path. Attempting to do so will result in an UnsupportedFormatException.

If you use FolderItem.PathModes.URL, the URL must begin with "file:///".

On MacOS with Xojo 2019r1 or earlier, constructing FolderItems with a URL where the filename included a ? character would cause that character and any that followed to be stripped. This is no longer the case in Xojo 2019r2 or greater and is now consistent across all platforms.

You can also create a FolderItem without passing any parameters. It works the same as passing an empty text string.


If a FolderItem is actually an alias to a FolderItem, the alias is automatically resolved when the FolderItem is accessed unless you use IgnoreAlias which returns the item itself, even if it is an alias. Use the Alias property to determine whether the FolderItem is an alias.


This example puts the names of all the items on the Desktop that are stored on the boot volume into ListBox1.

Var desktopFolder As FolderItem = SpecialFolder.Desktop
If desktopFolder Is Nil Then
End If

For Each file As Folderitem In DesktopFolder.Children
If file <> Nil Then
End If

This example uses MoveTo. The source file will be deleted and moved into the destination folder. The destination is specified as the root of Volume 0. The name of the destination file OPis the same as the source. Notice that it checks that the source file exists and the destination FolderItem is not Nil.

Var f, g As FolderItem

f = Folderitem.ShowOpenFileDialog(FileTypeGroup1.Text)
If f <> Nil Then // if the user didn't cancel..
If f.Exists Then // if it is a valid file...
g = Volume(0).Child(f.Name)
If g <> Nil Then
End If
End If
MessageBox("File not found!")
End If

This example displays the Open File dialog box and lets the user choose a JPEG file that is then assigned to the Backdrop property of a Canvas control.

Var f As FolderItem = Folderitem.ShowOpenFileDialog(FileTypeGroup1.Jpeg)
If f Is Nil Then
// user cancelled
End If

Canvas1.Backdrop = Picture.Open(f)
Catch e As IOException
// unable to open picture
End Try

This example displays an open-file dialog box that lets the user select a movie. The movie is then copied into the Movie property of a MoviePlayer control.

Var f As FolderItem = Folderitem.ShowOpenFileDialog(FileTypeGroup1.Movie)
If f <> Nil Then
Catch e As IOException
// Unable to open movie
End Try
// user cancelled
End If

This example copies all the files in a particular folder. The following code is a button's Pressed:

Var origin, destination As FolderItem
origin = Folderitem.ShowSelectFolderDialog
If origin <> Nil Then
destination = Folderitem.ShowSelectFolderDialog
If destination <> Nil Then
CopyFileOrFolder(origin, destination) // See below
MessageBox("Copy complete!")
End If
End If

The CopyFileOrFolder method is as follows:

Sub CopyFileOrFolder(source As FolderItem, destination As FolderItem)
Var newFolder As FolderItem

If source.IsFolder Then // it's a folder
newFolder = destination.Child(source.Name)
For Each file As Folderitem In source.Children // go through each item
If file.isFolder Then
// it's a folder
CopyFileOrFolder(file, newFolder) // recursively call this routine passing it the folder
file.CopyFileTo(newFolder) // it's a file so copy it
End If
Else // it's not a folder
End If
End Sub

Using FromSaveInfo:

Var f, g As FolderItem
f = New FolderItem
g = f.FromSaveInfo(f.SaveInfo(Volume(0).Child("Documents"), 0))
If g <> Nil Then
Label2.Text = g.NativePath
MessageBox("FolderItem does not exist!")
End If

See Also

BinaryStream, FolderItemDialog, OpenDialog, SaveAsDialog, SelectFolderDialog, SpecialFolder, TextInputStream, TextOutputStream classes