Doc: Move the common documentation to a qdocinc
The member functions of QStandardPath and Qt.labs.platform.StandardPath behave the same, so it's ideal to maintain their documentation in one place. Task-number: QTBUG-79827 Change-Id: I349dbb85cd9b6a3bedac329c0707fc07057cd64b Reviewed-by: Paul Wicking <paul.wicking@qt.io>
This commit is contained in:
Venugopal Shivashankar
parent
52c8e9dc99
commit
c30ffe1d33
129
doc/global/includes/standardpath/functiondocs.qdocinc
Normal file
129
doc/global/includes/standardpath/functiondocs.qdocinc
Normal file
@ -0,0 +1,129 @@
|
||||
/****************************************************************************
|
||||
**
|
||||
** Copyright (C) 2019 The Qt Company Ltd.
|
||||
** Contact: https://www.qt.io/licensing/
|
||||
**
|
||||
** This file is part of the documentation of the Qt Toolkit.
|
||||
**
|
||||
** $QT_BEGIN_LICENSE:FDL$
|
||||
** Commercial License Usage
|
||||
** Licensees holding valid commercial Qt licenses may use this file in
|
||||
** accordance with the commercial license agreement provided with the
|
||||
** Software or, alternatively, in accordance with the terms contained in
|
||||
** a written agreement between you and The Qt Company. For licensing terms
|
||||
** and conditions see https://www.qt.io/terms-conditions. For further
|
||||
** information use the contact form at https://www.qt.io/contact-us.
|
||||
**
|
||||
** GNU Free Documentation License Usage
|
||||
** Alternatively, this file may be used under the terms of the GNU Free
|
||||
** Documentation License version 1.3 as published by the Free Software
|
||||
** Foundation and appearing in the file included in the packaging of
|
||||
** this file. Please review the following information to ensure
|
||||
** the GNU Free Documentation License version 1.3 requirements
|
||||
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
|
||||
** $QT_END_LICENSE$
|
||||
**
|
||||
****************************************************************************/
|
||||
|
||||
//! [displayName]
|
||||
|
||||
Returns a localized display name for the given location \a type
|
||||
or an empty QString if no relevant location can be found.
|
||||
|
||||
//! [displayName]
|
||||
|
||||
|
||||
//! [findExecutable]
|
||||
|
||||
Finds the executable named \a executableName in the specified
|
||||
\a paths, or the system paths if paths is empty.
|
||||
|
||||
On most operating systems the system path is determined by the
|
||||
\c PATH environment variable. The directories where to search for
|
||||
the executable can be set in the paths argument. To search in
|
||||
both your own paths and the system paths, call findExecutable
|
||||
twice, once with paths set and once with paths empty.
|
||||
Symlinks are not resolved in order to preserve behavior for the
|
||||
case of executables whose behavior depends on the name they are
|
||||
invoked with
|
||||
.
|
||||
\note On Windows, the usual executable extensions (from the PATHEXT
|
||||
environment variable) are automatically appended. For example, the
|
||||
findExecutable("foo") call finds \c foo.exe or \c foo.bat if
|
||||
present.
|
||||
|
||||
Returns the absolute file path to the executable, or an empty
|
||||
string if not found.
|
||||
|
||||
//! [findExecutable]
|
||||
|
||||
//! [locate]
|
||||
|
||||
Finds a file or directory called \a fileName in the standard
|
||||
locations for \a type.
|
||||
|
||||
The \a options flag lets you specify whether to look for files
|
||||
or directories. By default, this flag is set to \c LocateFile.
|
||||
|
||||
Returns the absolute path to the first file or directory found,
|
||||
otherwise returns an empty string.
|
||||
|
||||
//! [locate]
|
||||
|
||||
//! [locateAll]
|
||||
|
||||
Finds all files or directories by the name, \a fileName, in the
|
||||
standard locations for \a type.
|
||||
|
||||
The \a options flag lets you specify whether to look for files
|
||||
or directories. By default, this flag is set to \c LocateFile.
|
||||
|
||||
Returns the list of all the files that were found.
|
||||
|
||||
//! [locateAll]
|
||||
|
||||
//! [setTestModeEnabled]
|
||||
|
||||
If \a testMode is \c true, this enables a special "test mode" in
|
||||
QStandardPaths, which changes writable locations to point to
|
||||
test directories. This prevents auto tests from reading
|
||||
or writing to the current user's configuration.
|
||||
|
||||
It affects the locations into which test programs might write
|
||||
files: \c GenericDataLocation, \c DataLocation, \c ConfigLocation,
|
||||
\c GenericConfigLocation, \c AppConfigLocation,
|
||||
\c GenericCacheLocation, and \c CacheLocation. Other locations
|
||||
are not affected.
|
||||
|
||||
On Unix, \c XDG_DATA_HOME is set to \c{~/.qttest/share},
|
||||
\c XDG_CONFIG_HOME is set to \c{~/.qttest/config}, and
|
||||
\c XDG_CACHE_HOME is set to \c{~/.qttest/cache}.
|
||||
|
||||
On macOS, data goes to \c{~/.qttest/Application Support},
|
||||
cache goes to \c{~/.qttest/Cache}, and config goes to
|
||||
\c{~/.qttest/Preferences}.
|
||||
|
||||
On Windows, everything goes to a "qttest" directory under
|
||||
\c{%APPDATA%}.
|
||||
|
||||
//! [setTestModeEnabled]
|
||||
|
||||
//! [standardLocations]
|
||||
|
||||
Returns all the directories where files of \a type belong.
|
||||
|
||||
The list of directories is sorted from high to low priority,
|
||||
starting with writableLocation() if it can be determined.
|
||||
This list is empty if no locations for type are defined.
|
||||
|
||||
//! [standardLocations]
|
||||
|
||||
//! [writableLocation]
|
||||
|
||||
Returns the directory where files of \a type should be written to,
|
||||
or an empty string if the location cannot be determined.
|
||||
|
||||
\note The storage location returned may not exist; that is,
|
||||
it may need to be created by the system or the user.
|
||||
|
||||
//! [writableLocation]
|
||||
@ -357,22 +357,14 @@ QT_BEGIN_NAMESPACE
|
||||
/*!
|
||||
\fn QString QStandardPaths::writableLocation(StandardLocation type)
|
||||
|
||||
Returns the directory where files of \a type should be written to, or an empty string
|
||||
if the location cannot be determined.
|
||||
|
||||
\note The storage location returned can be a directory that does not exist; i.e., it
|
||||
may need to be created by the system or the user.
|
||||
\include standardpath/functiondoc.qdocinc writableLocation
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn QStringList QStandardPaths::standardLocations(StandardLocation type)
|
||||
|
||||
Returns all the directories where files of \a type belong.
|
||||
|
||||
The list of directories is sorted from high to low priority, starting with
|
||||
writableLocation() if it can be determined. This list is empty if no locations
|
||||
for \a type are defined.
|
||||
\include standardpath/functiondoc.qdocinc standardLocations
|
||||
|
||||
\sa writableLocation()
|
||||
*/
|
||||
@ -396,11 +388,7 @@ static bool existsAsSpecified(const QString &path, QStandardPaths::LocateOptions
|
||||
}
|
||||
|
||||
/*!
|
||||
Tries to find a file or directory called \a fileName in the standard locations
|
||||
for \a type.
|
||||
|
||||
The full path to the first file or directory (depending on \a options) found is returned.
|
||||
If no such file or directory can be found, an empty string is returned.
|
||||
\include standardpath/functiondoc.qdocinc locate
|
||||
*/
|
||||
QString QStandardPaths::locate(StandardLocation type, const QString &fileName, LocateOptions options)
|
||||
{
|
||||
@ -414,12 +402,7 @@ QString QStandardPaths::locate(StandardLocation type, const QString &fileName, L
|
||||
}
|
||||
|
||||
/*!
|
||||
Tries to find all files or directories called \a fileName in the standard locations
|
||||
for \a type.
|
||||
|
||||
The \a options flag allows to specify whether to look for files or directories.
|
||||
|
||||
Returns the list of all the files that were found.
|
||||
\include standardpath/functiondoc.qdocinc locateAll
|
||||
*/
|
||||
QStringList QStandardPaths::locateAll(StandardLocation type, const QString &fileName, LocateOptions options)
|
||||
{
|
||||
@ -492,23 +475,7 @@ static inline QString
|
||||
#endif // Q_OS_WIN
|
||||
|
||||
/*!
|
||||
Finds the executable named \a executableName in the paths specified by \a paths,
|
||||
or the system paths if \a paths is empty.
|
||||
|
||||
On most operating systems the system path is determined by the PATH environment variable.
|
||||
|
||||
The directories where to search for the executable can be set in the \a paths argument.
|
||||
To search in both your own paths and the system paths, call findExecutable twice, once with
|
||||
\a paths set and once with \a paths empty.
|
||||
|
||||
Symlinks are not resolved, in order to preserve behavior for the case of executables
|
||||
whose behavior depends on the name they are invoked with.
|
||||
|
||||
\note On Windows, the usual executable extensions (from the PATHEXT environment variable)
|
||||
are automatically appended, so that for instance findExecutable("foo") will find foo.exe
|
||||
or foo.bat if present.
|
||||
|
||||
Returns the absolute file path to the executable, or an empty string if not found.
|
||||
\include standardpath/functiondoc.qdocinc findExecutable
|
||||
*/
|
||||
QString QStandardPaths::findExecutable(const QString &executableName, const QStringList &paths)
|
||||
{
|
||||
@ -566,10 +533,7 @@ QString QStandardPaths::findExecutable(const QString &executableName, const QStr
|
||||
}
|
||||
|
||||
/*!
|
||||
\fn QString QStandardPaths::displayName(StandardLocation type)
|
||||
|
||||
Returns a localized display name for the given location \a type or
|
||||
an empty QString if no relevant location can be found.
|
||||
\include standardpath/functiondoc.qdocinc displayName
|
||||
*/
|
||||
|
||||
#if !defined(Q_OS_MAC) && !defined(QT_BOOTSTRAPPED)
|
||||
@ -626,23 +590,7 @@ QString QStandardPaths::displayName(StandardLocation type)
|
||||
/*!
|
||||
\fn void QStandardPaths::setTestModeEnabled(bool testMode)
|
||||
|
||||
If \a testMode is true, this enables a special "test mode" in
|
||||
QStandardPaths, which changes writable locations
|
||||
to point to test directories, in order to prevent auto tests from reading from
|
||||
or writing to the current user's configuration.
|
||||
|
||||
This affects the locations into which test programs might write files:
|
||||
GenericDataLocation, DataLocation, ConfigLocation, GenericConfigLocation,
|
||||
AppConfigLocation, GenericCacheLocation, CacheLocation.
|
||||
Other locations are not affected.
|
||||
|
||||
On Unix, \c XDG_DATA_HOME is set to \e ~/.qttest/share, \c XDG_CONFIG_HOME is
|
||||
set to \e ~/.qttest/config, and \c XDG_CACHE_HOME is set to \e ~/.qttest/cache.
|
||||
|
||||
On \macos, data goes to \e ~/.qttest/Application Support, cache goes to
|
||||
\e ~/.qttest/Cache, and config goes to \e ~/.qttest/Preferences.
|
||||
|
||||
On Windows, everything goes to a "qttest" directory under Application Data.
|
||||
\include standardpath/functiondoc.qdocinc setTestModeEnabled
|
||||
*/
|
||||
|
||||
static bool qsp_testMode = false;
|
||||
|
||||
Loading…
Reference in New Issue
Block a user