FLTK 1.3.0
Fl_Native_File_Chooser Class Reference

This class lets an FLTK application easily and consistently access the operating system's native file chooser. More...

#include <Fl_Native_File_Chooser.H>

List of all members.

Public Types

enum  Option { NO_OPTIONS = 0x0000, SAVEAS_CONFIRM = 0x0001, NEW_FOLDER = 0x0002, PREVIEW = 0x0004 }
enum  Type {
  BROWSE_FILE = 0, BROWSE_DIRECTORY, BROWSE_MULTI_FILE, BROWSE_MULTI_DIRECTORY,
  BROWSE_SAVE_FILE, BROWSE_SAVE_DIRECTORY
}

Public Member Functions

int count () const
 Returns the number of filenames (or directory names) the user selected.
void directory (const char *val)
 Preset the directory the browser will show when opened.
const char * directory () const
 Returns the current preset directory() value.
const char * errmsg () const
 Returns a system dependent error message for the last method that failed.
const char * filename () const
 Return the filename the user choose.
const char * filename (int i) const
 Return one of the filenames the user selected.
const char * filter () const
 Returns the filter string last set.
void filter (const char *)
 Sets the filename filters used for browsing.
void filter_value (int i)
 Sets which filter will be initially selected.
int filter_value () const
 Returns which filter value was last selected by the user.
int filters () const
 Gets how many filters were available, not including "All Files".
 Fl_Native_File_Chooser (int val=BROWSE_FILE)
 The constructor.
void options (int)
 Sets the platform specific chooser options to val.
int options () const
 Gets the platform specific Fl_Native_File_Chooser::Option flags.
void preset_file (const char *)
 Sets the default filename for the chooser.
const char * preset_file () const
 Get the preset filename.
int show ()
 Post the chooser's dialog.
void title (const char *)
 Set the title of the file chooser's dialog window.
const char * title () const
 Get the title of the file chooser's dialog window.
void type (int)
 Sets the current Fl_Native_File_Chooser::Type of browser.
int type () const
 Gets the current Fl_Native_File_Chooser::Type of browser.
 ~Fl_Native_File_Chooser ()
 Destructor.

Static Public Attributes

static const char * file_exists_message = "File exists. Are you sure you want to overwrite?"
 Localizable message.

Detailed Description

This class lets an FLTK application easily and consistently access the operating system's native file chooser.

Some operating systems have very complex and specific file choosers that many users want access to specifically, instead of FLTK's default file chooser(s).

In cases where there is no native file browser, FLTK's own file browser is used instead.

To use this widget, use the following include in your code:

The following example shows how to pick a single file:

 // Create and post the local native file chooser
 #include <FL/Fl_Native_File_Chooser.H>
 [..]
 Fl_Native_File_Chooser fnfc;
 fnfc.title("Pick a file");
 fnfc.type(Fl_Native_File_Chooser::BROWSE_FILE);
 fnfc.filter("Text\t*.txt\n"
             "C Files\t*.{cxx,h,c}");
 fnfc.directory("/var/tmp");           // default directory to use
 // Show native chooser
 switch ( fnfc.show() ) {
   case -1: printf("ERROR: %s\n", fnfc.errmsg());    break;  // ERROR
   case  1: printf("CANCEL\n");                      break;  // CANCEL
   default: printf("PICKED: %s\n", fnfc.filename()); break;  // FILE CHOSEN
 }

Platform Specific Caveats

Fl_Native_File_Chooser.png
The Fl_Native_File_Chooser on different platforms.

Member Enumeration Documentation

Enumerator:
NO_OPTIONS 

no options enabled

SAVEAS_CONFIRM 

Show native 'Save As' overwrite confirm dialog (if supported)

NEW_FOLDER 

Show 'New Folder' icon (if supported)

PREVIEW 

enable preview mode

Enumerator:
BROWSE_FILE 

browse files (lets user choose one file)

BROWSE_DIRECTORY 

browse directories (lets user choose one directory)

BROWSE_MULTI_FILE 

browse files (lets user choose multiple files)

BROWSE_MULTI_DIRECTORY 

browse directories (lets user choose multiple directories)

BROWSE_SAVE_FILE 

browse to save a file

