Class

Xojo.IO.FolderItem

Warning

This item was deprecated in version 2020r2. Please use FolderItem as a replacement.

Description

The FolderItem class represents files, applications, folders and other items in the file system.

Properties

Name	Type	Read-Only
Count	UInteger	✓
CreationDate	Date
DisplayName	Text	✓
Exists	Boolean	✓
IsAlias	Boolean	✓
IsExtensionVisible	Boolean	✓
IsFolder	Boolean	✓
IsReadable	Boolean	✓
IsVisible	Boolean	✓
IsWriteable	Boolean	✓
Length	UInt64	✓
ModificationDate	Date
Name	Text
Parent	FolderItem	✓
Path	Text	✓
URLPath	Text	✓

Methods

Name	Parameters	Returns
Child	name As String, resolveAlias As Boolean = True	FolderItem
Children	resolveAlias As Boolean = True	Iterable
Constructor	path As String, resolveAlias As Boolean = True
CopyTo	destination As FolderItem
CreateAsFolder
Delete
MoveTo	destination As FolderItem

Property descriptions

Xojo.IO.FolderItem.Count

Count As UInteger

The number of items in the FolderItem if it is a folder. If the item is not a folder then it returns 0.

This property is read-only.

Get the count of files in the folder:

Var f As FolderItem = SpecialFolder.Documents
Var count As Integer = f.Count

Xojo.IO.FolderItem.CreationDate

CreationDate As Date

The creation date of the FolderItem.

In order to change the creation date, you need to create a new Date and then assign it to this property. Changing the CreationDate property directly will not cause the date to actually get changed.

Warning

A RuntimeException will be raised if the creation date can not be changed when attempting to set a new date.

Get the creation date:

Var createDate As Xojo.Core.Date
createDate = myFile.CreationDate

To change the creation date:

Var newDate As New Xojo.Core.Date(2014, 8, 1)
myFile.CreationDate = newDate

Xojo.IO.FolderItem.DisplayName

DisplayName As Text

The name of the FolderItem as it should be displayed to the user. This is usually the same as the Name property, but you should always use DisplayName rather than Name when displaying the name of the FolderItem to the user.

This property is read-only.

Get the display name:

Var name As String
name = myFile.DisplayName

Xojo.IO.FolderItem.Exists

Exists As Boolean

Indicates whether the FolderItem exists.

This property is read-only.

You can create a FolderItem that does not refer to actual existing file on disk. When you do so, this property returns False.

To check if a file exists:

Var f As New Xojo.IO.FolderItem("test.txt")

If f.Exists Then
  ' open the file
End If

Xojo.IO.FolderItem.IsAlias

IsAlias As Boolean

Indicates whether the FolderItem is a link or shortcut to another Folderitem.

This property is read-only.

Xojo.IO.FolderItem.IsExtensionVisible

IsExtensionVisible As Boolean

Tells you whether the file should have its extension visible or hidden based on the user's OS settings.

This property is read-only.

Xojo.IO.FolderItem.IsFolder

IsFolder As Boolean

Indicates if the FolderItem is a folder.

This property is read-only.

Xojo.IO.FolderItem.IsReadable

IsReadable As Boolean

This is True when you have permissions to read from the file or folder. In the case of a folder, it means you can read the contents of the folder.

This property is read-only.

Even if IsReadable is True, it does not provide a guarantee tha the read will succeed. If you want to read from a file, you should attempt to do so and handle any exceptions that may occur.

Xojo.IO.FolderItem.IsVisible

IsVisible As Boolean

ndicates whether the FolderItem is visible to standard file system tools (Explorer or Finder, for example).

This property is read-only.

If myFile.Visible Then
  ' open the file
End If

Xojo.IO.FolderItem.IsWriteable

IsWriteable As Boolean

This is True when you have permissions to write to the file or folder. In the case of a folder, it means you can create files in the folder.

This property is read-only.

Even if IsWriteable is True, an attempt to write may fail for other reasons, such as coding errors or insufficient disk space. For example, a write may fail because disk space runs out midway through the write operation. IsWriteable is not intended to check for these type of conditions. If you intend to write to a file, you should attempt to do so and handle any exceptions that may occur.

Xojo.IO.FolderItem.Length

Length As UInt64

The size of the file in bytes. For folders, the size is 0.

This property is read-only.

Gets the length of a file:

Var f As FolderItem = SpecialFolder.Documents("MyFile.txt")
If f.Exists Then
  Var length As UInt64 = f.Length
End If

Xojo.IO.FolderItem.ModificationDate

ModificationDate As Date

The modification date of the FolderItem.

In order to change the modification date, you need to create a new Date and then assign it to this property. Changing the ModificationDate property directly will not cause the date to actually get changed.

Get the modification date:

Var modDate As Xojo.Core.Date
modDate = myFile.ModificationDate

To change the modification date:

Var newDate As New Xojo.Core.Date(2014, 8, 1)
myFile.ModificationDate = newDate

Xojo.IO.FolderItem.Name

Name As Text

The name of the FolderItem. Changing this name renames the file or folder.

Renames a file:

Dim f As FolderItem = SpecialFolder.Documents("MyFile.txt")
f.Name = "NewFile.txt" ' renames file

Xojo.IO.FolderItem.Parent

Parent As FolderItem

This is the parent folder of the FolderItem (based on the file system hierarchy). If the Parent is the root of the file system, this returns Nil.

This property is read-only.

Dim f As FolderItem = SpecialFolder.Documents
Dim parent As FolderItem = f.Parent

Xojo.IO.FolderItem.Path

Path As Text

The full path to the FolderItem using the path format native to the OS.

