qfiledialog.3qt

Trolltech公司发布的基于C++图形开发环境

'\" t
.TH QFileDialog 3qt "24 January 2005" "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 \- Dialog widget for inputting file names
.br
.PP
\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 "void \fBsetSelection\fR ( const QString & ) "
.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 & ) "
.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
.in -1c
.SS "Public Slots"
.in +1c
.ti -1c
.BI "void \fBsetDir\fR ( const QString & ) "
.br
.ti -1c
.BI "void \fBsetUrl\fR ( const QUrlOperator & url ) "
.br
.ti -1c
.BI "void \fBsetFilter\fR ( const QString & ) "
.br
.ti -1c
.BI "void \fBsetFilters\fR ( const QString & ) "
.br
.ti -1c
.BI "void \fBsetFilters\fR ( const char ** ) "
.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 \fBdirEntered\fR ( const QString & ) "
.br
.in -1c
.SS "Static Public Members"
.in +1c
.ti -1c
.BI "QString \fBgetOpenFileName\fR ( const QString & initially = QString::null, const QString & filter = QString::null, QWidget * " "parent" " = 0, const char * " "name" " = 0 ) "
.br
.ti -1c
.BI "QString \fBgetOpenFileName\fR ( const QString & " "initially" ", const QString & " "filter" ", QWidget * " "parent" ", const char * " "name" ", const QString & caption ) "
.br
.ti -1c
.BI "QString \fBgetSaveFileName\fR ( const QString & initially = QString::null, const QString & filter = QString::null, QWidget * " "parent" " = 0, const char * " "name" " = 0 ) "
.br
.ti -1c
.BI "QString \fBgetSaveFileName\fR ( const QString & " "initially" ", const QString & " "filter" ", QWidget * " "parent" ", const char * " "name" ", const QString & caption ) "
.br
.ti -1c
.BI "QString \fBgetExistingDirectory\fR ( const QString & dir = QString::null, QWidget * " "parent" " = 0, const char * " "name" " = 0 ) "
.br
.ti -1c
.BI "QString \fBgetExistingDirectory\fR ( const QString & " "dir" ", QWidget * " "parent" ", const char * " "name" ", const QString & caption ) "
.br
.ti -1c
.BI "QString \fBgetExistingDirectory\fR ( const QString & " "dir" ", QWidget * " "parent" ", const char * " "name" ", const QString & " "caption" ", bool dirOnly ) "
.br
.ti -1c
.BI "QStringList \fBgetOpenFileNames\fR ( const QString & filter= QString::null, const QString & dir = QString::null, QWidget * " "parent" " = 0, const char * " "name" " = 0 ) "
.br
.ti -1c
.BI "QStringList \fBgetOpenFileNames\fR ( const QString & " "filter" ", const QString & " "dir" ", QWidget * " "parent" ", const char * " "name" ", const QString & caption ) "
.br
.ti -1c
.BI "void \fBsetIconProvider\fR ( QFileIconProvider * ) "
.br
.ti -1c
.BI "QFileIconProvider* \fBiconProvider\fR () "
.br
.in -1c
.SS "Protected Members"
.in +1c
.ti -1c
.BI "void \fBaddWidgets\fR ( QLabel *, QWidget *, QPushButton * ) "
.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
.ti -1c
.BI "void \fBaddFilter\fR ( const QString & filter ) "
.br
.in -1c
.SS "Properties"
.nf
.TS
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
ViewMode	viewMode	viewMode	setViewMode
PreviewMode	previewMode	previewMode	setPreviewMode
bool	infoPreview	isInfoPreviewEnabled	setInfoPreviewEnabled
bool	contentsPreview	isContentsPreviewEnabled	setContentsPreviewEnabled
.TE
.fi

.SH DESCRIPTION
The QFileDialog class provides a dialog widget for inputting file names.
.PP
This class implements a dialog which can be used if the user should select a file or a directory.
.PP
Example (e.g. to get a filename for saving a file):
.PP
.nf
.br
    QString fileName = QFileDialog::getSaveFileName( "newfile.txt", "Textfiles (*.txt)", this );
.br
    if ( !fileName.isNull() ) {                 // got a file name
.br
        ...
.br
    }
.fi
.PP
To let the user specify a filename for e.g. opening a file, you could use following code:
.PP
.nf
.br
    QString s( QFileDialog::getOpenFileName( QString::null, "Images (*.png *.xpm *.jpg)", this ) );
.br
    if ( s.isEmpty() )
.br
        return;
.br
.br
    open( s ); // open() being your function to read the file
