Class # FolderItem

forsearch

File

forsearch

Files --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ## Description FolderItem class objects can represent files, applications, folders and volumes. 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. ## Properties

table-centered_columns_3_and_4

| Name | Type | Read-Only | Shared | |---------------------------------------------------------|---------------------------------------------------|-----------|--------| | `Count` | `Integer` | ✓ | | | `CreationDateTime` | `DateTime` | | | | `DisplayName` | `String` | ✓ | | | `DriveCount` | `Integer` | ✓ | ✓ | | `Exists` | `Boolean` | ✓ | | | `Extension` | `String` | | | | `ExtensionVisible` | `Boolean` | | | | `Group` | `String` | | | | `Handle` | `Ptr` | ✓ | | | `IsAlias` | `Boolean` | ✓ | | | `IsFolder` | `Boolean` | ✓ | | | `IsReadable` | `Boolean` | ✓ | | | `IsWriteable` | `Boolean` | ✓ | | | `LastDriveIndex` | `Integer` | ✓ | ✓ | | `Length` | `UInt64` | ✓ | | | `Locked` | `Boolean` | | | | `ModificationDateTime` | `DateTime` | | | | `Name` | `String` | | | | `NativePath` | `String` | ✓ | | | `Owner` | `String` | | | | `Parent` | FolderItem | ✓ | | | `Permissions` | `Integer` | | | | `ShellPath` | `String` | ✓ | | | `Type` | `String` | ✓ | | | `URLPath` | `String` | ✓ | | | `Visible` | `Boolean` | | | ## Methods

table-centered_column_4

| 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` | activate As `Boolean` = `True` | | | | | parameters As `String` = "", 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, destinationFolder 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

forsearch

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

forsearch

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. |

forsearch

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

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

forsearch

FolderItem.Count **Count** As `Integer` > The number of items in the FolderItem if it is a directory/folder. > > Avoid calling this function several times as it is costly in processing time and will have poor performance. Instead, get its value once and store it in a variable for further use. > > This property is read-only. > > ``` xojo > Var f As FolderItem = FolderItem.ShowSelectFolderDialog > > MessageBox(f.Count.ToString) > ```

forsearch

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. > > ``` xojo > 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`. > > ``` xojo > Var f As FolderItem = FolderItem.ShowOpenFileDialog("") > > If f <> Nil Then > f.CreationDateTime = DateTime.Now > End If > ```

forsearch

FolderItem.DisplayName **DisplayName** As `String` > The name of the FolderItem as it should be seen by the user. > > 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. > > This property is read-only.

forsearch

FolderItem.DriveCount **DriveCount** As `Integer` > Returns the number of mounted drives. > > This property is read-only. > > This property is `shared`. > >

> >

> > Important > >

> > This property is not currently supported for Android. > >

forsearch

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. > > ``` xojo > Var f As FolderItem = SpecialFolder.Desktop.Child("Zippy.png") > > If f.Exists Then > Canvas1.Backdrop = Picture.Open(f) > End If > ```

forsearch

FolderItem.Extension **Extension** As `String` > Allows you to get and set the FolderItem's extension.

forsearch

FolderItem.ExtensionVisible **ExtensionVisible** As `Boolean` > Allows you to tell whether a given file has its file extension hidden or visible, or toggles that status. > > 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. > >

> >

> > Important > >

> > This property is not currently supported for Android. > >

> > This code checks the ExtensionVisible flag for a file. > > ``` xojo > 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 > ```

forsearch

FolderItem.Group **Group** As `String` > Gets or sets the name of the owning Group of the FolderItem. > > 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. > >

> >

> > Important > >

> > This property is not currently supported for Android. > >

> > The following gets the name of the selected FolderItem. > > ``` xojo > Var f As FolderItem = FolderItem.ShowOpenFileDialog("text/plain") > > MessageBox(f.Group) > ```

forsearch

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. > >

forsearch

FolderItem.IsAlias **IsAlias** As `Boolean` > Returns `True` if the item is an alias. > > 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.ChildAt`, `FolderItem.Child` or FolderItem.Constructor(path As String, pathMode As FolderItem.PathModes, followAlias As Boolean = True). > > This property is read-only. > >

> >

> > Important > >

> > This property is not currently supported for Android. > >

> > ``` xojo > 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 > ```

