From Xojo Documentation
Jump to: navigation, search

Class (inherits from Object)

FolderItem class objects represent files, applications, or folders. They are created by calling a method such as GetFolderItem or via the Parent or Item properties of other FolderItem objects.

AbsolutePath ReadOnlyProperty.png IsWriteable ReadOnlyProperty.png NativePath ReadOnlyProperty.png
Alias ReadOnlyProperty.png LastErrorCode ReadOnlyProperty.png Owner
Count ReadOnlyProperty.png Length ReadOnlyProperty.png Parent ReadOnlyProperty.png
CreationDate Locked Permissions
Directory ReadOnlyProperty.png MacCreator ResourceForkLength
DisplayName ReadOnlyProperty.png MacDirID ShellPath ReadOnlyProperty.png
Exists ReadOnlyProperty.png MacType Type ReadOnlyProperty.png
ExtensionVisible MacVRefNum URLPath ReadOnlyProperty.png
Group ModificationDate VirtualVolume
IsReadable ReadOnlyProperty.png Name Visible

Child GetSaveInfo OpenAsVectorPicture
CopyFileTo Item OpenAsVirtualVolume
CreateAsFolder Launch
CreateResourceFork MacFSRef
CreateVirtualVolume MoveFileTo OpenResourceMovie
Delete OpenAsMovie TrueChild
GetRelative OpenAsSound TrueItem

Shared Methods


FolderItem.Constructor(path as String, PathType as Integer=PathTypeAbsolute)

Copy Constructor


FolderItem.Constructor(f as FolderItem)

Class Constants


The following class constants can be used to specify the path type as the second parameter in the FolderItem constructor.

Class Constant Description
PathTypeAbsolute An absolute path. On macOS this is an HFS path. Deprecated. Use PathTypeNative instead.
PathTypeShell A shell path. On Windows, this is the short path. On macOS and Linux, this is the POSIX path.
PathTypeURL A URL path. If you use PathTypeURL, the URL must begin with "file:///".
PathTypeNative A Native path. On macOS this is the POSIX path.


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.

Performance Considerations

Avoid invoking functions such as Count, Item and TrueItem 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 1 and ending with the index that matches the directory'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 subdirectories, do not go depth-first. Instead, first collect all items into an array of FolderItems, then walk the array items and enter any directories you encounter.
  • To delete items from a directory, follow the above rules as well. Do not be tempted to walk the directory items backwards (from Count downto 1), 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 Volume function, the Parent property of the FolderItem class, and the Child method of the FolderItem class to specify pathnames. The Volume function returns a reference to any volume on the user's computer. Pass it a number that indicates the desired volume. Zero is the boot volume. You can get the number of volumes with the VolumeCount function. For example, to get a FolderItem for Microsoft Word in the Program Files folder on the boot volume, you can use the following line of code (The line continuation keyword, [[_]], is used to split the line into two printed lines).

Dim f as FolderItem
f = Volume(0).Child("Program Files").Child("Microsoft Office"). _

The GetFolderItem function can be used to get a FolderItem for an item in the current directory. Simply pass it the name of the item. For example, the following returns a FolderItem for the directory "MyTemplates" in the current folder:

Dim f As FolderItem
f = GetFolderItem("MyTemplates")

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

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

Dim f As FolderItem
f = GetFolderItem("")

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 directory that contains the directory that contains the application:

Dim f As FolderItem
f = GetFolderItem("").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 has three class constants that you use to indicate this, PathTypeAbsolute, PathTypeURL, and PathTypeShell. For example:

Dim f As FolderItem
f = New FolderItem("/home/shr/mytextdoc.txt",FolderItem.PathTypeShell)

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

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

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 TrueChild and TrueItem. They return the item itself, even if it is an alias. Use the Alias property to determine whether the FolderItem is an alias.


The OpenResourceMovie method allows you to get a movie stored in a MooV resource inside a file or application (Macintosh only). Prior to QuickTime 4.0, the actual movie in a QuickTime movie file was stored in a MooV resource. In QuickTime 4.0 (and above), the movie is stored in the data fork.

Mac OS

The Mac OS implementation of FolderItem uses the FSRef based File Manager API. As a result, it may not be possible to create FolderItems for some POSIX/BSD specific directories and files.


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

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

Dim count As Integer = desktopFolder.Count
For i As Integer = 1 To count
Dim f As FolderItem = desktopFolder.Item(i)
If f <> Nil Then
End If

This example uses MoveFileTo. 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.

Dim f, g As FolderItem

f = GetOpenFolderItem(FileTypes1.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
MsgBox("File not found!")
End If

The following example creates a text file, changes the Creator from the default creator of "R*ch" to "ttxt", and writes some data to the file.

Dim f As FolderItem
Dim stream As TextOutputStream
f = GetSaveFolderItem(FileTypes1.Text, "Daily Planet Staff.txt")
If f <> Nil then
stream = TextOutputStream.Create(f)
f.MacCreator = "ttxt"
Stream.WriteLine("Perry White")
Stream.WriteLine("Lois Lane")
Stream.WriteLine("Jimmy Olsen")
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.

Dim f As FolderItem = GetOpenFolderItem(FileTypes1.Jpeg)
If f Is Nil Then
// user cancelled
End If

Canvas1.Backdrop = Picture.Open(f)
If Canvas1.Backdrop Is Nil Then
// check f.LastErrorCode
End If

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.

Dim f As FolderItem = GetOpenFolderItem(FileTypes1.Movie)
If f <> Nil Then
MoviePlayer1.Movie = f.OpenAsMovie
If MoviePlayer1.Movie Is Nil Then
// Check f.LastErrorCode
End If
// user cancelled
End If

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

Dim origin, destination As FolderItem
origin = SelectFolder
If origin <> Nil Then
destination = SelectFolder
If destination <> Nil Then
CopyFileOrFolder(origin, destination) // See below
MsgBox("Copy complete!")
End If
End If

The CopyFileOrFolder method is as follows:

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

If source.Directory Then // it's a folder
newFolder = destination.Child(source.Name)
For i As Integer = 1 To source.Count //go through each item
If source.Item(i).Directory Then
// it's a folder
CopyFileOrFolder(source.Item(i), newFolder) // recursively call this routine passing it the folder
source.Item(i).CopyFileTo(newFolder) // it's a file so copy it
End If
Else // it's not a folder
End If
End Sub

Using GetRelative:

Dim f, g As FolderItem
f = New FolderItem
g = f.GetRelative(f.GetSaveInfo(Volume(0).Child("Documents"), 0))
If g <> Nil Then
Label2.Text = g.AbsolutePath
MsgBox("FolderItem does not exist!")
End If

See Also

GetFolderItem, GetTrueFolderItem, GetOpenFolderItem, GetSaveFolderItem, SelectFolder, GetTemporaryFolderItem, Volume, VolumeCount functions; BinaryStream, FolderItemDialog, OpenDialog, SaveAsDialog, SelectFolderDialog, SpecialFolder, TextInputStream, TextOutputStream classes.

Personal tools

Starting Out
Dig Deeper
More Help