.fi
.PP
Other convenient static methods are QFileDialog::getExistingDirectory() to let the user choose a directory or QFileDialog::getOpenFileNames() to let the user select multiple files.
.PP
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()).
.PP
To get the selection the user did then, see selectedFile(), selectedFiles(), selectedFilter() and url(). To set these things see setUrl() and setSelection().
.PP
For an example about how to use this customization of the QFileDialog, take a look at the qdir example (qt/examples/qdir/qdir.cpp)
.PP
.ce 1
.B "[Image Omitted]"
.PP

.ce 1
.B "[Image Omitted]"
.PP
See also QPrintDialog.
.PP
Examples:
.(l
movies/main.cpp
.)l
.SS "Member Type Documentation"
.SH "QFileDialog::Mode"
This enum type is used to set and read QFileDialog's operating mode. The defined values are:
.TP
\fCAnyFile\fR - Return the name of any file, whether existing or not.
.TP
\fCExistingFile\fR - Return the name of a single, existing, file.
.TP
\fCDirectory\fR - Return the name of a directory.
.TP
\fCDirectoryOnly\fR - Return the name of a directory and display no files in the file views of the filedialog.
.TP
\fCExistingFiles\fR - Return the names of zero or more existing files.
.PP
Using setMode() you can set this mode to the file dialog.
.SH "QFileDialog::PreviewMode"
This enum type describes the preview mode of the filedialog.
.TP
\fCNoPreview\fR - No preview is shown at all
.TP
\fCContents\fR - Besides the view with the files a preview widget is shown which shows the contents of the currently selected file
.TP
\fCInfo\fR - Besides the view with the files a preview widget is shown which shows infos of the currently selected file
.PP
Using setPreviewMode() this mode can be set to the file dialog.
.SH "QFileDialog::ViewMode"
This enum type describes the view mode of the filedialog.
.TP
\fCDetail\fR - View which shows except the filename also size, date, etc. of a file in columns
.TP
\fCList\fR - Simple view which shows only all filenames plus icons
.PP
Using setViewMode() you can set this mode to the file dialog.
.SH MEMBER FUNCTION DOCUMENTATION
.SH "QFileDialog::QFileDialog ( QWidget * parent=0, const char * name = 0, bool modal = FALSE )"
Constructs a file dialog with a \fIparent, name\fR and \fImodal\fR flag.
.PP
The dialog becomes modal if \fImodal\fR is TRUE, otherwise modeless.
.SH "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 \fIparent, name\fR and \fImodal\fR flag.
.PP
The dialog becomes modal if \fImodal\fR is TRUE, otherwise modeless.
.SH "QFileDialog::~QFileDialog ()"
Destructs the file dialog.
.SH "void QFileDialog::addFilter ( const QString & filter ) \fC[protected]\fR"
Adds \fIfilter\fR to the filter list and makes it the current one.
.SH "void QFileDialog::addLeftWidget ( QWidget * w ) \fC[protected]\fR"
Adds the widget \fIw\fR to the left of the filedialog.
.PP
See also addRightWidget(), addWidgets() and addToolButton().
.SH "void QFileDialog::addRightWidget ( QWidget * w ) \fC[protected]\fR"
Adds the widget \fIw\fR to the right of the filedialog.
.PP
See also addLeftWidget(), addWidgets() and addToolButton().
.SH "void QFileDialog::addToolButton ( QButton * b, bool separator = FALSE ) \fC[protected]\fR"
Adds a the button \fIb\fR to the row of tool buttons on the top of the filedialog. The button is appended at the end (right) of this row. If \fIseparator\fR is TRUE, a small space is inserted between the last button of the row and the new button \fIb.\fR
.PP
See also addWidgets(), addLeftWidget() and addRightWidget().
.SH "void QFileDialog::addWidgets ( QLabel * l, QWidget * w, QPushButton * b ) \fC[protected]\fR"
Adds 1-3 widgets to the bottom of the file dialog. \fIl\fR is the (optional) label, which is put beneath the "file name" and "file type" labels, \fIw\fR is a (optional) widget, which is put beneath the file type combo box, and \fIb\fR is the (you guessed it - optional) button, which is put beneath the cancel button.
.PP
If you don't want to add something in one of the columns, pass 0.
.PP
Each time calling this method adds a new row of widgets to the bottom of the filedialog.
.PP
See also addToolButton(), addLeftWidget() and addRightWidget().
.SH "const QDir * QFileDialog::dir () const"
Returns the active directory in the file dialog.
.PP
See also setDir().
.SH "void QFileDialog::dirEntered ( const QString & ) \fC[signal]\fR"
This signal is emitted when the user has selected a new directory.
.SH "QString QFileDialog::dirPath () const"
Returns the active directory path string in the file dialog.
.PP
See also dir() and setDir().
.SH "void QFileDialog::done ( int i ) \fC[virtual slot]\fR"
Reimplemented for internal reasons; the API is not affected.