This class lets an FLTK application easily and consistently access the operating system's native file chooser. More...
#include <Fl_Native_File_Chooser.H>
Public Types | |
enum | Option { NO_OPTIONS = 0x0000, SAVEAS_CONFIRM = 0x0001, NEW_FOLDER = 0x0002, PREVIEW = 0x0004, USE_FILTER_EXT = 0x0008 } |
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. | |
const char * | directory () const |
Returns the current preset directory() value. | |
void | directory (const char *val) |
Preset the directory the browser will show when opened. | |
const char * | errmsg () const |
Returns a system dependent error message for the last method that failed. | |
const char * | filename (int i) const |
Return one of the filenames the user selected. | |
const char * | filename () const |
Return the filename the user chose. | |
void | filter (const char *f) |
Sets the filename filters used for browsing. | |
const char * | filter () const |
Returns the filter string last set. | |
int | filter_value () const |
Returns which filter value was last selected by the user. | |
void | filter_value (int i) |
Sets which filter will be initially selected. | |
int | filters () const |
Gets how many filters were available, not including "All Files". | |
Fl_Native_File_Chooser (int val=BROWSE_FILE) | |
The constructor. | |
int | options () const |
Gets the platform specific Fl_Native_File_Chooser::Option flags. | |
void | options (int o) |
Sets the platform specific chooser options to val . | |
const char * | preset_file () const |
Get the preset filename. | |
void | preset_file (const char *f) |
Sets the default filename for the chooser. | |
int | show () |
Post the chooser's dialog. | |
const char * | title () const |
Get the title of the file chooser's dialog window. | |
void | title (const char *t) |
Set the title of the file chooser's dialog window. | |
int | type () const |
Gets the current Fl_Native_File_Chooser::Type of browser. | |
void | type (int t) |
Sets 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. |
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:
#include <FL/Fl_Native_File_Chooser.H>
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 }
The Fl_Native_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).
Platform Specific Caveats
The Fl_Native_File_Chooser on different platforms.
Fl_Native_File_Chooser::Fl_Native_File_Chooser | ( | int | val = BROWSE_FILE |
) |
The constructor.
Internally allocates the native widgets. Optional val
presets the type of browser this will be, which can also be changed with type().
Fl_Native_File_Chooser::~Fl_Native_File_Chooser | ( | ) |
Destructor.
Deallocates any resources allocated to this widget.
int Fl_Native_File_Chooser::count | ( | ) | const |
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 | ( | int | i | ) | const |
const char * Fl_Native_File_Chooser::filename | ( | ) | const |
Return the filename the user chose.
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).
void Fl_Native_File_Chooser::filter | ( | const char * | f | ) |
Sets the filename filters used for browsing.
The default is NULL, which browses all files.
The filter string can be any of:
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.
const char * Fl_Native_File_Chooser::filter | ( | ) | const |
Returns the filter string last set.
Can be NULL if no filter was set.
int Fl_Native_File_Chooser::filter_value | ( | ) | const |
Returns which filter value was last selected by the user.
This is only valid if the chooser returns success.
void Fl_Native_File_Chooser::filter_value | ( | int | i | ) |
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.
void Fl_Native_File_Chooser::options | ( | int | o | ) |
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 USE_FILTER_EXT Chooser filter pilots the output file extension. Ignored Used Used (GTK)
void Fl_Native_File_Chooser::preset_file | ( | const char * | f | ) |
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.
int Fl_Native_File_Chooser::show | ( | ) |
Post the chooser's dialog.
Blocks until dialog has been completed or cancelled.
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.
void Fl_Native_File_Chooser::title | ( | const char * | t | ) |
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.