BROWSE_SAVE_DIRECTORY 

browse to save a directory


Constructor & Destructor Documentation

The constructor.

Internally allocates the native widgets. Optional val presets the type of browser this will be, which can also be changed with type().

Destructor.

Deallocates any resources allocated to this widget.


Member Function Documentation

Returns the number of filenames (or directory names) the user selected.

Example:

  if ( fnfc->show() == 0 ) {
    // Print all filenames user selected
    for (int n=0; n<fnfc->count(); n++ ) {
      printf("%d) '%s'\n", n, fnfc->filename(n));
    }
  }
void Fl_Native_File_Chooser::directory ( const char *  val)

Preset the directory the browser will show when opened.

If val is NULL, or no directory is specified, the chooser will attempt to use the last non-cancelled folder.

const char * Fl_Native_File_Chooser::errmsg ( ) const

Returns a system dependent error message for the last method that failed.

This message should at least be flagged to the user in a dialog box, or to some kind of error log. Contents will be valid only for methods that document errmsg() will have info on failures.

const char * Fl_Native_File_Chooser::filename ( ) const

Return the filename the user choose.

Use this if only expecting a single filename. If more than one filename is expected, use filename(int) instead. Return value may be "" if no filename was chosen (eg. user cancelled).

const char * Fl_Native_File_Chooser::filename ( int  i) const

Return one of the filenames the user selected.

Use count() to determine how many filenames the user selected.

Example:

  if ( fnfc->show() == 0 ) {
    // Print all filenames user selected
    for (int n=0; n<fnfc->count(); n++ ) {
      printf("%d) '%s'\n", n, fnfc->filename(n));
    }
  }
const char * Fl_Native_File_Chooser::filter ( ) const

Returns the filter string last set.

Can be NULL if no filter was set.

void Fl_Native_File_Chooser::filter ( const char *  val)

Sets the filename filters used for browsing.

The default is NULL, which browses all files.

The filter string can be any of:

  • A single wildcard (eg. "*.txt")
  • Multiple wildcards (eg. "*.{cxx,h,H}")
  • A descriptive name followed by a "\t" and a wildcard (eg. "Text Files\t*.txt")
  • A list of separate wildcards with a "\n" between each (eg. "*.{cxx,H}\n*.txt")
  • A list of descriptive names and wildcards (eg. "C++ Files\t*.{cxx,H}\nTxt Files\t*.txt")

The format of each filter is a wildcard, or an optional user description followed by '\t' and the wildcard.

On most platforms, each filter is available to the user via a pulldown menu in the file chooser. The 'All Files' option is always available to the user.

Sets which filter will be initially selected.

The first filter is indexed as 0. If filter_value()==filters(), then "All Files" was chosen. If filter_value() > filters(), then a custom filter was set.

Returns which filter value was last selected by the user.

This is only valid if the chooser returns success.

Sets the platform specific chooser options to val.

val is expected to be one or more Fl_Native_File_Chooser::Option flags ORed together. Some platforms have OS-specific functions that can be enabled/disabled via this method.

  Flag              Description                                       Win       Mac       Other
  --------------    -----------------------------------------------   -------   -------   -------
  NEW_FOLDER        Shows the 'New Folder' button.                    Ignored   Used      Used
  PREVIEW           Enables the 'Preview' mode by default.            Ignored   Ignored   Used
  SAVEAS_CONFIRM    Confirm dialog if BROWSE_SAVE_FILE file exists.   Used      Used      Used
void Fl_Native_File_Chooser::preset_file ( const char *  val)

Sets the default filename for the chooser.

Use directory() to set the default directory. Mainly used to preset the filename for save dialogs, and on most platforms can be used for opening files as well.

Post the chooser's dialog.

Blocks until dialog has been completed or cancelled.

Returns:
  • 0 -- user picked a file
  • 1 -- user cancelled
  • -1 -- failed; errmsg() has reason
void Fl_Native_File_Chooser::title ( const char *  val)

Set the title of the file chooser's dialog window.

Can be NULL if no title desired. The default title varies according to the platform, so you are advised to set the title explicitly.

const char * Fl_Native_File_Chooser::title ( ) const

Get the title of the file chooser's dialog window.

Return value may be NULL if no title was set.


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