FLTK 1.4.4: Fl_File_Chooser Class Reference

FLTK 1.4.4

Loading...
Searching...
No Matches
Fl_File_Chooser Class Reference
Common Dialog Classes and Functions

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

## Public Types
enum | Type { SINGLE = 0 , MULTI = 1 , CREATE = 2 , DIRECTORY = 4 }
| Determines the type of file chooser presented to the user. More...

## Public Member Functions
Fl_Widget * | add_extra (Fl_Widget *gr)
| Adds an extra widget at the bottom of the Fl_File_Chooser window.
void | callback (void(*cb)(Fl_File_Chooser *, void *), void *d=0)
| Sets the file chooser callback cb and associated data `d`.
Fl_Color | color ()
| Gets the background color of the Fl_File_Browser list.
void | color (Fl_Color c)
| Sets the background color of the Fl_File_Browser list.
int | count ()
| Returns the number of selected files.
char * | directory ()
| Gets the current directory.
void | directory (const char *d)
| Sets the current directory.
const char * | filter ()
| Gets the current filename filter patterns.
void | filter (const char *p)
| Sets the current filename filter patterns.
int | filter_value ()
| Gets the current filename filter selection.
void | filter_value (int f)
| Sets the current filename filter selection.
| Fl_File_Chooser (const char *pathname, const char *pattern, int type_val, const char *title)
| The constructor creates the Fl_File_Chooser dialog shown.
int | h () const
void | hide ()
| Hides the Fl_File_Chooser window.
uchar | iconsize ()
| Gets the size of the icons in the Fl_File_Browser.
void | iconsize (uchar s)
| Sets the size of the icons in the Fl_File_Browser.
const char * | label ()
| Gets the title bar text for the Fl_File_Chooser.
void | label (const char *l)
| Sets the title bar text for the Fl_File_Chooser.
const char * | ok_label ()
| Gets the label for the "ok" button in the Fl_File_Chooser.
void | ok_label (const char *l)
| Sets the label for the "ok" button in the Fl_File_Chooser.
void | position (int x, int y)
int | preview () const
| Returns the current state of the preview box.
void | preview (int e)
| Enable or disable the preview tile.
void | rescan ()
| Reloads the current directory in the Fl_File_Browser.
void | rescan_keep_filename ()
| Rescan the current directory without clearing the filename, then select the file if it is in the list.
void | resize (int x, int y, int w, int h)
void | show ()
| Shows the Fl_File_Chooser window.
int | shown ()
| Returns non-zero if the file chooser main window show() has been called, but not hide().
void | size (int w, int h)
Fl_Color | textcolor ()
| Gets the current Fl_File_Browser text color.
void | textcolor (Fl_Color c)
| Sets the current Fl_File_Browser text color.
Fl_Font | textfont ()
| Gets the current Fl_File_Browser text font.
void | textfont (Fl_Font f)
| Sets the current Fl_File_Browser text font.
Fl_Fontsize | textsize ()
| Gets the current Fl_File_Browser text size.
void | textsize (Fl_Fontsize s)
| Sets the current Fl_File_Browser text size.
int | type ()
| Gets the current type of Fl_File_Chooser.
void | type (int t)
| Sets the current type of Fl_File_Chooser.
void * | user_data () const
| Gets the file chooser user data.
void | user_data (void *d)
| Sets the file chooser user data `d`.
void | value (const char *filename)
| Sets the current value of the selected file.
const char * | value (int f=1)
| Gets the current value of the selected file(s).
int | visible ()
| Returns 1 if the Fl_File_Chooser window is visible.
int | w () const
int | x () const
int | y () const
| ~Fl_File_Chooser ()
| Destroys the widget and frees all memory used by it.

## Public Attributes
Fl_Button * | newButton
| The "new directory" button is exported so that application developers can control the appearance and use.
Fl_Check_Button * | previewButton
| The "preview" button is exported so that application developers can control the appearance and use.
Fl_Check_Button * | showHiddenButton
| When checked, hidden files (i.e., filename begins with dot) are displayed.

