Constructor

Constructor(path As String, [pathType As Integer = PathTypeAbsolute])

Warning

This item was deprecated in version 2019r2. Please use FolderItem(path As String, pathMode As FolderItem.PathModes, followAlias As Boolean = True) in place of this Constructor as a replacement.

Description

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.

Notes

If the path points to an alias or shortcut, the file will resolve to the file pointed to by the alias or shortcut. If you need to point to the alias/shortcut itself, use FolderItem(f As FolderItem) in place of this Constructor.

The optional PathType parameter allows you to specify the type of path: PathTypeAbsolute, PathTypeShell, PathTypeURL or PathTypeNative. PathTypeAbsolute has been deprecated, but remains the default for backward compatibility. You should use PathTypeNative instead of PathTypeAbsolute. 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.

The PathType parameter uses a FolderItem class constant. The following class constants can be passed:

Class Constant	Value
PathTypeAbsolute	0 (Deprecated, use PathTypeNative instead)
PathTypeShell	1
PathTypeURL	2
PathTypeNative (new in Xojo 2013r1)	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

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/withspace", FolderItem.PathTypeShell)

is the same as:

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

Notes for mac

The Mac OS operating systems up to version 9.x used a colon character as a separator in file paths (PathTypeAbsolute). Since the appearance of (Mac) OS X v10.0, the operating system is based on UNIX, so it uses the same paths than Linux (called POSIX paths).

It took a while for Apple Inc. and developers to move to that new syntax. 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).

When using PathTypeURL, any query parameters are removed and thus are not considered part of the file name.

Forbidden characters and consequences in naming

As described above, the colon character is used as a separator by high-level layers of the operating system whereas the UNIX layer uses a forward slash character instead. As a consequence, the colon is a forbidden character in a file/folder's name for softwares using high-level API but it is allowed in pure-BSD softwares, and vice versa. It obviously creates a compatibility problem which is solved by automatically exchanging those two characters when necessary (on disk, the BSD notation is used).

What are the consequences for :doc:`FolderItems</api/files/folderitem>` in Xojo ? Xojo only uses high-level API, so the colon character is forbidden is any folder/file name. The only exception is when using the Constructor defined here with either PathTypeAbsolute or PathTypeNative constant. In such cases, you must use the BSD name, i.e. use the colon character in place of a forward slash.

In the following example, consider a file or folder named "Hello/World" located on the Desktop:

Dim f As FolderItem

' Using high-level functions (i.e. the colon is forbidden in the name)
f = SpecialFolder.Desktop.Child( "Hello/World" ) ' OK
f = SpecialFolder.Desktop.Child( "Hello:World" ) ' <<<<< ERROR

' Using the Constructor
f = New FolderItem(SpecialFolder.Desktop.NativePath + "/Hello:World", FolderItem.PathTypeNative ) ' OK at the BSD-level

Sample code

The following example passes the path to the new FolderItem.

Dim 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 the next example, a FolderItem is created from a shell path.

Dim f As New FolderItem("/Users/geoff", FolderItem.PathTypeShell)

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("")

Compatibility

All project types on all supported operating systems.