File chooser tutorial

From Murga-Projects Wiki

Practically every graphical user interface that makes use of external files has a file chooser tucked into it somewhere. It is common practice to give the user a dialog of some sort to navigate through the filesystem and pick a filename that can be used for a variety of purposes.

FLTK provides the Fl_File_Chooser class for this purpose. Fl_File_Chooser can be rather tedious to work with directly, but fortunately the fl_file_chooser and fl_dir_chooser functions are also provided to handle much of the work for you. These functions run in their own window, and return a file name or nil.

Here is one way you can use fl_file_chooser with a button to run the function interactively. We'll start by writing a simple function to be used as the button's callback:

function pick_file()
  local my_file=fltk.fl_file_chooser("pick a file","*",nil,nil)
  if my_file then
    my_output:value(my_file)
  end
end

The first line runs the fltk.fl_file_chooser function. The name 'my_file' is used to store the value returned by the chooser function. The function has four parameters:

1. The string used as a title for the file chooser
2. An expression representing a filename filter
3. The directory in which the file chooser starts
4. Absolute or relative path for the returned filename

The title string can be basically any string you desire.

The filename filter is the typical glob used in most file choosers. You can specify simply "*" to match everything, a single filename extension, such as "*.txt", a range of extensions: "*.{jpe?g,png,gif}", or even a specific file name. You can also include descriptive text: "Image Files (*.{jpe?g,png,gif})". The filter is apparently not case-sensitive.

The directory is also a string. If it is nil, the chooser will open in the current directory, and then in the last directory chosen if you run the chooser a second time during the same session.

The absolute/relative is a boolean. It will return an absolute file path if this parameter is nil/false/0. Anything else will return a file path that is relative to the current directory.

After the function completes its task, that is to say after the user has either chosen a file or cancelled the chooser window, it is always a good idea to check whether or not my_file now has a useable value before attempting to do something with the result. In this example, the check merely looks at whether or not the value is nil (if the chooser is cancelled, the value of my_file will be nil). A more reliable method for critical projects would be to also test if the value is indeed an existing file, but for now we'll keep it as basic as possible.

If my_file is *not* nil, then we can continue on to performing whatever tasks we want using that filename. Here, the filename is simply displayed in an output field:

my_output:value(my_file)

Here is some code to create that output field:

my_output=fltk:Fl_Output(10,10,300,30)

And finally, here we create a simple button and set its callback to the pick_file function:

my_button=fltk:Fl_Button(10,50,300,30,"open file chooser")
my_button:callback(pick_file)

Putting it all together into a full script looks something like this:

function pick_file()
  my_file=fltk.fl_file_chooser("pick a file","*",nil,nil)
  if my_file then
    my_output:value(my_file)
  end
end


win=fltk:Fl_Window(320,100,"File Chooser")

my_output=fltk:Fl_Output(10,10,300,30)

my_button=fltk:Fl_Button(10,50,300,30,"open file chooser")
my_button:callback(pick_file)

win:show()
Fl:run()