## Static Public Attributes
static const char * | add_favorites_label = "Add to Favorites"
| [standard text may be customized at run-time]
static const char * | all_files_label = "All Files (*)"
| [standard text may be customized at run-time]
static const char * | custom_filter_label = "Custom Filter"
| [standard text may be customized at run-time]
static const char * | existing_file_label = "Please choose an existing file!"
| [standard text may be customized at run-time]
static const char * | favorites_label = "Favorites"
| [standard text may be customized at run-time]
static const char * | filename_label = "Filename:"
| [standard text may be customized at run-time]
static const char * | filesystems_label = Fl::system_driver()->filesystems_label()
| [standard text may be customized at run-time]
static const char * | hidden_label = "Show hidden files"
| [standard text may be customized at run-time]
static const char * | manage_favorites_label = "Manage Favorites"
| [standard text may be customized at run-time]
static const char * | new_directory_label = "New Directory?"
| [standard text may be customized at run-time]
static const char * | new_directory_tooltip = "Create a new directory."
| [standard text may be customized at run-time]
static const char * | preview_label = "Preview"
| [standard text may be customized at run-time]
static const char * | save_label = "Save"
| [standard text may be customized at run-time]
static const char * | show_label = "Show:"
| [standard text may be customized at run-time]
static Fl_File_Sort_F * | sort = fl_numericsort
| the sort function that is used when loading the contents of a directory.

## Protected Member Functions
void | show_error_box (int val)
| Show error box if val=1, hide if val=0.

## Related Symbols
(Note that these are not member symbols.)
char * | fl_dir_chooser (const char *message, const char *fname, int relative)
| Shows a file chooser dialog and gets a directory.
char * | fl_file_chooser (const char *message, const char *pat, const char *fname, int relative)
| Shows a file chooser dialog and gets a filename.
void | fl_file_chooser_callback (void(*cb)(const char *))
| Set the file chooser callback.
void | fl_file_chooser_ok_label (const char *l)
| Set the "OK" button label.

## Detailed Description

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

Features include:

- Multiple filter patterns can be specified, with parenthesis around filters, and tabs to separate each pattern, e.g.:
  char pattern[] = "Image Files (*.{bmp,gif,jpg,png,xbm,xpm})\t"
  "Web Files (*.{htm,html,php})\t"
  "All Files (*)";
- If no "*" pattern is provided, then an entry for "All Files (*)" is automatically added.
- An optional file preview box is provided which can be toggled by programmer or user showing images, or the first 2048 bytes of printable text.
- Preview image loading functions can be registered to provide custom file previews.
- The favorites button shows up to 100 user-saved favorite directories, the user's home directory, and a filesystems item.
- A simple dialog is provided for managing saved directories.
- Shortcut keys are provided:

  Shortcut | Description
  --- | ---
  Alt+a | Adds a directory to the favorites list
  Alt+m | Manages the favorites list
  Alt+f | Shows the filesystem list
  Alt+h | Go to the home directory
  Alt+0..9 | going to any of the first 10 favorites

The Fl_File_Chooser widget transmits UTF-8 encoded filenames to its user. It is recommended to open files that may have non-ASCII names with the fl_fopen() or fl_open() utility functions that handle these names in a cross-platform way (whereas the standard fopen()/open() functions fail on the Windows platform to open files with a non-ASCII name).

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" (Windows) "File Systems" (all others)
hidden_label | "Show hidden files:"
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 Fl_File_Chooser::sort member specifies the sort function that is used when loading the contents of a directory and can be customized at run-time.

The Fl_File_Chooser class also exports the Fl_File_Chooser::newButton and Fl_File_Chooser::previewButton widgets so that application developers can control their appearance and use.

## Member Enumeration Documentation

## ◆ Type

enum Fl_File_Chooser::Type

Determines the type of file chooser presented to the user.

