FLTK 1.3.4
Fl_File_Chooser Class Reference

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

Public Types

enum  { SINGLE = 0, MULTI = 1, CREATE = 2, DIRECTORY = 4 }
 

Public Member Functions

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

Public Attributes

Fl_ButtonnewButton
 The "new directory" button is exported so that application developers can control the appearance and use.
 
Fl_Check_ButtonpreviewButton
 The "preview" button is exported so that application developers can control the appearance and use.
 
Fl_Check_ButtonshowHiddenButton
 When checked, hidden files (i.e., filename begins with dot) are displayed. More...
 

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 = "File Systems"
 [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_Fsort = fl_numericsort
 the sort function that is used when loading the contents of a directory.
 

Related Functions

(Note that these are not member functions.)

char * fl_dir_chooser (const char *message, const char *fname, int relative)
 Shows a file chooser dialog and gets a directory. More...
 
char * fl_file_chooser (const char *message, const char *pat, const char *fname, int relative)
 Shows a file chooser dialog and gets a filename. More...
 
void fl_file_chooser_callback (void(*cb)(const char *))
 Set the file chooser callback. More...
 
void fl_file_chooser_ok_label (const char *l)
 Set the "OK" button label. More...
 

Detailed Description

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

Fl_File_Chooser.jpg

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 MSWindows 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" (WIN32)
"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. For more complex customization, consider copying the FLTK file chooser code and changing it accordingly.

Constructor & Destructor Documentation

Fl_File_Chooser::Fl_File_Chooser ( const char *  pathname,
const char *  pattern,
int  type,
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 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::~Fl_File_Chooser ( )

Destroys the widget and frees all memory used by it.

Member Function Documentation

Fl_Widget * Fl_File_Chooser::add_extra ( Fl_Widget gr)

Adds extra widget at the bottom of Fl_File_Chooser window.

Returns pointer for previous extra widget or NULL if not set previously. If argument is NULL only remove previous extra widget.

Note
Fl_File_Chooser does not delete extra widget in destructor! To prevent memory leakage, don't forget to delete unused extra widgets
void Fl_File_Chooser::color ( Fl_Color  c)

Sets the background color of the Fl_File_Browser list.

Fl_Color Fl_File_Chooser::color ( )

Gets the background color of the Fl_File_Browser list.

int Fl_File_Chooser::count ( )

Returns the number of selected files.

void Fl_File_Chooser::directory ( const char *  pathname)

Sets the current directory.

const char * Fl_File_Chooser::directory ( )

Gets the current directory.

void Fl_File_Chooser::filter ( const char *  pattern)

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.

int Fl_File_Chooser::filter_value ( )

Gets the current filename filter selection.

void Fl_File_Chooser::filter_value ( int  f)

Sets the current filename filter selection.

void Fl_File_Chooser::hide ( )

Hides the Fl_File_Chooser window.

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().

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().

void Fl_File_Chooser::label ( const char *  l)

Sets the title bar text for the Fl_File_Chooser.

const char * Fl_File_Chooser::label ( )

Gets the title bar text for the Fl_File_Chooser.

void Fl_File_Chooser::preview ( int  e)

Enable or disable the preview tile.

1 = enable preview, 0 = disable preview.

int Fl_File_Chooser::preview ( ) const
inline

Returns the current state of the preview box.

void Fl_File_Chooser::rescan ( )

Reloads the current directory in the Fl_File_Browser.

void Fl_File_Chooser::show ( )

Shows the Fl_File_Chooser window.

void Fl_File_Chooser::textcolor ( Fl_Color  c)

Sets the current Fl_File_Browser text color.

Fl_Color Fl_File_Chooser::textcolor ( )

Gets the current Fl_File_Browser text color.

void Fl_File_Chooser::textfont ( Fl_Font  f)

Sets the current Fl_File_Browser text font.

Fl_Font Fl_File_Chooser::textfont ( )

Gets the current Fl_File_Browser text font.

void Fl_File_Chooser::textsize ( Fl_Fontsize  s)

Sets the current Fl_File_Browser text size.

Fl_Fontsize Fl_File_Chooser::textsize ( )

Gets the current Fl_File_Browser text size.

void Fl_File_Chooser::type ( int  t)

Sets the current type of Fl_File_Chooser.

int Fl_File_Chooser::type ( )

Gets the current type of Fl_File_Chooser.

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);
...
}
int Fl_File_Chooser::visible ( )

Returns 1 if the Fl_File_Chooser window is visible.

Member Data Documentation

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: