qfiledialog.3qt

Linux下的基于X11的图形开发环境。

'\" t
.TH QFileDialog 3qt "9 December 2002" "Trolltech AS" \" -*- nroff -*-
.\" Copyright 1992-2001 Trolltech AS.  All rights reserved.  See the
.\" license file included in the distribution for a complete license
.\" statement.
.\"
.ad l
.nh
.SH NAME
QFileDialog \- Dialogs that allow users to select files or directories
.SH SYNOPSIS
\fC#include <qfiledialog.h>\fR
.PP
Inherits QDialog.
.PP
.SS "Public Members"
.in +1c
.ti -1c
.BI "\fBQFileDialog\fR ( const QString & dirName, const QString & filter = QString::null, QWidget * parent = 0, const char * name = 0, bool modal = FALSE )"
.br
.ti -1c
.BI "\fBQFileDialog\fR ( QWidget * parent = 0, const char * name = 0, bool modal = FALSE )"
.br
.ti -1c
.BI "\fB~QFileDialog\fR ()"
.br
.ti -1c
.BI "QString \fBselectedFile\fR () const"
.br
.ti -1c
.BI "QString \fBselectedFilter\fR () const"
.br
.ti -1c
.BI "virtual void \fBsetSelectedFilter\fR ( const QString & mask )"
.br
.ti -1c
.BI "virtual void \fBsetSelectedFilter\fR ( int n )"
.br
.ti -1c
.BI "void \fBsetSelection\fR ( const QString & filename )"
.br
.ti -1c
.BI "void \fBselectAll\fR ( bool b )"
.br
.ti -1c
.BI "QStringList \fBselectedFiles\fR () const"
.br
.ti -1c
.BI "QString \fBdirPath\fR () const"
.br
.ti -1c
.BI "void \fBsetDir\fR ( const QDir & dir )"
.br
.ti -1c
.BI "const QDir * \fBdir\fR () const"
.br
.ti -1c
.BI "void \fBsetShowHiddenFiles\fR ( bool s )"
.br
.ti -1c
.BI "bool \fBshowHiddenFiles\fR () const"
.br
.ti -1c
.BI "void \fBrereadDir\fR ()"
.br
.ti -1c
.BI "void \fBresortDir\fR ()"
.br
.ti -1c
.BI "enum \fBMode\fR { AnyFile, ExistingFile, Directory, ExistingFiles, DirectoryOnly }"
.br
.ti -1c
.BI "void \fBsetMode\fR ( Mode )"
.br
.ti -1c
.BI "Mode \fBmode\fR () const"
.br
.ti -1c
.BI "enum \fBViewMode\fR { Detail, List }"
.br
.ti -1c
.BI "enum \fBPreviewMode\fR { NoPreview, Contents, Info }"
.br
.ti -1c
.BI "void \fBsetViewMode\fR ( ViewMode m )"
.br
.ti -1c
.BI "ViewMode \fBviewMode\fR () const"
.br
.ti -1c
.BI "void \fBsetPreviewMode\fR ( PreviewMode m )"
.br
.ti -1c
.BI "PreviewMode \fBpreviewMode\fR () const"
.br
.ti -1c
.BI "bool \fBisInfoPreviewEnabled\fR () const"
.br
.ti -1c
.BI "bool \fBisContentsPreviewEnabled\fR () const"
.br
.ti -1c
.BI "void \fBsetInfoPreviewEnabled\fR ( bool )"
.br
.ti -1c
.BI "void \fBsetContentsPreviewEnabled\fR ( bool )"
.br
.ti -1c
.BI "void \fBsetInfoPreview\fR ( QWidget * w, QFilePreview * preview )"
.br
.ti -1c
.BI "void \fBsetContentsPreview\fR ( QWidget * w, QFilePreview * preview )"
.br
.ti -1c
.BI "QUrl \fBurl\fR () const"
.br
.ti -1c
.BI "void \fBaddFilter\fR ( const QString & filter )"
.br
.in -1c
.SS "Public Slots"
.in +1c
.ti -1c
.BI "void \fBsetDir\fR ( const QString & pathstr )"
.br
.ti -1c
.BI "void \fBsetUrl\fR ( const QUrlOperator & url )"
.br
.ti -1c
.BI "void \fBsetFilter\fR ( const QString & newFilter )"
.br
.ti -1c
.BI "void \fBsetFilters\fR ( const QString & filters )"
.br
.ti -1c
.BI "void \fBsetFilters\fR ( const char ** types )"
.br
.ti -1c
.BI "void \fBsetFilters\fR ( const QStringList & )"
.br
.in -1c
.SS "Signals"
.in +1c
.ti -1c
.BI "void \fBfileHighlighted\fR ( const QString & )"
.br
.ti -1c
.BI "void \fBfileSelected\fR ( const QString & )"
.br
.ti -1c
.BI "void \fBfilesSelected\fR ( const QStringList & )"
.br
.ti -1c
.BI "void \fBdirEntered\fR ( const QString & )"
.br
.ti -1c
.BI "void \fBfilterSelected\fR ( const QString & )"
.br
.in -1c
.SS "Static Public Members"
.in +1c
.ti -1c
.BI "QString \fBgetOpenFileName\fR ( const QString & startWith = QString::null, const QString & filter = QString::null, QWidget * parent = 0, const char * name = 0, const QString & caption = QString::null, QString * selectedFilter = 0, bool resolveSymlinks = TRUE )"
.br
.ti -1c
.BI "QString \fBgetSaveFileName\fR ( const QString & startWith = QString::null, const QString & filter = QString::null, QWidget * parent = 0, const char * name = 0, const QString & caption = QString::null, QString * selectedFilter = 0, bool resolveSymlinks = TRUE )"
.br
.ti -1c
.BI "QString \fBgetExistingDirectory\fR ( const QString & dir = QString::null, QWidget * parent = 0, const char * name = 0, const QString & caption = QString::null, bool dirOnly = TRUE, bool resolveSymlinks = TRUE )"
.br
.ti -1c
.BI "QStringList \fBgetOpenFileNames\fR ( const QString & filter = QString::null, const QString & dir = QString::null, QWidget * parent = 0, const char * name = 0, const QString & caption = QString::null, QString * selectedFilter = 0, bool resolveSymlinks = TRUE )"
.br
.ti -1c
.BI "void \fBsetIconProvider\fR ( QFileIconProvider * provider )"
.br
.ti -1c
.BI "QFileIconProvider * \fBiconProvider\fR ()"
.br
.in -1c
.SS "Properties"
.in +1c
.ti -1c
.BI "bool \fBcontentsPreview\fR - whether the file dialog can provide a contents preview of the currently selected file"
.br
.ti -1c
.BI "QString \fBdirPath\fR - the file dialog's working directory  \fI(read " "only" ")\fR"
.br
.ti -1c
.BI "bool \fBinfoPreview\fR - whether the file dialog can provide preview information about the currently selected file"
.br
.ti -1c
.BI "Mode \fBmode\fR - the file dialog's mode"
.br
.ti -1c
.BI "PreviewMode \fBpreviewMode\fR - the preview mode for the file dialog"
.br
.ti -1c
.BI "QString \fBselectedFile\fR - the name of the selected file  \fI(read " "only" ")\fR"
.br
.ti -1c
.BI "QStringList \fBselectedFiles\fR - the list of selected files  \fI(read " "only" ")\fR"
.br
.ti -1c
.BI "QString \fBselectedFilter\fR - the filter which the user has selected in the file dialog  \fI(read " "only" ")\fR"
.br
.ti -1c
.BI "bool \fBshowHiddenFiles\fR - whether hidden files are shown in the file dialog"
.br
.ti -1c
.BI "ViewMode \fBviewMode\fR - the file dialog's view mode"
.br
.in -1c
.SS "Protected Members"
.in +1c
.ti -1c
.BI "void \fBaddWidgets\fR ( QLabel * l, QWidget * w, QPushButton * b )"
.br
.ti -1c
.BI "void \fBaddToolButton\fR ( QButton * b, bool separator = FALSE )"
.br
.ti -1c
.BI "void \fBaddLeftWidget\fR ( QWidget * w )"
.br
.ti -1c
.BI "void \fBaddRightWidget\fR ( QWidget * w )"
.br
.in -1c
.SH DESCRIPTION
The QFileDialog class provides dialogs that allow users to select files or directories.
.PP
The QFileDialog class enables a user to traverse their file system in order to select one or many files or a directory.
.PP
The easiest way to create a QFileDialog 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.
.PP
.nf
.br
    QString s = QFileDialog::getOpenFileName(
.br
                    "/home",
.br
                    "Images (*.png *.xpm *.jpg)",
.br
                    this,
.br
                    "open file dialog"
.br
                    "Choose a file" );
