Fl_File_Chooser

## class Fl_File_Chooser

### Class Hierarchy

    Fl_File_Chooser

### Include Files

    #include <FL/Fl_File_Chooser.H>

### Description

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

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.

### Methods

- Fl_File_Chooser
- ~Fl_File_Chooser
- color
- count
- directory
- filter
- filter_value
- hide
- iconsize
- label
- ok_label
- preview
- rescan
- show
- textcolor
- textfont
- textsize
- type
- value
- visible

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

#### ~Fl_File_Chooser()

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.