Enumerator
SINGLE | Select a single, existing file.
MULTI | Select one or more existing files.
CREATE | When used alone, select a single, existing file or specify a new filename. Can be combined with DIRECTORY (e.g. CREATE|DIRECTORY) to have the same effect for directories.
DIRECTORY | Select a single, existing directory. Can be combined with CREATE.

## Constructor & Destructor Documentation

## ◆ Fl_File_Chooser()

Fl_File_Chooser::Fl_File_Chooser | ( | const char * | pathname,
|  | const char * | pattern,
|  | int | type_val,
|  | const char * | title )

The constructor creates the Fl_File_Chooser dialog shown.

- 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_val` argument can be one of the Fl_File_Chooser::Type values.
- The `title` argument is used to set the title bar text for the Fl_File_Chooser window.

## Member Function Documentation

## ◆ add_extra()

Fl_Widget * Fl_File_Chooser::add_extra | ( | Fl_Widget * | extra | ) |

Adds an extra widget at the bottom of the Fl_File_Chooser window.

You can use any Fl_Widget or Fl_Group. If you use an Fl_Group, set its (x, y) coordinates to (0, 0) and position its children relative to (0, 0) inside the Fl_Group container widget. Make sure that all child widgets of the Fl_Group are entirely included inside the bounding box of their parents, i.e. the Fl_Group widget, and the Fl_File_Chooser window, respectively.

Note
  The width of the Fl_File_Chooser window is an undocumented implementation detail and may change in the future.

If `extra` is NULL any previous extra widget is removed.

Parameters

  [in] | extra | Custom widget or group to be added to the Fl_File_Chooser window.

Returns
  Pointer to previous extra widget or NULL if not set previously.

Note
  Fl_File_Chooser does not delete the extra widget in its destructor! The extra widget is removed from the Fl_File_Chooser window before the Fl_File_Chooser widget gets destroyed. To prevent memory leakage, don't forget to delete unused extra widgets.

## ◆ filter()

void Fl_File_Chooser::filter | ( | const char * | p | ) |

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

## ◆ iconsize() [1/2]

uchar Fl_File_Chooser::iconsize | ( |  | ) |

Gets the size of the icons in the Fl_File_Browser.

By default the icon size is set to 1.5 times the textsize().

## ◆ iconsize() [2/2]

void Fl_File_Chooser::iconsize | ( | uchar | s | ) |

Sets the size of the icons in the Fl_File_Browser.

By default the icon size is set to 1.5 times the textsize().

## ◆ preview()

void Fl_File_Chooser::preview | ( | int | e | ) |

Enable or disable the preview tile.

1 = enable preview, 0 = disable preview.

## ◆ shown()

int Fl_File_Chooser::shown | ( |  | ) |

Returns non-zero if the file chooser main window show() has been called, but not hide().

See also
  Fl_Window::shown()

## ◆ value() [1/2]

void Fl_File_Chooser::value | ( | const char * | filename | ) |

Sets the current value of the selected file.

If a relative path is provided in `filename` it is converted to an absolute path.

If `NULL` or an empty string is provided, the working directory is changed to the user's current directory and the filename is set to "".

After assigning the filename the entire string (if any) is selected, i.e.

- insert_position() is 0 (zero)
- mark() is strlen(<expanded filename>).

Note
  The selection of the entire string may not always be desired but it is kept for backwards compatibility.

Parameters

  [in] | filename | relative or absolute filename, may be NULL or ""

## ◆ value() [2/2]

const char * Fl_File_Chooser::value | ( | int | f = 1 | ) |

Gets the current value of the selected file(s).

`f` 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);
...
}

## Member Data Documentation

## ◆ showHiddenButton

Fl_Check_Button* Fl_File_Chooser::showHiddenButton

When checked, hidden files (i.e., filename begins with dot) are displayed.

The "showHiddenButton" button is exported so that application developers can control its appearance.

The documentation for this class was generated from the following files:

- Fl_File_Chooser.H
- Fl_File_Chooser.cxx
- Fl_File_Chooser2.cxx
- fl_file_dir.cxx