.br
.fi
.PP
In the above example, a modal QFileDialog 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 \fIthis\fR 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 \fItwo\fR semi-colons, e.g.
.PP
.nf
.br
  "Images (*.png *.xpm *.jpg);;Text files (*.txt);;XML files (*.xml)"
.br
.fi
.PP
You can create your own QFileDialog without using the static functions. By calling setMode(), you can set what can be returned by the QFileDialog.
.PP
.nf
.br
    QFileDialog* fd = new QFileDialog( this, "file dialog", TRUE );
.br
    fd->setMode( QFileDialog::AnyFile );
.br
.fi
.PP
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 QFileDialog::Mode enum for the complete list of modes.)
.PP
You can retrieve the dialog's mode with mode(). Use setFilter() to set the dialog's file filter, e.g.
.PP
.nf
.br
    fd->setFilter( "Images (*.png *.xpm *.jpg)" );
.br
.fi
.PP
In the above example, the filter is set to "Images (*.png *.xpm *.jpg)", this means that only files with the extension \fCpng\fR, \fCxpm\fR or \fCjpg\fR will be shown in the QFileDialog. 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.
.PP
The file dialog has two view modes, QFileDialog::List which simply lists file and directory names and QFileDialog::Detail which displays additional information alongside each name, e.g. file size, modification date, etc. Set the mode with setViewMode().
.PP
.nf
.br
    fd->setViewMode( QFileDialog::Detail );
.br
.fi
.PP
The last important function you will need to use when creating your own file dialog is selectedFile().
.PP
.nf
.br
    QString fileName;
.br
    if ( fd->exec() == QDialog::Accepted )
.br
        fileName = fd->selectedFile();
.br
.fi
.PP
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 \fCfileName\fR.
.PP
If you are using the ExistingFiles mode then you will need to use selectedFiles() which will return the selected files in a QStringList.
.PP
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().
.SH "Creating and using preview widgets"
There are two kinds of preview widgets that can be used with QFileDialogs: \fIcontent\fR preview widgets and \fIinformation\fR preview widgets. They are created and used in the same way except that the function names differ, e.g. setContentsPreview() and setInfoPreview().
.PP
A preview widget is a widget that is placed inside a QFileDialog so that the user can see either the contents of the file, or information about the file.
.PP
.nf
.br
    class Preview : public QLabel, public QFilePreview
.br
    {
.br
    public:
.br
        Preview( QWidget *parent=0 ) : QLabel( parent ) {}
.br
.br
        void previewUrl( const QUrl &u )
.br
        {
.br
            QString path = u.path();
.br
            QPixmap pix( path );
.br
            if ( pix.isNull() )
.br
                setText( "This is not a pixmap" );
.br
            else
.br
                setPixmap( pix );
.br
        }
.br
    };
.br