QFileDialog(3qt)QFileDialog(3qt)NAMEQFileDialog - Dialog widget for inputting file names
#include <qfiledialog.h>
Inherits QDialog.
Public Members
QFileDialog ( const QString & dirName, const QString &
filter = QString::null, QWidget * parent=0, const char
* name = 0, bool modal = FALSE )
QFileDialog ( QWidget * parent=0, const char * name = 0,
bool modal = FALSE )
~QFileDialog ()
QString selectedFile () const
QString selectedFilter () const
void setSelection ( const QString & )
void selectAll ( bool b )
QStringList selectedFiles () const
QString dirPath () const
void setDir ( const QDir & )
const QDir* dir () const
void setShowHiddenFiles ( bool s )
bool showHiddenFiles () const
void rereadDir ()
void resortDir ()
enum Mode { AnyFile, ExistingFile, Directory,
ExistingFiles, DirectoryOnly }
void setMode ( Mode )
Mode mode () const
enum ViewMode { Detail, List }
enum PreviewMode { NoPreview, Contents, Info }
void setViewMode ( ViewMode m )
ViewMode viewMode () const
void setPreviewMode ( PreviewMode m )
PreviewMode previewMode () const
bool isInfoPreviewEnabled () const
bool isContentsPreviewEnabled () const
void setInfoPreviewEnabled ( bool )
void setContentsPreviewEnabled ( bool )
void setInfoPreview ( QWidget * w, QFilePreview * preview
)
void setContentsPreview ( QWidget * w, QFilePreview *
preview )
QUrl url () const
Public Slots
void setDir ( const QString & )
void setUrl ( const QUrlOperator & url )
void setFilter ( const QString & )
void setFilters ( const QString & )
void setFilters ( const char ** )
void setFilters ( const QStringList & )
Trolltech AS 13 June 2001 1
QFileDialog(3qt)QFileDialog(3qt)
Signals
void fileHighlighted ( const QString & )
void fileSelected ( const QString & )
void dirEntered ( const QString & )
Static Public Members
QString getOpenFileName ( const QString & initially =
QString::null, const QString & filter = QString::null,
QWidget * parent = 0, const char * name = 0 )
QString getOpenFileName ( const QString & initially, const
QString & filter, QWidget * parent, const char * name,
const QString & caption )
QString getSaveFileName ( const QString & initially =
QString::null, const QString & filter = QString::null,
QWidget * parent = 0, const char * name = 0 )
QString getSaveFileName ( const QString & initially, const
QString & filter, QWidget * parent, const char * name,
const QString & caption )
QString getExistingDirectory ( const QString & dir =
QString::null, QWidget * parent = 0, const char * name
= 0 )
QString getExistingDirectory ( const QString & dir,
QWidget * parent, const char * name, const QString &
caption )
QString getExistingDirectory ( const QString & dir,
QWidget * parent, const char * name, const QString &
caption, bool dirOnly )
QStringList getOpenFileNames ( const QString & filter=
QString::null, const QString & dir = QString::null,
QWidget * parent = 0, const char * name = 0 )
QStringList getOpenFileNames ( const QString & filter,
const QString & dir, QWidget * parent, const char *
name, const QString & caption )
void setIconProvider ( QFileIconProvider * )
QFileIconProvider* iconProvider ()
Protected Members
void addWidgets ( QLabel *, QWidget *, QPushButton * )
void addToolButton ( QButton * b, bool separator = FALSE )
void addLeftWidget ( QWidget * w )
void addRightWidget ( QWidget * w )
void addFilter ( const QString & filter )
Properties
l l l l l
- - - - -
l l l l l.
Type Name READ WRITE Options
QString selectedFile selectedFile
QString selectedFilter selectedFilter
QStringList selectedFiles selectedFiles
QString dirPath dirPath
bool showHiddenFiles showHiddenFiles setShowHiddenFiles
Mode mode mode setMode
Trolltech AS 13 June 2001 2
QFileDialog(3qt)QFileDialog(3qt)
ViewMode viewMode viewMode setViewMode
PreviewMode previewMode previewMode setPreviewMode
bool infoPreview isInfoPreviewEnabled setInfoPreviewEnabled
bool contentsPreview isContentsPreviewEnabled setContentsPreviewEnabled
DESCRIPTION
The QFileDialog class provides a dialog widget for
inputting file names.
This class implements a dialog which can be used if the
user should select a file or a directory.
Example (e.g. to get a filename for saving a file):
QString fileName = QFileDialog::getSaveFileName( "newfile.txt", "Textfiles (*.txt)", this );
if ( !fileName.isNull() ) { // got a file name
...
}
To let the user specify a filename for e.g. opening a
file, you could use following code:
QString s( QFileDialog::getOpenFileName( QString::null, "Images (*.png *.xpm *.jpg)", this ) );
if ( s.isEmpty() )
return;
open( s ); // open() being your function to read the file
Other convenient static methods are
QFileDialog::getExistingDirectory() to let the user choose
a directory or QFileDialog::getOpenFileNames() to let the
user select multiple files.
Additionally to these convenient static methods you can
use one of QFileDialog's constructors, set a mode (see
setMode()) and do more things, like adding a preview
widget which will preview the current file or information
of the current file while the user does the selection (see
setInfoPreview(), setContentsPreview(),
setInfoPreviewEnabled() and setContentsPreviewEnabled())
or add additional widgets to the filedialog then (see
addWidgets(), addToolButton(), addLeftWidget() and
addRightWidget()).
To get the selection the user did then, see
selectedFile(), selectedFiles(), selectedFilter() and
url(). To set these things see setUrl() and
setSelection().
For an example about how to use this customization of the
QFileDialog, take a look at the qdir example
(qt/examples/qdir/qdir.cpp)
[Image Omitted]
Trolltech AS 13 June 2001 3
QFileDialog(3qt)QFileDialog(3qt)
[Image Omitted]
See also QPrintDialog.
Examples: movies/main.cpp
Member Type Documentation
QFileDialog::Mode
This enum type is used to set and read QFileDialog's
operating mode. The defined values are:
AnyFile - Return the name of any file, whether existing or
not.
ExistingFile - Return the name of a single, existing,
file.
Directory - Return the name of a directory.
DirectoryOnly - Return the name of a directory and display
no files in the file views of the filedialog.
ExistingFiles - Return the names of zero or more existing
files.
Using setMode() you can set this mode to the file dialog.
QFileDialog::PreviewMode
This enum type describes the preview mode of the
filedialog.
NoPreview - No preview is shown at all
Contents - Besides the view with the files a preview
widget is shown which shows the contents of the currently
selected file
Info - Besides the view with the files a preview widget is
shown which shows infos of the currently selected file
Using setPreviewMode() this mode can be set to the file
dialog.
QFileDialog::ViewMode
This enum type describes the view mode of the filedialog.
Detail - View which shows except the filename also size,
date, etc. of a file in columns
List - Simple view which shows only all filenames plus
icons
Using setViewMode() you can set this mode to the file
dialog.
Trolltech AS 13 June 2001 4
QFileDialog(3qt)QFileDialog(3qt)MEMBER FUNCTION DOCUMENTATIONQFileDialog::QFileDialog ( QWidget * parent=0, const char * name
= 0, bool modal = FALSE )
Constructs a file dialog with a parent, name and modal
flag.
The dialog becomes modal if modal is TRUE, otherwise
modeless.
QFileDialog::QFileDialog ( const QString & dirName, const QString
& filter = QString::null, QWidget * parent=0, const char *
name = 0, bool modal = FALSE )
Constructs a file dialog with a parent, name and modal
flag.
The dialog becomes modal if modal is TRUE, otherwise
modeless.
QFileDialog::~QFileDialog ()
Destructs the file dialog.
void QFileDialog::addFilter ( const QString & filter )
[protected]
Adds filter to the filter list and makes it the current
one.
void QFileDialog::addLeftWidget ( QWidget * w ) [protected]
Adds the widget w to the left of the filedialog.
See also addRightWidget(), addWidgets() and
addToolButton().
void QFileDialog::addRightWidget ( QWidget * w ) [protected]
Adds the widget w to the right of the filedialog.
See also addLeftWidget(), addWidgets() and
addToolButton().
void QFileDialog::addToolButton ( QButton * b, bool separator =
FALSE ) [protected]
Adds a the button b to the row of tool buttons on the top
of the filedialog. The button is appended at the end
(right) of this row. If separator is TRUE, a small space
is inserted between the last button of the row and the new
button b.
See also addWidgets(), addLeftWidget() and
addRightWidget().
void QFileDialog::addWidgets ( QLabel * l, QWidget * w,
QPushButton * b ) [protected]
Adds 1-3 widgets to the bottom of the file dialog. l is
the (optional) label, which is put beneath the "file name"
and "file type" labels, w is a (optional) widget, which is
Trolltech AS 13 June 2001 5
QFileDialog(3qt)QFileDialog(3qt)
put beneath the file type combo box, and b is the (you
guessed it - optional) button, which is put beneath the
cancel button.
If you don't want to add something in one of the columns,
pass 0.
Each time calling this method adds a new row of widgets to
the bottom of the filedialog.
See also addToolButton(), addLeftWidget() and
addRightWidget().
const QDir * QFileDialog::dir () const
Returns the active directory in the file dialog.
See also setDir().
void QFileDialog::dirEntered ( const QString & ) [signal]
This signal is emitted when the user has selected a new
directory.
QString QFileDialog::dirPath () const
Returns the active directory path string in the file
dialog.
See also dir() and setDir().
void QFileDialog::done ( int i ) [virtual slot]
Reimplemented for internal reasons; the API is not
affected.
Reimplemented from QDialog.
bool QFileDialog::eventFilter ( QObject * o, QEvent * e )
[virtual]
Reimplemented for internal reasons; the API is not
affected.
Reimplemented from QObject.
void QFileDialog::fileHighlighted ( const QString & ) [signal]
This signal is emitted when the user highlights a file.
void QFileDialog::fileSelected ( const QString & ) [signal]
This signal is emitted when the user selects a file.
QString QFileDialog::getExistingDirectory ( const QString & dir,
QWidget * parent, const char * name, const QString &
caption, bool dirOnly ) [static]
Ask the user for the name of an existing directory,
starting at dir. Returns the name of the directory the
user selected.
Trolltech AS 13 June 2001 6
QFileDialog(3qt)QFileDialog(3qt)
If dir is null, getExistingDirectory() starts wherever the
previous file dialog left off.
caption specifies the caption of the dialog, if this is
empty a default caption will be used. If dirOnly if TRUE
no files will be displayed in the file view widgets.
QString QFileDialog::getExistingDirectory ( const QString & dir =
QString::null, QWidget * parent = 0, const char * name = 0
) [static]
This is an overloaded member function, provided for
convenience. It differs from the above function only in
what argument(s) it accepts.
QString QFileDialog::getExistingDirectory ( const QString & dir,
QWidget * parent, const char * name, const QString &
caption ) [static]
This is an overloaded member function, provided for
convenience. It differs from the above function only in
what argument(s) it accepts.
QString QFileDialog::getOpenFileName ( const QString & startWith,
const QString & filter, QWidget * parent, const char *
name, const QString & caption ) [static]
Opens a modal file dialog and returns the name of the file
to be opened.
If startWith is the name of a directory, the dialog starts
off in that directory. If startWith is the name of an
existing file, the dialogs starts in that directory, and
with startWith selected.
Only files matching filter are selectable. If filter is
QString::null, all files are selectable. In the filter
string multiple filters can be specified separated by
either two semicolons next to each other or separated by
newlines. To add two filters, one to show all C++ files
and one to show all header files, the filter string could
look like "C++ Files (*.cpp *.cc *.C *.cxx *.c++);;Header
Files (*.h *.hxx *.h++)"
If widget and/or name is provided, the dialog will be
centered over widget and named name.
getOpenFileName() returns a null string if the user
cancelled the dialog.
This static function is less capable than the full
QFileDialog object, but is convenient and easy to use.
Example:
// start at the current working directory and with *.cpp as filter
QString f = QFileDialog::getOpenFileName( QString::null, "*.cpp", this );
Trolltech AS 13 June 2001 7
QFileDialog(3qt)QFileDialog(3qt)
if ( !f.isEmpty() ) {
// the user selected a valid existing file
} else {
// the user cancelled the dialog
}
getSaveFileName() is another convenience function, equal
to this one except that it allows the user to specify the
name of a nonexistent file name.
NOTE: In the windows version of Qt this static method uses
the native windows file dialog, and not the QFileDialog.
See also getSaveFileName().
QString QFileDialog::getOpenFileName ( const QString & startWith
= QString::null, const QString & filter = QString::null,
QWidget * parent = 0, const char * name = 0 ) [static]
This is an overloaded member function, provided for
convenience. It differs from the above function only in
what argument(s) it accepts.
QStringList QFileDialog::getOpenFileNames ( const QString &
filter, const QString & dir, QWidget * parent, const char
* name, const QString & caption ) [static]
Lets the user select N files from a single directory, and
returns a list of the selected files. The list may be
empty, and the file names are fully qualified (i.e.
"/usr/games/quake" or" c:\\quake\\quake").
filter is the default glob pattern (which the user can
change). The default is all files. In the filter string
multiple filters can be specified separated by either two
semicolons next to each other or separated by newlines. To
add two filters, one to show all C++ files and one to show
all header files, the filter string could look like "C++
Files (*.cpp *.cc *.C *.cxx *.c++);;Header Files (*.h
*.hxx *.h++)"
dir is the starting directory. If dir is not supplied,
QFileDialog picks something presumably useful (such as the
directory where the user selected something last, or the
current working directory).
parent is a widget over which the dialog should be
positioned and name is the object name of the temporary
QFileDialog object.
Example:
QStringList s( QFileDialog::getOpenFileNames() );
// do something with the files in s.
NOTE: In the windows version of Qt this static method uses
Trolltech AS 13 June 2001 8
QFileDialog(3qt)QFileDialog(3qt)
the native windows file dialog, and not the QFileDialog.
QStringList QFileDialog::getOpenFileNames ( const QString &
filter= QString::null, const QString & dir =
QString::null, QWidget * parent = 0, const char * name = 0
) [static]
This is an overloaded member function, provided for
convenience. It differs from the above function only in
what argument(s) it accepts.
QString QFileDialog::getSaveFileName ( const QString & startWith,
const QString & filter, QWidget * parent, const char *
name, const QString & caption ) [static]
Opens a modal file dialog and returns the name of the file
to be saved.
If startWith is the name of a directory, the dialog starts
off in that directory. If startWith is the name of an
existing file, the dialogs starts in that directory, and
with startWith selected.
Only files matching filter are selectable. If filter is
QString::null, all files are selectable. In the filter
string multiple filters can be specified separated by
either two semicolons next to each other or separated by
newlines. To add two filters, one to show all C++ files
and one to show all header files, the filter string could
look like "C++ Files (*.cpp *.cc *.C *.cxx *.c++);;Header
Files (*.h *.hxx *.h++)"
If widget and/or name is provided, the dialog will be
centered over widget and named name.
Returns a null string if the user cancelled the dialog.
This static function is less capable than the full
QFileDialog object, but is convenient and easy to use.
Example:
// start at the current working directory and with *.cpp as filter
QString f = QFileDialog::getSaveFileName( QString::null, "*.cpp", this );
if ( !f.isEmpty() ) {
// the user gave a file name
} else {
// the user cancelled the dialog
}
getOpenFileName() is another convenience function, equal
to this one except that it does not allow the user to
specify the name of a nonexistent file name.
NOTE: In the windows version of Qt this static method uses
the native windows file dialog, and not the QFileDialog.
Trolltech AS 13 June 2001 9
QFileDialog(3qt)QFileDialog(3qt)
See also getOpenFileName().
QString QFileDialog::getSaveFileName ( const QString & startWith
= QString::null, const QString & filter = QString::null,
QWidget * parent = 0, const char * name = 0 ) [static]
This is an overloaded member function, provided for
convenience. It differs from the above function only in
what argument(s) it accepts.
QFileIconProvider * QFileDialog::iconProvider () [static]
Returns the icon provider currently in use. By default
there is no icon provider and this function returns 0.
See also setIconProvider() and QFileIconProvider.
bool QFileDialog::isContentsPreviewEnabled () const
Returns TRUE if the file dialog offers the user the
possibility to preview the contents of the currently
selected file.
See also setContentsPreviewWidget().
bool QFileDialog::isInfoPreviewEnabled () const
Returns TRUE if the file dialog offers the user the
possibility to preview the information of the currently
selected file.
See also setInfoPreviewEnabled().
void QFileDialog::keyPressEvent ( QKeyEvent * ke ) [virtual
protected]
Reimplemented for internal reasons; the API is not
affected.
Reimplemented from QWidget.
QFileDialog::Mode QFileDialog::mode() const
Returns the file mode of this dialog.
See also setMode().
QFileDialog::PreviewMode QFileDialog::previewMode() const
Returns the preview mode of the filedialog.
See also setPreviewMode().
void QFileDialog::rereadDir ()
Re-reads the active directory in the file dialog.
It is seldom necessary to call this function. It is
provided in case the directory contents change and you
want to refresh the directory list box.
Trolltech AS 13 June 2001 10
QFileDialog(3qt)QFileDialog(3qt)void QFileDialog::resizeEvent ( QResizeEvent * e ) [virtual
protected]
Reimplemented for internal reasons; the API is not
affected.
Reimplemented from QWidget.
void QFileDialog::resortDir ()
Resorts the displayed directory.
void QFileDialog::selectAll ( bool b )
If you pass TRUE for b all files are selected, otherwise
they are de-selected. This only works in ExistingFiles
mode.
QString QFileDialog::selectedFile () const
Returns the selected file name.
If a file name was selected, the returned string contains
the absolute path name. The returned string is an empty
string if no file name was selected.
See also QString::isNull(), QFileDialog::selectedFiles()
and QFileDialog::selectedFilter().
QStringList QFileDialog::selectedFiles () const
Returns a list of selected files. This is only useful, if
the mode of the filedialog is ExistingFiles. Else the list
will only contain one entry, which is the the
selectedFile. If no files were selected, this list is
empty.
See also QFileDialog::selectedFile() and
QValueList::isEmpty().
QString QFileDialog::selectedFilter () const
Returns the filter which the user has chosen in the file
dialog.
See also QString::isNull() and
QFileDialog::selectedFiles().
void QFileDialog::setContentsPreview ( QWidget * w, QFilePreview
* preview )
Sets the widget which should be used for displaying the
contents of a file to w and the preview object of that to
preview.
Normally as preview widget you create a class which
derives from a widget type class (which actually displays
the preview) and from QFilePreview. So you will pass here
two times the same pointer then.
A implementation of a preview class could look like this:
Trolltech AS 13 June 2001 11
QFileDialog(3qt)QFileDialog(3qt)
class MyPreview : public QWidget, public QFilePreview
{
public:
MyPreview() : QWidget(), QFilePreview() {}
// reimplementation from QFilePreview
void previewUrl( const QUrl &url ) {
QPainter p( this );
p.drawThePreviewOfUrl();
p.end();
}
}
Later you would use this...
MyPreview *preview = new MyPreview;
fd.setInfoPreviewEnabled( TRUE );
fd.setInfoPreview( preview, preview );
void QFileDialog::setContentsPreviewEnabled ( bool contents )
Specifies if the filedialog should offer the possibility
to preview the contents of the currently selected file, if
contents is TRUE, else not.
See also setInfoPreview().
void QFileDialog::setDir ( const QDir & dir )
Sets a directory path for the file dialog.
See also dir().
void QFileDialog::setDir ( const QString & pathstr ) [slot]
Sets a directory path string for the file dialog.
See also dir().
void QFileDialog::setFilter ( const QString & newFilter ) [slot]
Sets the filter spec in use to newFilter.
If newFilter matches the regular expression ([a-zA-
Z0-9\.\*\?\ \+\;]*)$ (ie. it ends with a normal wildcard
expression enclosed in parentheses), only the
parenthesized is used. This means that these calls are all
equivalent:
fd->setFilter( "All C++ files (*.cpp *.cc *.C *.cxx *.c++)" );
fd->setFilter( "*.cpp *.cc *.C *.cxx *.c++" )
fd->setFilter( "All C++ files (*.cpp;*.cc;*.C;*.cxx;*.c++)" );
fd->setFilter( "*.cpp;*.cc;*.C;*.cxx;*.c++" )
void QFileDialog::setFilters ( const char ** types ) [slot]
Sets this file dialog to offer types in the File Type
combo box. types must be a null-terminated list of
strings; each string must be in the format described in
the documentation for setFilter().
Trolltech AS 13 June 2001 12
QFileDialog(3qt)QFileDialog(3qt)
See also setFilter().
void QFileDialog::setFilters ( const QString & ) [slot]
This is an overloaded member function, provided for
convenience. It differs from the above function only in
what argument(s) it accepts.
void QFileDialog::setFilters ( const QStringList & ) [slot]
This is an overloaded member function, provided for
convenience. It differs from the above function only in
what argument(s) it accepts.
void QFileDialog::setIconProvider ( QFileIconProvider * provider
) [static]
Sets all file dialogs to use provider to select icons to
draw for each file. By default there is no icon provider,
and QFileDialog simply draws a "folder" icon next to each
directory and nothing next to the files.
See also QFileIconProvider and iconProvider().
Examples: showimg/main.cpp
void QFileDialog::setInfoPreview ( QWidget * w, QFilePreview *
preview )
Sets the widget which should be used for displaying
information of a file to w and the preview object of that
to preview.
Normally as preview widget you create a class which
derives from a widget type class (which actually displays
the preview) and from QFilePreview. So you will pass here
two times the same pointer then.
A implementation of a preview class could look like this:
class MyPreview : public QWidget, public QFilePreview
{
public:
MyPreview() : QWidget(), QFilePreview() {}
// reimplementation from QFilePreview
void previewUrl( const QUrl &url ) {
QPainter p( this );
p.drawThePreviewOfUrl();
p.end();
}
}
Later you would use this...
MyPreview *preview = new MyPreview;
fd.setInfoPreviewEnabled( TRUE );
fd.setInfoPreview( preview, preview );
Trolltech AS 13 June 2001 13
QFileDialog(3qt)QFileDialog(3qt)void QFileDialog::setInfoPreviewEnabled ( bool info )
Specifies if the filedialog should offer the possibility
to preview the information of the currently selected file,
if info is TRUE, else not.
See also setInfoPreview().
void QFileDialog::setMode ( Mode newMode )
Sets this file dialog to newMode, which can be one of
Directory (directories are accepted), ExistingFile
(existing files are accepted), AnyFile (any valid file
name is accepted) or ExistingFiles (like ExistingFile, but
multiple files may be selected)
See also mode().
void QFileDialog::setPreviewMode ( PreviewMode m )
Set the preview mode of the filedialog. You can choose
between NoPreview, Info and Contents.
To be able to set a preview mode other than NoPreview you
need to set the preview widget, and enable this preview
mode.
See also setInfoPreviewEnabled(),
setContentsPreviewEnabled(), setInfoPreview() and
setContentsPreview().
void QFileDialog::setSelection ( const QString & filename )
Sets the default selection to filename. If filename is
absolute, setDir() is also called.
void QFileDialog::setShowHiddenFiles ( bool s )
If s is TRUE, hidden files are shown in the filedialog,
else no hidden files are shown.
void QFileDialog::setUrl ( const QUrlOperator & url ) [slot]
Sets the url which should be used as working directory.
void QFileDialog::setViewMode ( ViewMode m )
Sets the viewmode of the filedialog. You can choose
between Detail, List.
See also setPreviewMode().
bool QFileDialog::showHiddenFiles () const
Returns TRUE if hidden files are shown in the filedialog,
else FALSE.
QUrl QFileDialog::url () const
Returns the URL of the current working directory.
QFileDialog::ViewMode QFileDialog::viewMode() const
Returns the viewmode of the filedialog.
Trolltech AS 13 June 2001 14
QFileDialog(3qt)QFileDialog(3qt)
See also setViewMode().
SEE ALSO
http://doc.trolltech.com/qfiledialog.html
http://www.trolltech.com/faq/tech.html
COPYRIGHT
Copyright 1992-2001 Trolltech AS,
http://www.trolltech.com. See the license file included
in the distribution for a complete license statement.
AUTHOR
Generated automatically from the source code.
BUGS
If you find a bug in Qt, please report it as described in
http://doc.trolltech.com/bughowto.html. Good bug reports
make our job much simpler. Thank you.
In case of content or formattting problems with this
manual page, please report them to qt-bugs@trolltech.com.
Please include the name of the manual page
(qfiledialog.3qt) and the Qt version (2.3.1).
Trolltech AS 13 June 2001 15
