Class

FolderItem

Description

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.

Methods

Name

Parameters

Returns

Shared

Child

name As String, followAlias As Boolean = True

FolderItem

ChildAt

index As Integer, followAlias As Boolean = True

FolderItem

Children

followAlias As Boolean = True

Iterable

Constructor

source As FolderItem

Constructor

path As String, pathMode As FolderItem.PathModes, followAlias As Boolean = True

CopyTo

destination As FolderItem

CreateFolder

DriveAt

index As Integer

FolderItem

✓

FromSaveInfo

saveInfo As MemoryBlock

FolderItem

✓

MoveTo

destination As FolderItem

Open

parameters As String = "", activate As Boolean = True

activate As Boolean = True

Remove

RemoveFolderAndContents

SaveInfo

relativeTo As FolderItem, saveInfoMode As FolderItem.SaveInfoModes = FolderItem.SaveInfoModes.Default

MemoryBlock

ShowOpenFileDialog

filter As String

FolderItem

✓

ShowSaveFileDialog

filter As String, defaultName As String

FolderItem

✓

ShowSelectFolderDialog

FolderItem

✓

TemporaryFile

FolderItem

✓

UnZip

Extends f As FolderItem, destination As FolderItem, password As String = ""

Extends f As FolderItem, password As String = ""

Zip

Extends f As FolderItem, contentsOnly As Boolean = False, compression As ZipCompressions = ZipCompressions.Normal, password As String = ""

FolderItem

Extends f As FolderItem, destination As FolderItem, contentsOnly As Boolean = False, compression As ZipCompressions = ZipCompressions.Normal, password As String = ""

FolderItem

Enumerations

FolderItem.PathModes

PathModes

Specifies the type of path when creating the FolderItem.

Enum

Description

Native

A Native path. On macOS this is the POSIX path.

Shell

A shell path. On Windows, this is the short path. On macOS and Linux, this is the POSIX path.

URL

A URL path. The URL must begin with "file:///".

FolderItem.SaveInfoModes

SaveInfoModes

Specifies the type of path to be used to open the FolderItem.

Enum

Description

Default

The FolderItem should be open in any way that it can possibly be created. This is the default value.

Relative

The FolderItem should only be opened using relative path information.

Full

The FolderItem should only be opened using absolute path information.

FolderItem.ZipCompressions

ZipCompressions

Specifies the type of compression to be used.

Enum

Description

Best

Compresses the file the most but is slowest.

Fast

Compresses the file in the shortest amount of time but with the least amount of compression.

None

No compression.

Normal

The sweet spot between the amount of compression and the time it takes to compress.

Property descriptions

FolderItem.Count

Count As Integer

The number of items in the FolderItem if it is a directory/folder.

This property is read-only.

Avoid calling this function several times as it is costly in processing time and will have poor performance.

Especially avoid calling it repeatedly in a loop. Instead, get its value once and store it in a variable for further use.

Var f As FolderItem
f = FolderItem.ShowSelectFolderDialog
MessageBox(f.Count.ToString)

FolderItem.CreationDateTime

CreationDateTime As DateTime

The creation date and time of the FolderItem.

Because the DateTime class properties are all read-only, you cannot directly change the CreationDateTime. It's instead by assigning to it an entirely new date. See the example below.

On Windows, the CreationDateTime cannot be changed if the file is open. This includes if it is open using a BinaryStream, TextInputStream or TextOutputStream. Close the file before changing the CreationDateTime.

On Linux, the CreationDateTime cannot be modified. Attempting to change it raises an UnsupportedOperationException. Also, the CreationDateTime may not be accurate as many Linux file systems do NOT actually track the creation date.

This example displays the creation date in the ShortDate format. In this case, the None format is specified for the Time format so that time is not included.

Var f As New FolderItem
MessageBox(f.CreationDateTime.ToString(DateTime.FormatStyles.Short, DateTime.FormatStyles.None))

To change the CreationDateTime, you must create a new instance of a DateTime and assign it to the property. In this example, the user selects a file and the CreationDateTime of that file is set to the current date time via DateTime.

Var f As FolderItem
f = FolderItem.ShowOpenFileDialog("")

If f <> Nil Then
  f.CreationDateTime = DateTime.Now
End If

FolderItem.DisplayName

DisplayName As String

The name of the FolderItem as it should be seen by the user.

This property is read-only.

It is usually the same as the Name property. Under macOS, use DisplayName rather than Name when displaying the name of the item to the user.

FolderItem.DriveCount

DriveCount As Integer

