mirror of https://github.com/fltk/fltk
285 lines
11 KiB
C++
285 lines
11 KiB
C++
//
|
|
// FLTK native OS file chooser widget
|
|
//
|
|
// Copyright 2004 Greg Ercolano.
|
|
// Copyright 2005-2024 by Bill Spitzak and others.
|
|
//
|
|
// This library is free software. Distribution and use rights are outlined in
|
|
// the file "COPYING" which should have been included with this file. If this
|
|
// file is missing or damaged, see the license at:
|
|
//
|
|
// https://www.fltk.org/COPYING.php
|
|
//
|
|
// Please see the following page on how to report bugs and issues:
|
|
//
|
|
// https://www.fltk.org/bugs.php
|
|
//
|
|
|
|
/** \file
|
|
Fl_Native_File_Chooser widget. */
|
|
|
|
/* Implementation note:
|
|
|
|
class Fl_Native_File_Chooser <== public API used by applications
|
|
|
|
class Fl_Native_File_Chooser_Driver <== virtual API that a platform may implement
|
|
this API has a do-nothing default implementation
|
|
|
|
class Fl_Native_File_Chooser_FLTK_Driver <== this API implementation is the default FLTK file chooser
|
|
class Fl_GTK_Native_File_Chooser_Driver <== this API implementation runs a GTK file chooser
|
|
class Fl_Kdialog_Native_File_Chooser_Driver <== this API implementation runs a KDE file chooser
|
|
it is determined at run-time if the GTK dynamic libraries are available
|
|
and the KDE file chooser runs under the KDE desktop
|
|
|
|
class Fl_Quartz_Native_File_Chooser_Driver <== this API implementation runs a Mac OS X file chooser
|
|
|
|
class Fl_WinAPI_Native_File_Chooser_Driver <== this API implementation runs a Windows file chooser
|
|
|
|
|
|
Each platform must implement the constructor of the Fl_Native_File_Chooser class.
|
|
This particular implementation:
|
|
|
|
Fl_Native_File_Chooser::Fl_Native_File_Chooser(int val) {
|
|
platform_fnfc = new Fl_Native_File_Chooser_FLTK_Driver(val);
|
|
}
|
|
|
|
can be used by any platform.
|
|
No more code is required. The cross-platform Fl_Native_File_Chooser_FLTK.cxx file must be compiled in libfltk,
|
|
and the default FLTK file chooser will be used.
|
|
|
|
This other implementation:
|
|
Fl_Native_File_Chooser::Fl_Native_File_Chooser(int val) {
|
|
platform_fnfc = 0;
|
|
}
|
|
can be used by a platform that needs no file chooser.
|
|
*/
|
|
|
|
#ifndef FL_NATIVE_FILE_CHOOSER_H
|
|
#define FL_NATIVE_FILE_CHOOSER_H
|
|
|
|
#include <FL/Fl_Export.H>
|
|
#include <FL/Fl_File_Chooser.H>
|
|
|
|
class Fl_Native_File_Chooser_Driver;
|
|
|
|
/**
|
|
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:
|
|
\code
|
|
#include <FL/Fl_Native_File_Chooser.H>
|
|
\endcode
|
|
|
|
The following example shows how to pick a single file:
|
|
\code
|
|
// 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
|
|
}
|
|
\endcode
|
|
|
|
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).
|
|
|
|
<B>Platform Specific Caveats</B>
|
|
|
|
- Under X11/Wayland the dialog is chosen as follows:
|
|
-# If command \p zenity is available at run-time and if \p Fl::option(OPTION_FNFC_USES_ZENITY) is
|
|
not turned off, the \p zenity -based dialog opens. This is expected to be more appropriate
|
|
than other dialog forms for sandboxed apps.
|
|
-# Else if the app runs under the KDE desktop and if command \p kdialog is available at run-time
|
|
and if the library was not built with <tt>cmake -D FLTK_USE_KDIALOG=OFF</tt>, the
|
|
\p kdialog -based dialog opens.
|
|
-# Else if the GTK library is available at run-time on the computer and if \p 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.
|
|
-# 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.
|
|
|
|
\todo Improve documentation about selection of native file choosers on X11/Wayland.\n
|
|
|
|
- Some operating systems support certain OS specific options; see
|
|
Fl_Native_File_Chooser::options() for a list.
|
|
|
|
\image html Fl_Native_File_Chooser.png "The Fl_Native_File_Chooser on different platforms."
|
|
\image latex Fl_Native_File_Chooser.png "The Fl_Native_File_Chooser on different platforms" width=14cm
|
|
|
|
*/
|
|
class FL_EXPORT Fl_Native_File_Chooser {
|
|
private:
|
|
Fl_Native_File_Chooser_Driver *platform_fnfc;
|
|
public:
|
|
enum Type {
|
|
BROWSE_FILE = 0, ///< 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
|
|
};
|
|
enum Option {
|
|
NO_OPTIONS = 0x0000, ///< no options enabled
|
|
SAVEAS_CONFIRM = 0x0001, ///< Show native 'Save As' overwrite confirm dialog
|
|
NEW_FOLDER = 0x0002, ///< Show 'New Folder' icon (if supported)
|
|
PREVIEW = 0x0004, ///< enable preview mode (if supported)
|
|
USE_FILTER_EXT = 0x0008 ///< Chooser filter presets the output file extension (if supported)
|
|
};
|
|
static const char *file_exists_message;
|
|
|
|
/**
|
|
The constructor. Internally allocates the native widgets.
|
|
Optional \p val presets the type of browser this will be,
|
|
which can also be changed with type().
|
|
*/
|
|
Fl_Native_File_Chooser(int val = BROWSE_FILE); // each platorm implements it
|
|
~Fl_Native_File_Chooser();
|
|
void type(int t);
|
|
int type() const ;
|
|
void options(int o);
|
|
int options() const;
|
|
int count() const;
|
|
const char *filename() const ;
|
|
const char *filename(int i) const ;
|
|
void directory(const char *val) ;
|
|
const char *directory() const;
|
|
void title(const char *t);
|
|
const char* title() const;
|
|
const char *filter() const ;
|
|
void filter(const char *f);
|
|
int filters() const ;
|
|
void filter_value(int i) ;
|
|
int filter_value() const ;
|
|
void preset_file(const char*f) ;
|
|
const char* preset_file() const;
|
|
const char *errmsg() const ;
|
|
int show() ;
|
|
};
|
|
|
|
/**
|
|
\cond DriverDev
|
|
\addtogroup DriverDeveloper
|
|
\{
|
|
*/
|
|
|
|
/** Represents the interface between FLTK and a native file chooser.
|
|
This class is only for internal use by the FLTK library.
|
|
A platform that wants to provide a native file chooser implements all virtual methods
|
|
of this class. Each platform supported by FLTK must also implement the constructor of the
|
|
Fl_Native_File_Chooser class.
|
|
*/
|
|
class Fl_Native_File_Chooser_Driver {
|
|
protected:
|
|
static void chrcat(char *s, char c);
|
|
static char *strapp(char *s, const char *val);
|
|
static char *strfree(char *val);
|
|
static char *strnew(const char *val);
|
|
public:
|
|
Fl_Native_File_Chooser_Driver(int) {}
|
|
virtual ~Fl_Native_File_Chooser_Driver() {}
|
|
virtual void type(int) {}
|
|
virtual int type() const {return 0;}
|
|
virtual void options(int) {}
|
|
virtual int options() const {return 0;}
|
|
virtual int count() const {return 0;}
|
|
virtual const char *filename() const {return 0;}
|
|
virtual const char *filename(int) const {return 0;}
|
|
virtual void directory(const char *) {}
|
|
virtual const char *directory() const {return 0;}
|
|
virtual void title(const char *) {}
|
|
virtual const char* title() const {return 0;}
|
|
virtual const char *filter() const {return 0;}
|
|
virtual void filter(const char *) {}
|
|
virtual int filters() const {return 0;}
|
|
virtual void filter_value(int) {}
|
|
virtual int filter_value() const {return 0;}
|
|
virtual void preset_file(const char*) {}
|
|
virtual const char* preset_file() const {return 0;}
|
|
virtual const char *errmsg() const {return 0;}
|
|
virtual int show() {return 1;}
|
|
};
|
|
|
|
/** A cross-platform implementation of Fl_Native_File_Chooser_Driver.
|
|
This implementation uses a Fl_File_Chooser object as file chooser.
|
|
|
|
Any platform can support the Fl_Native_File_Chooser class by implementing
|
|
its constructor as follows:
|
|
\code
|
|
Fl_Native_File_Chooser::Fl_Native_File_Chooser(int type) {
|
|
platform_fnfc = new Fl_Native_File_Chooser_FLTK_Driver(type);
|
|
}
|
|
\endcode
|
|
*/
|
|
class Fl_Native_File_Chooser_FLTK_Driver : public Fl_Native_File_Chooser_Driver {
|
|
private:
|
|
void errmsg(const char *msg);
|
|
int type_fl_file(int val);
|
|
int exist_dialog();
|
|
void parse_filter();
|
|
protected:
|
|
int _btype; // kind-of browser to show()
|
|
int _options; // general options
|
|
int _nfilters;
|
|
char *_filter; // user supplied filter
|
|
char *_parsedfilt; // parsed filter
|
|
int _filtvalue; // selected filter
|
|
char *_preset_file;
|
|
char *_prevvalue; // Returned filename
|
|
char *_directory;
|
|
char *_errmsg; // error message
|
|
Fl_File_Chooser *_file_chooser;
|
|
public:
|
|
Fl_Native_File_Chooser_FLTK_Driver(int val);
|
|
virtual ~Fl_Native_File_Chooser_FLTK_Driver();
|
|
void type(int t) FL_OVERRIDE;
|
|
int type() const FL_OVERRIDE;
|
|
void options(int o) FL_OVERRIDE;
|
|
int options() const FL_OVERRIDE;
|
|
int count() const FL_OVERRIDE;
|
|
const char *filename() const FL_OVERRIDE;
|
|
const char *filename(int i) const FL_OVERRIDE;
|
|
void directory(const char *val) FL_OVERRIDE;
|
|
const char *directory() const FL_OVERRIDE;
|
|
void title(const char *t) FL_OVERRIDE;
|
|
const char* title() const FL_OVERRIDE;
|
|
const char *filter() const FL_OVERRIDE;
|
|
void filter(const char *f) FL_OVERRIDE;
|
|
int filters() const FL_OVERRIDE;
|
|
void filter_value(int i) FL_OVERRIDE;
|
|
int filter_value() const FL_OVERRIDE;
|
|
void preset_file(const char*f) FL_OVERRIDE;
|
|
const char* preset_file() const FL_OVERRIDE;
|
|
const char *errmsg() const FL_OVERRIDE;
|
|
int show() FL_OVERRIDE;
|
|
};
|
|
|
|
/**
|
|
\}
|
|
\endcond
|
|
*/
|
|
|
|
|
|
#endif /*FL_NATIVE_FILE_CHOOSER_H*/
|