forsearch

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: > > ``` xojo > Var f As FolderItem = 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: > > ``` xojo > Var f As FolderItem = New FolderItem("Resources", FolderItem.PathModes.Native) > > 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 > ```

forsearch

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. > > ``` xojo > Var f As FolderItem = FolderItem.ShowOpenFileDialog("text/plain") > > If f.IsReadable Then > ' conduct the read.. > Else > MessageBox("The file cannot be read!") > End If > ```

forsearch

FolderItem.IsWriteable **IsWriteable** As `Boolean` > IsWriteable is `True` if you have permissions to write to the FolderItem. > > 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 property is read-only. > > This example checks the IsWritable flag prior to doing the write. > > ``` xojo > Var f As FolderItem = FolderItem.ShowOpenFileDialog("text/plain") > > If f.IsWriteable Then > ' conduct the write operation > Else > MessageBox("You cannot write to the file!") > End If > ```

forsearch

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. > >

forsearch

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. > > ``` xojo > Var f As FolderItem = FolderItem.ShowOpenFileDialog("text/plain") > > If f <> Nil then > MessageBox(f.Length.ToString) > End If > ```

forsearch

FolderItem.Locked **Locked** As `Boolean` > The FolderItem is locked or is on a locked volume and thus cannot be written to or deleted. > > ``` xojo > Var f As FolderItem = FolderItem.ShowOpenFileDialog("text/plain") > > If f.Locked Then > MessageBox("The file is locked!") > Else > ' access the file > End If > ```

forsearch

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 ModificationDateTime 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. > > ``` xojo > Var f As FolderItem = 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`. > > ``` xojo > Var f As FolderItem = FolderItem.ShowOpenFileDialog("") > > If f <> Nil Then > f.ModificationDateTime = DateTime.Now > End If > ```

forsearch

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. > > ``` xojo > Var f As FolderItem = FolderItem.ShowOpenFileDialog("text/plain") > > f.Name = "NewFilename" > ```

forsearch

FolderItem.NativePath **NativePath** As `String` > The full path to the FolderItem using the path format native to the OS. > > 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). > > 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 property is read-only. > > This example displays the native path: > > ``` xojo > Var f As New FolderItem > > MessageBox(f.NativePath) > ```

forsearch

FolderItem.Owner **Owner** As `String` > Gets or sets the Owner of the FolderItem under Unix-based operating systems (macOS and Linux). > > 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. > >

> >

> > Important > >

> > This property is not currently supported for Android. > >

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

forsearch

FolderItem.Parent **Parent** As **FolderItem** > Returns the FolderItem object for the parent of this item in the file hierarchy. > > Returns `Nil` if this item is the root. > > This property is read-only. > > The following example displays the Name of the Parent. > > ``` xojo > Var f As FolderItem = FolderItem.ShowOpenFileDialog("text/plain") > > If f.Parent <> Nil Then > MessageBox("Parent folder name: " + f.Parent.Name) > End If > ```

forsearch

FolderItem.Permissions **Permissions** As `Integer` > Gets and sets the permissions of the FolderItem on Unix-based operating systems only (macOS and Linux). > > 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. > >

> >

> > Important > >

> > This property is not currently supported for Android. > >

> > 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., > > ``` xojo > myFile.Permissions = &o764 > ```

forsearch

