FLTK matrix user chat room
(using Element browser app)   FLTK gitter user chat room   GitHub FLTK Project   FLTK News RSS Feed  
  FLTK Apps      FLTK Library      Forums      Links     Login 
 Home  |  Articles & FAQs  |  Bugs & Features  |  Documentation  |  Download  ]

class Fl_File_Chooser

Class Hierarchy


Include Files

    #include <FL/Fl_File_Chooser.H>


The Fl_File_Chooser widget displays a standard file selection dialog that supports various selection modes.

Fl_File_Chooser widget

The Fl_File_Chooser class also exports several static values that may be used to localize or customize the appearance of all file chooser dialogs:

Member Default value
add_favorites_label "Add to Favorites"
all_files_label "All Files (*)"
custom_filter_label "Custom Filter"
existing_file_label "Please choose an existing file!"
favorites_label "Favorites"
filename_label "Filename:"
filesystems_label "My Computer" (WIN32)
"File Systems" (all others)
manage_favorites_label "Manage Favorites"
new_directory_label "New Directory?"
new_directory_tooltip "Create a new directory."
preview_label "Preview"
save_label "Save"
show_label "Show:"
sort fl_numericsort

The sort member specifies the sort function that is used when loading the contents of a directory.

Public Members

The Fl_File_Chooser class exports the "new directory" (newButton) and "preview" (previewButton) widgets so that application developers can control their appearance and use. For more complex customization, consider copying the FLTK file chooser code and changing it accordingly.


Fl_File_Chooser(const char *pathname, const char *pattern, int type, const char *title)

The constructor creates the Fl_File_Chooser dialog pictured above. The pathname argument can be a directory name or a complete file name (in which case the corresponding file is highlighted in the list and in the filename input field.)

The pattern argument can be a NULL string or "*" to list all files, or it can be a series of descriptions and filter strings separated by tab characters (\t). The format of filters is either "Description text (patterns)" or just "patterns". A file chooser that provides filters for HTML and image files might look like:

    "HTML Files (*.html)\tImage Files (*.{bmp,gif,jpg,png})"

The file chooser will automatically add the "All Files (*)" pattern to the end of the string you pass if you do not provide one. The first filter in the string is the default filter.

See the FLTK documentation on fl_filename_match() for the kinds of pattern strings that are supported.

The type argument can be one of the following:

  • SINGLE - allows the user to select a single, existing file.
  • MULTI - allows the user to select one or more existing files.
  • CREATE - allows the user to select a single, existing file or specify a new filename.
  • DIRECTORY - allows the user to select a single, existing directory.

The title argument is used to set the title bar text for the Fl_File_Chooser window.


Destroys the widget and frees all memory used by it.

void color(Fl_Color c)
Fl_Color color()

Sets or gets the background color of the Fl_File_Browser list.

int count()

Returns the number of selected files.

void directory(const char *pathname)
const char *directory()

Sets or gets the current directory.

void filter(const char *pattern)
const char *filter()

Sets or gets the current filename filter patterns. The filter patterns use fl_filename_match(). Multiple patterns can be used by separating them with tabs, like "*.jpg\t*.png\t*.gif\t*". In addition, you can provide human-readable labels with the patterns inside parenthesis, like "JPEG Files (*.jpg)\tPNG Files (*.png)\tGIF Files (*.gif)\tAll Files (*)". Use filter(NULL) to show all files.

void filter_value(int f)
int filter_value()

Sets or gets the current filename filter selection.

void hide()

Hides the Fl_File_Chooser window.

void iconsize(uchar s)
uchar iconsize()

Sets or gets the size of the icons in the Fl_File_Browser. By default the icon size is set to 1.5 times the textsize().

void label(const char *l)
const char *label()

Sets or gets the title bar text for the Fl_File_Chooser.

void ok_label(const char *l)
const char *ok_label()

Sets or gets the label for the "ok" button in the Fl_File_Chooser.

void preview(int e)
int preview()

The first form enables or disables the preview box in the file chooser. The second form returns the current state of the preview box.

void rescan()

Reloads the current directory in the Fl_File_Browser.

void show()

Shows the Fl_File_Chooser window.

