1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Doc: Review and improve QFileDialog documentation

Browse Source 
Grammar improvements made. A screenshot added.

Task-number: QTBUG-119551
Change-Id: Ia14c654e92eede5a32bba18cd4d05a74d289f64b
Reviewed-by: Mats Honkamaa <mats.honkamaa@qt.io>
(cherry picked from commit 26ac6bd4a4e004acd4602d346c3fe45e79a51bf6)
Reviewed-by: Kai Köhne <kai.koehne@qt.io>
This commit is contained in:
Inkamari Harjula 2023-12-08 11:45:32 +02:00 committed by Kai Köhne
parent 84365c0b60
commit 56f6eb2c09
2 changed files with 123 additions and 120 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

243
src/widgets/dialogs/qfiledialog.cpp
View File

@ -58,14 +58,17 @@ Q_GLOBAL_STATIC(QUrl, lastVisitedDir)
/*! /*!
\class QFileDialog \class QFileDialog
\brief The QFileDialog class provides a dialog that allow users to select files or directories. \brief The QFileDialog class provides a dialog that allows users to select files or directories.
\ingroup standard-dialogs \ingroup standard-dialogs
\inmodule QtWidgets \inmodule QtWidgets
The QFileDialog class enables a user to traverse the file system in The QFileDialog class enables a user to traverse the file system
order to select one or many files or a directory. to select one or many files or a directory.
The easiest way to create a QFileDialog is to use the static functions. \image qtquickdialogs-filedialog-gtk.png
The easiest way to create a QFileDialog is to use the static functions,
such as \l getOpenFileName().
\snippet code/src_gui_dialogs_qfiledialog.cpp 0 \snippet code/src_gui_dialogs_qfiledialog.cpp 0
@ -90,7 +93,7 @@ Q_GLOBAL_STATIC(QUrl, lastVisitedDir)
AnyFile, meaning that the user can select any file, or even specify a 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 that doesn't exist. This mode is useful for creating a
"Save As" file dialog. Use ExistingFile if the user must select an "Save As" file dialog. Use ExistingFile if the user must select an
existing file, or \l Directory if only a directory may be selected. existing file, or \l Directory if only a directory can be selected.
See the \l QFileDialog::FileMode enum for the complete list of modes. See the \l QFileDialog::FileMode enum for the complete list of modes.
The fileMode property contains the mode of operation for the dialog; The fileMode property contains the mode of operation for the dialog;
@ -99,9 +102,9 @@ Q_GLOBAL_STATIC(QUrl, lastVisitedDir)
\snippet code/src_gui_dialogs_qfiledialog.cpp 3 \snippet code/src_gui_dialogs_qfiledialog.cpp 3
In the above example, the filter is set to \c{"Images (*.png *.xpm *.jpg)"}, In the above example, the filter is set to \c{"Images (*.png *.xpm *.jpg)"}.
this means that only files with the extension \c png, \c xpm, This means that only files with the extension \c png, \c xpm,
or \c jpg will be shown in the QFileDialog. You can apply or \c jpg are shown in the QFileDialog. You can apply
several filters by using setNameFilters(). Use selectNameFilter() to select several filters by using setNameFilters(). Use selectNameFilter() to select
one of the filters you've given as the file dialog's default filter. one of the filters you've given as the file dialog's default filter.
@ -115,7 +118,7 @@ Q_GLOBAL_STATIC(QUrl, lastVisitedDir)
\snippet code/src_gui_dialogs_qfiledialog.cpp 4 \snippet code/src_gui_dialogs_qfiledialog.cpp 4
The last important function you will need to use when creating your The last important function you need to use when creating your
own file dialog is selectedFiles(). own file dialog is selectedFiles().
\snippet code/src_gui_dialogs_qfiledialog.cpp 5 \snippet code/src_gui_dialogs_qfiledialog.cpp 5
@ -130,13 +133,13 @@ Q_GLOBAL_STATIC(QUrl, lastVisitedDir)
The \l{dialogs/standarddialogs}{Standard Dialogs} example shows The \l{dialogs/standarddialogs}{Standard Dialogs} example shows
how to use QFileDialog as well as other built-in Qt dialogs. how to use QFileDialog as well as other built-in Qt dialogs.
By default, a platform-native file dialog will be used if the platform has By default, a platform-native file dialog is used if the platform has
one. In that case, the widgets which would otherwise be used to construct the one. In that case, the widgets that would otherwise be used to construct the
dialog will not be instantiated, so related accessors such as layout() and dialog are not instantiated, so related accessors such as layout() and
itemDelegate() will return null. Also, not all platforms show file dialogs itemDelegate() return null. Also, not all platforms show file dialogs
with a title bar, so be aware that the caption text might not be visible to with a title bar, so be aware that the caption text might not be visible to
the user. You can set the \l DontUseNativeDialog option to ensure that the the user. You can set the \l DontUseNativeDialog option to ensure that the
widget-based implementation will be used instead of the native dialog. widget-based implementation is used instead of the native dialog.
\sa QDir, QFileInfo, QFile, QColorDialog, QFontDialog, {Standard Dialogs Example} \sa QDir, QFileInfo, QFile, QColorDialog, QFontDialog, {Standard Dialogs Example}
*/ */
@ -151,8 +154,8 @@ Q_GLOBAL_STATIC(QUrl, lastVisitedDir)
/*! /*!
\enum QFileDialog::ViewMode \enum QFileDialog::ViewMode
This enum describes the view mode of the file dialog; i.e. what This enum describes the view mode of the file dialog; that is, what
information about each file will be displayed. information about each file is displayed.
\value Detail Displays an icon, a name, and details for each item in \value Detail Displays an icon, a name, and details for each item in
the directory. the directory.
@ -166,7 +169,7 @@ Q_GLOBAL_STATIC(QUrl, lastVisitedDir)
\enum QFileDialog::FileMode \enum QFileDialog::FileMode
This enum is used to indicate what the user may select in the file This enum is used to indicate what the user may select in the file
dialog; i.e. what the dialog will return if the user clicks OK. dialog; that is, what the dialog returns if the user clicks OK.
\value AnyFile The name of a file, whether it exists or not. \value AnyFile The name of a file, whether it exists or not.
\value ExistingFile The name of a single existing file. \value ExistingFile The name of a single existing file.
@ -190,7 +193,7 @@ Q_GLOBAL_STATIC(QUrl, lastVisitedDir)
dialog. By default symlinks are resolved. dialog. By default symlinks are resolved.
\value DontConfirmOverwrite Don't ask for confirmation if an \value DontConfirmOverwrite Don't ask for confirmation if an
existing file is selected. By default, confirmation is requested. existing file is selected. By default, confirmation is requested.
(Valid only if \l acceptMode is \l {QFileDialog::}{AcceptSave}). (Valid only if \l acceptMode is \l {QFileDialog::}{AcceptSave}).
Note: This option is not supported on macOS when using the Note: This option is not supported on macOS when using the
@ -211,7 +214,7 @@ Q_GLOBAL_STATIC(QUrl, lastVisitedDir)
\value DontUseCustomDirectoryIcons Always use the default directory icon. \value DontUseCustomDirectoryIcons Always use the default directory icon.
Some platforms allow the user to set a different icon. Custom icon lookup Some platforms allow the user to set a different icon. Custom icon lookup
cause a big performance impact over network or removable drives. causes a big performance impact over network or removable drives.
Setting this will enable the QFileIconProvider::DontUseCustomDirectoryIcons Setting this will enable the QFileIconProvider::DontUseCustomDirectoryIcons
option in the icon provider. This enum value was added in Qt 5.2. option in the icon provider. This enum value was added in Qt 5.2.
*/ */
@ -380,7 +383,7 @@ QFileDialog::~QFileDialog()
\snippet filedialogurls/filedialogurls.cpp 0 \snippet filedialogurls/filedialogurls.cpp 0
The file dialog will then look like this: Then the file dialog looks like this:
\image filedialogurls.png \image filedialogurls.png
@ -737,7 +740,7 @@ bool QFileDialog::testOption(Option option) const
/*! /*!
\property QFileDialog::options \property QFileDialog::options
\brief the various options that affect the look and feel of the dialog \brief The various options that affect the look and feel of the dialog.
\since 4.5 \since 4.5
By default, all options are disabled. By default, all options are disabled.
@ -811,11 +814,11 @@ QFileDialog::Options QFileDialog::options() const
/*! /*!
\since 4.5 \since 4.5
This function connects one of its signals to the slot specified by \a receiver This function shows the dialog, and connects the slot specified by \a receiver
and \a member. The specific signal depends is filesSelected() if fileMode is and \a member to the signal that informs about selection changes. If the fileMode is
ExistingFiles and fileSelected() if fileMode is anything else. ExistingFiles, this is the filesSelected() signal, otherwise it is the fileSelected() signal.
The signal will be disconnected from the slot when the dialog is closed. The signal is disconnected from the slot when the dialog is closed.
*/ */
void QFileDialog::open(QObject *receiver, const char *member) void QFileDialog::open(QObject *receiver, const char *member)
{ {
@ -904,7 +907,7 @@ void QFileDialogPrivate::_q_goToUrl(const QUrl &url)
\note On iOS, if you set \a directory to \l{QStandardPaths::standardLocations()} \note On iOS, if you set \a directory to \l{QStandardPaths::standardLocations()}
{QStandardPaths::standardLocations(QStandardPaths::PicturesLocation).last()}, {QStandardPaths::standardLocations(QStandardPaths::PicturesLocation).last()},
a native image picker dialog will be used for accessing the user's photo album. a native image picker dialog is used for accessing the user's photo album.
The filename returned can be loaded using QFile and related APIs. The filename returned can be loaded using QFile and related APIs.
For this to be enabled, the Info.plist assigned to QMAKE_INFO_PLIST in the For this to be enabled, the Info.plist assigned to QMAKE_INFO_PLIST in the
project file must contain the key \c NSPhotoLibraryUsageDescription. See project file must contain the key \c NSPhotoLibraryUsageDescription. See
@ -1397,15 +1400,15 @@ QStringList qt_strip_filters(const QStringList &filters)
assumption that the file extension determines the file type is not assumption that the file extension determines the file type is not
consistent on every operating system. It is possible to have a file with no consistent on every operating system. It is possible to have a file with no
dot in its name (for example, \c Makefile). In a native Windows file dot in its name (for example, \c Makefile). In a native Windows file
dialog, \b{*.*} will match such files, while in other types of file dialogs dialog, \b{*.*} matches such files, while in other types of file dialogs
it may not. So it is better to use \b{*} if you mean to select any file. it might not match. So, it's better to use \b{*} if you mean to select any file.
\snippet code/src_gui_dialogs_qfiledialog.cpp 7 \snippet code/src_gui_dialogs_qfiledialog.cpp 7
\l setMimeTypeFilters() has the advantage of providing all possible name \l setMimeTypeFilters() has the advantage of providing all possible name
filters for each file type. For example, JPEG images have three possible filters for each file type. For example, JPEG images have three possible
extensions; if your application can open such files, selecting the extensions; if your application can open such files, selecting the
\c image/jpeg mime type as a filter will allow you to open all of them. \c image/jpeg mime type as a filter allows you to open all of them.
*/ */
void QFileDialog::setNameFilters(const QStringList &filters) void QFileDialog::setNameFilters(const QStringList &filters)
{ {
@ -1641,7 +1644,7 @@ QString QFileDialog::selectedMimeTypeFilter() const
/*! /*!
\property QFileDialog::viewMode \property QFileDialog::viewMode
\brief the way files and directories are displayed in the dialog \brief The way files and directories are displayed in the dialog.
By default, the \c Detail mode is used to display information about By default, the \c Detail mode is used to display information about
files and directories. files and directories.
@ -1670,14 +1673,14 @@ QFileDialog::ViewMode QFileDialog::viewMode() const
/*! /*!
\property QFileDialog::fileMode \property QFileDialog::fileMode
\brief the file mode of the dialog \brief The file mode of the dialog.
The file mode defines the number and type of items that the user is The file mode defines the number and type of items that the user is
expected to select in the dialog. expected to select in the dialog.
By default, this property is set to AnyFile. By default, this property is set to AnyFile.
This function will set the labels for the FileName and This function sets the labels for the FileName and
\l{QFileDialog::}{Accept} \l{DialogLabel}s. It is possible to set \l{QFileDialog::}{Accept} \l{DialogLabel}s. It is possible to set
custom text after the call to setFileMode(). custom text after the call to setFileMode().
@ -1722,7 +1725,7 @@ QFileDialog::FileMode QFileDialog::fileMode() const
/*! /*!
\property QFileDialog::acceptMode \property QFileDialog::acceptMode
\brief the accept mode of the dialog \brief The accept mode of the dialog.
The action mode defines whether the dialog is for opening or saving files. The action mode defines whether the dialog is for opening or saving files.
@ -1750,14 +1753,14 @@ void QFileDialog::setAcceptMode(QFileDialog::AcceptMode mode)
/*! /*!
\property QFileDialog::supportedSchemes \property QFileDialog::supportedSchemes
\brief the URL schemes that the file dialog should allow navigating to. \brief The URL schemes that the file dialog should allow navigating to.
\since 5.6 \since 5.6
Setting this property allows to restrict the type of URLs the Setting this property allows to restrict the type of URLs the
user will be able to select. It is a way for the application to declare user can select. It is a way for the application to declare
the protocols it will support to fetch the file content. An empty list the protocols it supports to fetch the file content. An empty list
means that no restriction is applied (the default). means that no restriction is applied (the default).
Supported for local files ("file" scheme) is implicit and always enabled; Support for local files ("file" scheme) is implicit and always enabled;
it is not necessary to include it in the restriction. it is not necessary to include it in the restriction.
*/ */
@ -1839,10 +1842,10 @@ QFileDialog::AcceptMode QFileDialog::acceptMode() const
/*! /*!
\property QFileDialog::defaultSuffix \property QFileDialog::defaultSuffix
\brief suffix added to the filename if no other suffix was specified \brief Suffix added to the filename if no other suffix was specified.
This property specifies a string that will be added to the This property specifies a string that is added to the
filename if it has no suffix already. The suffix is typically filename if it has no suffix yet. The suffix is typically
used to indicate the file type (e.g. "txt" indicates a text used to indicate the file type (e.g. "txt" indicates a text
file). file).
@ -2045,41 +2048,41 @@ QString QFileDialog::labelText(DialogLabel label) const
\snippet code/src_gui_dialogs_qfiledialog.cpp 8 \snippet code/src_gui_dialogs_qfiledialog.cpp 8
The function creates a modal file dialog with the given \a parent widget. The function creates a modal file dialog with the given \a parent widget.
If \a parent is not \nullptr, the dialog will be shown centered over the If \a parent is not \nullptr, the dialog is shown centered over the
parent widget. parent widget.
The file dialog's working directory will be set to \a dir. If \a dir The file dialog's working directory is set to \a dir. If \a dir
includes a file name, the file will be selected. Only files that match the includes a file name, the file is selected. Only files that match the
given \a filter are shown. The filter selected is set to \a selectedFilter. given \a filter are shown. The selected filter is set to \a selectedFilter.
The parameters \a dir, \a selectedFilter, and \a filter may be empty The parameters \a dir, \a selectedFilter, and \a filter may be empty
strings. If you want multiple filters, separate them with ';;', for strings. If you want multiple filters, separate them with ';;', for
example: example:
\snippet code/src_gui_dialogs_qfiledialog.cpp 14 \snippet code/src_gui_dialogs_qfiledialog.cpp 14
The \a options argument holds various options about how to run the dialog, The \a options argument holds various options about how to run the dialog.
see the QFileDialog::Option enum for more information on the flags you can See the QFileDialog::Option enum for more information on the flags you can
pass. pass.
The dialog's caption is set to \a caption. If \a caption is not specified The dialog's caption is set to \a caption. If \a caption is not specified,
then a default caption will be used. then a default caption will be used.
On Windows, and \macos, this static function will use the On Windows, and \macos, this static function uses the
native file dialog and not a QFileDialog. Note that the \macos native file native file dialog and not a QFileDialog. Note that the \macos native file
dialog does not show a title bar. dialog does not show a title bar.
On Windows the dialog will spin a blocking modal event loop that will not On Windows the dialog spins a blocking modal event loop that does not
dispatch any QTimers, and if \a parent is not \nullptr then it will position dispatch any QTimers, and if \a parent is not \nullptr then it positions
the dialog just below the parent's title bar. the dialog just below the parent's title bar.
On Unix/X11, the normal behavior of the file dialog is to resolve and On Unix/X11, the normal behavior of the file dialog is to resolve and
follow symlinks. For example, if \c{/usr/tmp} is a symlink to \c{/var/tmp}, follow symlinks. For example, if \c{/usr/tmp} is a symlink to \c{/var/tmp},
the file dialog will change to \c{/var/tmp} after entering \c{/usr/tmp}. If the file dialog changes to \c{/var/tmp} after entering \c{/usr/tmp}. If
\a options includes DontResolveSymlinks, the file dialog will treat \a options includes DontResolveSymlinks, the file dialog treats
symlinks as regular directories. symlinks as regular directories.
\warning Do not delete \a parent during the execution of the dialog. If you \warning Do not delete \a parent during the execution of the dialog. If you
want to do this, you should create the dialog yourself using one of the want to do this, you must create the dialog yourself using one of the
QFileDialog constructors. QFileDialog constructors.
\sa getOpenFileNames(), getSaveFileName(), getExistingDirectory() \sa getOpenFileNames(), getSaveFileName(), getExistingDirectory()
@ -2107,21 +2110,21 @@ QString QFileDialog::getOpenFileName(QWidget *parent,
The function is used similarly to QFileDialog::getOpenFileName(). In The function is used similarly to QFileDialog::getOpenFileName(). In
particular \a parent, \a caption, \a dir, \a filter, \a selectedFilter particular \a parent, \a caption, \a dir, \a filter, \a selectedFilter
and \a options are used in the exact same way. and \a options are used in exactly the same way.
The main difference with QFileDialog::getOpenFileName() comes from The main difference with QFileDialog::getOpenFileName() comes from
the ability offered to the user to select a remote file. That's why the ability offered to the user to select a remote file. That's why
the return type and the type of \a dir is QUrl. the return type and the type of \a dir is QUrl.
The \a supportedSchemes argument allows to restrict the type of URLs the The \a supportedSchemes argument allows to restrict the type of URLs the
user will be able to select. It is a way for the application to declare user is able to select. It is a way for the application to declare
the protocols it will support to fetch the file content. An empty list the protocols it will support to fetch the file content. An empty list
means that no restriction is applied (the default). means that no restriction is applied (the default).
Supported for local files ("file" scheme) is implicit and always enabled; Support for local files ("file" scheme) is implicit and always enabled;
it is not necessary to include it in the restriction. it is not necessary to include it in the restriction.
When possible, this static function will use the native file dialog and When possible, this static function uses the native file dialog and
not a QFileDialog. On platforms which don't support selecting remote not a QFileDialog. On platforms that don't support selecting remote
files, Qt will allow to select only local files. files, Qt will allow to select only local files.
\sa getOpenFileName(), getOpenFileUrls(), getSaveFileUrl(), getExistingDirectoryUrl() \sa getOpenFileName(), getOpenFileUrls(), getSaveFileUrl(), getExistingDirectoryUrl()
@ -2155,33 +2158,33 @@ QUrl QFileDialog::getOpenFileUrl(QWidget *parent,
} }
/*! /*!
This is a convenience static function that will return one or more existing This is a convenience static function that returns one or more existing
files selected by the user. files selected by the user.
\snippet code/src_gui_dialogs_qfiledialog.cpp 9 \snippet code/src_gui_dialogs_qfiledialog.cpp 9
This function creates a modal file dialog with the given \a parent widget. This function creates a modal file dialog with the given \a parent widget.
If \a parent is not \nullptr, the dialog will be shown centered over the If \a parent is not \nullptr, the dialog is shown centered over the
parent widget. parent widget.
The file dialog's working directory will be set to \a dir. If \a dir The file dialog's working directory is set to \a dir. If \a dir
includes a file name, the file will be selected. The filter is set to includes a file name, the file is selected. The filter is set to
\a filter so that only those files which match the filter are shown. The \a filter so that only those files which match the filter are shown. The
filter selected is set to \a selectedFilter. The parameters \a dir, filter selected is set to \a selectedFilter. The parameters \a dir,
\a selectedFilter and \a filter may be empty strings. If you need multiple \a selectedFilter and \a filter can be empty strings. If you need multiple
filters, separate them with ';;', for instance: filters, separate them with ';;', for instance:
\snippet code/src_gui_dialogs_qfiledialog.cpp 14 \snippet code/src_gui_dialogs_qfiledialog.cpp 14
The dialog's caption is set to \a caption. If \a caption is not specified The dialog's caption is set to \a caption. If \a caption is not specified,
then a default caption will be used. then a default caption is used.
On Windows, and \macos, this static function will use the On Windows and \macos, this static function uses the
native file dialog and not a QFileDialog. Note that the \macos native file native file dialog and not a QFileDialog. Note that the \macos native file
dialog does not show a title bar. dialog does not show a title bar.
On Windows the dialog will spin a blocking modal event loop that will not On Windows the dialog spins a blocking modal event loop that does not
dispatch any QTimers, and if \a parent is not \nullptr then it will position dispatch any QTimers, and if \a parent is not \nullptr then it positions
the dialog just below the parent's title bar. the dialog just below the parent's title bar.
On Unix/X11, the normal behavior of the file dialog is to resolve and On Unix/X11, the normal behavior of the file dialog is to resolve and
@ -2192,7 +2195,7 @@ QUrl QFileDialog::getOpenFileUrl(QWidget *parent,
pass. pass.
\warning Do not delete \a parent during the execution of the dialog. If you \warning Do not delete \a parent during the execution of the dialog. If you
want to do this, you should create the dialog yourself using one of the want to do this, you must create the dialog yourself using one of the
QFileDialog constructors. QFileDialog constructors.
\sa getOpenFileName(), getSaveFileName(), getExistingDirectory() \sa getOpenFileName(), getSaveFileName(), getExistingDirectory()
@ -2215,13 +2218,13 @@ QStringList QFileDialog::getOpenFileNames(QWidget *parent,
} }
/*! /*!
This is a convenience static function that will return one or more existing This is a convenience static function that returns one or more existing
files selected by the user. If the user presses Cancel, it returns an files selected by the user. If the user presses Cancel, it returns an
empty list. empty list.
The function is used similarly to QFileDialog::getOpenFileNames(). In The function is used similarly to QFileDialog::getOpenFileNames(). In
particular \a parent, \a caption, \a dir, \a filter, \a selectedFilter particular \a parent, \a caption, \a dir, \a filter, \a selectedFilter
and \a options are used in the exact same way. and \a options are used in exactly the same way.
The main difference with QFileDialog::getOpenFileNames() comes from The main difference with QFileDialog::getOpenFileNames() comes from
the ability offered to the user to select remote files. That's why the ability offered to the user to select remote files. That's why
@ -2229,14 +2232,14 @@ QStringList QFileDialog::getOpenFileNames(QWidget *parent,
and QUrl. and QUrl.
The \a supportedSchemes argument allows to restrict the type of URLs the The \a supportedSchemes argument allows to restrict the type of URLs the
user will be able to select. It is a way for the application to declare user can select. It is a way for the application to declare
the protocols it will support to fetch the file content. An empty list the protocols it supports to fetch the file content. An empty list
means that no restriction is applied (the default). means that no restriction is applied (the default).
Supported for local files ("file" scheme) is implicit and always enabled; Support for local files ("file" scheme) is implicit and always enabled;
it is not necessary to include it in the restriction. it is not necessary to include it in the restriction.
When possible, this static function will use the native file dialog and When possible, this static function uses the native file dialog and
not a QFileDialog. On platforms which don't support selecting remote not a QFileDialog. On platforms that don't support selecting remote
files, Qt will allow to select only local files. files, Qt will allow to select only local files.
\sa getOpenFileNames(), getOpenFileUrl(), getSaveFileUrl(), getExistingDirectoryUrl() \sa getOpenFileNames(), getOpenFileUrl(), getSaveFileUrl(), getExistingDirectoryUrl()
@ -2270,15 +2273,15 @@ QList<QUrl> QFileDialog::getOpenFileUrls(QWidget *parent,
} }
/*! /*!
This is a convenience static function that will return the content of a file This is a convenience static function that returns the content of a file
selected by the user. selected by the user.
This function is used to access local files on Qt for WebAssembly, where the web This function is used to access local files on Qt for WebAssembly, where the web
sandbox places restrictions on how such access may happen. Its implementation will sandbox places restrictions on how such access can happen. Its implementation will
make the browser display a native file dialog, where the user makes the file selection make the browser display a native file dialog, where the user makes the file selection
based on the parameter \a nameFilter. based on the parameter \a nameFilter.
It can also be used on other platforms, where it will fall back to using QFileDialog. It can also be used on other platforms, where it falls back to using QFileDialog.
The function is asynchronous and returns immediately. The \a fileOpenCompleted The function is asynchronous and returns immediately. The \a fileOpenCompleted
callback will be called when a file has been selected and its contents have been callback will be called when a file has been selected and its contents have been
@ -2345,10 +2348,10 @@ void QFileDialog::getOpenFileContent(const QString &nameFilter, const std::funct
suggest a file name to the user. suggest a file name to the user.
This function is used to save files to the local file system on Qt for WebAssembly, where This function is used to save files to the local file system on Qt for WebAssembly, where
the web sandbox places restrictions on how such access may happen. Its implementation will the web sandbox places restrictions on how such access can happen. Its implementation will
make the browser display a native file dialog, where the user makes the file selection. make the browser display a native file dialog, where the user makes the file selection.
It can also be used on other platforms, where it will fall back to using QFileDialog. It can also be used on other platforms, where it falls back to using QFileDialog.
The function is asynchronous and returns immediately. The function is asynchronous and returns immediately.
@ -2380,7 +2383,7 @@ void QFileDialog::saveFileContent(const QByteArray &fileContent, const QString &
} }
/*! /*!
This is a convenience static function that will return a file name selected This is a convenience static function that returns a file name selected
by the user. The file does not have to exist. by the user. The file does not have to exist.
It creates a modal file dialog with the given \a parent widget. If It creates a modal file dialog with the given \a parent widget. If
@ -2389,8 +2392,8 @@ void QFileDialog::saveFileContent(const QByteArray &fileContent, const QString &
\snippet code/src_gui_dialogs_qfiledialog.cpp 11 \snippet code/src_gui_dialogs_qfiledialog.cpp 11
The file dialog's working directory will be set to \a dir. If \a dir The file dialog's working directory is set to \a dir. If \a dir
includes a file name, the file will be selected. Only files that match the includes a file name, the file is selected. Only files that match the
\a filter are shown. The filter selected is set to \a selectedFilter. The \a filter are shown. The filter selected is set to \a selectedFilter. The
parameters \a dir, \a selectedFilter, and \a filter may be empty strings. parameters \a dir, \a selectedFilter, and \a filter may be empty strings.
Multiple filters are separated with ';;'. For instance: Multiple filters are separated with ';;'. For instance:
@ -2405,24 +2408,24 @@ void QFileDialog::saveFileContent(const QByteArray &fileContent, const QString &
desired value. desired value.
The dialog's caption is set to \a caption. If \a caption is not specified, The dialog's caption is set to \a caption. If \a caption is not specified,
a default caption will be used. a default caption is used.
On Windows, and \macos, this static function will use the On Windows, and \macos, this static function uses the
native file dialog and not a QFileDialog. native file dialog and not a QFileDialog.
On Windows the dialog will spin a blocking modal event loop that will not On Windows the dialog spins a blocking modal event loop that does not
dispatch any QTimers, and if \a parent is not \nullptr then it will dispatch any QTimers, and if \a parent is not \nullptr then it
position the dialog just below the parent's title bar. On \macos, with its positions the dialog just below the parent's title bar. On \macos, with its
native file dialog, the filter argument is ignored. native file dialog, the filter argument is ignored.
On Unix/X11, the normal behavior of the file dialog is to resolve and On Unix/X11, the normal behavior of the file dialog is to resolve and
follow symlinks. For example, if \c{/usr/tmp} is a symlink to \c{/var/tmp}, follow symlinks. For example, if \c{/usr/tmp} is a symlink to \c{/var/tmp},
the file dialog will change to \c{/var/tmp} after entering \c{/usr/tmp}. If the file dialog changes to \c{/var/tmp} after entering \c{/usr/tmp}. If
\a options includes DontResolveSymlinks the file dialog will treat symlinks \a options includes DontResolveSymlinks, the file dialog treats symlinks
as regular directories. as regular directories.
\warning Do not delete \a parent during the execution of the dialog. If you \warning Do not delete \a parent during the execution of the dialog. If you
want to do this, you should create the dialog yourself using one of the want to do this, you must create the dialog yourself using one of the
QFileDialog constructors. QFileDialog constructors.
\sa getOpenFileName(), getOpenFileNames(), getExistingDirectory() \sa getOpenFileName(), getOpenFileNames(), getExistingDirectory()
@ -2450,21 +2453,21 @@ QString QFileDialog::getSaveFileName(QWidget *parent,
The function is used similarly to QFileDialog::getSaveFileName(). In The function is used similarly to QFileDialog::getSaveFileName(). In
particular \a parent, \a caption, \a dir, \a filter, \a selectedFilter particular \a parent, \a caption, \a dir, \a filter, \a selectedFilter
and \a options are used in the exact same way. and \a options are used in exactly the same way.
The main difference with QFileDialog::getSaveFileName() comes from The main difference with QFileDialog::getSaveFileName() comes from
the ability offered to the user to select a remote file. That's why the ability offered to the user to select a remote file. That's why
the return type and the type of \a dir is QUrl. the return type and the type of \a dir is QUrl.
The \a supportedSchemes argument allows to restrict the type of URLs the The \a supportedSchemes argument allows to restrict the type of URLs the
user will be able to select. It is a way for the application to declare user can select. It is a way for the application to declare
the protocols it will support to save the file content. An empty list the protocols it supports to save the file content. An empty list
means that no restriction is applied (the default). means that no restriction is applied (the default).
Supported for local files ("file" scheme) is implicit and always enabled; Support for local files ("file" scheme) is implicit and always enabled;
it is not necessary to include it in the restriction. it is not necessary to include it in the restriction.
When possible, this static function will use the native file dialog and When possible, this static function uses the native file dialog and
not a QFileDialog. On platforms which don't support selecting remote not a QFileDialog. On platforms that don't support selecting remote
files, Qt will allow to select only local files. files, Qt will allow to select only local files.
\sa getSaveFileName(), getOpenFileUrl(), getOpenFileUrls(), getExistingDirectoryUrl() \sa getSaveFileName(), getOpenFileUrl(), getOpenFileUrls(), getExistingDirectoryUrl()
@ -2499,25 +2502,25 @@ QUrl QFileDialog::getSaveFileUrl(QWidget *parent,
} }
/*! /*!
This is a convenience static function that will return an existing This is a convenience static function that returns an existing
directory selected by the user. directory selected by the user.
\snippet code/src_gui_dialogs_qfiledialog.cpp 12 \snippet code/src_gui_dialogs_qfiledialog.cpp 12
This function creates a modal file dialog with the given \a parent widget. This function creates a modal file dialog with the given \a parent widget.
If \a parent is not \nullptr, the dialog will be shown centered over the If \a parent is not \nullptr, the dialog is shown centered over the
parent widget. parent widget.
The dialog's working directory is set to \a dir, and the caption is set to The dialog's working directory is set to \a dir, and the caption is set to
\a caption. Either of these may be an empty string in which case the \a caption. Either of these can be an empty string in which case the
current directory and a default caption will be used respectively. current directory and a default caption are used respectively.
The \a options argument holds various options about how to run the dialog, The \a options argument holds various options about how to run the dialog.
see the QFileDialog::Option enum for more information on the flags you can See the QFileDialog::Option enum for more information on the flags you can
pass. To ensure a native file dialog, \l{QFileDialog::}{ShowDirsOnly} must pass. To ensure a native file dialog, \l{QFileDialog::}{ShowDirsOnly} must
be set. be set.
On Windows and \macos, this static function will use the On Windows and \macos, this static function uses the
native file dialog and not a QFileDialog. However, the native Windows file native file dialog and not a QFileDialog. However, the native Windows file
dialog does not support displaying files in the directory chooser. You need dialog does not support displaying files in the directory chooser. You need
to pass \l{QFileDialog::}{DontUseNativeDialog} to display files using a to pass \l{QFileDialog::}{DontUseNativeDialog} to display files using a
@ -2527,16 +2530,16 @@ QUrl QFileDialog::getSaveFileUrl(QWidget *parent,
On Unix/X11, the normal behavior of the file dialog is to resolve and On Unix/X11, the normal behavior of the file dialog is to resolve and
follow symlinks. For example, if \c{/usr/tmp} is a symlink to \c{/var/tmp}, follow symlinks. For example, if \c{/usr/tmp} is a symlink to \c{/var/tmp},
the file dialog will change to \c{/var/tmp} after entering \c{/usr/tmp}. If the file dialog changes to \c{/var/tmp} after entering \c{/usr/tmp}. If
\a options includes DontResolveSymlinks, the file dialog will treat \a options includes DontResolveSymlinks, the file dialog treats
symlinks as regular directories. symlinks as regular directories.
On Windows, the dialog will spin a blocking modal event loop that will not On Windows, the dialog spins a blocking modal event loop that does not
dispatch any QTimers, and if \a parent is not \nullptr then it will position dispatch any QTimers, and if \a parent is not \nullptr then it positions
the dialog just below the parent's title bar. the dialog just below the parent's title bar.
\warning Do not delete \a parent during the execution of the dialog. If you \warning Do not delete \a parent during the execution of the dialog. If you
want to do this, you should create the dialog yourself using one of the want to do this, you must create the dialog yourself using one of the
QFileDialog constructors. QFileDialog constructors.
\sa getOpenFileName(), getOpenFileNames(), getSaveFileName() \sa getOpenFileName(), getOpenFileNames(), getSaveFileName()
@ -2556,28 +2559,28 @@ QString QFileDialog::getExistingDirectory(QWidget *parent,
} }
/*! /*!
This is a convenience static function that will return an existing This is a convenience static function that returns an existing
directory selected by the user. If the user presses Cancel, it directory selected by the user. If the user presses Cancel, it
returns an empty url. returns an empty url.
The function is used similarly to QFileDialog::getExistingDirectory(). The function is used similarly to QFileDialog::getExistingDirectory().
In particular \a parent, \a caption, \a dir and \a options are used In particular \a parent, \a caption, \a dir and \a options are used
in the exact same way. in exactly the same way.
The main difference with QFileDialog::getExistingDirectory() comes from The main difference with QFileDialog::getExistingDirectory() comes from
the ability offered to the user to select a remote directory. That's why the ability offered to the user to select a remote directory. That's why
the return type and the type of \a dir is QUrl. the return type and the type of \a dir is QUrl.
The \a supportedSchemes argument allows to restrict the type of URLs the The \a supportedSchemes argument allows to restrict the type of URLs the
user will be able to select. It is a way for the application to declare user is able to select. It is a way for the application to declare
the protocols it will support to fetch the file content. An empty list the protocols it supports to fetch the file content. An empty list
means that no restriction is applied (the default). means that no restriction is applied (the default).
Supported for local files ("file" scheme) is implicit and always enabled; Support for local files ("file" scheme) is implicit and always enabled;
it is not necessary to include it in the restriction. it is not necessary to include it in the restriction.
When possible, this static function will use the native file dialog and When possible, this static function uses the native file dialog and
not a QFileDialog. On platforms which don't support selecting remote not a QFileDialog. On platforms that don't support selecting remote
files, Qt will allow to select only local files. files, Qt allows to select only local files.
\sa getExistingDirectory(), getOpenFileUrl(), getOpenFileUrls(), getSaveFileUrl() \sa getExistingDirectory(), getOpenFileUrl(), getOpenFileUrls(), getSaveFileUrl()
\since 5.2 \since 5.2
@ -3143,8 +3146,8 @@ void QFileDialogPrivate::_q_showHeader(QAction *action)
want to modify the underlying model; for example, to add columns, filter want to modify the underlying model; for example, to add columns, filter
data or add drives. data or add drives.
Any existing proxy model will be removed, but not deleted. The file dialog Any existing proxy model is removed, but not deleted. The file dialog
will take ownership of the \a proxyModel. takes ownership of the \a proxyModel.
\sa proxyModel() \sa proxyModel()
*/ */

BIN
src/widgets/doc/images/qtquickdialogs-filedialog-gtk.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 39 KiB