FLTK 1.4.4: Fl_Native_File_Chooser Class Reference

FLTK 1.4.4

Loading...
Searching...
No Matches
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>`

## 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 () const
| Return the filename the user chose.
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 *f)
| Sets the filename filters used for browsing.
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.

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

#include <FL/Fl_Native_File_Chooser.H>
Fl_Native_File_Chooser.H
Fl_Native_File_Chooser widget.

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
}
Fl_Native_File_Chooser::filter
const char * filter() const
Returns the filter string last set.
Definition Fl_Native_File_Chooser.cxx:153
Fl_Native_File_Chooser::title
void title(const char *t)
Set the title of the file chooser's dialog window.
Definition Fl_Native_File_Chooser.cxx:137
Fl_Native_File_Chooser::directory
void directory(const char *val)
Preset the directory the browser will show when opened.
Definition Fl_Native_File_Chooser.cxx:121
Fl_Native_File_Chooser::errmsg
const char * errmsg() const
Returns a system dependent error message for the last method that failed.
Definition Fl_Native_File_Chooser.cxx:254
Fl_Native_File_Chooser::type
void type(int t)
Sets the current Fl_Native_File_Chooser::Type of browser.
Definition Fl_Native_File_Chooser.cxx:35
Fl_Native_File_Chooser::filename
const char * filename() const
Return the filename the user chose.
Definition Fl_Native_File_Chooser.cxx:94
Fl_Native_File_Chooser::Fl_Native_File_Chooser
Fl_Native_File_Chooser(int val=BROWSE_FILE)
The constructor.
Definition Fl_Native_File_Chooser_GTK.cxx:924
Fl_Native_File_Chooser::BROWSE_FILE
@ BROWSE_FILE
browse files (lets user choose one file)
Definition Fl_Native_File_Chooser.H:135
Fl_Native_File_Chooser::show
int show()
Post the chooser's dialog.
Definition Fl_Native_File_Chooser.cxx:265

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 Windows platform to open files with a non-ASCII name).

Platform Specific Caveats

- Under X11/Wayland the dialog is chosen as follows:

1. If command `zenity` is available at run-time and if `Fl::option(OPTION_FNFC_USES_ZENITY)` is turned on, the `zenity` -based dialog opens. This is expected to be more appropriate than other dialog forms for sandboxed apps, but member function filter_value() is not effective.
2. Else if the app runs under the KDE desktop and if `Fl::option(OPTION_FNFC_USES_KDIALOG)` is turned on, and if command `kdialog` is available at run-time, the `kdialog` -based dialog opens. Member function filter_value() is not effective with this dialog.
3. Else if the GTK library is available at run-time on the computer and if `Fl::option(OPTION_FNFC_USES_GTK)` is not turned off, the GTK-styled dialog opens. Call fl_register_images() to add a "Preview" button to this dialog. Use the static public attributes of class Fl_File_Chooser to localize the browser.
4. Otherwise, FLTK's own dialog produced by the Fl_File_Chooser class opens. Call fl_register_images() to add a "Preview" button to it. It's best if you also call Fl_File_Icon::load_system_icons() at the start of main(), to enable the nicer looking file browser widgets. Use the static public attributes of class Fl_File_Chooser to localize the browser.

- Some operating systems support certain OS specific options; see Fl_Native_File_Chooser::options() for a list.

The Fl_Native_File_Chooser on different platforms.

## Member Enumeration Documentation

## ◆ Option

enum Fl_Native_File_Chooser::Option

Enumerator
NO_OPTIONS | no options enabled
SAVEAS_CONFIRM | Show native 'Save As' overwrite confirm dialog.
NEW_FOLDER | Show 'New Folder' icon (if supported).
PREVIEW | enable preview mode (if supported)
USE_FILTER_EXT | Chooser filter presets the output file extension (if supported).

## ◆ Type

enum Fl_Native_File_Chooser::Type

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

## ◆ Fl_Native_File_Chooser()

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::~Fl_Native_File_Chooser | ( |  | ) |

Destructor.

Deallocates any resources allocated to this widget.

## Member Function Documentation

## ◆ count()

int Fl_Native_File_Chooser::count | ( |  | ) | const

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));
}
}

## ◆ directory()

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.

## ◆ errmsg()

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.

## ◆ filename() [1/2]

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

## ◆ filename() [2/2]

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));
}
}

## ◆ filter() [1/2]

const char * Fl_Native_File_Chooser::filter | ( |  | ) | const

Returns the filter string last set.

Can be NULL if no filter was set.

## ◆ filter() [2/2]

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:

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

## ◆ filter_value() [1/2]

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 and if the particular file chooser supports it. Otherwise the value is not changed.

Some "native" file choosers don't support returning the filter selection by the user, particularly the system dialog based browsers:

- kdialog (KDE system dialog)
- zenity (another system dialog based chooser).

Note: this list may not be complete.

These system file chooser dialogs don't return the filter value chosen by the user.

See also
  filter(const char *f)

## ◆ filter_value() [2/2]

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.

Some "native" file choosers don't support this way to set the initial filter type, particularly the system dialog based browsers:

- kdialog (KDE system dialog)
- zenity (another system dialog based chooser).

Note: this list may not be complete.

As far as we know these dialogs use the first item in the list of filter values as the initial filter presented to the user.

See also
  filter(const char *f)

## ◆ options()

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 presets the output file extension. Ignored Used Used (GTK)
Fl_Native_File_Chooser::BROWSE_SAVE_FILE
@ BROWSE_SAVE_FILE
browse to save a file
Definition Fl_Native_File_Chooser.H:139
Fl_Native_File_Chooser::NEW_FOLDER
@ NEW_FOLDER
Show 'New Folder' icon (if supported).
Definition Fl_Native_File_Chooser.H:145
Fl_Native_File_Chooser::PREVIEW
@ PREVIEW
enable preview mode (if supported)
Definition Fl_Native_File_Chooser.H:146
Fl_Native_File_Chooser::USE_FILTER_EXT
@ USE_FILTER_EXT
Chooser filter presets the output file extension (if supported).
Definition Fl_Native_File_Chooser.H:147
Fl_Native_File_Chooser::SAVEAS_CONFIRM
@ SAVEAS_CONFIRM
Show native 'Save As' overwrite confirm dialog.
Definition Fl_Native_File_Chooser.H:144

## ◆ preset_file()

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.

## ◆ show()

int Fl_Native_File_Chooser::show | ( |  | ) |

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

## ◆ title() [1/2]

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.

## ◆ title() [2/2]

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.

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

- Fl_Native_File_Chooser.H
- Fl_Native_File_Chooser.cxx
- Fl_Native_File_Chooser_GTK.cxx