FolderItem.ShellPath **ShellPath** As `String` > Gets the shell path of the FolderItem. > > 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](http://msdn.microsoft.com/en-us/library/aa365247(v=vs.85).aspx#short_vs._long_names). > > 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`. > > This property is read-only. > >

> >

> > Important > >

> > This property is not currently supported for Android. > >

> > ``` xojo > Var f As FolderItem = FolderItem.ShowOpenFileDialog("????") > > MessageBox(f.ShellPath) > ```

forsearch

FolderItem.Type **Type** As `String` > If the FolderItem is not a folder, this property returns the `Name` (MIME name) of the matching `FileType` from a File Type Set defined in your project. If the FolderItem is a folder (macOS), it will return a matching file type if you have created one. If no File Type Set in the project matches the file, this property will be empty. > > This property is read-only. > >

> >

> > Important > >

> > This property is not currently supported for Android. > >

> > To compare the returned value against a `FileType`, use its `Name` property. Because `FileType` has a built-in conversion to `String` that returns its `Name`, you can also compare directly against the `FileType` object itself: > > ``` xojo > Var f As FolderItem = SpecialFolder.Desktop.Child("test.txt") > ' Compare using the FileType.Name property (explicit) > If f.Type = FileTypes1.PlainText.Name Then > MessageBox("Plain text file") > End If > > ' Or use the implicit String conversion of FileType (equivalent) > If f.Type = FileTypes1.PlainText Then > MessageBox("Plain text file") > End If > ``` > >

> >

> > Note > >

> > This property is only populated when the file's type matches a `FileType` in one of your project's File Type Sets. If no match is found — for example, when a file type uses a dynamic UTI that does not correspond to a defined `FileType` — `Type` returns an empty string. In that case, compare using `Extension` instead: > > ``` xojo > If f.Extension = "helpbook" Then > ' Handle the file > End If > ``` > >

forsearch

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. > > ``` xojo > Var f As FolderItem = FolderItem.ShowOpenFileDialog("????") > > If Not f.URLPath.IsEmpty Then > MessageBox(f.URLPath) > Else > MessageBox("The URLPath is null") > End If > ```

forsearch

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. > >

> > ``` xojo > Var f As FolderItem = FolderItem.ShowOpenFileDialog("????") > > If f.Visible Then > MessageBox(f.DisplayName) > Else > MessageBox("The FolderItem is not visible.") > End If > ``` ## Method descriptions

forsearch

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: > > ``` xojo > 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

forsearch

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: > > ``` xojo > 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: > > ``` xojo > Var docFile As FolderItem = SpecialFolder.Documents.ChildAt(0) > ```

forsearch

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: > > ``` xojo > 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: > >

forsearch

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.

forsearch

FolderItem.Constructor **Constructor**(path As `String`, pathMode As `FolderItem.PathModes`, followAlias As `Boolean` = `True`) > 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 *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. > > ``` xojo > Var f As FolderItem = New FolderItem("myDoc.txt", FolderItem.PathModes.Native) > ``` > > 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. > > ``` xojo > 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: > > ``` xojo > Var f As New FolderItem("", FolderItem.PathModes.Native) > > 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: > > ``` xojo > Var f As New FolderItem("Zippy.png", FolderItem.PathModes.Native) > > 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: > > ``` xojo > 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: > > ``` xojo > 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 > ```

forsearch

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: > > ``` xojo > #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. > > ``` xojo > 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 > ```

forsearch

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: > > ``` xojo > Var myDataFolder As FolderItem = SpecialFolder.Documents.Child("MyData") > > myDataFolder.CreateFolder > ```

forsearch

FolderItem.DriveAt **DriveAt**(index As `Integer`) As FolderItem > Returns a FolderItem that represents a mounted/connected drive. > > 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 method is `shared`. > >

> >

> > Important > >

> > This property is not currently supported for Android. > >

> > This example places the names of all mounted drives into a `ListBox` control: > > ``` xojo > For i As Integer = 0 To FolderItem.LastDriveIndex > ListBox1.AddRow(FolderItem.DriveAt(i).Name) > Next > ```

forsearch

FolderItem.FromSaveInfo **FromSaveInfo**(saveInfo As `MemoryBlock`) As FolderItem > Returns a FolderItem based on the `SaveInfo` passed to it. > > 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). > > This method is `shared`. > >

> >

> > Important > >

> > This property is not currently supported for Android. > >

> > ``` xojo > ' Obtain a SaveInfo reference for a file (typically stored in a preferences file) > Var myFile As FolderItem = SpecialFolder.Documents.Child("MyFile.txt") > Var savedInfo As String = myFile.SaveInfo(Nil) > > ' Later, use the saved reference to restore the FolderItem > Var file As FolderItem = FolderItem.FromSaveInfo(savedInfo) > > If file <> Nil Then > Var path As String = file.NativePath > End If > ```

forsearch

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. > > ``` xojo > Var f As FolderItem = FolderItem.ShowOpenFileDialog(FileTypes1.Text) > > If f <> Nil Then ' if the user didn't cancel.. > > If f.Exists Then ' if it is a valid file... > > Var g As FolderItem = 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 > ```

forsearch