Returns the number of mounted drives.

This property is read-only.

Important

This property is not currently supported for Android.

This property is shared.

The DriveCount function returns the number of mounted Drive.

FolderItem.Exists

Exists As Boolean

Indicates whether or not the folder item points to a file or directory that exists.

This property is read-only.

This example checks whether a FolderItem exists before using it.

Var f As FolderItem
f = SpecialFolder.Desktop.Child("Zippy.png")
If f.Exists Then
  Canvas1.Backdrop = Picture.Open(f)
End If

FolderItem.Extension

Extension As String

Allows you to get and set the FolderItem's extension.

FolderItem.ExtensionVisible

ExtensionVisible As Boolean

Allows you to tell whether a given file has its file extension hidden or visible, or toggles that status.

Important

This property is not currently supported for Android.

Note that when you change this setting, the operating system's Desktop Manager or subsequent Navigation dialogs may not reflect the change right away. When you create a new file under macOS, the "hide extension" flag is set according to the current value of this property. On Windows, hiding the file extension is a global property, so if it is true for one FolderItem on the user's computer it is true for all of them.

This code checks the ExtensionVisible flag for a file.

Var f As FolderItem = SpecialFolder.Desktop.Child("MyDocument.txt")
If f.ExtensionVisible Then
  MessageBox("The extension is visible!")
Else
  MessageBox("The extension is not visible!")
End If

FolderItem.Group

Group As String

Gets or sets the name of the owning Group of the FolderItem.

Important

This property is not currently supported for Android.

Supported on Unix-based operating systems only (macOS and Linux). Use the FolderItem's Permissions property or the Permissions class to get and set permissions for the owning Group. The Owner property gets and sets the FolderItem's Owner.

The following gets the name of the selected FolderItem.

Var f As FolderItem
f = FolderItem.ShowOpenFileDialog("text/plain")
MessageBox(f.Group)

FolderItem.Handle

Handle As Ptr

A pointer to the object for use with declares.

This property is read-only.

Important

This property is currently only supported for Android.

FolderItem.IsAlias

IsAlias As Boolean

Returns True if the item is an alias.

This property is read-only.

Important

This property is not currently supported for Android.

In most cases, a FolderItem is going to resolve the alias to point to the actual file. If you need the actual alias itself, then you should use FolderItem, FolderItem or FolderItem.Constructor(path as String, pathMode as FolderItem.PathModes, followAlias as Boolean = true).

Var f As New FolderItem
If f.IsAlias Then
  MessageBox("The FolderItem is an alias.")
Else
  MessageBox("The FolderItem is not an alias.")
End If

FolderItem.IsFolder

IsFolder As Boolean

True if the FolderItem is a folder or directory.

This property is read-only.

Prompt the user to choose a folder and then display the number of files it contains:

Var f As FolderItem
f = FolderItem.ShowSelectFolderDialog

If f.IsFolder Then
  MessageBox("The folder has " + f.Count.ToString + " files.")
Else
  MessageBox("The folderitem is not a folder!")
End If

This code checks for a specific folder on the drive:

Var f As FolderItem
f = New FolderItem("Resources")
If f <> Nil And f.Exists And f.IsFolder Then
  ' The folder exists so fetch a file from it
  Var file As FolderItem = f.Child("sample.html")
End If

FolderItem.IsReadable

IsReadable As Boolean

IsReadable is True if you have permissions to read from the FolderItem. It is not a guarantee that the read will succeed. If you want to read from a file, you should attempt to do so. If the read operation can work, it will work.

This property is read-only.

Var f As FolderItem
f = FolderItem.ShowOpenFileDialog("text/plain")

If f.IsReadable Then
  ' conduct the read..
Else
  MessageBox("The file cannot be read!")
End If

FolderItem.IsWriteable

IsWriteable As Boolean

IsWriteable is True if you have permissions to write to the FolderItem.

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 the information to be written. For example, a write may fail because disk space runs out midway through the write operation. IsWriteable is not intended to check for that condition. If your intention is to write to a file, you should attempt to do so.

This example checks the IsWritable flag prior to doing the write.

Var f As FolderItem
f = FolderItem.ShowOpenFileDialog("text/plain")
If f.IsWriteable Then
  ' conduct the write operation
Else
  MessageBox("You cannot write to the file!")
End If

FolderItem.LastDriveIndex

LastDriveIndex As Integer

Returns the index of the last mounted drive.

This property is read-only.

This property is shared.

Important

This property is not currently supported for Android.

FolderItem.Length

Length As UInt64

