Sooner or later your app will need to work with files, maybe to save the data generated with the app itself, to open the files created with other apps or because is the main purpose of the utility you are working on. Xojo gives you the class FolderItem fully loaded with a useful bunch of properties that allow you to examine the attributes of any file; for example, the creation or modification of dates, the file path (in several formats), if the file is an alias, etc. The FolderItem class also gives you the methods to do a lot of file operations without effort.
Of course, as Xojo is a native multi-platform development environment, the FolderItem class is available for all the supported deployment platforms: desktop (macOS, Windows, Linux, Raspberry Pi), console, web or iOS. Of course, under iOS and other sandboxed deployments, you will have to consider the limitations imposed by the OS when dealing with files, as for example not writing to the app bundle (under OS X and iOS), accessing only the allowed folders/directories, etc.
As it goes when using any class, the first thing you will have to do is get a new class instance (an object) pointing to the file item you want to work with, whether it is one already available or one you want to create from scratch (i.e: giving the path, name and extension). In both scenarios, the most basic way to go is the same:
Dim f as new FolderItem("\users\myusuario\documents\test.txt")
With the previous line of code we will be using the FolderItem class Constructor, passing along as the argument the native path to the file we want to get the reference to, if it already exists; or to the file our app expects to create. It is important to point out the fact that the path format, as String, is the native one to the platform over which we are going to deploy the app, something you have to consider if you want to create a multiplatform app. For these cases, you can turn to the use of the conditional compilation clause #If…#Then…#Endif, providing the native path variation expected by the OS under which your app is running.
In addition, when we use the FolderItem constructor in combination with absolute paths as arguments, we have not guarantees that the resulting reference assigned to the FolderItem variable is a valid one (in our example, pointed by the ‘f’ variable). For example, if we were trying to open a file, it could be the case that the file was no longer in the referenced path anymore (moved, deleted…); or maybe we have included a typo in the path composition. It is for things like these that we should always check the correctness of the variable before using any of the provided methods or accessing the properties, because it is possible that we were dealing with a Nil reference.
For example, we can check our FolderItem variables using the conditional form like this:
if f <> Nil then // this is a valid reference // so we can work with it end if
Or, preferably, catching the exceptions as in the following example. This way we avoid the use of multiple if…then…else in the same code fragment:
Exception e as NilObjectException MsgBox "The file is not valid"
How can we get a reference to a file for those cases were we don’t know the file path in advance? I mean, this is what happens, for example, when using most of the apps that allows us to choose the file via a File Dialog Box; a Window that brings access to the OS file system showing all the files that are compatibles with the app.
Choosing Files: GetOpenFolderItem
For these cases Xojo offers the GetOpenFolderItem function, passing along as a unique parameter the string representing, as a filter, the kind of files our app is interested in. When we use this parameter, the File Dialog Box will show only the compatibles ones as selectable by the user, leaving the rest in ghost mode. We can also choose to not use any filter at all, passing the string “????” as the function parameter.
As result of this function invocation we will get a FolderItem instance. For example:
Dim f a FolderItem = GetOpenFolderItem("????")
MsgBox f.path
However, during the user interaction with the File Dialog Box it can be the case that the user selected a valid file clicking next the ‘Ok’ button, in whose case our app would get a valid reference; but it can also be the case that the user canceled the operation clicking on the ‘Cancel’ button, in which case our variable (‘f’ in the code example) would get a Nil reference. Thus, it’s important to apply the same kind of test over the variable that we have seen on the previous section.
SpecialFolder: Direct Access to Well Known Directories
Xojo also puts in our hands a third option, we can use to get valid references to files in a faster and multiplatform way using the SpecialFolder Module. This module gives us access to well known paths on every supported OS, so our app always points to the right path no matter the OS it is running on. This is the way to go, for example, when we want to point to the Documents folder or other specific folders such as Library or Cache.
For example, if we want to get the right reference to the Documents folder on every supported deployment OS, we would have to use this fragment of code:
Dim docs As Xojo.IO.FolderItem docs = Xojo.IO.SpecialFolder.Documents msgbx docs.path
Try to run the previous fragment of code on several operating systems (virtual machines are a great help for this), and you will see how Xojo points to the right path in every case.
Child: Adding Items to a FolderItem Path
In the previous section we saw how to get a reference to a folder or directory; but, how can we complete the path so it also includes a specific file item, either an existing one or the one we want to create? For that we can use the method of the class instance Child. With this method we can add as many path components as we need (for example, several folder or directories levels in the file system hierarchy) until we point to the file item over which we can get a valid reference. For example:
Using Xojo.IO
Dim docs as FolderItem = SpecialFolder.Documents
docs = docs.child("MyFile.txt")
Or we can use also:
Using Xojo.IO
Dim docs as FolderItem = SpecialFolder.Documents
docs = docs.child("Recipes").child("MyRecipe.doc")
With the first example, the reference points to a file item thanks to the use of the Child method. While the second example also adds an additional directory (“Recipes”) to the path via the use of Child, to finally point to the file item. In both cases, the referenced file may or may not exist. If the file doesn’t exist yet, then the ‘docs’ variable will not include valid data on all of the properties that you could read if the variable were pointing to an existing file. For example, some of these properties are creation date, modification date or file length. When the variable points to a folder or directory, then we can use the Count property to know the number of items contained by the folder so we can iterate on them, for example.
Iterating Files and Folders
However, when we need to iterate a folder item, for example to manipulate every available item or transverse the file system hierarchy walking every found folder, the best we can do is get an Iterator on the folder/directory we want to use as the root point of the process. For this, the Xojo.IO.FolderItem class gives us the Children method, so we can use the For…Each…In loop to walk every available item in the iterator.
For example, we can add all the visible files available under the Documents folder to a ListBox using the following code snippet:
using Xojo.io dim f as FolderItem = SpecialFolder.Documents for each i as FolderItem in f.Children if i.IsFolder = false and i.IsVisible then Listbox1.AddRow i.name next
In Brief…
We have seen the basics of the FolderItem class and how we can use it to get references to folders/directories and files, both using the Classic Framework or the Modern one. We have seen also several ways to compose the FolderItem paths, how to deal with Nil references, and the best way to walk through all the available files under a folder via an Iterator. Once we get the reference to the file and/or folder of interest, there are a lot of methods and properties you can explore under the FolderItem class!
Javier Rodriguez has been the Xojo Spanish Evangelist since 2008, he’s also a Developer, Consultant and Trainer who has used Xojo since 1998. He is in charge of AprendeXojo.com and the developer behind the GuancheMOS plug-in for Xojo Developers and the Snippery app, among others.