void textcolor(Fl_Color c)
Fl_Color textcolor()

Sets or gets the current Fl_File_Browser text color.

void textfont(uchar f)
uchar textfont()

Sets or gets the current Fl_File_Browser text font.

void textsize(uchar s)
uchar textsize()

Sets or gets the current Fl_File_Browser text size.

void type(int t)
int type()

Sets or gets the current type of Fl_File_Chooser.

const char *value(const char *pathname)
const char *value(int file)
const char *value()

Sets or gets the current value of the selected file.

In the second form, file is a 1-based index into a list of file names. The number of selected files is returned by Fl_File_Chooser::count().

This sample code loops through all selected files:

// Get list of filenames user selected from a MULTI chooser
for ( int t=1; t<=chooser->count(); t++ ) {
    const char *filename = chooser->value(t);

int visible()

Returns 1 if the Fl_File_Chooser window is visible.

User Comments [ Add Comment ]

From svartalf, 16:19 Apr 18, 2005 (score=3)

Well, I couldn't stand this stuff not working like it's "supposed" to, so I went a Googling for anyone else that ran afoul of this little convienience class.  Fortunately, there was one, and there IS a way around the whole thing.  It's not pretty, but it will work...

// Now call the file chooser ... fc->show();

// ... them make FL wait until the file selection is done while(fc->shown())

// finally manipulate the file name String filename = fc -> value();

Fl_File_Chooser will have a null value as a return for value(), if the user clicked Cancel and will always contain a value if they chose something once they double-click a filename, click okay, or press enter with something in the text entry field.  For many, the callback will be much less than useful as it appears that there's a design misfeature in that it will call the callback if the user selects something with a single click AND when they finally select something.  The above trick is a workaround.
Reply ]

From svartalf, 15:25 Apr 18, 2005 (score=3)

It's still got one issue in that it doesn't appear to work along the standard lines (i.e. it doesn't allow me to set user_data for the callback.  If someone is going to have a standard way about doing callbacks, etc. then someone should stick with it.  I'm going to be able to work around the damn thing, but it's a pain to encapsulate the ui code in a class when people do things like this.
Reply ]

From greg.ercolano, 21:44 Aug 04, 2005 (score=3)

> It's still got one issue in that it doesn't appear to work
> along the standard lines (i.e. it doesn't allow me to set
> user_data for the callback.

I'd agree, with the caveat that you can set the user_data as the second argument to callback(), but it's true once set, you can't get/set it with a 'user_data()' method.

The docs show the widget is derived from Fl_Group, when in fact it's not; it is actually a standalone class with lots of fltk-ish methods, user_data() being a notable omission.

So in that respect, the docs definitely mislead one into expecting all the methods of an Fl_Group to be accessable, when in fact that's not the case.

And it is indeed unusual that the class isn't derived from an Fl_Group or Fl_Window. Not sure why that is.

I've posted an STR for this; #969.
Reply ]

From squisher, 14:36 Feb 20, 2005 (score=3)

Using this class is pretty simple: Use this global function:

void save_input_file(Fl_File_Chooser *w, void *userdata)
    cout << "File selected:" << w->value() << endl;
And this snippet to activate the dialog, i.e. in a callback function of a button:
    Fl_File_Chooser *fc = new Fl_File_Chooser(".",NULL,0,"Input File");

Reply ]

From Mark T., 16:53 Sep 17, 2004 (score=1)

This document is essentially unusable. Although this class ultimately descends from Fl_Widget, it has a non-standard callback member function, and it has no user_data member function.  Nothing here tells how to get the chosen filename.
Reply ]

From greg.ercolano, 21:19 Aug 04, 2005 (score=3)

> Nothing here tells how to get the chosen filename.

It's terse, I'll admit, but this doc is a reference for the class, not a tutorial. Possibly this is a fault with the docs, but the standard procedure in fltk for learning how to use a core widget is to look at the fltk/test directory for examples. Seems clear to me from the above docs that value() gets the chosen filename. eg:

    const char *value()
    Sets or gets the current value of the selected file.

Reply ]


Comments are owned by the poster. All other content is copyright 1998-2023 by Bill Spitzak and others. This project is hosted by The FLTK Team. Please report site problems to ''.