QWebEngineProfile Class
The QWebEngineProfile class provides a web engine profile shared by multiple pages. More...
Header: | #include <QWebEngineProfile> |
qmake: | QT += webenginewidgets |
Since: | Qt 5.5 |
Inherits: | QObject |
Public Types
enum | HttpCacheType { MemoryHttpCache, DiskHttpCache, NoCache } |
enum | PersistentCookiesPolicy { NoPersistentCookies, AllowPersistentCookies, ForcePersistentCookies } |
Public Functions
QWebEngineProfile(QObject *parent = Q_NULLPTR) | |
QWebEngineProfile(const QString &storageName, QObject *parent = Q_NULLPTR) | |
QString | cachePath() const |
void | clearAllVisitedLinks() |
void | clearHttpCache() |
void | clearVisitedLinks(const QList<QUrl> &urls) |
QWebEngineCookieStore * | cookieStore() |
QString | httpAcceptLanguage() const |
int | httpCacheMaximumSize() const |
HttpCacheType | httpCacheType() const |
QString | httpUserAgent() const |
void | installUrlSchemeHandler(const QByteArray &scheme, QWebEngineUrlSchemeHandler *handler) |
bool | isOffTheRecord() const |
bool | isSpellCheckEnabled() const |
PersistentCookiesPolicy | persistentCookiesPolicy() const |
QString | persistentStoragePath() const |
void | removeAllUrlSchemeHandlers() |
void | removeUrlScheme(const QByteArray &scheme) |
void | removeUrlSchemeHandler(QWebEngineUrlSchemeHandler *handler) |
QWebEngineScriptCollection * | scripts() const |
void | setCachePath(const QString &path) |
void | setHttpAcceptLanguage(const QString &httpAcceptLanguage) |
void | setHttpCacheMaximumSize(int maxSize) |
void | setHttpCacheType(QWebEngineProfile::HttpCacheType httpCacheType) |
void | setHttpUserAgent(const QString &userAgent) |
void | setPersistentCookiesPolicy(QWebEngineProfile::PersistentCookiesPolicy newPersistentCookiesPolicy) |
void | setPersistentStoragePath(const QString &path) |
void | setRequestInterceptor(QWebEngineUrlRequestInterceptor *interceptor) |
void | setSpellCheckEnabled(bool enable) |
void | setSpellCheckLanguages(const QStringList &languages) |
QWebEngineSettings * | settings() const |
QStringList | spellCheckLanguages() const |
QString | storageName() const |
const QWebEngineUrlSchemeHandler * | urlSchemeHandler(const QByteArray &scheme) const |
bool | visitedLinksContainsUrl(const QUrl &url) const |
- 32 public functions inherited from QObject
Signals
void | downloadRequested(QWebEngineDownloadItem *download) |
- 2 signals inherited from QObject
Static Public Members
QWebEngineProfile * | defaultProfile() |
- 11 static public members inherited from QObject
Additional Inherited Members
- 1 property inherited from QObject
- 1 public slot inherited from QObject
- 9 protected functions inherited from QObject
Detailed Description
The QWebEngineProfile class provides a web engine profile shared by multiple pages.
A web engine profile contains settings, scripts, persistent cookie policy, and the list of visited links shared by all web engine pages that belong to the profile.
All pages that belong to the profile share a common QWebEngineSettings instance, which can be accessed with the settings() method. Likewise, the scripts() method provides access to a common QWebEngineScriptCollection instance.
Information about visited links is stored together with persistent cookies and other persistent data in a storage returned by persistentStoragePath(). The cache can be cleared of links by clearVisitedLinks() or clearAllVisitedLinks(). PersistentCookiesPolicy describes whether session and persistent cookies are saved to and restored from memory or disk.
Profiles can be used to isolate pages from each other. A typical use case is a dedicated off-the-record profile for a private browsing mode. Using QWebEngineProfile() without defining a storage name constructs a new off-the-record profile that leaves no record on the local machine, and has no persistent data or cache. The isOffTheRecord() method can be used to check whether a profile is off-the-record.
The default profile can be accessed by defaultProfile(). It is a built-in profile that all web pages not specifically created with another profile belong to.
Implementing the QWebEngineUrlRequestInterceptor interface and registering the interceptor on a profile by setRequestInterceptor() enables intercepting, blocking, and modifying URL requests (QWebEngineUrlRequestInfo) before they reach the networking stack of Chromium.
A QWebEngineUrlSchemeHandler can be registered for a profile by installUrlSchemeHandler() to add support for custom URL schemes. Requests for the scheme are then issued to QWebEngineUrlSchemeHandler::requestStarted() as QWebEngineUrlRequestJob objects.
Spellchecking HTML form fields can be enabled per profile by using the setSpellCheckEnabled() method and the current languages used for spellchecking can be set by using the setSpellCheckLanguages() method.
Member Type Documentation
enum QWebEngineProfile::HttpCacheType
This enum describes the HTTP cache type:
Constant | Value | Description |
---|---|---|
QWebEngineProfile::MemoryHttpCache |
0 |
Use an in-memory cache. This is the only setting possible if off-the-record is set or no cache path is available. |
QWebEngineProfile::DiskHttpCache |
1 |
Use a disk cache. This is the default. |
QWebEngineProfile::NoCache |
2 |
Disable both in-memory and disk caching. (Added in Qt 5.7) |
enum QWebEngineProfile::PersistentCookiesPolicy
This enum describes policy for cookie persistency:
Constant | Value | Description |
---|---|---|
QWebEngineProfile::NoPersistentCookies |
0 |
Both session and persistent cookies are stored in memory. This is the only setting possible if off-the-record is set or no persistent data path is available. |
QWebEngineProfile::AllowPersistentCookies |
1 |
Cookies marked persistent are saved to and restored from disk, whereas session cookies are only stored to disk for crash recovery. This is the default setting. |
QWebEngineProfile::ForcePersistentCookies |
2 |
Both session and persistent cookies are saved to and restored from disk. |
Member Function Documentation
QWebEngineProfile::QWebEngineProfile(QObject *parent = Q_NULLPTR)
Constructs a new off-the-record profile with the parent parent.
An off-the-record profile leaves no record on the local machine, and has no persistent data or cache. Thus, the HTTP cache can only be in memory and the cookies can only be non-persistent. Trying to change these settings will have no effect.
See also isOffTheRecord().
QWebEngineProfile::QWebEngineProfile(const QString &storageName, QObject *parent = Q_NULLPTR)
Constructs a new profile with the storage name storageName and parent parent.
The storage name must be unique.
A disk-based QWebEngineProfile should be destroyed on or before application exit, otherwise the cache and persistent data may not be fully flushed to disk.
See also storageName().
QString QWebEngineProfile::cachePath() const
Returns the path used for caches.
By default, this is below QStandardPaths::writableLocation() in a storage name specific directory.
See also setCachePath(), storageName(), and QStandardPaths::writableLocation().
void QWebEngineProfile::clearAllVisitedLinks()
Clears all links from the visited links database.
See also clearVisitedLinks().
void QWebEngineProfile::clearHttpCache()
Removes the profile's cache entries.
This function was introduced in Qt 5.7.
void QWebEngineProfile::clearVisitedLinks(const QList<QUrl> &urls)
Clears the links in urls from the visited links database.
See also clearAllVisitedLinks().
QWebEngineCookieStore *QWebEngineProfile::cookieStore()
Returns the cookie store for this profile.
This function was introduced in Qt 5.6.
[static]
QWebEngineProfile *QWebEngineProfile::defaultProfile()
Returns the default profile.
The default profile uses the storage name "Default".
See also storageName().
[signal]
void QWebEngineProfile::downloadRequested(QWebEngineDownloadItem *download)
This signal is emitted whenever a download has been triggered. The download argument holds the state of the download. The download has to be explicitly accepted with QWebEngineDownloadItem::accept() or it will be cancelled by default. The download item is parented by the profile. If it is not accepted, it will be deleted immediately after the signal emission. This signal cannot be used with a queued connection.
This function was introduced in Qt 5.5.
See also QWebEngineDownloadItem.
QString QWebEngineProfile::httpAcceptLanguage() const
Returns the value of the Accept-Language HTTP request-header field.
This function was introduced in Qt 5.6.
See also setHttpAcceptLanguage().
int QWebEngineProfile::httpCacheMaximumSize() const
Returns the maximum size of the HTTP cache in bytes.
Will return 0
if the size is automatically controlled by QtWebEngine.
See also setHttpCacheMaximumSize() and httpCacheType().
HttpCacheType QWebEngineProfile::httpCacheType() const
Returns the type of HTTP cache used.
If the profile is off-the-record, MemoryHttpCache is returned.
See also setHttpCacheType() and cachePath().
QString QWebEngineProfile::httpUserAgent() const
Returns the user-agent string sent with HTTP to identify the browser.
Note: On Windows 8.1 and newer, the default user agent will always report "Windows NT 6.2" (Windows 8), unless the application does contain a manifest that declares newer Windows versions as supported.
See also setHttpUserAgent().
void QWebEngineProfile::installUrlSchemeHandler(const QByteArray &scheme, QWebEngineUrlSchemeHandler *handler)
Registers a handler handler for custom URL scheme scheme in the profile.
This function was introduced in Qt 5.6.
bool QWebEngineProfile::isOffTheRecord() const
Returns true
if this is an off-the-record profile that leaves no record on the computer.
This will force cookies and HTTP cache to be in memory, but also force all other normally persistent data to be stored in memory.
bool QWebEngineProfile::isSpellCheckEnabled() const
Returns true
if the spell checker is enabled; otherwise returns false
.
This function was introduced in Qt 5.8.
See also setSpellCheckEnabled().
PersistentCookiesPolicy QWebEngineProfile::persistentCookiesPolicy() const
Returns the current policy for persistent cookies.
If the profile is off-the-record, NoPersistentCookies is returned.
See also setPersistentCookiesPolicy().
QString QWebEngineProfile::persistentStoragePath() const
Returns the path used to store persistent data for the browser and web content.
Persistent data includes persistent cookies, HTML5 local storage, and visited links.
By default, this is below QStandardPaths::writableLocation() in a storage name specific directory.
See also setPersistentStoragePath(), storageName(), and QStandardPaths::writableLocation().
void QWebEngineProfile::removeAllUrlSchemeHandlers()
Removes all custom URL scheme handlers installed in the profile.
This function was introduced in Qt 5.6.
void QWebEngineProfile::removeUrlScheme(const QByteArray &scheme)
Removes the custom URL scheme scheme from the profile.
This function was introduced in Qt 5.6.
See also removeUrlSchemeHandler().
void QWebEngineProfile::removeUrlSchemeHandler(QWebEngineUrlSchemeHandler *handler)
Removes the custom URL scheme handler handler from the profile.
This function was introduced in Qt 5.6.
See also removeUrlScheme().
QWebEngineScriptCollection *QWebEngineProfile::scripts() const
Returns the collection of scripts that are injected into all pages that share this profile.
See also QWebEngineScriptCollection, QWebEngineScript, and QWebEnginePage::scripts().
void QWebEngineProfile::setCachePath(const QString &path)
Overrides the default path used for disk caches, setting it to path.
If set to the null string, the default path is restored.
See also cachePath().
void QWebEngineProfile::setHttpAcceptLanguage(const QString &httpAcceptLanguage)
Sets the value of the Accept-Language HTTP request-header field to httpAcceptLanguage.
This function was introduced in Qt 5.6.
See also httpAcceptLanguage().
void QWebEngineProfile::setHttpCacheMaximumSize(int maxSize)
Sets the maximum size of the HTTP cache to maxSize bytes.
Setting it to 0
means the size will be controlled automatically by QtWebEngine.
See also httpCacheMaximumSize() and setHttpCacheType().
void QWebEngineProfile::setHttpCacheType(QWebEngineProfile::HttpCacheType httpCacheType)
Sets the HTTP cache type to httpCacheType.
See also httpCacheType() and setCachePath().
void QWebEngineProfile::setHttpUserAgent(const QString &userAgent)
Overrides the default user-agent string, setting it to userAgent.
See also httpUserAgent().
void QWebEngineProfile::setPersistentCookiesPolicy(QWebEngineProfile::PersistentCookiesPolicy newPersistentCookiesPolicy)
Sets the policy for persistent cookies to newPersistentCookiesPolicy.
See also persistentCookiesPolicy().
void QWebEngineProfile::setPersistentStoragePath(const QString &path)
Overrides the default path used to store persistent web engine data.
If path is set to the null string, the default path is restored.
See also persistentStoragePath().
void QWebEngineProfile::setRequestInterceptor(QWebEngineUrlRequestInterceptor *interceptor)
Registers a request interceptor singleton interceptor to intercept URL requests.
The profile does not take ownership of the pointer.
This function was introduced in Qt 5.6.
See also QWebEngineUrlRequestInfo.
void QWebEngineProfile::setSpellCheckEnabled(bool enable)
Enables spell checker if enable is true
, otherwise disables it.
This function was introduced in Qt 5.8.
See also isSpellCheckEnabled().
void QWebEngineProfile::setSpellCheckLanguages(const QStringList &languages)
Sets the current list of languages for the spell checker. Each language should match the name of the .bdic
dictionary. For example, the language en-US
will load the en-US.bdic
dictionary file.
Qt WebEngine checks for the qtwebengine_dictionaries
subdirectory first in the local directory and if it is not found, in the Qt installation directory.
On macOS, depending on how Qt WebEngine is configured at build time, there are two possibilities how spellchecking data is found:
- Hunspell dictionaries (default) - .bdic dictionaries are used, just like on other platforms
- Native dictionaries - the macOS spellchecking APIs are used (which means the results will depend on the installed OS dictionaries)
Thus, in the macOS Hunspell case, Qt WebEngine will look in the qtwebengine_dictionaries subdirectory located inside the application bundle Resources
directory, and also in the Resources
directory located inside the Qt framework bundle.
To summarize, in case of Hunspell usage, the following paths are considered:
- QCoreApplication::applicationDirPath()/qtwebengine_dictionaries or QCoreApplication::applicationDirPath()/../Contents/Resources/qtwebengine_dictionaries (on macOS)
- [QLibraryInfo::DataPath]/qtwebengine_dictionaries or path/to/QtWebEngineCore.framework/Resources/qtwebengine_dictionaries (Qt framework bundle on macOS)
For more information about how to compile .bdic
dictionaries, see the Spellchecker Example.
This function was introduced in Qt 5.8.
See also spellCheckLanguages().
QWebEngineSettings *QWebEngineProfile::settings() const
Returns the default settings for all pages in this profile.
QStringList QWebEngineProfile::spellCheckLanguages() const
Returns the list of languages used by the spell checker.
This function was introduced in Qt 5.8.
See also setSpellCheckLanguages().
QString QWebEngineProfile::storageName() const
Returns the storage name for the profile.
The storage name is used to give each profile that uses the disk separate subdirectories for persistent data and cache.
const QWebEngineUrlSchemeHandler *QWebEngineProfile::urlSchemeHandler(const QByteArray &scheme) const
Returns the custom URL scheme handler register for the URL scheme scheme.
This function was introduced in Qt 5.6.
bool QWebEngineProfile::visitedLinksContainsUrl(const QUrl &url) const
Returns true
if url is considered a visited link by this profile.
© The Qt Company Ltd
Licensed under the GNU Free Documentation License, Version 1.3.
https://doc.qt.io/qt-5.9/qwebengineprofile.html