FolderItem.Open **Open**(activate As `Boolean` = `True`) **Open**(parameters As `String` = "", 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: > > ``` xojo > ' 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: > > ``` xojo > Var pdfFile As FolderItem = FolderItem.ShowOpenFileDialog("") > > If pdfFile <> Nil Then > pdfFile.Open > End If > ```

forsearch

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. > > ``` xojo > Var f As FolderItem = New FolderItem("Project Templates", FolderItem.PathModes.Native) > > Try > f.Remove > MessageBox("File removed!") > Catch error As IOException > MessageBox(error.Message) > End Try > ```

forsearch

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. > >

forsearch

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`. > > ``` xojo > Var myFile As FolderItem = SpecialFolder.Documents.Child("MyFile.txt") > Var saveInfo As String = myFile.SaveInfo(SpecialFolder.Documents) > ```

forsearch

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. > > 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 method is `shared`. > >

> >

> > Important > >

> > This property is not supported for console and mobile projects. > >

> > 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. > > ``` xojo > Var f As FolderItem = FolderItem.ShowOpenFileDialog("video/mp4") > > If f <> Nil Then > Var m As New Movie > m = 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. > > ``` xojo > 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. > > ``` xojo > 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 > ```

forsearch

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. > > 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 method is `shared`. > >

> >

> > Important > >

> > This property is not supported for console and mobile projects. > >

> > 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. > > ``` xojo > Var f As FolderItem > > f = FolderItem.ShowSaveFileDialog(FileTypeGroup1.Text.Extensions, "MyInfo.txt") > > If f <> Nil Then > Var fileStream As TextOutputStream = TextOutputStream.Create(f) > > fileStream.WriteLine(NameField.Text) > fileStream.WriteLine(AddressField.Text) > fileStream.WriteLine(PhoneField.Text) > fileStream.Close > End If > ```

forsearch

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. > > 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 method is `shared`. > >

> >

> > Important > >

> > This property is not supported for console and mobile projects. > >

> > This example displays the name of the folder the user chose. > > ``` xojo > Var f As FolderItem = FolderItem.ShowSelectFolderDialog > > If f <> Nil Then > MessageBox(f.Name) > End If > ```

forsearch

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. > > 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. > > This method is `shared`. > >

> >

> > Important > >

> > This property is not supported for mobile projects. > >

> > The following code creates FolderItem in the active Temporary folder and displays its absolute pathname. > > ``` xojo > Var f As FolderItem = FolderItem.TemporaryFile > > MessageBox(f.NativePath) > ```

forsearch

FolderItem.Unzip **Unzip**(`Extends` f As FolderItem, destinationFolder As FolderItem, password As `String` = "") > Decompresses the FolderItem into the *destinationFolder* passed. > > To unzip a file: > > ``` xojo > 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. > > If you wanted to unzip a file: > > ``` xojo > Var zipFile As FolderItem = SpecialFolder.Desktop.Child("Compressed.zip") > zipFile.Unzip > ```

forsearch

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. > > This is an example of zipping SomeFolder on your Desktop: > > ``` xojo > 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. > > This is an example of zipping SomeFolder on your Desktop: > > ``` xojo > 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). ``` xojo 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: ``` xojo 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. ``` xojo 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: ``` xojo Var f As New FolderItem("", FolderItem.PathModes.Native) f = f.Parent ``` Remember, macOS is based on BSD Unix which uses "/" as the separator. --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Windows path separators On Windows, both the backslash \\ and forward slash / are valid path separators when constructing a FolderItem. For example, both of the following are valid: ``` xojo Var f1 As New FolderItem("C:\This\Does\Exist", FolderItem.PathModes.Native) Var f2 As New FolderItem("C:/This/Does/Exist", FolderItem.PathModes.Native) ``` This does not apply to macOS or Linux, where only the forward slash is valid. --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### 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: ``` xojo 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 "".

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`. ``` xojo 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`. ``` xojo Var f As FolderItem = FolderItem.ShowOpenFileDialog(FileTypeGroup1.Text) If f <> Nil Then ' if the user didn't cancel.. If f.Exists Then ' if it is a valid file... Var g As FolderItem = 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. ``` xojo 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. ``` xojo 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: ``` xojo Var origin As FolderItem = FolderItem.ShowSelectFolderDialog If origin <> Nil Then Var destination As FolderItem = FolderItem.ShowSelectFolderDialog If destination <> Nil Then CopyFileOrFolder(origin, destination) ' See below MessageBox("Copy complete!") End If End If ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The CopyFileOrFolder method is as follows: ``` xojo 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: ``` xojo 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 | | | |-----------------------|-----| | **Project Types** | All | | **Operating Systems** | All |

`Object` parent class; `BinaryStream`, `FolderItemDialog`, `OpenFileDialog`, `SaveFileDialog`, `SelectFolderDialog`, `SpecialFolder`, `TextInputStream`, `TextOutputStream` classes