diff options
Diffstat (limited to 'src/webenginewidgets/doc/src/qwebenginesettings_lgpl.qdoc')
| -rw-r--r-- | src/webenginewidgets/doc/src/qwebenginesettings_lgpl.qdoc | 578 |
1 files changed, 578 insertions, 0 deletions
diff --git a/src/webenginewidgets/doc/src/qwebenginesettings_lgpl.qdoc b/src/webenginewidgets/doc/src/qwebenginesettings_lgpl.qdoc new file mode 100644 index 000000000..e24ab64e1 --- /dev/null +++ b/src/webenginewidgets/doc/src/qwebenginesettings_lgpl.qdoc @@ -0,0 +1,578 @@ +/* + Copyright (C) 2008 Nokia Corporation and/or its subsidiary(-ies) + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Library General Public + License as published by the Free Software Foundation; either + version 2 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Library General Public License for more details. + + You should have received a copy of the GNU Library General Public License + along with this library; see the file COPYING.LIB. If not, write to + the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. +*/ + +// The documentation in this file was imported from QtWebKit and is thus constrained +// by its LGPL license. Documentation written from scratch for new methods should be +// placed inline in the code as usual. + +/*! + \class QWebSettings + \since 4.4 + \brief The QWebSettings class provides an object to store the settings used + by QWebPage and QWebFrame. + + \inmodule QtWebKit + + Each QWebPage object has its own QWebSettings object, which configures the + settings for that page. If a setting is not configured, then it is looked + up in the global settings object, which can be accessed using + globalSettings(). + + QWebSettings allows configuration of browser properties, such as font sizes and + families, the location of a custom style sheet, and generic attributes like + JavaScript and plugins. Individual attributes are set using the setAttribute() + function. The \l{QWebSettings::WebAttribute}{WebAttribute} enum further describes + each attribute. + + QWebSettings also configures global properties such as the web page memory + cache, icon database, local database storage and offline + applications storage. + + \section1 Enabling Plugins + + Support for browser plugins can enabled by setting the + \l{QWebSettings::PluginsEnabled}{PluginsEnabled} attribute. For many applications, + this attribute is enabled for all pages by setting it on the + \l{globalSettings()}{global settings object}. Qt WebKit will always ignore this setting + when processing Qt plugins. The decision to allow a Qt plugin is made by the client + in its reimplementation of QWebPage::createPlugin(). + + \section1 Web Application Support + + WebKit provides support for features specified in \l{HTML 5} that improve the + performance and capabilities of Web applications. These include client-side + (offline) storage and the use of a Web application cache. + + Client-side (offline) storage is an improvement over the use of cookies to + store persistent data in Web applications. Applications can configure and + enable the use of an offline storage database by calling the + setOfflineStoragePath() with an appropriate file path, and can limit the quota + for each application by calling setOfflineStorageDefaultQuota(). + + \sa QWebPage::settings(), QWebView::settings(), {Web Browser} +*/ + +/*! + \fn QWebSettings* QWebSettings::globalSettings() + Returns the global settings object. + + Any setting changed on the default object is automatically applied to all + QWebPage instances where the particular setting is not overridden already. +*/ + +/*! + \enum QWebSettings::FontFamily + + This enum describes the generic font families defined by CSS 2. + For more information see the + \l{http://www.w3.org/TR/REC-CSS2/fonts.html#generic-font-families}{CSS standard}. + + \value StandardFont + \value FixedFont + \value SerifFont + \value SansSerifFont + \value CursiveFont + \value FantasyFont +*/ + +/*! + \enum QWebSettings::FontSize + + This enum describes the font sizes configurable through QWebSettings. + + \value MinimumFontSize The hard minimum font size. + \value MinimumLogicalFontSize The minimum logical font size that is applied + when zooming out with QWebFrame::setTextSizeMultiplier(). + \value DefaultFontSize The default font size for regular text. + \value DefaultFixedFontSize The default font size for fixed-pitch text. +*/ + +/*! + \enum QWebSettings::ThirdPartyCookiePolicy + + This enum describes the policies configurable for accepting and sending + third-party cookies. These are cookies that are set or retrieved when fetching + a resource that is stored for a different registry-controlled domain from the page containing it. + + \value AlwaysAllowThirdPartyCookies Allow third-party resources to set and retrieve cookies. + \value AlwaysBlockThirdPartyCookies Never allow third-party resources to set and retrieve cookies. + \value AllowThirdPartyWithExistingCookies If the cookie jar already contains cookies + from a third-party, allow it to set and retrieve new and existing cookies. + + \since QtWebKit 2,3 +*/ + +/*! + \enum QWebSettings::WebGraphic + + This enums describes the standard graphical elements used in webpages. + + \value MissingImageGraphic The replacement graphic shown when an image could not be loaded. + \value MissingPluginGraphic The replacement graphic shown when a plugin could not be loaded. + \value DefaultFrameIconGraphic The default icon for QWebFrame::icon(). + \value TextAreaSizeGripCornerGraphic The graphic shown for the size grip of text areas. + \value DeleteButtonGraphic The graphic shown for the WebKit-Editing-Delete-Button in Deletion UI. + \value InputSpeechButtonGraphic The graphic shown in input fields that support speech recognition. + \value SearchCancelButtonGraphic The graphic shown for clearing the text in a search field. + \value SearchCancelButtonPressedGraphic The graphic shown when SearchCancelButtonGraphic is pressed. +*/ + +/*! + \enum QWebSettings::WebAttribute + + This enum describes various attributes that are configurable through QWebSettings. + + \value AutoLoadImages Specifies whether images are automatically loaded in + web pages. This is enabled by default. + \value DnsPrefetchEnabled Specifies whether Qt WebKit will try to pre-fetch DNS entries to + speed up browsing. This only works as a global attribute. Only for Qt 4.6 and later. This is disabled by default. + \value JavascriptEnabled Enables or disables the running of JavaScript + programs. This is enabled by default + \value JavaEnabled Enables or disables Java applets. + Currently Java applets are not supported. + \value PluginsEnabled Enables or disables plugins in Web pages (e.g. using NPAPI). Qt plugins + with a mimetype such as "application/x-qt-plugin" are not affected by this setting. This is disabled by default. + \value PrivateBrowsingEnabled Private browsing prevents WebKit from + recording visited pages in the history and storing web page icons. This is disabled by default. + \value JavascriptCanOpenWindows Specifies whether JavaScript programs + can open new windows. This is disabled by default. + \value JavascriptCanCloseWindows Specifies whether JavaScript programs + can close windows. This is disabled by default. + \value JavascriptCanAccessClipboard Specifies whether JavaScript programs + can read or write to the clipboard. This is disabled by default. + \value DeveloperExtrasEnabled Enables extra tools for Web developers. + Currently this enables the "Inspect" element in the context menu as + well as the use of QWebInspector which controls the web inspector + for web site debugging. This is disabled by default. + \value SpatialNavigationEnabled Enables or disables the Spatial Navigation + feature, which consists in the ability to navigate between focusable + elements in a Web page, such as hyperlinks and form controls, by using + Left, Right, Up and Down arrow keys. For example, if a user presses the + Right key, heuristics determine whether there is an element he might be + trying to reach towards the right and which element he probably wants. + This is disabled by default. + \value LinksIncludedInFocusChain Specifies whether hyperlinks should be + included in the keyboard focus chain. This is enabled by default. + \value ZoomTextOnly Specifies whether the zoom factor on a frame applies + only to the text or to all content. This is disabled by default. + \value PrintElementBackgrounds Specifies whether the background color and images + are also drawn when the page is printed. This is enabled by default. + \value OfflineStorageDatabaseEnabled Specifies whether support for the HTML 5 + offline storage feature is enabled or not. This is disabled by default. + \value OfflineWebApplicationCacheEnabled Specifies whether support for the HTML 5 + web application cache feature is enabled or not. This is disabled by default. + \value LocalStorageEnabled Specifies whether support for the HTML 5 + local storage feature is enabled or not. This is disabled by default. + (This value was introduced in 4.6.) + \value LocalStorageDatabaseEnabled \e{This enum value is deprecated.} Use + QWebSettings::LocalStorageEnabled instead. + \value LocalContentCanAccessRemoteUrls Specifies whether locally loaded documents are + allowed to access remote urls. This is disabled by default. For more information + about security origins and local vs. remote content see QWebSecurityOrigin. + (This value was introduced in 4.6.) + \value LocalContentCanAccessFileUrls Specifies whether locally loaded documents are + allowed to access other local urls. This is enabled by default. For more information + about security origins and local vs. remote content see QWebSecurityOrigin. + \value XSSAuditingEnabled Specifies whether load requests should be monitored for cross-site + scripting attempts. Suspicious scripts will be blocked and reported in the inspector's + JavaScript console. Enabling this feature might have an impact on performance + and it is disabled by default. + \value AcceleratedCompositingEnabled This feature, when used in conjunction with + QGraphicsWebView, accelerates animations of web content. CSS animations of the transform and + opacity properties will be rendered by composing the cached content of the animated elements. + This is enabled by default. + \value TiledBackingStoreEnabled This setting enables the tiled backing store feature + for a QGraphicsWebView. With the tiled backing store enabled, the web page contents in and around + the current visible area is speculatively cached to bitmap tiles. The tiles are automatically kept + in sync with the web page as it changes. Enabling tiling can significantly speed up painting heavy + operations like scrolling. Enabling the feature increases memory consumption. It does not work well + with contents using CSS fixed positioning (see also \l{QGraphicsWebView::}{resizesToContents} property). + \l{QGraphicsWebView::}{tiledBackingStoreFrozen} property allows application to temporarily + freeze the contents of the backing store. This is disabled by default. + \value FrameFlatteningEnabled With this setting each subframe is expanded to its contents. + On touch devices, it is desired to not have any scrollable sub parts of the page + as it results in a confusing user experience, with scrolling sometimes scrolling sub parts + and at other times scrolling the page itself. For this reason iframes and framesets are + barely usable on touch devices. This will flatten all the frames to become one scrollable page. + This is disabled by default. + \value SiteSpecificQuirksEnabled This setting enables WebKit's workaround for broken sites. It is + enabled by default. + \value CSSGridLayoutEnabled This setting enables support for the CSS 3 Grid Layout module. This + CSS module is currently only a draft and support for it is disabled by default. + \value ScrollAnimatorEnabled This setting enables animated scrolling. It is disabled by default. + \value CaretBrowsingEnabled This setting enables caret browsing. It is disabled by default. + \value NotificationsEnabled Specifies whether support for the HTML 5 web notifications is enabled + or not. This is enabled by default. +*/ + +/*! + \fn void QWebSettings::setFontSize(FontSize type, int size) + Sets the font size for \a type to \a size. +*/ + +/*! + \fn int QWebSettings::fontSize(FontSize type) const + Returns the default font size for \a type. +*/ + +/*! + \fn void QWebSettings::resetFontSize(FontSize type) + Resets the font size for \a type to the size specified in the global + settings object. + + This function has no effect on the global QWebSettings instance. +*/ + +/*! + \fn void QWebSettings::setUserStyleSheetUrl(const QUrl& location) + Specifies the location of a user stylesheet to load with every web page. + + The \a location must be either a path on the local filesystem, or a data URL + with UTF-8 and Base64 encoded data, such as: + + "data:text/css;charset=utf-8;base64,cCB7IGJhY2tncm91bmQtY29sb3I6IHJlZCB9Ow==" + + \note If the base64 data is not valid, the style will not be applied. + + \sa userStyleSheetUrl() +*/ + +/*! + \fn QUrl QWebSettings::userStyleSheetUrl() const + Returns the location of the user stylesheet. + + \sa setUserStyleSheetUrl() +*/ + +/*! + \fn void QWebSettings::setDefaultTextEncoding(const QString& encoding) + \since 4.6 + Specifies the default text encoding system. + + The \a encoding, must be a string describing an encoding such as "utf-8", + "iso-8859-1", etc. If left empty a default value will be used. For a more + extensive list of encoding names see \l{QTextCodec} + + \sa defaultTextEncoding() +*/ + +/*! + \fn QString QWebSettings::defaultTextEncoding() const + \since 4.6 + Returns the default text encoding. + + \sa setDefaultTextEncoding() +*/ + +/*! + \fn void QWebSettings::setIconDatabasePath(const QString& path) + Sets the path of the icon database to \a path. The icon database is used + to store "favicons" associated with web sites. + + \a path must point to an existing directory. + + Setting an empty path disables the icon database. + + \sa iconDatabasePath(), clearIconDatabase() +*/ + +/*! + \fn QString QWebSettings::iconDatabasePath() + Returns the path of the icon database or an empty string if the icon + database is disabled. + + \sa setIconDatabasePath(), clearIconDatabase() +*/ + +/*! + \fn void QWebSettings::clearIconDatabase() + Clears the icon database. +*/ + +/*! + \fn QIcon QWebSettings::iconForUrl(const QUrl& url) + Returns the web site's icon for \a url. + + If the web site does not specify an icon \b OR if the icon is not in the + database, a null QIcon is returned. + + \note The returned icon's size is arbitrary. + + \sa setIconDatabasePath() +*/ + +/*! + \fn void QWebSettings::setWebGraphic(WebGraphic type, const QPixmap& graphic) + Sets \a graphic to be drawn when Qt WebKit needs to draw an image of the + given \a type. + + For example, when an image cannot be loaded, the pixmap specified by + \l{QWebSettings::WebGraphic}{MissingImageGraphic} is drawn instead. + + \sa webGraphic() +*/ + +/*! + \fn QPixmap QWebSettings::webGraphic(WebGraphic type) + Returns a previously set pixmap used to draw replacement graphics of the + specified \a type. + + \sa setWebGraphic() +*/ + +/*! + \fn void QWebSettings::clearMemoryCaches() + Frees up as much memory as possible by calling the JavaScript garbage collector and cleaning all memory caches such + as page, object and font cache. + + \since 4.6 + */ + +/*! + \fn void QWebSettings::setMaximumPagesInCache(int pages) + Sets the maximum number of pages to hold in the memory page cache to \a pages. + + The Page Cache allows for a nicer user experience when navigating forth or back + to pages in the forward/back history, by pausing and resuming up to \a pages. + + For more information about the feature, please refer to: + + http://webkit.org/blog/427/webkit-page-cache-i-the-basics/ +*/ + +/*! + \fn int QWebSettings::maximumPagesInCache() + Returns the maximum number of web pages that are kept in the memory cache. +*/ + +/*! + \fn void QWebSettings::setObjectCacheCapacities(int cacheMinDeadCapacity, int cacheMaxDead, int totalCapacity) + Specifies the capacities for the memory cache for dead objects such as + stylesheets or scripts. + + The \a cacheMinDeadCapacity specifies the \e minimum number of bytes that + dead objects should consume when the cache is under pressure. + + \a cacheMaxDead is the \e maximum number of bytes that dead objects should + consume when the cache is \b not under pressure. + + \a totalCapacity specifies the \e maximum number of bytes that the cache + should consume \b overall. + + The cache is enabled by default. Calling setObjectCacheCapacities(0, 0, 0) + will disable the cache. Calling it with one non-zero enables it again. +*/ + +/*! + \fn void QWebSettings::setThirdPartyCookiePolicy(ThirdPartyCookiePolicy policy) + Sets the third-party cookie policy, the default is AlwaysAllowThirdPartyCookies. +*/ + +/*! + \fn QWebSettings::ThirdPartyCookiePolicy QWebSettings::thirdPartyCookiePolicy() const + Returns the third-party cookie policy. +*/ + +/*! + \fn void QWebSettings::setCSSMediaType(const QString& type) + Sets the CSS media type to \a type. + + Setting this will override the normal value of the CSS media property. + + \note Setting the value to null QString will restore the default value. +*/ + +/*! + \fn QString QWebSettings::cssMediaType() const + Returns the current CSS media type. + + \note It will only return the value set through setCSSMediaType and not the one used internally. +*/ + +/*! + \fn void QWebSettings::setFontFamily(FontFamily which, const QString& family) + Sets the actual font family to \a family for the specified generic family, + \a which. +*/ + +/*! + \fn QString QWebSettings::fontFamily(FontFamily which) const + Returns the actual font family for the specified generic font family, + \a which. +*/ + +/*! + \fn void QWebSettings::resetFontFamily(FontFamily which) + Resets the actual font family specified by \a which to the one set + in the global QWebSettings instance. + + This function has no effect on the global QWebSettings instance. +*/ + +/*! + \fn void QWebSettings::setAttribute(WebAttribute attribute, bool on) + + Enables or disables the specified \a attribute feature depending on the + value of \a on. +*/ + +/*! + \fn bool QWebSettings::testAttribute(WebAttribute attribute) const + + Returns true if \a attribute is enabled; otherwise returns false. +*/ + +/*! + \fn void QWebSettings::resetAttribute(WebAttribute attribute) + + Resets the setting of \a attribute to the value specified in the + global QWebSettings instance. + + This function has no effect on the global QWebSettings instance. + + \sa globalSettings() +*/ + +/*! + \fn void QWebSettings::setOfflineStoragePath(const QString& path) + \since 4.5 + + Sets \a path as the save location for HTML5 client-side database storage data. + + \a path must point to an existing directory. + + Setting an empty path disables the feature. + + Support for client-side databases can enabled by setting the + \l{QWebSettings::OfflineStorageDatabaseEnabled}{OfflineStorageDatabaseEnabled} attribute. + + \sa offlineStoragePath() +*/ + +/*! + \fn QString QWebSettings::offlineStoragePath() + \since 4.5 + + Returns the path of the HTML5 client-side database storage or an empty string if the + feature is disabled. + + \sa setOfflineStoragePath() +*/ + +/*! + \fn void QWebSettings::setOfflineStorageDefaultQuota(qint64 maximumSize) + \since 4.5 + + Sets the value of the default quota for new offline storage databases + to \a maximumSize. +*/ + +/*! + \fn qint64 QWebSettings::offlineStorageDefaultQuota() + \since 4.5 + + Returns the value of the default quota for new offline storage databases. +*/ + +/*! + \fn void QWebSettings::setOfflineWebApplicationCachePath(const QString& path) + \since 4.6 + + Sets the path for HTML5 offline web application cache storage to \a path. + + An application cache acts like an HTTP cache in some sense. For documents + that use the application cache via JavaScript, the loader engine will + first ask the application cache for the contents, before hitting the + network. + + The feature is described in details at: + http://dev.w3.org/html5/spec/Overview.html#appcache + + \a path must point to an existing directory. + + Setting an empty path disables the feature. + + Support for offline web application cache storage can enabled by setting the + \l{QWebSettings::OfflineWebApplicationCacheEnabled}{OfflineWebApplicationCacheEnabled} attribute. + + \sa offlineWebApplicationCachePath() +*/ + +/*! + \fn QString QWebSettings::offlineWebApplicationCachePath() + \since 4.6 + + Returns the path of the HTML5 offline web application cache storage + or an empty string if the feature is disabled. + + \sa setOfflineWebApplicationCachePath() +*/ + +/*! + \fn void QWebSettings::setOfflineWebApplicationCacheQuota(qint64 maximumSize) + \since 4.6 + + Sets the value of the quota for the offline web application cache + to \a maximumSize. +*/ + +/*! + \fn qint64 QWebSettings::offlineWebApplicationCacheQuota() + \since 4.6 + + Returns the value of the quota for the offline web application cache. +*/ + +/*! + \fn void QWebSettings::setLocalStoragePath(const QString& path) + \since 4.6 + + Sets the path for HTML5 local storage to \a path. + + For more information on HTML5 local storage see the + \l{http://www.w3.org/TR/webstorage/#the-localstorage-attribute}{Web Storage standard}. + + Support for local storage can enabled by setting the + \l{QWebSettings::LocalStorageEnabled}{LocalStorageEnabled} attribute. + + \sa localStoragePath() +*/ + +/*! + \fn QString QWebSettings::localStoragePath() const + \since 4.6 + + Returns the path for HTML5 local storage. + + \sa setLocalStoragePath() +*/ + +/*! + \fn void QWebSettings::enablePersistentStorage(const QString& path) + \since 4.6 + + Enables WebKit data persistence and sets the path to \a path. + If \a path is empty, the user-specific data location specified by + \l{QDesktopServices::DataLocation}{DataLocation} will be used instead. + + This method will simultaneously set and enable the iconDatabasePath(), + localStoragePath(), offlineStoragePath() and offlineWebApplicationCachePath(). + + \sa localStoragePath() +*/ |