QFileDialog Class Reference

The QFileDialog class provides a dialog widget for inputting file names. More...

#include <qfiledialog.h>

Inherits QDialog.

List of all member functions.

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

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

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
ViewMode	viewMode	viewMode	setViewMode
PreviewMode	previewMode	previewMode	setPreviewMode
bool	infoPreview	isInfoPreviewEnabled	setInfoPreviewEnabled
bool	contentsPreview	isContentsPreviewEnabled	setContentsPreviewEnabled

---

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

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.

---

Member Function Documentation

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

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 );
    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 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 parent is provided, the dialog will be centered over parent. If name is provided, it will be 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.

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.

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:

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

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

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.

See also setViewMode().

---

Search the documentation, FAQ, qt-interest archive and more (uses www.trolltech.com):

---

This file is part of the Qt toolkit, copyright © 1995-2005 Trolltech, all rights reserved.