Tutorial: File Chooser

Introduction to File Choosers in Quorum

As noted in the name, File Choosers are meant to be used when interacting with Files and it is important to have at least a small understanding of how Files work in Quorum to use them. For this tutorial we will be doing minimal interaction with Files as the focus of this tutorial is with the File Chooser GUI component instead of the Files themselves which deal more with the internals of the System.

Files in Quorum

The File class is used to access and gather information about files on disk. They can represent a file or a directory, and actions are provided for both manipulation and gathering of file data (such as file name, last time modified, etc). But a File object is not used for modifying the contents of files, but actions are provided that allow this functionality through other classes. For more information on the File class and modifying the contents of files, see the File, FileReader, FileWriter, and FileRandomAccess documentation.

What is a File Chooser?

A File Chooser is an interface tool that gives users a way to navigate the File System, usually in the form of a system dialog. In Quorum, the File Chooser class gives you the actions necessary to open a File Chooser dialog but the dialog itself is provided by the Operating System. How the dialog looks and functions may vary from system to system but generally a dialog will appear where you can view the Files and Folders on the system and then you will be able to choose a file and the dialog will return the file the user chose.

File Filters

A File Filter is a class that represents a filter for files in an open or save dialog. It does not do much on its own, but is used in relation to the FileChooser class. An example of a filter in action may be in a File Chooser dialog that is meant for opening an image. You may when the user to only select a valid image file so you can add a filter so only files with a "png" will be shown and allowed to be selected. We will show how to use filters with file choosers in Quorum in later section in this tutorial.

Making File Chooser Dialogs

For this tutorial we will be using buttons and behaviors to trigger the File Chooser Dialogs. We will start by making three Behavior classes that will open one of three File Chooser Dialogs.

The three File Chooser Dialogs are the Open File Dialogs, the Save File Dialog, and the Choose Folder Dialog. The difference between them is that the Dialog will look slightly different and that depends on the OS and exact appearance depends on the OS, for the Quorum side all we need to worry about is calling the right actions with the right parameters and getting the return value.

Open File Dialog

The first Behavior we will make will call the Open File Dialog. We will make a Quorum class file for it and we will name it "openFile.quorum."

For all three of these behaviors we will need the File Chooser and File Libraries. You can include them with the following use statements:

use Libraries.Interface.Controls.FileChooser
use Libraries.System.File

We want to open the file chooser when the button is clicked so we will overwrite the Run action. To open the File Chooser all we need to do is make a FileChooser object and then call the OpenFileDialog action. But OpenFileDialog returns the File that was chosen so we need to make a File object that will hold the returned file. Then if the user chooses a file to open we will output the absolute path of the file and its name. The full openFile Behavior is provided in the code block below:

use Libraries.Interface.Behaviors.Behavior
use Libraries.Interface.Events.BehaviorEvent
use Libraries.Interface.Controls.FileChooser
use Libraries.System.File

class openFile is Behavior
    action Run(BehaviorEvent event)
        FileChooser chooser
        File file = chooser:OpenFileDialog()

        if file not= undefined
            output file:GetAbsolutePath()
            output file:GetFileName()
        end
    end
end

Save File Dialog

Now we will make the behavior that will call the Save File Dialog, we will make a new Quorum class file and name it "saveFile.quorum." This behavior is almost exactly the same as openFile but with the name saveFile and replacing the OpenFileDialog action with the SaveFileDialog action. The call for the Save File Dialog is shown in the following line of code:

File file = chooser:SaveFileDialog()

In the Save File Dialog the user provides a name for the File and they choose a directory. This is useful when you want to the user to create a new File at a location they want. To create a new file and then write to it you can go to the File class documentation to learn how.

Choose Folder Dialog

Lastly we will make the behavior that will open the Choose Folder Dialog, we make another new Quorum class file and name it "chooseFolder.quorum." This dialog is opened a bit differently because you need provide a file as a parameter. The file parameter is used as the location where the Dialog will open to. The other two Dialogs also can take a File as parameter for location, but if none is provided or the File’s Path was not set then it will open to either to default of the system or the path to your project.

In the following code block is the chooseFolder behavior but with the use statements excluded. You will notice that other than calling the ChooseFolderDialog action we also add a new output statement that will output true if the File is a directory.

use Libraries.Interface.Behaviors.Behavior
use Libraries.Interface.Events.BehaviorEvent
use Libraries.Interface.Controls.FileChooser
use Libraries.System.File

class chooseFolder is Behavior
    action Run(BehaviorEvent event)
        FileChooser chooser
        File location
        File folder = chooser:ChooseFolderDialog(location)

        if file not= undefined
            output folder:GetAbsolutePath()
            output folder:GetFileName()
            output folder:isDirectory()
        end
    end
end

Adding a File Filter

File Chooser dialogs have an option to add File Filter which will force the user to choose a file or only view Files with a specific file extension. You do need to add it for this tutorial but to use File Filter you will need the FileFilter library which you can include using the following use statement:

use Libraries.Interface.Controls.FileFilter

To show how you set the filter and use it for a dialog an example of how you would add one so the user can only select Quorum files is shown below:

FileFilter filter
filter:Add("quorum")
File file = chooser:OpenFileDialog(filter)

Since the File Filter only works on files only the Open File and Save File Dialogs can accept a filter. If you need to add a Filter and a Location then the first parameter for the action call will be the location and the second parameter is the filter.

Adding Buttons to Open File Choosers

To open the File Choosers we will simply make Buttons that when clicked will call a behavior that will open the file choosers for us. We will make Three Buttons for the three different dialogs you can open. The code for this will be in the CreateGame action of the main class and is provided below:

action CreateGame
    Button open
    Button save
    Button folder

    open:SetName("Open File")
    save:SetName("Save File")
    folder:SetName("Choose Folder")

    open:SetPosition(300, 400)
    save:SetPosition(300, 350)
    folder:SetPosition(300, 300)

    openFile openBehavior
    open:SetBehavior(openBehavior)

    saveFile saveBehavior
    save:SetBehavior(saveBehavior)

    chooseFolder foldBehavior
    folder:SetBehavior(foldBehavior)

    open:SetNextFocus(save)
    save:SetNextFocus(folder)
    folder:SetNextFocus(open)
    open:SetPreviousFocus(folder)
    save:SetPreviousFocus(open)
    folder:SetPreviousFocus(save)
    SetFocus(open)

    Add(open)
    Add(save)
    Add(folder)
end

Note that we also added to a Focus Cycle to ensure that our application is accessible.

Now we can run the program and there will be three Buttons and you can activate a Button to open one of the File Chooser Dialogs. After interacting with the Dialogs the File chosen will be returned and the program will output the absolute path to the File and the File’s name.

Next Tutorial

In the next tutorial, we will discuss Spreadsheets, which describes how to use Spreadsheets.