This property is read-only.

On macOS, iOS and Linux, this returns the POSIX path (separated by slashes).

If the FolderItem is a folder, the Path ends with a backslash on Windows and a forward slash on Linux.

When accessing a drive on Windows that you do not have permissions for or one that does not exist, there is no trailing slash. For example, "f:" is a drive that is not mounted, "f:" is mounted.

Get the full path of a file:

Dim fullPath As Text = myFolderItem.Path

Xojo.IO.FolderItem.URLPath

URLPath As Text

The URL path of the FolderItem, which uses the form file://path/to/file. It can be used to load a local file into an HTML viewer.

This property is read-only.

Get the URL path for a file:

Dim urlPath As Text = myFolderItem.URLPath

Method descriptions

Xojo.IO.FolderItem.Child

Child(name As String, resolveAlias As Boolean = True) As FolderItem

Returns a FolderItem with the specified name that represents a file or folder within the FolderItem.

Gets a specific file in the Documents folder:

Using Xojo.IO
Var docs As FolderItem
docs = SpecialFolder.Documents
Var docFile As FolderItem = docs.Child("MyFile.txt")

Xojo.IO.FolderItem.Children

Children(resolveAlias As Boolean = True) As Iterable

Returns an iterator which can be used with a For Each...Next loop to go through all the files in a folder.

Get all the files in the Documents folder and add their names to an array:

Using Xojo.IO
Var docs As FolderItem
docs = SpecialFolder.Documents

Var files() As Text
For Each f As FolderItem In docs.Children
  files.AddRow(f.Name)
Next

Xojo.IO.FolderItem.Constructor

Constructor(path As String, resolveAlias As Boolean = True)

Note

Constructors are special methods called when you create an object with the New keyword and pass in the parameters above.

Creates a new FolderItem using an absolute path.

Create a FolderItem that points to a file in a folder in the root of the drive:

Var saveFile As New FolderItem("c:\data\savefile.txt")

To create a Xojo.IO.FolderItem from a FolderItem returned from a classic framework class or method:

Var userFile As FolderItem = GetOpenFolderItem("")
Var newFile As New Xojo.IO.FolderItem(userFile.NativePath.ToText)

Xojo.IO.FolderItem.CopyTo

CopyTo(destination As FolderItem)

Copies the FolderItem to the specified destination Folderitem.

If destination is a folder, then the FolderItem is copied into the folder.

If destination is a file and the file exists, the copy is cancelled and a RuntimeException is raised. You'll need to first delete the destination file before copying the original.

If the source FolderItem is a folder, then the folder and all its contents are recursively copied.

Warning

A RuntimeException will be raised when the destination is a file and the file exists.

Copy a file:

Using Xojo.IO
Var sourceFile As FolderItem = SpecialFolder.Documents.Child("MyFile.txt")

If sourceFile.Exists Then
  Var destFile As FolderItem = SpecialFolder.Documents.Child(sourceFile.Name + " copy")
  sourceFile.CopyTo(destFile)
End If

Xojo.IO.FolderItem.CreateAsFolder

CreateAsFolder

Creates a folder at the location of the FolderItem.

Create a new folder:

Using Xojo.IO
Var f As FolderItem = SpecialFolder.Documents.Child("MyFolder")
f.CreateAsFolder

Xojo.IO.FolderItem.Delete

Delete

Deletes the file or folder specified by the FolderItem.

This method irreversibly removes the file or directory from the volumes it is stored on. It does not put things in the "trash". Folders must be empty before they can be deleted.

== Exceptions == .. warning:: A RuntimeException will be raised if the FolderItem cannot be deleted. This could occur because the file is in use, the file is locked, the folder is not empty or the volume, file or folder is not longer available.

Delete a file:

Using Xojo.IO
Var f As FolderItem = SpecialFolder.Documents.Child("MyFile.txt")

If f.Exists Then
  f.Delete
End If

Xojo.IO.FolderItem.MoveTo

MoveTo(destination As FolderItem)

Moves the FolderItem to the specified destination Folderitem.

This method does a move rather than a copy even when the source is on a different volume than the destination. After the move, the Exists property of the original FolderItem is False.

If the source FolderItem is a folder, then the folder and all its contents are recursively copied.

The destination parameter is a file, not a folder.

Warning

A RuntimeException will be raised if the FolderItem could not be moved, for example if the destination is a file and it already exists.

Move a file to a new location:

Using Xojo.IO
Var sourceFile As FolderItem = SpecialFolder.Documents.Child("MyFile.txt")

If sourceFile.Exists Then
  Var destFile As FolderItem = SpecialFolder.ApplicationSupport.Child(sourceFile.Name)
  sourceFile.MoveTo(destFile)
End If

Notes

Implements Xojo.Core.Iterable.

On iOS, to get a reference to a FolderItem, use SpecialFolder. For example:

Var file As FolderItem = SpecialFolder.Documents("MyFile.txt")

To convert a classic FolderItem to a Xojo.IO.FolderItem, use the Constructor like this:

Var classicFile As FolderItem = GetFolderItem("")
Var newFile As New Xojo.IO.FolderItem(classicFile.NativePath.ToText)

To convert Xojo.IO.FolderItem to a classic FolderItem:

Var newFile As Xojo.IO.FolderItem = Xojo.IO.SpecialFolder.GetResource("MyFile.txt")
Var classicFile As New FolderItem(newFile.Path, FolderItem.PathTypeNative)

Compatibility

All project types on all supported operating systems.

Xojo.IO.FolderItem

Description

Properties

Methods

Property descriptions

Method descriptions

Notes

Compatibility

See also