The size of the file's data fork in bytes. For directories, the size will be zero.

This property is read-only.

This example displays the value of Length if the open was successful.

Var f As FolderItem
f = FolderItem.ShowOpenFileDialog("text/plain")
If f <> Nil then
  MessageBox(f.Length.ToString)
End If

FolderItem.Locked

Locked As Boolean

The FolderItem is locked or is on a locked volume and thus cannot be written to or deleted.

Var f As FolderItem
f = FolderItem.ShowOpenFileDialog("text/plain")

If f.Locked Then
  MessageBox("The file is locked!")
Else
  ' access the file
End If

FolderItem.ModificationDateTime

ModificationDateTime As DateTime

The modification date and time of the FolderItem.

Because the DateTime class properties are all read-only, you cannot directly change the ModificationDateTime. It's instead by assigning to it an entirely new date. See the example below.

On Windows, the ModificationDate cannot be changed if the file is open. This includes if it is open using a BinaryStream, TextInputStream or TextOutputStream. Close the file before changing the ModificationDateTime.

This example displays the modification date in the ShortDate format. In this case, the None format is specified for the Time format so that time is not included.

Var f As FolderItem
f = FolderItem.ShowOpenFileDialog("")
If f <> Nil Then
  MessageBox(f.ModificationDateTime.ToString(DateTime.FormatStyles.Short, DateTime.FormatStyles.None)
End If

To change the ModificationDateTime, you must create a new instance of a DateTime and assign it to the property. In this example, the user selects a file and the ModificationDateTime of that file is set to the current date time via DateTime.

Var f As FolderItem
f = FolderItem.ShowOpenFileDialog("")

If f <> Nil Then
  f.ModificationDateTime = DateTime.Now
End If

FolderItem.Name

Name As String

The name of the FolderItem. Changing this name will change the name of the file or folder.

A file can be renamed if the user has the appropriate permissions and the file is not in use. You should avoid renaming temporary folder or files as that behavior can vary by OS.

A file must exist in order to be renamed.

Renaming fails if another file with same name exists already. In that case, delete the existing file before renaming.

If renaming the file fails for any reason, an IOException will occur.

Var f As FolderItem
f = FolderItem.ShowOpenFileDialog("text/plain")
f.Name = "NewFilename"

FolderItem.NativePath

NativePath As String

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

This property is read-only.

Applications should not assume that there is a trailing slash on the path returned when the FolderItem is a directory. If the trailing slash is required, the Directory property should be checked and the trailing slash appended based off that value (backslash on Windows and forward slash on Linux).

Unlike AbsolutePath, on macOS this returns the POSIX path (separated by slashes).

When accessing a drive on Windows that you do not have permissions for or does not exist, there is no trailing slash. For example, "a:" is a floppy drive with no disk, "a:" has a disk.

This example displays the native path:

Var f As New FolderItem
MessageBox(f.NativePath)

FolderItem.Owner

Owner As String

Gets or sets the Owner of the FolderItem under Unix-based operating systems (macOS and Linux).

Important

This property is not currently supported for Android.

Use the FolderItem's Permissions property or the Permissions class to get and set permissions for the Owner. The Group property gets and sets the FolderItem's Group.

Var f As FolderItem
f = FolderItem.ShowOpenFileDialog("text/plain")
MessageBox(f.Owner)

FolderItem.Parent

Parent As FolderItem

Returns the FolderItem object for the parent of this item in the file hierarchy.

This property is read-only.

Returns Nil if this item is the root.

The following example displays the Name of the Parent.

Var f As FolderItem
f = FolderItem.ShowOpenFileDialog("text/plain")

If f.Parent <> Nil Then
  MessageBox("Parent folder name: " + f.Parent.Name)
End If

FolderItem.Permissions

Permissions As Integer

Gets and sets the permissions of the FolderItem on Unix-based operating systems only (macOS and Linux).

Important

This property is not currently supported for Android.

For web apps, it is important to ensure that you set permissions correctly for any files that you create on the web server and later intend to modify, write or delete.

You can get and set the permissions as an octal Integer or you can get and set the permissions via the properties of the Permissions class. Permissions is represented as a three-digit numeric code (in octal or base 8), in which each digit ranges from 0 to 7.

The digits correspond to the permissions of the FolderItem owner, the owning group, and other users not in the owning group, in that order. The code for each digit is computed using the following values:

Value

Description

1

Execute

2

Write

4

Read

For each digit, the permissions are expressed by adding up the values. Each digit can take on the following values:

Value

Description

0

No permissions

1

Execute

2

Write

3

Write and Execute

4

Read

5

Read ane Execute

6

Read and Write

7

Read, Write, and Execute

For example, the the octal value "764" is interpreted as follows:

Value

Description

Owner

7

Read, Write, and Execute

Owning User

6

Read and Write

Owning Group

4

Read

Others

When referring to an octal number in Xojo, you have to prefix it with the "&o". So octal 764 is written as: &o764

You can set these permissions by assigning the octal value to the Permissions property, i.e.,

myFile.Permissions = &o764

FolderItem.ShellPath

ShellPath As String

Gets the shell path of the FolderItem.

This property is read-only.

Important

This property is not currently supported for Android.

On Windows, ShellPath returns the short path, if the item exists. Otherwise, ShellPath returns the long path as returned by NativePath. For discussion of short v. long paths, see Naming Files, Paths, and Namespaces.

On macOS and Linux, this is the POSIX path, but escaped.

Escaped means that special characters such as blanks are prefixed with an escape character. Therefore, you can use it to pass to the Shell object, but you can not directly pass it to OS functions that expect a POSIX path. To get a proper, unescaped, POSIX path on macOS or Linux, use FolderItem.

Var f As FolderItem
f = FolderItem.ShowOpenFileDialog("????")

MessageBox(f.ShellPath)

FolderItem.Type

Type As String

If the FolderItem is not a folder, this property contains the file type of the FolderItem. If the FolderItem is a folder (macOS), it will return a matching file type if you have created one. The file types must be defined in your project. If not, this property will be empty.

This property is read-only.

Important

This property is not currently supported for Android.

This property only contains a type if you open a file for which there is a corresponding File Type Set.

If the standard "text/plain" file type been added to a File Type Set, then this gets the type:

Var f As FolderItem = SpecialFolder.Desktop.Child("test.txt")
' f.Type has a value if there is a File Type Set configured for ".txt" files
' "text/plain" if available in a File Type Set

FolderItem.URLPath

URLPath As String

Returns a URL for the FolderItem that can be passed to System.GotoURL and other methods that require a valid URL.

This property is read-only.

Var f As FolderItem
f = FolderItem.ShowOpenFileDialog("????")

If f.URLPath <> "" Then
  MessageBox(f.URLPath)
Else
  MessageBox("The URLPath is null")
End If

FolderItem.Visible

Visible As Boolean

True if the FolderItem is visible and False if it is not.

Important

This property is not currently supported for Android. On that platform, to make a file invisible, prefix it with a period.

Var f As FolderItem
f = FolderItem.ShowOpenFileDialog("????")

If f.Visible Then
  MessageBox(f.DisplayName)
Else
 MessageBox("The FolderItem is not visible.")
End If

Method descriptions

FolderItem.Child

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

Returns a FolderItem that represents a file or folder/directory within this FolderItem with the matching name or index passed.

Shortcuts and aliases are resolved on all platforms when followAlias is True.

Note

Passing an empty String in the name parameter will return the parent Folderitem. However, for code clarity, use the FolderItem.Parent property instead.

Returns Nil only when some portion of the path to the child does not exist. For example:

SpecialFolder.System.Child("Yummy").Child("Cake")

will return Nil if:

  • SpecialFolder.System is nil or does not exist

  • the folder/directory "Yummy" does not exist

FolderItem.ChildAt

ChildAt(index As Integer, followAlias As Boolean = True) As FolderItem

Returns a FolderItem that represents a file or folder/directory within this FolderItem with the matching index passed.

Shortcuts and aliases are resolved on all platforms when followAlias is True.

Returns Nil only when some portion of the path to the child does not exist. For example:

SpecialFolder.System.Child("Yummy").ChildAt(0)

will return Nil if:

  • SpecialFolder.System is nil or does not exist

  • the folder "Yummy" does not exist

  • there is nothing in the folder "Yummy"

Tip

When browsing a folder/directory recursively, instead of ChildAt, consider using a For Each with the iterator FolderItem.Children as it's considerable faster.

Get the first file in the Documents folder:

Var docFile As FolderItem = SpecialFolder.Documents.ChildAt(0)

FolderItem.Children

Children(followAlias As Boolean = True) As Iterable

Allows you to iterate through all the files in a folder.

If the path points to an alias or shortcut, the file will resolve to the file pointed to by the alias or shortcut when followAlias is True. If you need to point to the alias/shortcut itself, use False for the followAlias parameter.

This example adds the names of all the files on the desktop to a listbox:

Var desktopFiles As FolderItem = SpecialFolder.Desktop
For Each file As FolderItem In DesktopFiles.Children
  Listbox1.AddRow(file.Name)
Next

Due to underlying differences in architecture, macOS and Linux return unordered FolderItem.Children lists. Windows is the exception and returns an ascending ordered list. If you want to return a sorted list on macOS or Linux, consider using an Array Sort method as described here:

https://documentation.xojo.com/api/language/arrays.html#arrays-sort

FolderItem.Constructor

Constructor(source As FolderItem)

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. You can create a copy of a FolderItem by passing the FolderItem to be copied to the constructor. The result is a copy of the passed FolderItem rather than a reference to it.

FolderItem.Constructor

Constructor(path As String, pathMode As FolderItem.PathModes, followAlias 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. 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.

This code passes the path to the new FolderItem.

If the path points to an alias or shortcut, the file will resolve to the file pointed to by the alias or shortcut when followAlias is True. If you need to point to the alias/shortcut itself, use False for the followAlias parameter.

The optional PathMode parameter allows you to specify the type of path: Native, Shell, or URL. 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.

Var 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 this code, a FolderItem is created from a shell path.

Var f As New FolderItem("/Users/geoff", FolderItem.pathModes.Shell)

The following code uses the Parent property of the FolderItem class to get the parent directory for the directory that contains the application:

Var f As New FolderItem("")
f = f.Parent

The following code opens a PNG file in the current folder and uses it as the background image ("backdrop") for a Canvas control:

Var f As New FolderItem("Zippy.png")
If f.Exists Then
  Canvas1.BackDrop = Picture.Open(f)
End If

The following code uses the URL path to the user's "Documents" folder on Windows:

Var f As New FolderItem("file:///C:/Documents%20and%20Settings/Joe%20User/My%20Documents/",  _
  FolderItem.PathModes.URL)
If f.Exists Then
  MessageBox(f.NativePath)
Else
  MessageBox("The folderitem does not exist.")
End If

The following code uses the shell path to the Documents folder on macOS:

Var f As New FolderItem("/Users/Joe/Documents", FolderItem.PathModes.Shell)
If f.Exists Then
  TextField1.Text = f.NativePath
Else
  MessageBox("The FolderItem does not exist.")
End If

FolderItem.CopyTo

CopyTo(destination As FolderItem)

If the FolderItem is a folder, then the folder and its contents are copied into destination.

If destination is a file and the file already exists, the copy is cancelled. You need to delete the existing file first. If there is an error, an IOException is raised.

On Xojo Cloud, FolderItems that are copied using CopyTo cannot have their permissions changed. For now, the workaround is to use a Shell command to alter the permissions:

#If TargetXojoCloud Then
  Var sh As New Shell
  sh.Execute("chmod 666 " + f.ShellPath)
#EndIf

The following example method copies a source FolderItem to a new destination using CopyTo. It returns True if all files in the folder were successfully copied and returns False otherwise.

Function CopyFileOrFolder(source As FolderItem, destination As FolderItem) As Boolean
  Var newFolder As FolderItem
  If source.IsFolder Then ' it's a folder
    newFolder = destination.Child(source.Name)
    newFolder.CreateFolder
    If Not newFolder.Exists Or Not newFolder.IsFolder Then
      ' folder was not created - stop processing
      Return False
    End If
    For Each file As FolderItem In source.Children
      If file = Nil Then
        ' inaccessible
        Return False
      End If
      If Not CopyFileOrFolder(file, newFolder) Then
        ' copy operation failed
        Return False
      End If
    Next
  Else ' it's not a folder
    Try
      source.CopyTo(destination)
      Return False
    Catch error As IOException
      MessageBox(error.Message)
    End Try
  End If
  Return True
End Function

FolderItem.CreateFolder

CreateFolder

Creates a folder at the location specified by the FolderItem.

An IOException is raised if an error occurs.

Create a folder in Documents:

Var myDataFolder As FolderItem = SpecialFolder.Documents.Child("MyData")
myDataFolder.CreateFolder

FolderItem.DriveAt

DriveAt(index As Integer) As FolderItem

Returns a FolderItem that represents a mounted/connected drive.

This method is shared.

Important

This property is not currently supported for Android.

The DriveAt function returns a FolderItem that represents the mounted drive whose number was passed. Drive zero is the boot drive. This function can be used in conjunction with the DriveCount function to loop through the mounted drives.

This example places the names of all mounted drives into a ListBox control:

For i As Integer = 0 To FolderItem.LastDriveIndex
  ListBox1.AddRow(FolderItem.DriveAt(i).Name)
Next

FolderItem.FromSaveInfo

FromSaveInfo(saveInfo As MemoryBlock) As FolderItem

Returns a FolderItem based on the SaveInfo passed to it.

This method is shared.

Important

This property is not currently supported for Android.

If the SaveInfo indicates a relative path, the current FolderItem is considered its reference point. If the SaveInfo passed to it is absolute, then the current FolderItem is ignored when resolving the path.

FromSaveInfo returns Nil only if there is not sufficient information in SaveInfo to construct a FolderItem (e.g., using a relative path that causes the parsing to descend below root level).

' the SaveInfo was previously retrieved from FolderItem.SaveInfo and saved somewhere,
' such as a preferences file.
Var saveInfo As String ' Assign your SaveInfo to this variable

Var path As String
Var file As FolderItem
file = FolderItem.FromSaveInfo(saveInfo)
If file <> Nil Then
  path = file.NativePath
End If

FolderItem.MoveTo

MoveTo(destination As FolderItem)

Moves the FolderItem to the path specified by destination.

It moves the file rather than copying it even when the source file is on another volume. After the move, the original file no longer exists. An IOException is raised if an error occurs.

If destination is a file and the file already exists, the move is cancelled. You need to delete the existing file first.

This example uses MoveTo. The source file will be deleted and moved into the destination folder.

Var f, g As FolderItem
f = FolderItem.ShowOpenFileDialog(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
      f.MoveTo(g)
      MessageBox("Success!")
    End If
  End If
Else
  MessageBox("File not found!")
End If

FolderItem.Open

Open(parameters As String = "", activate As Boolean = True)

Open(activate As Boolean = True)

If the FolderItem is an app, the app is opened. If the FolderItem is a document, the document is opened using its default app.

parameters is the app's parameters to be passed to the app being opened. The optional parameter activate specifies whether the app should be opened frontmost or behind other apps. The default value is True (foreground). If you specify False, the app will attempt to open in the background, but this may not work with certain apps.

Important

This method is not supported for console and mobile projects.

MacOS does not open multiple copies of apps. If you need to open multiple copies of an app, you should use a Shell with the "open -n Appname.app" terminal command like this:

' myApp is a FolderItem pointing to the app you want to open
Var sh As New Shell
sh.Execute("open -n " + myApp.ShellPath)

This code displays a PDF file in the built-in PDF viewer:

Var pdfFile As FolderItem
pdfFile = FolderItem.ShowOpenFileDialog("")
If pdfFile <>  Nil Then
  pdfFile.Open
End If

FolderItem.Remove

Remove

Removes/deletes the file or folder specified by the FolderItem.

This method irreversibly removes the file or folder from the volume it was stored on. If you are deleting a folder, it needs to be empty.

If the file could not be deleted, an IOException occurs. You can then check the IOException.ErrorNumber, IOException.Message or IOException.Reason to find out what went wrong (e.g. the file could still be in use, or it was locked, the directory was not empty, or the entire volume may have vanished in the mean time).

This example removes a specific file.

Var f As FolderItem
f = New FolderItem("Project Templates")
Try
  f.Remove
  MessageBox("File removed!")
Catch error As IOException
  MessageBox(error.Message)
End Try

FolderItem.RemoveFolderAndContents

RemoveFolderAndContents

Irreversibly removes/deletes the folder specified by the FolderItem as well as all items within it.

Note

An IOException will be raised if any item could not be removed/deleted.

FolderItem.SaveInfo

SaveInfo(relativeTo As FolderItem, saveInfoMode As FolderItem.SaveInfoModes = FolderItem.SaveInfoModes.Default) As MemoryBlock

Allows saving FolderItem references without relying on the absolute path.

The returned String is binary data that indicates a path which is relative to the supplied RelativeTo folder.

Important

This method is not currently supported for Android.

You may pass Nil to indicate that you do not care for a relative resolution of the path (this is, for instance, still useful on macOS where renamed and moved files can still be found with the FromSaveInfo function nonetheless).

Note

The returned String is not intended to be human-readable and any modifications may render it useless.

Gets the SaveInfo for a file. Typically you save this somewhere (perhaps a preference file) so the file can be recreated later using FromSaveInfo.

Var myFile As FolderItem = SpecialFolder.Documents.Child("MyFile.txt")
Var saveInfo As String = myFile.SaveInfo(SpecialFolder.Documents)

FolderItem.ShowOpenFileDialog

ShowOpenFileDialog(filter As String) As FolderItem

Shows the standard Open File dialog box and returns the file (as a FolderItem) selected by the user.

This method is shared.

Important

This property is not supported for console and mobile projects.

The ShowOpenFileDialog function displays the standard open-file dialog box for the platform on which the application is running. The FolderItemDialog class has the same purpose but allows for some customization.

The filter parameter is used to limit the types of files that the user can open to one or more of the file types defined via the FileType class or in the File Type Sets Editor in the IDE. The filter is a semicolon-separated list of file type names. For example, if you wanted the user to be able to open only text files and postscript files when making a particular call to the ShowOpenFileDialog function, you would define two file types using either the File Type Sets Editor or the FileType class. You would then pass "application/text; application/postscript" (or the name you chose) as the filter to the ShowOpenFileDialog function.

Only files whose type matches one of the file types passed in the filter will be displayed in the open file dialog box. If you want to display all files, you will need to add a file type to the project that uses "????" as its Mac Type.

You can also pass in actual FileType names; they are converted to their corresponding strings.

The ShowOpenFileDialog function returns a FolderItem that represents the file the user selected. You can then use the FolderItem to access various data about the file such as its name, full path, etc. See the FolderItem class for more information.

Aliases are resolved, so if the user chooses an alias file, the returned FolderItem will be to the file pointed to by the alias.

If the user clicks the Cancel button in the open file dialog box, the FolderItem will be Nil. You can test for this by comparing the FolderItem with the Nil value. Accessing a Nil FolderItem will cause a NilObjectException error.

This code opens an mp4 file and then opens it as a movie. The file type was added using the File Types Editor as a custom Common File Type.

Var f As FolderItem
Var m As New Movie

f = FolderItem.ShowOpenFileDialog("video/mp4")
If f <> Nil Then
  Movie.Open(f)
Else
  MessageBox("Open failed.")
End If

This code illustrates how to use the FileType class do specify the types of files that can be opened by ShowOpenFileDialog. When you define FileType objects, you must specify the MacType and Extensions properties. The call to ShowOpenFileDialog can combine several FileTypes in the way the example shows.

Var jpegType As New FileType
jpegType.Name = "image/jpeg"
jpegType.Extensions = "jpg;jpeg"

Var pngType As New FileType
pngType.Name = "image/png"
pngType.Extensions = "png"

Var f As FolderItem

' The actual FileTypes are converted to strings automatically for use
' with OpenFileDialog
f = FolderItem.ShowOpenFileDialog(jpegType + pngType)

In the IDE you can create file types for practically all types using the Common File Types button in the File Type Sets editor. It displays a pop-up menu of the most common types and a "More" button that displays a much larger pop-up. Instead of creating your file types in code, you can use the Common File Types feature to set these properties.

The following code uses the built-in file type for WMV movies to open a WMV file, assign the movie to the Movie property of a MoviePlayer, and plays the movie.

Var f As FolderItem
f = Folderitem.ShowOpenFileDialog(FileTypes1.VideoXMsWmv) ' Converts FileType1.VideoXMsWmv to a string
If f <> Nil Then
  MoviePlayer1.Movie = Movie.Open(f)
  MoviePlayer1.Play
End If

FolderItem.ShowSaveFileDialog

ShowSaveFileDialog(filter As String, defaultName As String) As FolderItem

Used to present the standard Save As dialog box to the user and return a FolderItem representing the file to be created.

This method is shared.

Important

This property is not supported for console and mobile projects.

The ShowSaveFileDialog function displays the standard Save As file dialog box, allowing the user to choose a location and enter a name for the file to be saved. The SaveFileDialog class provides the same functionality but allows for customization.

The ShowSaveFileDialog function does not create the file. It returns a FolderItem that represents the potential file. To create the actual file, you will need to call or Create shared method for TextOutputStream or the Create shared method of the BinaryStream.

The filter should either be an empty string or the name of a file type as defined in the File Type Sets Editor or via the FileType class.

On macOS 10.11 through 10.15, a Hide Filename Extension checkbox appears in the save-file dialog. The FolderItem returned has its ExtensionVisible property set according to the user's use of this checkbox.

This example displays the save as file dialog box. The File Type referred to by ShowSaveFileDialog declares the common file type "text/plain", which you will first want to add to your project using the File Type Group Editor.

A text file is then created and the text properties of three TextFields are written to the new file. Finally the file is closed.

Var f As FolderItem
Var fileStream As TextOutputStream
f = FolderItem.ShowSaveFileDialog(FileTypeGroup1.Text.Extensions, "MyInfo.txt")
If f <> Nil Then
  fileStream = TextOutputStream.Create(f)
  fileStream.WriteLine(NameField.Text)
  fileStream.WriteLine(AddressField.Text)
  fileStream.WriteLine(PhoneField.Text)
  fileStream.Close
End If

FolderItem.ShowSelectFolderDialog

ShowSelectFolderDialog As FolderItem

Displays a dialog box similar to the open-file dialog allowing the user to select a folder rather than a file.

This method is shared.

Important

This property is not supported for console and mobile projects.

The ShowSelectFolderDialog function displays a dialog box similar to the open-file dialog box displayed by the FolderItem function. The difference is that the dialog box displayed by the ShowSelectFolderDialog function allows the user to choose a folder rather than a file.

This example displays the name of the folder the user chose.

Var f As FolderItem
f = Folderitem.ShowSelectFolderDialog
If f <> Nil Then
  MessageBox(f.Name)
End If

FolderItem.TemporaryFile

TemporaryFile As FolderItem

The TemporaryFile function creates a FolderItem object in the current Temporary Folder. See the SpecialFolder module for information on the paths for each platform.

This method is shared.

Important

This property is not supported for mobile projects.

On Xojo Cloud, you are restricted to using the specific names returned by this method. If you need a generic folder for your own temporary files, use SpecialFolder.Temporary instead.

The following code creates FolderItem in the active Temporary folder and displays its absolute pathname.

Var f As FolderItem
f = FolderItem.TemporaryFile
MessageBox(f.NativePath)

FolderItem.UnZip

UnZip(Extends f As FolderItem, destination As FolderItem, password As String = "")

Decompresses the FolderItem into the destination passed.

Important

This method is currently not supported for Android.

To unzip a file:

Var zipFile As FolderItem = SpecialFolder.Desktop.Child("Compressed.zip")
Var destFile As FolderItem = SpecialFolder.Desktop.Child("Extracted")

If Not destFile.Exists Then destFile.CreateFolder

zipFile.Unzip(destFile)

UnZip(Extends f As FolderItem, password As String = "")

Decompresses the FolderItem in the same location as the zip file being decompressed.

Important

This method is currently not supported for Android.

If you wanted to unzip a file:

Var zipFile As FolderItem = SpecialFolder.Desktop.Child("Compressed.zip")
zipFile.Unzip

FolderItem.Zip

Zip(Extends f As FolderItem, contentsOnly As Boolean = False, compression As ZipCompressions = ZipCompressions.Normal, password As String = "") As FolderItem

Compresses the file using the compression indicated. If contentsOnly is True and the FolderItem is a folder, only the items inside the folder are added to the zip file rather than the folder itself.

Important

This method is currently not supported for Android.

This is an example of zipping SomeFolder on your Desktop:

Var someFolder As FolderItem = SpecialFolder.Desktop.Child("SomeFolder")
Var outputFile As FolderItem = someFolder.Zip

Zip(Extends f As FolderItem, destination As FolderItem, contentsOnly As Boolean = False, compression As ZipCompressions = ZipCompressions.Normal, password As String = "") As FolderItem

Compresses the file using the compression indicated. If contentsOnly is True and the FolderItem is a folder, only the items inside the folder are added to the zip file rather than the folder itself.

destination is a folder where you wish the created zip file to saved.

Important

This method is currently not supported for Android.

This is an example of zipping SomeFolder on your Desktop:

Var someFolder As FolderItem = SpecialFolder.Desktop.Child("SomeFolder")
Var destFile As FolderItem = SpecialFolder.Desktop.Child("Compressed.zip")

Call someFolder.Zip(destFile)

Notes

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"). _
Child("OFFICE11").Child("WINWORD.EXE")

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

Warning

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.

Aliases

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.

Sample code

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
  Return
End If

For Each file As Folderitem In DesktopFolder.Children
If file <> Nil Then
    ListBox1.AddRow(file.Name)
  End If
Next

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
      f.MoveTo(g)
      MessageBox("success!")
    End If
  End If
Else
  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
  Return
End If

Try
  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
  Try
    MoviePlayer1.Movie.Open(f)
  Catch e As IOException
    ' Unable to open movie
  End Try
Else
  ' 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)
    newFolder.CreateFolder
    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
      Else
        file.CopyTo(newFolder) ' it's a file so copy it
      End If
    Next
  Else ' it's not a folder
    source.CopyTo(destination)
  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
Else
  MessageBox("FolderItem does not exist!")
End If

Compatibility

All project types on all supported operating systems.