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

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

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.

Dim currentFolder As FolderItem
currentFolder = GetFolderItem("")
MsgBox(currentFolder.Name)

The following code gets an item within the current directory:

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:

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:

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.

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:

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:

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":

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.