Q3FileDialog Class Reference
[Qt3Support module]

Detailed Description

The Q3FileDialog class provides dialogs that allow users to select files or directories.

The Q3FileDialog class enables a user to traverse their file system in order to select one or many files or a directory.

The easiest way to create a Q3FileDialog is to use the static functions. On Windows, these static functions will call the native Windows file dialog and on Mac OS X, these static function will call the native Mac OS X file dialog.

 QString s = Q3FileDialog::getOpenFileName(
                 "/home",
                 "Images (*.png *.xpm *.jpg)",
                 this,
                 "open file dialog",
                 "Choose a file");

In the above example, a modal Q3FileDialog is created using a static function. The startup directory is set to "/home". The file filter is set to "Images (*.png *.xpm *.jpg)". The parent of the file dialog is set to this and it is given the identification name - "open file dialog". The caption at the top of file dialog is set to "Choose a file". If you want to use multiple filters, separate each one with two semicolons, e.g.

 "Images (*.png *.xpm *.jpg);;Text files (*.txt);;XML files (*.xml)"

You can create your own Q3FileDialog without using the static functions. By calling setMode(), you can set what can be returned by the Q3FileDialog.

 Q3FileDialog* fd = new Q3FileDialog(this, "file dialog", true);
 fd->setMode(Q3FileDialog::AnyFile);

In the above example, the mode of the file dialog is set to AnyFile, meaning that the user can select any file, or even specify a file that doesn't exist. This mode is useful for creating a "File Save As" file dialog. Use ExistingFile if the user must select an existing file or Directory if only a directory may be selected. (See the Q3FileDialog::Mode enum for the complete list of modes.)

You can retrieve the dialog's mode with mode(). Use setFilter() to set the dialog's file filter, e.g.

 fd->setFilter("Images (*.png *.xpm *.jpg)");

In the above example, the filter is set to "Images (*.png *.xpm *.jpg)", this means that only files with the extension png, xpm or jpg will be shown in the Q3FileDialog. You can apply several filters by using setFilters() and add additional filters with addFilter(). Use setSelectedFilter() to select one of the filters you've given as the file dialog's default filter. Whenever the user changes the filter the filterSelected() signal is emitted.

The file dialog has two view modes, Q3FileDialog::List which simply lists file and directory names and Q3FileDialog::Detail which displays additional information alongside each name, e.g. file size, modification date, etc. Set the mode with setViewMode().

 fd->setViewMode(Q3FileDialog::Detail);

The last important function you will need to use when creating your own file dialog is selectedFile().

 QString fileName;
 if (fd->exec() == QDialog::Accepted)
     fileName = fd->selectedFile();

In the above example, a modal file dialog is created and shown. If the user clicked OK, then the file they selected is put in fileName.

If you are using the ExistingFiles mode then you will need to use selectedFiles() which will return the selected files in a QStringList.

The dialog's working directory can be set with setDir(). The display of hidden files is controlled with setShowHiddenFiles(). The dialog can be forced to re-read the directory with rereadDir() and re-sort the directory with resortDir(). All the files in the current directory can be selected with selectAll().

 class Preview : public QLabel, public Q3FilePreview
 {
 public:
     Preview(QWidget *parent=0) : QLabel(parent) {}

     void previewUrl(const Q3Url &u)
     {
         QString path = u.path();
         QPixmap pix(path);
         if (pix.isNull())
             setText("This is not a pixmap");
         else
             setPixmap(pix);
     }
 };

 Preview* p = new Preview;

 Q3FileDialog* fd = new Q3FileDialog(this);
 fd->setContentsPreviewEnabled(true);
 fd->setContentsPreview(p, p);
 fd->setPreviewMode(Q3FileDialog::Contents);
 fd->show();

 QStringList list = myFileDialog.selectedFiles();
 QStringList::Iterator it = list.begin();
 while(it != list.end()) {
     myProcessing(*it);
     ++it;
 }

 Q3FileDialog* fd = new Q3FileDialog(this);
 fd->addFilter("Images (*.png *.jpg *.xpm)");
 fd->show();

 MyFileDialog::MyFileDialog(QWidget* parent, const char* name) :
     Q3FileDialog(parent, name)
 {
     QLabel* label = new QLabel("Added widgets", this);
     QLineEdit* lineedit = new QLineEdit(this);
     QPushButton* pushbutton = new QPushButton(this);

     addWidgets(label, lineedit, pushbutton);
 }

 QString s = Q3FileDialog::getExistingDirectory(
                 "/home",
                 this,
                 "get existing directory",
                 "Choose a directory",
                 true);

 QString s = Q3FileDialog::getOpenFileName(
                 "/home",
                 "Images (*.png *.xpm *.jpg)",
                 this,
                 "open file dialog",
                 "Choose a file to open");

 QStringList files = Q3FileDialog::getOpenFileNames(
                         "Images (*.png *.xpm *.jpg)",
                         "/home",
                         this,
                         "open files dialog",
                         "Select one or more files to open");

 QStringList list = files;
 QStringList::Iterator it = list.begin();
 while(it != list.end()) {
     myProcessing(*it);
     ++it;
 }

 QString s = Q3FileDialog::getSaveFileName(
                 "/home",
                 "Images (*.png *.xpm *.jpg)",
                 this,
                 "save file dialog",
                 "Choose a filename to save under");

 class Preview : public QLabel, public Q3FilePreview
 {
 public:
     Preview(QWidget *parent=0) : QLabel(parent) {}

     void previewUrl(const Q3Url &u)
     {
         QString path = u.path();
         QPixmap pix(path);
         if (pix.isNull())
             setText("This is not a pixmap");
         else
             setPixmap(pix);
     }
 };

 //...

 int main(int argc, char** argv)
 {
     Preview* p = new Preview;

     Q3FileDialog* fd = new Q3FileDialog(this);
     fd->setContentsPreviewEnabled(true);
     fd->setContentsPreview(p, p);
     fd->setPreviewMode(Q3FileDialog::Contents);
     fd->show();
 }

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

 QString types("Image files (*.png *.xpm *.jpg);;"
               "Text files (*.txt);;"
               "Any files (*)");
 Q3FileDialog fd = new Q3FileDialog(this);
 fd->setFilters(types);
 fd->show();

 class Preview : public QLabel, public Q3FilePreview
 {
 public:
     Preview(QWidget *parent=0) : QLabel(parent) {}

     void previewUrl(const Q3Url &u)
     {
         QString path = u.path();
         QPixmap pix(path);
         if (pix.isNull())
             setText("This is not a pixmap");
         else
             setText("This is a pixmap");
     }
 };

 //...

 int main(int argc, char** argv)
 {
     Preview* p = new Preview;

     Q3FileDialog* fd = new Q3FileDialog(this);
     fd->setInfoPreviewEnabled(true);
     fd->setInfoPreview(p, p);
     fd->setPreviewMode(Q3FileDialog::Info);
     fd->show();
 }