diff options
19 files changed, 4741 insertions, 0 deletions
diff --git a/src/webengine/doc/src/qquickwebengineview_lgpl.qdoc b/src/webengine/doc/src/qquickwebengineview_lgpl.qdoc new file mode 100644 index 000000000..2a72eb1e8 --- /dev/null +++ b/src/webengine/doc/src/qquickwebengineview_lgpl.qdoc @@ -0,0 +1,396 @@ +/* + * Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies) + * Copyright (c) 2012 Hewlett-Packard Development Company, L.P. + * Copyright (C) 2013 Digia Plc 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 program 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 program; 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. + +/*! + \page qtwebkit-index.html + \title Qt WebKit + + The Qt WebKit module provides the WebView API which allows QML applications + to render regions of dynamic web content. A \e{WebView} component may share + the screen with other QML components or encompass the full screen as + specified within the QML application. + + QML WebView version 3.0 is incompatible with previous QML \l + {QtWebKit1::WebView} {WebView} API versions. It allows an + application to load pages into the WebView, either by URL or with + an HTML string, and navigate within session history. By default, + links to different pages load within the same WebView, but applications + may intercept requests to delegate links to other functions. + + The following sample QML application loads a web page, responds to session + history context, and intercepts requests for external links. It also makes + use of \l ScrollView from \l {Qt Quick Controls} to add scroll bars for + the content area. + + \code + import QtQuick 2.0 + import QtQuick.Controls 1.0 + import QtWebKit 3.0 + + ScrollView { + width: 1280 + height: 720 + WebView { + id: webview + url: "http://qt-project.org" + anchors.fill: parent + onNavigationRequested: { + // detect URL scheme prefix, most likely an external link + var schemaRE = /^\w+:/; + if (schemaRE.test(request.url)) { + request.action = WebView.AcceptRequest; + } else { + request.action = WebView.IgnoreRequest; + // delegate request.url here + } + } + } + } + \endcode + + \section1 Examples + + There are several Qt WebKit examples located in the + \l{Qt WebKit Examples} page. + +*/ + + +/*! + \qmltype WebView + \instantiates QQuickWebView + \inqmlmodule QtWebKit 3.0 + \brief A WebView renders web content within a QML application +*/ + +/*! + \qmlmethod void WebView::goBack() + + Go backward within the browser's session history, if possible. + (Equivalent to the \c{window.history.back()} DOM method.) + + \sa WebView::canGoBack +*/ + +/*! + \qmlmethod void WebView::goForward() + + Go forward within the browser's session history, if possible. + (Equivalent to the \c{window.history.forward()} DOM method.) +*/ + +/*! + \qmlmethod void WebView::stop() + + Stop loading the current page. +*/ + +/*! + \qmlmethod void WebView::reload() + + Reload the current page. (Equivalent to the + \c{window.location.reload()} DOM method.) +*/ + +/*! + \qmlproperty url WebView::url + + The location of the currently displaying HTML page. This writable + property offers the main interface to load a page into a web view. + It functions the same as the \c{window.location} DOM property. + + \sa WebView::loadHtml() +*/ + +/*! + \qmlproperty url WebView::icon + + The location of the currently displaying Web site icon, also known as favicon + or shortcut icon. This read-only URL corresponds to the image used within a + mobile browser application to represent a bookmarked page on the device's home + screen. + + This example uses the \c{icon} property to build an \c{Image} element: + + \code + Image { + id: appIcon + source: webView.icon != "" ? webView.icon : "fallbackFavIcon.png"; + ... + } + \endcode +*/ + +/*! + \qmlproperty int WebView::loadProgress + + The amount of the page that has been loaded, expressed as an integer + percentage in the range from \c{0} to \c{100}. +*/ + +/*! + \qmlproperty bool WebView::canGoBack + + Returns \c{true} if there are prior session history entries, \c{false} + otherwise. +*/ + +/*! + \qmlproperty bool WebView::canGoForward + + Returns \c{true} if there are subsequent session history entries, + \c{false} otherwise. +*/ + +/*! + \qmlproperty bool WebView::loading + + Returns \c{true} if the HTML page is currently loading, \c{false} otherwise. +*/ + +/*! + \qmlproperty string WebView::title + + The title of the currently displaying HTML page, a read-only value + that reflects the contents of the \c{<title>} tag. +*/ + +/*! + \qmlmethod void WebView::loadHtml(string html, url baseUrl, url unreachableUrl) + \brief Loads the specified \a html as the content of the web view. + + (This method offers a lower-level alternative to the \c{url} property, + which references HTML pages via URL.) + + External objects such as stylesheets or images referenced in the HTML + document are located relative to \a baseUrl. For example if provided \a html + was originally retrieved from \c http://www.example.com/documents/overview.html + and that was the base url, then an image referenced with the relative url \c diagram.png + would be looked for at \c{http://www.example.com/documents/diagram.png}. + + If an \a unreachableUrl is passed it is used as the url for the loaded + content. This is typically used to display error pages for a failed + load. + + \sa WebView::url +*/ + +/*! + \qmlsignal WebView::onLoadingChanged(loadRequest) + + Occurs when any page load begins, ends, or fails. Various read-only + parameters are available on the \a loadRequest: + + \list + + \li \c{url}: the location of the resource that is loading. + + \li \c{status}: Reflects one of three load states: + \c{LoadStartedStatus}, \c{LoadSucceededStatus}, or + \c{LoadFailedStatus}. See \c{WebView::LoadStatus}. + + \li \c{errorString}: description of load error. + + \li \c{errorCode}: HTTP error code. + + \li \c{errorDomain}: high-level error types, one of + \c{NetworkErrorDomain}, \c{HttpErrorDomain}, \c{InternalErrorDomain}, + \c{DownloadErrorDomain}, or \c{NoErrorDomain}. See + \l{WebView::ErrorDomain}. + + \endlist + + \sa WebView::loading +*/ + +/*! + \qmlsignal WebView::onLinkHovered(hoveredUrl, hoveredTitle) + + Within a mouse-driven interface, this signal is emitted when a mouse + pointer passes over a link, corresponding to the \c{mouseover} DOM + event. (May also occur in touch interfaces for \c{mouseover} events + that are not cancelled with \c{preventDefault()}.) The \a{hoveredUrl} + provides the link's location, and the \a{hoveredTitle} is any avalable + link text. +*/ + +/*! + \qmlsignal WebView::onNavigationRequested(request) + + Occurs for various kinds of navigation. If the application listens + for this signal, it must set the \c{request.action} to either of the + following \l{WebView::NavigationRequestAction} enum values: + + \list + + \li \c{AcceptRequest}: Allow navigation to external pages within the + web view. This represents the default behavior when no listener is + active. + + \li \c{IgnoreRequest}: Suppress navigation to new pages within the web + view. (The listener may then delegate navigation externally to + the browser application.) + + \endlist + + The \a{request} also provides the following read-only values: + + \list + + \li \c{url}: The location of the requested page. + + \li \c{navigationType}: contextual information, one of + \c{LinkClickedNavigation}, \c{BackForwardNavigation}, + \c{ReloadNavigation}, \c{FormSubmittedNavigation}, + \c{FormResubmittedNavigation}, or \c{OtherNavigation} enum values. + See \l{WebView::NavigationType}. + + \li \c{keyboardModifiers}: potential states for \l{Qt::KeyboardModifier}. + + \li \c{mouseButton}: potential states for \l{Qt::MouseButton}. + + \endlist +*/ + +/*! + \qmlproperty enumeration WebView::ErrorDomain + + Details various high-level error types. + + \table + + \header + \li Constant + \li Description + + \row + \li InternalErrorDomain + \li Content fails to be interpreted by Qt WebKit. + + \row + \li NetworkErrorDomain + \li Error results from faulty network connection. + + \row + \li HttpErrorDomain + \li Error is produced by server. + + \row + \li DownloadErrorDomain + \li Error in saving file. + + \row + \li NoErrorDomain + \li Unspecified fallback error. + + \endtable +*/ + +/*! + \qmlproperty enumeration WebView::NavigationType + + Distinguishes context for various navigation actions. + + \table + + \header + \li Constant + \li Description + + \row + \li LinkClickedNavigation + \li Navigation via link. + + \row + \li FormSubmittedNavigation + \li Form data is posted. + + \row + \li BackForwardNavigation + \li Navigation back and forth within session history. + + \row + \li ReloadNavigation + \li The current page is reloaded. + + \row + \li FormResubmittedNavigation + \li Form data is re-posted. + + \row + \li OtherNavigation + \li Unspecified fallback method of navigation. + + \endtable +*/ + +/*! + \qmlproperty enumeration WebView::LoadStatus + + Reflects a page's load status. + + \table + + \header + \li Constant + \li Description + + \row + \li LoadStartedStatus + \li Page is currently loading. + + \row + \li LoadSucceededStatus + \li Page has successfully loaded, and is not currently loading. + + \row + \li LoadFailedStatus + \li Page has failed to load, and is not currently loading. + + \endtable +*/ + +/*! + \qmlproperty enumeration WebView::NavigationRequestAction + + Specifies a policy when navigating a link to an external page. + + \table + + \header + \li Constant + \li Description + + \row + \li AcceptRequest + \li Allow navigation to external pages within the web view. + + \row + \li IgnoreRequest + \li Suppress navigation to new pages within the web view. + + \endtable +*/ diff --git a/src/webengine/doc/src/qtwebengine.qdoc b/src/webengine/doc/src/qtwebengine.qdoc new file mode 100644 index 000000000..7f7b7890f --- /dev/null +++ b/src/webengine/doc/src/qtwebengine.qdoc @@ -0,0 +1,37 @@ +/* + Copyright (C) 2005, 2006, 2007, 2008, 2009 Apple Inc. All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + 1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + 2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + + THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS'' AND ANY + EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED + WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS BE LIABLE FOR ANY + DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; + LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON + ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +*/ + +/*! + \qmlmodule QtWebKit 3.0 + \title Qt WebKit QML Types + \brief Provides QML types for rendering web content within a QML application + + The QML types can be imported into your applciation using the following + import statement in your .qml file: + + \code + import QtQuick 2.0 + import QtWebKit 3.0 + \endcode +*/ diff --git a/src/webenginewidgets/doc/snippets/qtwebengine_build_snippet.qdoc b/src/webenginewidgets/doc/snippets/qtwebengine_build_snippet.qdoc new file mode 100644 index 000000000..d4fc2bd85 --- /dev/null +++ b/src/webenginewidgets/doc/snippets/qtwebengine_build_snippet.qdoc @@ -0,0 +1,8 @@ +//! [0] +QT += webkit +//! [0] + + +//! [1] +#include <QtWebKit> +//! [1] diff --git a/src/webenginewidgets/doc/snippets/qtwebengine_qwebengineinspector_snippet.cpp b/src/webenginewidgets/doc/snippets/qtwebengine_qwebengineinspector_snippet.cpp new file mode 100644 index 000000000..5e57de027 --- /dev/null +++ b/src/webenginewidgets/doc/snippets/qtwebengine_qwebengineinspector_snippet.cpp @@ -0,0 +1,38 @@ +/* + Copyright (C) 2005, 2006, 2007, 2008, 2009 Apple Inc. All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + 1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + 2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + + THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS'' AND ANY + EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED + WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS BE LIABLE FOR ANY + DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; + LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON + ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +*/ + +void wrapInFunction() +{ + +//! [0] + // ... + QWebPage *page = new QWebPage; + // ... + + QWebInspector *inspector = new QWebInspector; + inspector->setPage(page); +//! [0] + +} + diff --git a/src/webenginewidgets/doc/snippets/qtwebengine_qwebengineview_snippet.cpp b/src/webenginewidgets/doc/snippets/qtwebengine_qwebengineview_snippet.cpp new file mode 100644 index 000000000..2bf43b848 --- /dev/null +++ b/src/webenginewidgets/doc/snippets/qtwebengine_qwebengineview_snippet.cpp @@ -0,0 +1,58 @@ +/* + Copyright (C) 2005, 2006, 2007, 2008, 2009 Apple Inc. All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + 1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + 2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + + THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS'' AND ANY + EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED + WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS BE LIABLE FOR ANY + DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; + LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON + ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +*/ + +void wrapInFunction() +{ + +//! [0] + view->page()->history(); +//! [0] + + +//! [1] + view->page()->settings(); +//! [1] + + +//! [2] + view->triggerAction(QWebPage::Copy); +//! [2] + + +//! [3] + view->page()->triggerPageAction(QWebPage::Stop); +//! [3] + + +//! [4] + view->page()->triggerPageAction(QWebPage::GoBack); +//! [4] + + +//! [5] + view->page()->triggerPageAction(QWebPage::GoForward); +//! [5] + +} + diff --git a/src/webenginewidgets/doc/snippets/simple/main.cpp b/src/webenginewidgets/doc/snippets/simple/main.cpp new file mode 100644 index 000000000..408630eb1 --- /dev/null +++ b/src/webenginewidgets/doc/snippets/simple/main.cpp @@ -0,0 +1,34 @@ +/* + Copyright (C) 2009 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. +*/ + +#include <QApplication> +#include <QUrl> +#include <QWebView> + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + QWidget *parent = 0; +//! [Using QWebView] + QWebView *view = new QWebView(parent); + view->load(QUrl("http://qt.nokia.com/")); + view->show(); +//! [Using QWebView] + return app.exec(); +} diff --git a/src/webenginewidgets/doc/snippets/simple/simple.pro b/src/webenginewidgets/doc/snippets/simple/simple.pro new file mode 100644 index 000000000..7fe095809 --- /dev/null +++ b/src/webenginewidgets/doc/snippets/simple/simple.pro @@ -0,0 +1,2 @@ +QT += webkitwidgets +SOURCES = main.cpp diff --git a/src/webenginewidgets/doc/snippets/webelement/main.cpp b/src/webenginewidgets/doc/snippets/webelement/main.cpp new file mode 100644 index 000000000..b1781a6f4 --- /dev/null +++ b/src/webenginewidgets/doc/snippets/webelement/main.cpp @@ -0,0 +1,125 @@ +/* + Copyright (C) 2009 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. +*/ + +#include <QApplication> +#include <QUrl> +#include <qwebview.h> +#include <qwebframe.h> +#include <qwebelement.h> + +static QWebFrame *frame; + +static void traverse() +{ +//! [Traversing with QWebElement] + frame->setHtml("<html><body><p>First Paragraph</p><p>Second Paragraph</p></body></html>"); + QWebElement doc = frame->documentElement(); + QWebElement body = doc.firstChild(); + QWebElement firstParagraph = body.firstChild(); + QWebElement secondParagraph = firstParagraph.nextSibling(); +//! [Traversing with QWebElement] +} + +static void findButtonAndClick() +{ + + frame->setHtml("<form name=\"myform\" action=\"submit_form.asp\" method=\"get\">" + "<input type=\"text\" name=\"myfield\">" + "<input type=\"submit\" value=\"Submit\">" + "</form>"); + +//! [Calling a DOM element method] + + QWebElement document = frame->documentElement(); + /* Assume that the document has the following structure: + + <form name="myform" action="submit_form.asp" method="get"> + <input type="text" name="myfield"> + <input type="submit" value="Submit"> + </form> + + */ + + QWebElement button = document.findFirst("input[type=submit]"); + button.evaluateJavaScript("click()"); + +//! [Calling a DOM element method] + + } + +static void autocomplete1() +{ + QWebElement document = frame->documentElement(); + +//! [autocomplete1] + QWebElement firstTextInput = document.findFirst("input[type=text]"); + QString storedText = firstTextInput.attribute("value"); +//! [autocomplete1] + +} + + +static void autocomplete2() +{ + + QWebElement document = frame->documentElement(); + QString storedText = "text"; + +//! [autocomplete2] + QWebElement firstTextInput = document.findFirst("input[type=text]"); + textInput.setAttribute("value", storedText); +//! [autocomplete2] + +} + + +static void findAll() +{ +//! [FindAll] + QWebElement document = frame->documentElement(); + /* Assume the document has the following structure: + + <p class=intro> + <span>Intro</span> + <span>Snippets</span> + </p> + <p> + <span>Content</span> + <span>Here</span> + </p> + */ + +//! [FindAll intro] + QWebElementCollection allSpans = document.findAll("span"); + QWebElementCollection introSpans = document.findAll("p.intro span"); +//! [FindAll intro] //! [FindAll] +} + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + QWebView *view = new QWebView(0); + frame = view->page()->mainFrame(); + traverse(); + findAll(); + findButtonAndClick(); + autocomplete1(); + autocomplete2(); + return 0; +} diff --git a/src/webenginewidgets/doc/snippets/webelement/webelement.pro b/src/webenginewidgets/doc/snippets/webelement/webelement.pro new file mode 100644 index 000000000..fbe701314 --- /dev/null +++ b/src/webenginewidgets/doc/snippets/webelement/webelement.pro @@ -0,0 +1,2 @@ +TEMPLATE = app +SOURCES = main.cpp diff --git a/src/webenginewidgets/doc/snippets/webpage/main.cpp b/src/webenginewidgets/doc/snippets/webpage/main.cpp new file mode 100644 index 000000000..daeed2bc6 --- /dev/null +++ b/src/webenginewidgets/doc/snippets/webpage/main.cpp @@ -0,0 +1,82 @@ +/* + Copyright (C) 2009 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. +*/ + +#include <QApplication> +#include <QPainter> +#include <QWebFrame> +#include <QWebPage> + +//! [0] +class Thumbnailer : public QObject +{ + Q_OBJECT + +public: + Thumbnailer(const QUrl &url); + +Q_SIGNALS: + void finished(); + +private Q_SLOTS: + void render(); + +private: + QWebPage page; + +}; +//! [0] + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + + Thumbnailer thumbnail(QUrl("http://qt.nokia.com")); + + QObject::connect(&thumbnail, SIGNAL(finished()), + &app, SLOT(quit())); + + return app.exec(); +} + +//! [1] +Thumbnailer::Thumbnailer(const QUrl &url) +{ + page.mainFrame()->load(url); + connect(&page, SIGNAL(loadFinished(bool)), + this, SLOT(render())); +} +//! [1] + +//! [2] +void Thumbnailer::render() +{ + page.setViewportSize(page.mainFrame()->contentsSize()); + QImage image(page.viewportSize(), QImage::Format_ARGB32); + QPainter painter(&image); + + page.mainFrame()->render(&painter); + painter.end(); + + QImage thumbnail = image.scaled(400, 400); + thumbnail.save("thumbnail.png"); + + emit finished(); +} +//! [2] +#include "main.moc" diff --git a/src/webenginewidgets/doc/snippets/webpage/webpage.pro b/src/webenginewidgets/doc/snippets/webpage/webpage.pro new file mode 100644 index 000000000..8d9c6938e --- /dev/null +++ b/src/webenginewidgets/doc/snippets/webpage/webpage.pro @@ -0,0 +1,3 @@ +CONFIG += console +QT += webkitwidgets +SOURCES = main.cpp diff --git a/src/webenginewidgets/doc/src/qtwebenginewidgets.qdoc b/src/webenginewidgets/doc/src/qtwebenginewidgets.qdoc new file mode 100644 index 000000000..5847d1403 --- /dev/null +++ b/src/webenginewidgets/doc/src/qtwebenginewidgets.qdoc @@ -0,0 +1,237 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** 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 Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \module QtWebKit + \title Qt WebKit Widgets C++ Classes + \brief Provides a web browser engine as well as C++ classes to render and + interact with web content + + To include the definitions of the module's classes, use the + following directive: + + \snippet webkitsnippets/qtwebkit_build_snippet.qdoc 1 + + To link against the module, add this line to your \l qmake \c + .pro file: + + \snippet webkitsnippets/qtwebkit_build_snippet.qdoc 0 +*/ + +/*! + \page qtwebkitwidgets-index.html + \title Qt WebKit Widgets + \ingroup modules + + \brief The Qt WebKit Widgets module provides a web browser engine as well as + C++ classes to render and interact with web content. + + Qt WebKit Widgets provides a Web browser engine that makes it easy to embed + content from the World Wide Web into your Qt application. At the same time + Web content can be enhanced with native controls. + + Qt WebKit Widgets provides facilities for rendering of HyperText Markup + Language (HTML), Extensible HyperText Markup Language (XHTML) and Scalable + Vector Graphics (SVG) documents, styled using Cascading Style Sheets (CSS) + and scripted with JavaScript. + + A bridge between the JavaScript execution environment and the Qt object + model makes it possible for custom QObjects to be scripted. For detailed + documentation see \l{The Qt WebKit Bridge}. + Integration with the Qt networking module enables Web pages to be transparently loaded + from Web servers, the local file system or even the Qt resource system. + + In addition to providing pure rendering features, HTML documents can be + made fully editable to the user through the use of the \c{contenteditable} + attribute on HTML elements. + + QtWebKit has been enhanced to become more attractive on the mobile front as well. + For more information see \l{QtWebKit Goes Mobile}. + + Qt WebKit is based on the Open Source WebKit engine. More information about + WebKit itself can be found on the \l{WebKit Open Source Project} Web site. + + \section1 Including In Your Project + + To include the definitions of the module's classes, use the + following directive: + + \snippet webkitsnippets/qtwebkit_build_snippet.qdoc 1 + + To link against the module, add this line to your \l qmake \c + .pro file: + + \snippet webkitsnippets/qtwebkit_build_snippet.qdoc 0 + + \section1 Notes + + \note Building the Qt WebKit module with debugging symbols is problematic + on many platforms due to the size of the WebKit engine. We recommend + building the module only in release mode for embedded platforms. + Currently Qt WebKit will always be compiled without debugging symbols + when using gcc. Take a look at + \c{Tools/mkspecs/features/production_build.prf} if you need to change this. + + \note Web site icons, also known as "FavIcons", are currently not supported + on Windows. We plan to address this in a future release. + + \note WebKit has certain minimum requirements that must be met on + Embedded Linux systems. See the \l{Qt for Embedded Linux Requirements} + document for more information. + + \section1 Architecture + + The easiest way to render content is through the QWebView class. As a + widget it can be embedded into your forms or a graphics view, and it + provides convenience functions for downloading and rendering web sites. + + \snippet webkitsnippets/simple/main.cpp Using QWebView + + QWebView is used to view Web pages. An instance of QWebView has one + QWebPage. QWebPage provides access to the document structure in a page, + describing features such as frames, the navigation history, and the + undo/redo stack for editable content. + + HTML documents can be nested using frames in a frameset. An individual + frame in HTML is represented using the QWebFrame class. This class includes the + bridge to the JavaScript window object and can be painted using QPainter. + Each QWebPage has one QWebFrame object as its main frame, and the main frame + may contain many child frames. + + Individual elements of an HTML document can be accessed via DOM JavaScript + interfaces from within a web page. The equivalent of this API in Qt WebKit + is represented by QWebElement. QWebElement objects are obtained using QWebFrame's + \l{QWebFrame::}{findAllElements()} and \l{QWebFrame::}{findFirstElement()} + functions with CSS selector queries. + + Common web browser features, defaults and other settings can be configured + through the QWebSettings class. It is possible to provide defaults for all + QWebPage instances through the default settings. Individual attributes + can be overridden by the page specific settings object. + + \section1 Netscape Plugin Support + + \note Netscape plugin support is only available on desktop platforms. + + Since WebKit supports the Netscape Plugin API, Qt applications can display + Web pages that embed common plugins on platforms for which those plugins + are available. To enable plugin support, the user must have the appropriate + binary files for those plugins installed and the \l{QWebSettings::PluginsEnabled} + attribute must be enabled for the application. + + The following locations are searched for plugins: + + \table + \header \li Linux/Unix (X11) + \row \li + \list + \li \c{.mozilla/plugins} in the user's home directory + \li \c{.netscape/plugins} in the user's home directory + \li System locations, such as + \list + \li \c{/usr/lib/browser/plugins} + \li \c{/usr/local/lib/mozilla/plugins} + \li \c{/usr/lib/firefox/plugins} + \li \c{/usr/lib64/browser-plugins} + \li \c{/usr/lib/browser-plugins} + \li \c{/usr/lib/mozilla/plugins} + \li \c{/usr/local/netscape/plugins} + \li \c{/opt/mozilla/plugins} + \li \c{/opt/mozilla/lib/plugins} + \li \c{/opt/netscape/plugins} + \li \c{/opt/netscape/communicator/plugins} + \li \c{/usr/lib/netscape/plugins} + \li \c{/usr/lib/netscape/plugins-libc5} + \li \c{/usr/lib/netscape/plugins-libc6} + \li \c{/usr/lib64/netscape/plugins} + \li \c{/usr/lib64/mozilla/plugins} + \endlist + \li Locations specified by environment variables: + \list + \li \c{$MOZILLA_HOME/plugins} + \li \c{$MOZ_PLUGIN_PATH} + \li \c{$QTWEBKIT_PLUGIN_PATH} + \endlist + \endlist + \endtable + + \table + \header \li Windows + \row \li + \list + \li The user's \c{Application Data\Mozilla\plugins} directory + \li Standard system locations of plugins for Quicktime, Flash, etc. + \endlist + \endtable + + \table + \header \li Mac OS X + \row \li + \list + \li \c{Library/Internet Plug-Ins} in the user's home directory + \li The system \c{/Library/Internet Plug-Ins} directory + \endlist + \endtable + + \section1 Examples + + There are several Qt WebKit Widgets examples located in the + \l{Qt WebKit Examples} page. + + \section1 License Information + + This is a snapshot of the Qt port of WebKit. The exact version information + can be found in the \c{VERSION} file supplied with Qt. + + Qt Commercial Edition licensees that wish to distribute applications that + use the Qt WebKit module need to be aware of their obligations under the + GNU Library General Public License (LGPL). + + Developers using the Open Source Edition can choose to redistribute + the module under the appropriate version of the GNU LGPL. + + \legalese + WebKit is licensed under the GNU Library General Public License. + Individual contributor names and copyright dates can be found + inline in the code. + + 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. + \endlegalese +*/ diff --git a/src/webenginewidgets/doc/src/qwebenginehistory_lgpl.qdoc b/src/webenginewidgets/doc/src/qwebenginehistory_lgpl.qdoc new file mode 100644 index 000000000..fc6d5e50e --- /dev/null +++ b/src/webenginewidgets/doc/src/qwebenginehistory_lgpl.qdoc @@ -0,0 +1,301 @@ +/* + 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 QWebHistoryItem + \since 4.4 + \brief The QWebHistoryItem class represents one item in the history of a QWebPage + + \inmodule QtWebKit + + Each QWebHistoryItem instance represents an entry in the history stack of a Web page, + containing information about the page, its location, and when it was last visited. + + The following table shows the properties of the page held by the history item, and + the functions used to access them. + + \table + \header \li Function \li Description + \row \li title() \li The page title. + \row \li url() \li The location of the page. + \row \li originalUrl() \li The URL used to access the page. + \row \li lastVisited() \li The date and time of the user's last visit to the page. + \row \li icon() \li The icon associated with the page that was provided by the server. + \row \li userData() \li The user specific data that was stored with the history item. + \endtable + + \note QWebHistoryItem objects are value based, but \e{explicitly shared}. Changing + a QWebHistoryItem instance by calling setUserData() will change all copies of that + instance. + + \sa QWebHistory, QWebPage::history(), QWebHistoryInterface +*/ + +/*! + \fn QWebHistoryItem::QWebHistoryItem(const QWebHistoryItem &other) + Constructs a history item from \a other. The new item and \a other + will share their data, and modifying either this item or \a other will + modify both instances. +*/ + +/*! + \fn QWebHistoryItem &QWebHistoryItem::operator=(const QWebHistoryItem &other) + Assigns the \a other history item to this. This item and \a other + will share their data, and modifying either this item or \a other will + modify both instances. +*/ + +/*! + \fn QWebHistoryItem::~QWebHistoryItem() + Destroys the history item. +*/ + +/*! + \fn QUrl QWebHistoryItem::originalUrl() const + Returns the original URL associated with the history item. + + \sa url() +*/ + +/*! + \fn QUrl QWebHistoryItem::url() const + Returns the URL associated with the history item. + + \sa originalUrl(), title(), lastVisited() +*/ + +/*! + \fn QString QWebHistoryItem::title() const + Returns the title of the page associated with the history item. + + \sa icon(), url(), lastVisited() +*/ + +/*! + \fn QDateTime QWebHistoryItem::lastVisited() const + Returns the date and time that the page associated with the item was last visited. + + \sa title(), icon(), url() +*/ + +/*! + \fn QIcon QWebHistoryItem::icon() const + Returns the icon associated with the history item. + + \sa title(), url(), lastVisited() +*/ + +/*! + \fn QVariant QWebHistoryItem::userData() const + \since 4.5 + Returns the user specific data that was stored with the history item. + + \sa setUserData() +*/ + +/*! + \fn void QWebHistoryItem::setUserData(const QVariant& userData) + \since 4.5 + + Stores user specific data \a userData with the history item. + + \note All copies of this item will be modified. + + \sa userData() +*/ + +/*! + \fn bool QWebHistoryItem::isValid() const + \since 4.5 + Returns whether this is a valid history item. +*/ + +/*! + \class QWebHistory + \since 4.4 + \brief The QWebHistory class represents the history of a QWebPage + + \inmodule QtWebKit + + Each QWebPage instance contains a history of visited pages that can be accessed + by QWebPage::history(). QWebHistory represents this history and makes it possible + to navigate it. + + The history uses the concept of a \e{current item}, dividing the pages visited + into those that can be visited by navigating \e back and \e forward using the + back() and forward() functions. The current item can be obtained by calling + currentItem(), and an arbitrary item in the history can be made the current + item by passing it to goToItem(). + + A list of items describing the pages that can be visited by going back can be + obtained by calling the backItems() function; similarly, items describing the + pages ahead of the current page can be obtained with the forwardItems() function. + The total list of items is obtained with the items() function. + + Just as with containers, functions are available to examine the history in terms + of a list. Arbitrary items in the history can be obtained with itemAt(), the total + number of items is given by count(), and the history can be cleared with the + clear() function. + + QWebHistory's state can be saved to a QDataStream using the >> operator and loaded + by using the << operator. + + \sa QWebHistoryItem, QWebHistoryInterface, QWebPage +*/ + +/*! + \fn void QWebHistory::clear() + Clears the history. + + \sa count(), items() +*/ + +/*! + \fn QList<QWebHistoryItem> QWebHistory::items() const + Returns a list of all items currently in the history. + + \sa count(), clear() +*/ + +/*! + \fn QList<QWebHistoryItem> QWebHistory::backItems(int maxItems) const + Returns the list of items in the backwards history list. + At most \a maxItems entries are returned. + + \sa forwardItems() +*/ + +/*! + \fn QList<QWebHistoryItem> QWebHistory::forwardItems(int maxItems) const + Returns the list of items in the forward history list. + At most \a maxItems entries are returned. + + \sa backItems() +*/ + +/*! + \fn bool QWebHistory::canGoBack() const + Returns true if there is an item preceding the current item in the history; + otherwise returns false. + + \sa canGoForward() +*/ + +/*! + \fn bool QWebHistory::canGoForward() const + Returns true if we have an item to go forward to; otherwise returns false. + + \sa canGoBack() +*/ + +/*! + \fn void QWebHistory::back() + Set the current item to be the previous item in the history and goes to the + corresponding page; i.e., goes back one history item. + + \sa forward(), goToItem() +*/ + +/*! + \fn void QWebHistory::forward() + Sets the current item to be the next item in the history and goes to the + corresponding page; i.e., goes forward one history item. + + \sa back(), goToItem() +*/ + +/*! + \fn void QWebHistory::goToItem(const QWebHistoryItem &item) + Sets the current item to be the specified \a item in the history and goes to the page. + + \sa back(), forward() +*/ + +/*! + \fn QWebHistoryItem QWebHistory::backItem() const + Returns the item before the current item in the history. +*/ + +/*! + \fn QWebHistoryItem QWebHistory::currentItem() const + Returns the current item in the history. +*/ + +/*! + \fn QWebHistoryItem QWebHistory::forwardItem() const + Returns the item after the current item in the history. +*/ + +/*! + \fn int QWebHistory::currentItemIndex() const + \since 4.5 + Returns the index of the current item in history. +*/ + +/*! + \fn QWebHistoryItem QWebHistory::itemAt(int i) const + Returns the item at index \a i in the history. +*/ + +/*! + \fn int QWebHistory::count() const + Returns the total number of items in the history. +*/ + +/*! + \fn int QWebHistory::maximumItemCount() const + \since 4.5 + Returns the maximum number of items in the history. + + \sa setMaximumItemCount() +*/ + +/*! + \fn void QWebHistory::setMaximumItemCount(int count) + \since 4.5 + Sets the maximum number of items in the history to \a count. + + \sa maximumItemCount() +*/ + +/*! + \fn QDataStream& operator<<(QDataStream& target, const QWebHistory& history) + \since 4.6 + \relates QWebHistory + + \brief The operator<< function streams a history into a data stream. + + It saves the \a history into the specified \a stream. +*/ + + +/*! + \fn QDataStream& operator>>(QDataStream& source, QWebHistory& history) + \relates QWebHistory + \since 4.6 + + \brief The operator>> function loads a history from a data stream. + + Loads a QWebHistory from the specified \a stream into the given \a history. +*/ + diff --git a/src/webenginewidgets/doc/src/qwebenginehistoryinterface_lgpl.qdoc b/src/webenginewidgets/doc/src/qwebenginehistoryinterface_lgpl.qdoc new file mode 100644 index 000000000..1d17e7ce0 --- /dev/null +++ b/src/webenginewidgets/doc/src/qwebenginehistoryinterface_lgpl.qdoc @@ -0,0 +1,83 @@ +/* + Copyright (C) 2007 Staikos Computing Services Inc. <info@staikos.net> + + 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. + + This class provides all functionality needed for tracking global history. +*/ + +// 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 QWebHistoryInterface + \since 4.4 + \brief The QWebHistoryInterface class provides an interface to implement link history. + + \inmodule QtWebKit + + The QWebHistoryInterface is an interface that can be used to + keep track of visited links. It contains two pure virtual methods that + are called by the WebKit engine: addHistoryEntry() is used to add + urls that have been visited to the interface, while + historyContains() is used to query whether the given url has been + visited by the user. By default the QWebHistoryInterface is not set, so WebKit does not keep + track of visited links. + + \note The history tracked by QWebHistoryInterface is not specific to an instance of QWebPage + but applies to all pages. +*/ + +/*! + \fn void QWebHistoryInterface::setDefaultInterface(QWebHistoryInterface* defaultInterface) + Sets a new default interface, \a defaultInterface, that will be used by all of WebKit + to keep track of visited links. + + If an interface without a parent has already been set, the old interface will be deleted. + When the application exists QWebHistoryInterface will automatically delete the + \a defaultInterface if it does not have a parent. +*/ + +/*! + \fn QWebHistoryInterface* QWebHistoryInterface::defaultInterface() + Returns the default interface that will be used by WebKit. If no default interface has been set, + WebKit will not keep track of visited links and a null pointer will be returned. + \sa setDefaultInterface() +*/ + +/*! + \fn QWebHistoryInterface::QWebHistoryInterface(QObject* parent) + Constructs a new QWebHistoryInterface with parent \a parent. +*/ + +/*! + \fn QWebHistoryInterface::~QWebHistoryInterface() + Destroys the interface. If this is currently the default interface it will be unset. +*/ + +/*! + \fn bool QWebHistoryInterface::historyContains(const QString &url) const = 0 + + Called by the WebKit engine to query whether a certain \a url has been visited by the user already. + Returns true if the \a url is part of the history of visited links; otherwise returns false. +*/ + +/*! + \fn void QWebHistoryInterface::addHistoryEntry(const QString &url) = 0 + + Called by WebKit to add another \a url to the list of visited pages. +*/ diff --git a/src/webenginewidgets/doc/src/qwebengineinspector_lgpl.qdoc b/src/webenginewidgets/doc/src/qwebengineinspector_lgpl.qdoc new file mode 100644 index 000000000..864618309 --- /dev/null +++ b/src/webenginewidgets/doc/src/qwebengineinspector_lgpl.qdoc @@ -0,0 +1,103 @@ +/* + Copyright (C) 2009 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 QWebInspector + \since 4.6 + \inmodule QtWebKit + \brief The QWebInspector class allows the placement and control of a + QWebPage's inspector. + The inspector can display a page's hierarchy, its loading statistics and + the current state of its individual elements. It is mostly used by web + developers. + + The QWebPage to be inspected must be specified using the setPage() method. + + A typical use of QWebInspector follows: + + \snippet webkitsnippets/qtwebkit_qwebinspector_snippet.cpp 0 + + A QWebInspector can be made visible either programmatically using + setVisible(), or by the user through the attached QWebPage's context + menu. + + \note A QWebInspector will display a blank widget if either: + \list + \li page() is null + \li QWebSettings::DeveloperExtrasEnabled is false + \endlist + + \section1 Resources + + This class acts mostly as a container and a controller for the inspector. + Most of the resources needed by the inspector are owned by the associated + QWebPage and are allocated the first time that: + \list + \li an element is inspected + \li the QWebInspector is shown. + \endlist + + \section1 Inspector configuration persistence + + The inspector allows the user to configure some options through its + user interface (e.g. the resource tracking "Always enable" option). + The inspector UI is itself a web page and is using HTML local storage + to persist those settings. + Since the internal QWebPage used by the inspector isn't exposed in the API, + the only way to enable those settings to be persisted is currently to enable + local storage globally through QWebSettings::globalSettings(). + + \sa QWebSettings::localStoragePath(), QWebSettings::LocalStorageEnabled +*/ + +/*! + \fn QWebInspector::QWebInspector(QWidget* parent) + Constructs an unbound QWebInspector with \a parent as its parent. +*/ + +/*! + \fn QWebInspector::~QWebInspector() + Destroys the inspector. +*/ + +/*! + \fn void QWebInspector::setPage(QWebPage* page) + Bind this inspector to the QWebPage to be inspected. + + \b {Notes:} + \list + \li There can only be one QWebInspector associated with a QWebPage + and vice versa. + \li Calling this method with a null \a page will break the current association, if any. + \li If \a page is already associated to another QWebInspector, the association + will be replaced and the previous QWebInspector will become unbound + \endlist + + \sa page() +*/ + +/*! + \fn QWebPage* QWebInspector::page() const + Returns the inspected QWebPage. + If no web page is currently associated, a null pointer is returned. +*/ diff --git a/src/webenginewidgets/doc/src/qwebenginepage_lgpl.qdoc b/src/webenginewidgets/doc/src/qwebenginepage_lgpl.qdoc new file mode 100644 index 000000000..a63ac9c6f --- /dev/null +++ b/src/webenginewidgets/doc/src/qwebenginepage_lgpl.qdoc @@ -0,0 +1,1962 @@ +/* + Copyright (C) 2008, 2009, 2012 Nokia Corporation and/or its subsidiary(-ies) + Copyright (C) 2007 Staikos Computing Services Inc. + Copyright (C) 2007 Apple Inc. + + 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 QWebPage + \since 4.4 + \brief The QWebPage class provides an object to view and edit web documents. + + \inmodule QtWebKit + + QWebPage holds a main frame responsible for web content, settings, the history + of navigated links and actions. This class can be used, together with QWebFrame, + to provide functionality like QWebView in a widget-less environment. + + QWebPage's API is very similar to QWebView, as you are still provided with + common functions like action() (known as + \l{QWebView::pageAction()}{pageAction}() in QWebView), triggerAction(), + findText() and settings(). More QWebView-like functions can be found in the + main frame of QWebPage, obtained via the mainFrame() function. For example, + the \l{QWebFrame::load()}{load}(), \l{QWebFrame::setUrl()}{setUrl}() and + \l{QWebFrame::setHtml()}{setHtml}() functions for QWebPage can be accessed + using QWebFrame. + + The loadStarted() signal is emitted when the page begins to load.The + loadProgress() signal, on the other hand, is emitted whenever an element + of the web page completes loading, such as an embedded image, a script, + etc. Finally, the loadFinished() signal is emitted when the page contents + are loaded completely, independent of script execution or page rendering. + Its argument, either true or false, indicates whether or not the load + operation succeeded. + + \section1 Using QWebPage in a Widget-less Environment + + Before you begin painting a QWebPage object, you need to set the size of + the viewport by calling setViewportSize(). Then, you invoke the main + frame's render function (QWebFrame::render()). An example of this + is shown in the code snippet below. + + Suppose we have a \c Thumbnail class as follows: + + \snippet webkitsnippets/webpage/main.cpp 0 + + The \c Thumbnail's constructor takes in a \a url. We connect our QWebPage + object's \l{QWebPage::}{loadFinished()} signal to our private slot, + \c render(). + + \snippet webkitsnippets/webpage/main.cpp 1 + + The \c render() function shows how we can paint a thumbnail using a + QWebPage object. + + \snippet webkitsnippets/webpage/main.cpp 2 + + We begin by setting the \l{QWebPage::viewportSize()}{viewportSize} and + then we instantiate a QImage object, \c image, with the same size as our + \l{QWebPage::viewportSize()}{viewportSize}. This image is then sent + as a parameter to \c painter. Next, we render the contents of the main + frame and its subframes into \c painter. Finally, we save the scaled image. + + \sa QWebFrame +*/ + +/*! + \fn QMenu *QWebPage::createStandardContextMenu() + \since 4.5 + This function creates the standard context menu which is shown when + the user clicks on the web page with the right mouse button. It is + called from the default contextMenuEvent() handler. The popup menu's + ownership is transferred to the caller. + */ + +/*! + \property QWebPage::palette + \brief the page's palette + + The base brush of the palette is used to draw the background of the main frame. + + By default, this property contains the application's default palette. +*/ + +/*! + \fn QVariant QWebPage::inputMethodQuery(Qt::InputMethodQuery property) const + This method is used by the input method to query a set of properties of the page + to be able to support complex input method operations as support for surrounding + text and reconversions. + + \a property specifies which property is queried. + + \sa QWidget::inputMethodEvent(), QInputMethodEvent, QInputContext +*/ + +/*! + \enum QWebPage::FindFlag + + This enum describes the options available to the findText() function. The options + can be OR-ed together from the following list: + + \value FindBackward Searches backwards instead of forwards. + \value FindCaseSensitively By default findText() works case insensitive. Specifying this option + changes the behavior to a case sensitive find operation. + \value FindWrapsAroundDocument Makes findText() restart from the beginning of the document if the end + was reached and the text was not found. + \value HighlightAllOccurrences Highlights all existing occurrences of a specific string. + (This value was introduced in 4.6.) + \value FindAtWordBeginningsOnly Searches for the sub-string only at the beginnings of words. + (This value was introduced in 5.2.) + \value TreatMedialCapitalAsWordBeginning Treats a capital letter occurring anywhere in the middle of a word + as the beginning of a new word. + (This value was introduced in 5.2.) + \value FindBeginsInSelection Begin searching inside the text selection first. + (This value was introduced in 5.2.) +*/ + +/*! + \enum QWebPage::LinkDelegationPolicy + + This enum defines the delegation policies a webpage can have when activating links and emitting + the linkClicked() signal. + + \value DontDelegateLinks No links are delegated. Instead, QWebPage tries to handle them all. + \value DelegateExternalLinks When activating links that point to documents not stored on the + local filesystem or an equivalent - such as the Qt resource system - then linkClicked() is emitted. + \value DelegateAllLinks Whenever a link is activated the linkClicked() signal is emitted. + + \sa QWebPage::linkDelegationPolicy +*/ + +/*! + \enum QWebPage::NavigationType + + This enum describes the types of navigation available when browsing through hyperlinked + documents. + + \value NavigationTypeLinkClicked The user clicked on a link or pressed return on a focused link. + \value NavigationTypeFormSubmitted The user activated a submit button for an HTML form. + \value NavigationTypeBackOrForward Navigation to a previously shown document in the back or forward history is requested. + \value NavigationTypeReload The user activated the reload action. + \value NavigationTypeFormResubmitted An HTML form was submitted a second time. + \value NavigationTypeOther A navigation to another document using a method not listed above. + + \sa acceptNavigationRequest() +*/ + +/*! + \enum QWebPage::WebAction + + This enum describes the types of action which can be performed on the web page. + + Actions only have an effect when they are applicable. The availability of + actions can be be determined by checking \l{QAction::}{isEnabled()} on the + action returned by action(). + + One method of enabling the text editing, cursor movement, and text selection actions + is by setting \l contentEditable to true. + + \value NoWebAction No action is triggered. + \value OpenLink Open the current link. + \value OpenLinkInNewWindow Open the current link in a new window. + \value OpenLinkInThisWindow Open the current link without opening a new window. Used on links that would default to opening in another frame or a new window. (Added in Qt 5.0) + \value OpenFrameInNewWindow Replicate the current frame in a new window. + \value DownloadLinkToDisk Download the current link to the disk. + \value CopyLinkToClipboard Copy the current link to the clipboard. + \value OpenImageInNewWindow Open the highlighted image in a new window. + \value DownloadImageToDisk Download the highlighted image to the disk. + \value CopyImageToClipboard Copy the highlighted image to the clipboard. (Added in Qt 4.8) + \value CopyImageUrlToClipboard Copy the highlighted image's URL to the clipboard. + \value Back Navigate back in the history of navigated links. + \value Forward Navigate forward in the history of navigated links. + \value Stop Stop loading the current page. + \value StopScheduledPageRefresh Stop all pending page refresh/redirect requests. (Added in Qt 4.7) + \value Reload Reload the current page. + \value ReloadAndBypassCache Reload the current page, but do not use any local cache. (Added in Qt 4.6) + \value Cut Cut the content currently selected into the clipboard. + \value Copy Copy the content currently selected into the clipboard. + \value Paste Paste content from the clipboard. + \value Undo Undo the last editing action. + \value Redo Redo the last editing action. + \value MoveToNextChar Move the cursor to the next character. + \value MoveToPreviousChar Move the cursor to the previous character. + \value MoveToNextWord Move the cursor to the next word. + \value MoveToPreviousWord Move the cursor to the previous word. + \value MoveToNextLine Move the cursor to the next line. + \value MoveToPreviousLine Move the cursor to the previous line. + \value MoveToStartOfLine Move the cursor to the start of the line. + \value MoveToEndOfLine Move the cursor to the end of the line. + \value MoveToStartOfBlock Move the cursor to the start of the block. + \value MoveToEndOfBlock Move the cursor to the end of the block. + \value MoveToStartOfDocument Move the cursor to the start of the document. + \value MoveToEndOfDocument Move the cursor to the end of the document. + \value SelectNextChar Select to the next character. + \value SelectPreviousChar Select to the previous character. + \value SelectNextWord Select to the next word. + \value SelectPreviousWord Select to the previous word. + \value SelectNextLine Select to the next line. + \value SelectPreviousLine Select to the previous line. + \value SelectStartOfLine Select to the start of the line. + \value SelectEndOfLine Select to the end of the line. + \value SelectStartOfBlock Select to the start of the block. + \value SelectEndOfBlock Select to the end of the block. + \value SelectStartOfDocument Select to the start of the document. + \value SelectEndOfDocument Select to the end of the document. + \value DeleteStartOfWord Delete to the start of the word. + \value DeleteEndOfWord Delete to the end of the word. + \value SetTextDirectionDefault Set the text direction to the default direction. + \value SetTextDirectionLeftToRight Set the text direction to left-to-right. + \value SetTextDirectionRightToLeft Set the text direction to right-to-left. + \value ToggleBold Toggle the formatting between bold and normal weight. + \value ToggleItalic Toggle the formatting between italic and normal style. + \value ToggleUnderline Toggle underlining. + \value InspectElement Show the Web Inspector with the currently highlighted HTML element. + \value InsertParagraphSeparator Insert a new paragraph. + \value InsertLineSeparator Insert a new line. + \value SelectAll Selects all content. + \value PasteAndMatchStyle Paste content from the clipboard with current style. (Added in Qt 4.6) + \value RemoveFormat Removes formatting and style. (Added in Qt 4.6) + \value ToggleStrikethrough Toggle the formatting between strikethrough and normal style. (Added in Qt 4.6) + \value ToggleSubscript Toggle the formatting between subscript and baseline. (Added in Qt 4.6) + \value ToggleSuperscript Toggle the formatting between supercript and baseline. (Added in Qt 4.6) + \value InsertUnorderedList Toggles the selection between an ordered list and a normal block. (Added in Qt 4.6) + \value InsertOrderedList Toggles the selection between an ordered list and a normal block. (Added in Qt 4.6) + \value Indent Increases the indentation of the currently selected format block by one increment. (Added in Qt 4.6) + \value Outdent Decreases the indentation of the currently selected format block by one increment. (Added in Qt 4.6) + \value AlignCenter Applies center alignment to content. (Added in Qt 4.6) + \value AlignJustified Applies full justification to content. (Added in Qt 4.6) + \value AlignLeft Applies left justification to content. (Added in Qt 4.6) + \value AlignRight Applies right justification to content. (Added in Qt 4.6) + + \omitvalue WebActionCount + +*/ + +/*! + \enum QWebPage::WebWindowType + + This enum describes the types of window that can be created by the createWindow() function. + + \value WebBrowserWindow The window is a regular web browser window. + \value WebModalDialog The window acts as modal dialog. +*/ + +/*! + \class QWebPage::ViewportAttributes + \since 4.7 + \brief The QWebPage::ViewportAttributes class describes hints that can be applied to a viewport. + + QWebPage::ViewportAttributes provides a description of a viewport, such as viewport geometry, + initial scale factor with limits, plus information about whether a user should be able + to scale the contents in the viewport or not, ie. by zooming. + + ViewportAttributes can be set by a web author using the viewport meta tag extension, documented + at \l{http://developer.apple.com/safari/library/documentation/appleapplications/reference/safariwebcontent/usingtheviewport/usingtheviewport.html}{Safari Reference Library: Using the Viewport Meta Tag}. + + All values might not be set, as such when dealing with the hints, the developer needs to + check whether the values are valid. Negative values denote an invalid qreal value. + + \inmodule QtWebKit +*/ + +/*! + \fn QWebPage::ViewportAttributes::ViewportAttributes() + Constructs an empty QWebPage::ViewportAttributes. +*/ + +/*! + \fn QWebPage::ViewportAttributes::ViewportAttributes(const QWebPage::ViewportAttributes& other) + Constructs a QWebPage::ViewportAttributes which is a copy from \a other . +*/ + +/*! + \fn QWebPage::ViewportAttributes::~ViewportAttributes() + Destroys the QWebPage::ViewportAttributes. +*/ + +/*! + \fn QWebPage::ViewportAttributes& QWebPage::ViewportAttributes::operator=(const QWebPage::ViewportAttributes& other) + Assigns the given QWebPage::ViewportAttributes to this viewport hints and returns a + reference to this. +*/ + +/*! \fn inline bool QWebPage::ViewportAttributes::isValid() const + Returns whether this is a valid ViewportAttributes or not. + + An invalid ViewportAttributes will have an empty QSize, negative values for scale factors and + true for the boolean isUserScalable. +*/ + +/*! \fn inline QSize QWebPage::ViewportAttributes::size() const + Returns the size of the viewport. +*/ + +/*! \fn inline qreal QWebPage::ViewportAttributes::initialScaleFactor() const + Returns the initial scale of the viewport as a multiplier. +*/ + +/*! \fn inline qreal QWebPage::ViewportAttributes::minimumScaleFactor() const + Returns the minimum scale value of the viewport as a multiplier. +*/ + +/*! \fn inline qreal QWebPage::ViewportAttributes::maximumScaleFactor() const + Returns the maximum scale value of the viewport as a multiplier. +*/ + +/*! \fn inline bool QWebPage::ViewportAttributes::isUserScalable() const + Determines whether or not the scale can be modified by the user. +*/ + +/*! + \fn QWebPage::QWebPage(QObject *parent) + Constructs an empty QWebPage with parent \a parent. +*/ + +/*! + \fn QWebPage::~QWebPage() + Destroys the web page. +*/ + +/*! + \fn QWebFrame *QWebPage::mainFrame() const + Returns the main frame of the page. + + The main frame provides access to the hierarchy of sub-frames and is also needed if you + want to explicitly render a web page into a given painter. + + \sa currentFrame() +*/ + +/*! + \fn QWebFrame *QWebPage::currentFrame() const + Returns the frame currently active. + + \sa mainFrame(), frameCreated() +*/ + +/*! + \fn QWebFrame* QWebPage::frameAt(const QPoint& pos) const + \since 4.6 + + Returns the frame at the given point \a pos, or 0 if there is no frame at + that position. + + \sa mainFrame(), currentFrame() +*/ + +/*! + \fn QWebHistory *QWebPage::history() const + Returns a pointer to the view's history of navigated web pages. +*/ + +/*! + \fn void QWebPage::setView(QWidget* view) + Sets the \a view that is associated with the web page. + + \sa view() +*/ + +/*! + \fn QWidget *QWebPage::view() const + Returns the view widget that is associated with the web page. + + \sa setView() +*/ + +/*! + \fn void QWebPage::javaScriptConsoleMessage(const QString& message, int lineNumber, const QString& sourceID) + This function is called whenever a JavaScript program tries to print a \a message to the web browser's console. + + For example in case of evaluation errors the source URL may be provided in \a sourceID as well as the \a lineNumber. + + The default implementation prints nothing. +*/ + +/*! + \fn void QWebPage::javaScriptAlert(QWebFrame *frame, const QString& msg) + This function is called whenever a JavaScript program running inside \a frame calls the alert() function with + the message \a msg. + + The default implementation shows the message, \a msg, with QMessageBox::information. +*/ + +/*! + \fn bool QWebPage::javaScriptConfirm(QWebFrame *frame, const QString& msg) + This function is called whenever a JavaScript program running inside \a frame calls the confirm() function + with the message, \a msg. Returns true if the user confirms the message; otherwise returns false. + + The default implementation executes the query using QMessageBox::information with QMessageBox::Ok and QMessageBox::Cancel buttons. +*/ + +/*! + \fn bool QWebPage::javaScriptPrompt(QWebFrame *frame, const QString& msg, const QString& defaultValue, QString* result) + This function is called whenever a JavaScript program running inside \a frame tries to prompt the user for input. + The program may provide an optional message, \a msg, as well as a default value for the input in \a defaultValue. + + If the prompt was cancelled by the user the implementation should return false; otherwise the + result should be written to \a result and true should be returned. If the prompt was not cancelled by the + user, the implementation should return true and the result string must not be null. + + The default implementation uses QInputDialog::getText(). +*/ + +/*! + \fn bool QWebPage::shouldInterruptJavaScript() + \since 4.6 + This function is called when a JavaScript program is running for a long period of time. + + If the user wanted to stop the JavaScript the implementation should return true; otherwise false. + + The default implementation executes the query using QMessageBox::information with QMessageBox::Yes and QMessageBox::No buttons. +*/ + +/*! + \fn QWebPage *QWebPage::createWindow(WebWindowType type) + This function is called whenever WebKit wants to create a new window of the given \a type, for + example when a JavaScript program requests to open a document in a new window. + + If the new window can be created, the new window's QWebPage is returned; otherwise a null pointer is returned. + + If the view associated with the web page is a QWebView object, then the default implementation forwards + the request to QWebView's createWindow() function; otherwise it returns a null pointer. + + If \a type is WebModalDialog, the application must call setWindowModality(Qt::ApplicationModal) on the new window. + + \note In the cases when the window creation is being triggered by JavaScript, apart from + reimplementing this method application must also set the JavaScriptCanOpenWindows attribute + of QWebSettings to true in order for it to get called. + + \sa acceptNavigationRequest(), QWebView::createWindow() +*/ + +/*! + \fn QObject *QWebPage::createPlugin(const QString &classid, const QUrl &url, const QStringList ¶mNames, const QStringList ¶mValues) + This function is called whenever WebKit encounters a HTML object element with type "application/x-qt-plugin". It is + called regardless of the value of QWebSettings::PluginsEnabled. The \a classid, \a url, \a paramNames and \a paramValues + correspond to the HTML object element attributes and child elements to configure the embeddable object. +*/ + +/*! + \fn QStringList QWebPage::supportedContentTypes() const + Returns the list of all content types supported by QWebPage. +*/ + +/*! + \fn bool QWebPage::supportsContentType(const QString& mimeType) const + Returns true if QWebPage can handle the given \a mimeType; otherwise, returns false. +*/ + +/*! + \fn void QWebPage::triggerAction(WebAction action, bool) + This function can be called to trigger the specified \a action. + It is also called by Qt WebKit if the user triggers the action, for example + through a context menu item. + + If \a action is a checkable action then \a checked specified whether the action + is toggled or not. + + \sa action() +*/ + +/*! + \fn void QWebPage::setViewportSize(const QSize &size) const + \property QWebPage::viewportSize + \brief the size of the viewport + + The size affects for example the visibility of scrollbars + if the document is larger than the viewport. + + By default, for a newly-created Web page, this property contains a size with + zero width and height. + + \sa QWebFrame::render(), preferredContentsSize +*/ + +/*! + \fn QWebPage::ViewportAttributes QWebPage::viewportAttributesForSize(const QSize& availableSize) const + Computes the optimal viewport configuration given the \a availableSize, when + user interface components are disregarded. + + The configuration is also dependent on the device screen size which is obtained + automatically. For testing purposes the size can be overridden by setting two + environment variables QTWEBKIT_DEVICE_WIDTH and QTWEBKIT_DEVICE_HEIGHT, which + both needs to be set. + + The ViewportAttributes includes a pixel density ratio, which will also be exposed to + the web author though the -webkit-pixel-ratio media feature. This is the ratio + between 1 density-independent pixel (DPI) and physical pixels. + + A density-independent pixel is equivalent to one physical pixel on a 160 DPI screen, + so on our platform assumes that as the baseline density. + + The conversion of DIP units to screen pixels is quite simple: + + pixels = DIPs * (density / 160). + + Thus, on a 240 DPI screen, 1 DIPs would equal 1.5 physical pixels. + + An invalid instance will be returned in the case an empty size is passed to the + method. + + \note The density is automatically obtained from the DPI of the screen where the page + is being shown, but as many X11 servers are reporting wrong DPI, it is possible to + override it using QX11Info::setAppDpiY(). +*/ + +/*! + \fn void QWebPage::setPreferredContentsSize(const QSize& size) const + \property QWebPage::preferredContentsSize + \since 4.6 + \brief a custom size used for laying out the page contents. + + By default all pages are laid out using the viewport of the page as the base. + + As pages mostly are designed for desktop usage, they often do not layout properly + on small devices as the contents require a certain view width. For this reason + it is common to use a different layout size and then scale the contents to fit + within the actual view. + + If this property is set to a valid size, this size is used for all layout needs + instead of the size of the viewport. + + Setting an invalid size, makes the page fall back to using the viewport size for layout. + + \sa viewportSize +*/ + +/* + \fn void QWebPage::setActualVisibleContentRect(const QRect& rect) const + This function is to be called after any (animated) scroll/pan has ended, in the case the application handles the + scrolling/panning of the web contents. This is commonly used in combination with tiling where is it common for + the application to pan the actual view, which then resizes itself to the size of the contents. + + \note Calling this function makes WebKit stop trying to calculate the visibleContentRect. To turn that on + again, call this method with an empty rect. + + \sa QGraphicsWebView::resizesToContents, QWebSettings::TiledBackingStoreEnabled +*/ + +/*! + \fn bool QWebPage::acceptNavigationRequest(QWebFrame *frame, const QNetworkRequest &request, QWebPage::NavigationType type) + + This function is called whenever WebKit requests to navigate \a frame to the resource specified by \a request by means of + the specified navigation type \a type. + + If \a frame is a null pointer then navigation to a new window is requested. If the request is + accepted createWindow() will be called. + + The default implementation interprets the page's linkDelegationPolicy and emits linkClicked accordingly or returns true + to let QWebPage handle the navigation itself. + + \sa createWindow() +*/ + +/*! + \fn bool QWebPage::hasSelection() const + \property QWebPage::hasSelection + \brief whether this page contains selected content or not. + + \sa selectionChanged() +*/ + +/*! + \fn QString QWebPage::selectedText() const + \property QWebPage::selectedText + \brief the text currently selected + + By default, this property contains an empty string. + + \sa selectionChanged(), selectedHtml() +*/ + +/*! + \fn QString QWebPage::selectedHtml() const + \since 4.8 + \property QWebPage::selectedHtml + \brief the HTML currently selected + + By default, this property contains an empty string. + + \sa selectionChanged(), selectedText() +*/ + +/*! + \fn QAction *QWebPage::action(WebAction action) const + Returns a QAction for the specified WebAction \a action. + + The action is owned by the QWebPage but you can customize the look by + changing its properties. + + QWebPage also takes care of implementing the action, so that upon + triggering the corresponding action is performed on the page. + + \sa triggerAction() +*/ + +/*! + \fn bool QWebPage::isModified() const + \property QWebPage::modified + \brief whether the page contains unsubmitted form data, or the contents have been changed. + + By default, this property is false. + + \sa contentsChanged(), contentEditable, undoStack() +*/ + +/*! + \fn QUndoStack *QWebPage::undoStack() const + Returns a pointer to the undo stack used for editable content. + + \sa modified +*/ + +/*! + \fn bool QWebPage::focusNextPrevChild(bool next) + Similar to QWidget::focusNextPrevChild() it focuses the next focusable web element + if \a next is true; otherwise the previous element is focused. + + Returns true if it can find a new focusable element, or false if it can't. +*/ + +/*! + \fn void QWebPage::setContentEditable(bool editable) + \property QWebPage::contentEditable + \brief whether the content in this QWebPage is editable or not + \since 4.5 + + If this property is enabled the contents of the page can be edited by the user through a visible + cursor. If disabled (the default) only HTML elements in the web page with their + \c{contenteditable} attribute set are editable. + + \sa modified, contentsChanged(), WebAction +*/ + +/*! + \fn void QWebPage::setForwardUnsupportedContent(bool forward) + \property QWebPage::forwardUnsupportedContent + \brief whether QWebPage should forward unsupported content + + If enabled, the unsupportedContent() signal is emitted with a network reply that + can be used to read the content. + + If disabled, the download of such content is aborted immediately. + + By default unsupported content is not forwarded. +*/ + +/*! + \fn void QWebPage::setLinkDelegationPolicy(LinkDelegationPolicy policy) + \property QWebPage::linkDelegationPolicy + \brief how QWebPage should delegate the handling of links through the + linkClicked() signal + + The default is to delegate no links. +*/ + +/*! + \fn bool QWebPage::swallowContextMenuEvent(QContextMenuEvent *event) + Filters the context menu event, \a event, through handlers for scrollbars and + custom event handlers in the web page. Returns true if the event was handled; + otherwise false. + + A web page may swallow a context menu event through a custom event handler, allowing for context + menus to be implemented in HTML/JavaScript. This is used by \l{http://maps.google.com/}{Google + Maps}, for example. +*/ + +/*! + \fn void QWebPage::updatePositionDependentActions(const QPoint &pos) + Updates the page's actions depending on the position \a pos. For example if \a pos is over an image + element the CopyImageToClipboard action is enabled. +*/ + +/*! + \enum QWebPage::Extension + + This enum describes the types of extensions that the page can support. Before using these extensions, you + should verify that the extension is supported by calling supportsExtension(). + + \value ChooseMultipleFilesExtension Whether the web page supports multiple file selection. + This extension is invoked when the web content requests one or more file names, for example + as a result of the user clicking on a "file upload" button in a HTML form where multiple + file selection is allowed. + + \value ErrorPageExtension Whether the web page can provide an error page when loading fails. + (introduced in Qt 4.6) + + \sa ChooseMultipleFilesExtensionOption, ChooseMultipleFilesExtensionReturn, ErrorPageExtensionOption, ErrorPageExtensionReturn +*/ + +/*! + \enum QWebPage::ErrorDomain + \since 4.6 + + This enum describes the domain of an ErrorPageExtensionOption object (i.e. the layer in which the error occurred). + + \value QtNetwork The error occurred in the QtNetwork layer; the error code is of type QNetworkReply::NetworkError. + \value Http The error occurred in the HTTP layer; the error code is a HTTP status code (see QNetworkRequest::HttpStatusCodeAttribute). + \value WebKit The error is an internal WebKit error. +*/ + +/*! + \class QWebPage::ExtensionOption + \since 4.4 + \brief The ExtensionOption class provides an extended input argument to QWebPage's extension support. + + \inmodule QtWebKit + + \sa QWebPage::extension(), QWebPage::ExtensionReturn +*/ + +/*! + \class QWebPage::ExtensionReturn + \since 4.4 + \brief The ExtensionReturn class provides an output result from a QWebPage's extension. + + \inmodule QtWebKit + + \sa QWebPage::extension(), QWebPage::ExtensionOption +*/ + +/*! + \class QWebPage::ErrorPageExtensionOption + \since 4.6 + \brief The ErrorPageExtensionOption class describes the option + for the error page extension. + + \inmodule QtWebKit + + The ErrorPageExtensionOption class holds the \a url for which an error occurred as well as + the associated \a frame. + + The error itself is reported by an error \a domain, the \a error code as well as \a errorString. + + \sa QWebPage::extension(), QWebPage::ErrorPageExtensionReturn +*/ + +/*! + \variable QWebPage::ErrorPageExtensionOption::url + \brief the url for which an error occurred +*/ + +/*! + \variable QWebPage::ErrorPageExtensionOption::frame + \brief the frame associated with the error +*/ + +/*! + \variable QWebPage::ErrorPageExtensionOption::domain + \brief the domain that reported the error +*/ + +/*! + \variable QWebPage::ErrorPageExtensionOption::error + \brief the error code. Interpretation of the value depends on the \a domain + \sa QWebPage::ErrorDomain +*/ + +/*! + \variable QWebPage::ErrorPageExtensionOption::errorString + \brief a string that describes the error +*/ + +/*! + \class QWebPage::ErrorPageExtensionReturn + \since 4.6 + \brief The ErrorPageExtensionReturn describes the error page, which will be shown for the + frame for which the error occurred. + + \inmodule QtWebKit + + The ErrorPageExtensionReturn class holds the data needed for creating an error page. Some are + optional such as \a contentType, which defaults to "text/html", as well as the \a encoding, which + is assumed to be UTF-8 if not indicated otherwise. + + The error page is stored in the \a content byte array, as HTML content. In order to convert a + QString to a byte array, the QString::toUtf8() method can be used. + + External objects such as stylesheets or images referenced in the HTML are located relative to + \a baseUrl. + + \sa QWebPage::extension(), QWebPage::ErrorPageExtensionOption, QString::toUtf8() +*/ + +/*! + \fn QWebPage::ErrorPageExtensionReturn::ErrorPageExtensionReturn() + + Constructs a new error page object. +*/ + +/*! + \variable QWebPage::ErrorPageExtensionReturn::contentType + \brief the error page's content type +*/ + +/*! + \variable QWebPage::ErrorPageExtensionReturn::encoding + \brief the error page encoding +*/ + +/*! + \variable QWebPage::ErrorPageExtensionReturn::baseUrl + \brief the base url + + External objects such as stylesheets or images referenced in the HTML are located relative to this url. +*/ + +/*! + \variable QWebPage::ErrorPageExtensionReturn::content + \brief the HTML content of the error page +*/ + +/*! + \class QWebPage::ChooseMultipleFilesExtensionOption + \since 4.5 + \brief The ChooseMultipleFilesExtensionOption class describes the option + for the multiple files selection extension. + + \inmodule QtWebKit + + The ChooseMultipleFilesExtensionOption class holds the frame originating the request + and the suggested filenames which might be provided. + + \sa QWebPage::extension(), QWebPage::chooseFile(), QWebPage::ChooseMultipleFilesExtensionReturn +*/ + +/*! + \variable QWebPage::ChooseMultipleFilesExtensionOption::parentFrame + \brief The frame in which the request originated +*/ + +/*! + \variable QWebPage::ChooseMultipleFilesExtensionOption::suggestedFileNames + \brief The suggested filenames +*/ + +/*! + \variable QWebPage::ChooseMultipleFilesExtensionReturn::fileNames + \brief The selected filenames +*/ + +/*! + \class QWebPage::ChooseMultipleFilesExtensionReturn + \since 4.5 + \brief The ChooseMultipleFilesExtensionReturn describes the return value + for the multiple files selection extension. + + \inmodule QtWebKit + + The ChooseMultipleFilesExtensionReturn class holds the filenames selected by the user + when the extension is invoked. + + \sa QWebPage::extension(), QWebPage::ChooseMultipleFilesExtensionOption +*/ + +/*! + \fn bool QWebPage::extension(Extension extension, const ExtensionOption *option, ExtensionReturn *output) + This virtual function can be reimplemented in a QWebPage subclass to provide support for extensions. The \a option + argument is provided as input to the extension; the output results can be stored in \a output. + + The behavior of this function is determined by \a extension. The \a option + and \a output values are typically casted to the corresponding types (for + example, ChooseMultipleFilesExtensionOption and + ChooseMultipleFilesExtensionReturn for ChooseMultipleFilesExtension). + + You can call supportsExtension() to check if an extension is supported by the page. + + Returns true if the extension was called successfully; otherwise returns false. + + \sa supportsExtension(), Extension +*/ + +/*! + \fn bool QWebPage::supportsExtension(Extension extension) const + This virtual function returns true if the web page supports \a extension; otherwise false is returned. + + \sa extension() +*/ + +/*! + \fn bool QWebPage::findText(const QString &subString, FindFlags options) + Finds the specified string, \a subString, in the page, using the given \a options. + + If the HighlightAllOccurrences flag is passed, the function will highlight all occurrences + that exist in the page. All subsequent calls will extend the highlight, rather than + replace it, with occurrences of the new string. + + If the HighlightAllOccurrences flag is not passed, the function will select an occurrence + and all subsequent calls will replace the current occurrence with the next one. + + To clear the selection, just pass an empty string. + + Returns true if \a subString was found; otherwise returns false. +*/ + +/*! + \fn QWebSettings *QWebPage::settings() const + Returns a pointer to the page's settings object. + + \sa QWebSettings::globalSettings() +*/ + +/*! + \fn QString QWebPage::chooseFile(QWebFrame *parentFrame, const QString& suggestedFile) + This function is called when the web content requests a file name, for example + as a result of the user clicking on a "file upload" button in a HTML form. + + A suggested filename may be provided in \a suggestedFile. The frame originating the + request is provided as \a parentFrame. + + \sa ChooseMultipleFilesExtension +*/ + +/*! + \fn void QWebPage::setNetworkAccessManager(QNetworkAccessManager *manager) + Sets the QNetworkAccessManager \a manager responsible for serving network requests for this + QWebPage. + + \note It is currently not supported to change the network access manager after the + QWebPage has used it. The results of doing this are undefined. + + \sa networkAccessManager() +*/ + +/*! + \fn QNetworkAccessManager *QWebPage::networkAccessManager() const + Returns the QNetworkAccessManager that is responsible for serving network + requests for this QWebPage. + + \sa setNetworkAccessManager() +*/ + +/*! + \fn void QWebPage::setPluginFactory(QWebPluginFactory *factory) + Sets the QWebPluginFactory \a factory responsible for creating plugins embedded into this + QWebPage. + + Note: The plugin factory is only used if the QWebSettings::PluginsEnabled attribute is enabled. + + \sa pluginFactory() +*/ + +/*! + \fn QWebPluginFactory *QWebPage::pluginFactory() const + Returns the QWebPluginFactory that is responsible for creating plugins embedded into + this QWebPage. If no plugin factory is installed a null pointer is returned. + + \sa setPluginFactory() +*/ + +/*! + \fn QString QWebPage::userAgentForUrl(const QUrl&) const + This function is called when a user agent for HTTP requests is needed. You can reimplement this + function to dynamically return different user agents for different URLs, based on the \a url parameter. + + The default implementation returns the following value: + + "Mozilla/5.0 (%Platform%%Security%%Subplatform%) AppleWebKit/%WebKitVersion% (KHTML, like Gecko) %AppVersion Safari/%WebKitVersion%" + + In this string the following values are replaced at run-time: + \list + \li %Platform% expands to the windowing system followed by "; " if it is not Windows (e.g. "X11; "). + \li %Security% expands to "N; " if SSL is disabled. + \li %Subplatform% expands to the operating system version (e.g. "Windows NT 6.1" or "Intel Mac OS X 10.5"). + \li %WebKitVersion% is the version of WebKit the application was compiled against. + \li %AppVersion% expands to QCoreApplication::applicationName()/QCoreApplication::applicationVersion() if they're set; otherwise defaulting to Qt and the current Qt version. + \endlist +*/ + +/*! + \fn quint64 QWebPage::totalBytes() const + Returns the total number of bytes that were received from the network to render the current page, + including extra content such as embedded images. + + \sa bytesReceived() +*/ + +/*! + \fn quint64 QWebPage::bytesReceived() const + Returns the number of bytes that were received from the network to render the current page. + + \sa totalBytes(), loadProgress() +*/ + +/*! + \fn void QWebPage::setVisibilityState(VisibilityState state) + \property QWebPage::visibilityState + \brief the page's visibility state + + This property should be changed by Qt applications who want to notify the JavaScript application + that the visibility state has changed (e.g. by reimplementing QWidget::setVisible). + The visibility state will be updated with the \a state parameter value only if it's different from the previous set. + Then, HTML DOM Document Object attributes 'hidden' and 'visibilityState' + will be updated to the correct value and a 'visiblitychange' event will be fired. + More information about this HTML5 API can be found at \l{http://www.w3.org/TR/page-visibility/}{W3C Recommendation: Page Visibility}. + + By default, this property is set to VisibilityStateVisible. +*/ + +/*! + \since 4.8 + \fn void QWebPage::viewportChangeRequested() + + Page authors can provide the supplied values by using the viewport meta tag. More information + about this can be found at \l{http://developer.apple.com/safari/library/documentation/appleapplications/reference/safariwebcontent/usingtheviewport/usingtheviewport.html}{Safari Reference Library: Using the Viewport Meta Tag}. + + \sa QWebPage::ViewportAttributes, setPreferredContentsSize(), QGraphicsWebView::setScale() +*/ + +/*! + \fn void QWebPage::loadStarted() + + This signal is emitted when a page starts loading content. + + \sa loadFinished() +*/ + +/*! + \fn void QWebPage::loadProgress(int progress) + + This signal is emitted when the global progress status changes. + The current value is provided by \a progress and scales from 0 to 100, + which is the default range of QProgressBar. + It accumulates changes from all the child frames. + + \sa bytesReceived() +*/ + +/*! + \fn void QWebPage::loadFinished(bool ok) + + This signal is emitted when the page finishes loading content. This signal + is independent of script execution or page rendering. + \a ok will indicate whether the load was successful or any error occurred. + + \sa loadStarted(), ErrorPageExtension +*/ + +/*! + \fn void QWebPage::linkHovered(const QString &link, const QString &title, const QString &textContent) + + This signal is emitted when the mouse hovers over a link. + + \a link contains the link url. + \a title is the link element's title, if it is specified in the markup. + \a textContent provides text within the link element, e.g., text inside an HTML anchor tag. + + When the mouse leaves the link element the signal is emitted with empty parameters. + + \sa linkClicked() +*/ + +/*! + \fn void QWebPage::statusBarMessage(const QString& text) + + This signal is emitted when the statusbar \a text is changed by the page. +*/ + +/*! + \fn void QWebPage::frameCreated(QWebFrame *frame) + + This signal is emitted whenever the page creates a new \a frame. + + \sa currentFrame() +*/ + +/*! + \fn void QWebPage::selectionChanged() + + This signal is emitted whenever the selection changes, either interactively + or programmatically (e.g. by calling triggerAction() with a selection action). + + \sa selectedText() +*/ + +/*! + \fn void QWebPage::contentsChanged() + \since 4.5 + + This signal is emitted whenever the text in form elements changes + as well as other editable content. + + \sa contentEditable, modified, QWebFrame::toHtml(), QWebFrame::toPlainText() +*/ + +/*! + \fn void QWebPage::geometryChangeRequested(const QRect& geom) + + This signal is emitted whenever the document wants to change the position and size of the + page to \a geom. This can happen for example through JavaScript. +*/ + +/*! + \fn void QWebPage::repaintRequested(const QRect& dirtyRect) + + This signal is emitted whenever this QWebPage should be updated. It's useful + when rendering a QWebPage without a QWebView or QGraphicsWebView. + \a dirtyRect contains the area that needs to be updated. To paint the QWebPage get + the mainFrame() and call the render(QPainter*, const QRegion&) method with the + \a dirtyRect as the second parameter. + + \sa mainFrame() + \sa view() +*/ + +/*! + \fn void QWebPage::scrollRequested(int dx, int dy, const QRect& rectToScroll) + + This signal is emitted whenever the content given by \a rectToScroll needs + to be scrolled \a dx and \a dy downwards and no view was set. + + \sa view() +*/ + +/*! + \fn void QWebPage::windowCloseRequested() + + This signal is emitted whenever the page requests the web browser window to be closed, + for example through the JavaScript \c{window.close()} call. +*/ + +/*! + \fn void QWebPage::printRequested(QWebFrame *frame) + + This signal is emitted whenever the page requests the web browser to print \a frame, + for example through the JavaScript \c{window.print()} call. + + \sa QWebFrame::print(), QPrintPreviewDialog +*/ + +/*! + \fn void QWebPage::unsupportedContent(QNetworkReply *reply) + + This signal is emitted when WebKit cannot handle a link the user navigated to or a + web server's response includes a "Content-Disposition" header with the 'attachment' + directive. If "Content-Disposition" is present in \a reply, the web server is indicating + that the client should prompt the user to save the content regardless of content-type. + See RFC 2616 sections 19.5.1 for details about Content-Disposition. + + At signal emission time the meta-data of the QNetworkReply \a reply is available. + + \note The receiving slot is responsible for deleting the QNetworkReply \a reply. + + \note This signal is only emitted if the forwardUnsupportedContent property is set to true. + + \sa downloadRequested() +*/ + +/*! + \fn void QWebPage::downloadRequested(const QNetworkRequest &request) + + This signal is emitted when the user decides to download a link. The url of + the link as well as additional meta-information is contained in \a request. + + \sa unsupportedContent() +*/ + +/*! + \fn void QWebPage::microFocusChanged() + + This signal is emitted when for example the position of the cursor in an editable form + element changes. It is used to inform input methods about the new on-screen position where + the user is able to enter text. This signal is usually connected to the + QWidget::updateMicroFocus() slot. +*/ + +/*! + \fn void QWebPage::linkClicked(const QUrl &url) + + This signal is emitted whenever the user clicks on a link and the page's linkDelegationPolicy + property is set to delegate the link handling for the specified \a url. + + By default no links are delegated and are handled by QWebPage instead. + + \note This signal possibly won't be emitted for clicked links which use + JavaScript to trigger navigation. + + \sa linkHovered() +*/ + +/*! + \fn void QWebPage::toolBarVisibilityChangeRequested(bool visible) + + This signal is emitted whenever the visibility of the toolbar in a web browser + window that hosts QWebPage should be changed to \a visible. +*/ + +/*! + \fn void QWebPage::statusBarVisibilityChangeRequested(bool visible) + + This signal is emitted whenever the visibility of the statusbar in a web browser + window that hosts QWebPage should be changed to \a visible. +*/ + +/*! + \fn void QWebPage::menuBarVisibilityChangeRequested(bool visible) + + This signal is emitted whenever the visibility of the menubar in a web browser + window that hosts QWebPage should be changed to \a visible. +*/ + +/*! + \fn void QWebPage::databaseQuotaExceeded(QWebFrame* frame, QString databaseName); + \since 4.5 + + This signal is emitted whenever the web site shown in \a frame is asking to store data + to the database \a databaseName and the quota allocated to that web site is exceeded. + + \sa QWebDatabase +*/ +/*! + \fn void QWebPage::applicationCacheQuotaExceeded(QWebSecurityOrigin* origin, quint64 defaultOriginQuota, quint64 totalSpaceNeeded); + + This signal is emitted whenever the web site is asking to store data to the application cache + database databaseName and the quota allocated to that web site is exceeded. + +*/ + +/*! + \since 4.5 + \fn void QWebPage::saveFrameStateRequested(QWebFrame* frame, QWebHistoryItem* item); + + This signal is emitted shortly before the history of navigated pages + in \a frame is changed, for example when navigating back in the history. + + The provided QWebHistoryItem, \a item, holds the history entry of the frame before + the change. + + A potential use-case for this signal is to store custom data in + the QWebHistoryItem associated to the frame, using QWebHistoryItem::setUserData(). +*/ + +/*! + \since 4.5 + \fn void QWebPage::restoreFrameStateRequested(QWebFrame* frame); + + This signal is emitted when the load of \a frame is finished and the application may now update its state accordingly. +*/ + +/*! + \class QWebFrame + \since 4.4 + \brief The QWebFrame class represents a frame in a web page. + + \inmodule QtWebKit + + QWebFrame represents a frame inside a web page. Each QWebPage + object contains at least one frame, the main frame, obtained using + QWebPage::mainFrame(). Additional frames will be created for HTML + \c{<frame>} or \c{<iframe>} elements. + + A frame can be loaded using load() or setUrl(). Alternatively, if you have + the HTML content readily available, you can use setHtml() instead. + + The page() function returns a pointer to the web page object. See + \l{QWebView}{Elements of QWebView} for an explanation of how web + frames are related to a web page and web view. + + The QWebFrame class also offers methods to retrieve both the URL currently + loaded by the frame (see url()) as well as the URL originally requested + to be loaded (see requestedUrl()). These methods make possible the retrieval + of the URL before and after a DNS resolution or a redirection occurs during + the load process. The requestedUrl() also matches to the URL added to the + frame history (\l{QWebHistory}) if load is successful. + + The title of an HTML frame can be accessed with the title() property. + Additionally, a frame may also specify an icon, which can be accessed + using the icon() property. If the title or the icon changes, the + corresponding titleChanged() and iconChanged() signals will be emitted. + The zoomFactor() property can be used to change the overall size + of the content displayed in the frame. + + QWebFrame objects are created and controlled by the web page. You + can connect to the web page's \l{QWebPage::}{frameCreated()} signal + to be notified when a new frame is created. + + There are multiple ways to programmatically examine the contents of a frame. + The hitTestContent() function can be used to find elements by coordinate. + For access to the underlying DOM tree, there is documentElement(), + findAllElements() and findFirstElement(). + + A QWebFrame can be printed onto a QPrinter using the print() function. + This function is marked as a slot and can be conveniently connected to + \l{QPrintPreviewDialog}'s \l{QPrintPreviewDialog::}{paintRequested()} + signal. + + \sa QWebPage +*/ + +/*! + \enum QWebFrame::RenderLayer + + This enum describes the layers available for rendering using \l{QWebFrame::}{render()}. + The layers can be OR-ed together from the following list: + + \value ContentsLayer The web content of the frame + \value ScrollBarLayer The scrollbars of the frame + \value PanIconLayer The icon used when panning the frame + + \value AllLayers Includes all the above layers +*/ + +/*! + \fn void QWebFrame::addToJavaScriptWindowObject(const QString &name, QObject *object, ValueOwnership own) + + Make \a object available under \a name from within the frame's JavaScript + context. The \a object will be inserted as a child of the frame's window + object. + + Qt properties will be exposed as JavaScript properties and slots as + JavaScript methods. + The interaction between C++ and JavaScript is explained in the documentation of the \l{The Qt WebKit Bridge}{Qt WebKit bridge}. + + If you want to ensure that your QObjects remain accessible after loading a + new URL, you should add them in a slot connected to the + javaScriptWindowObjectCleared() signal. + + If Javascript is not enabled for this page, then this method does nothing. + + The ownership of \a object is specified using \a own. +*/ + +/*! + \fn QString QWebFrame::toHtml() const + Returns the frame's content as HTML, enclosed in HTML and BODY tags. + + \sa setHtml(), toPlainText() +*/ + +/*! + \fn QString QWebFrame::toPlainText() const + Returns the content of this frame converted to plain text, completely + stripped of all HTML formatting. + + \sa toHtml() +*/ + +/*! + \fn QString QWebFrame::title() const + \property QWebFrame::title + \brief the title of the frame as defined by the HTML <title> element + + \sa titleChanged() +*/ + +/*! + \fn QMultiMap<QString, QString> QWebFrame::metaData() const + \since 4.5 + \brief Returns the meta data in this frame as a QMultiMap + + The meta data consists of the name and content attributes of the + of the \c{<meta>} tags in the HTML document. + + For example: + + \code + <html> + <head> + <meta name="description" content="This document is a tutorial about Qt development"> + <meta name="keywords" content="Qt, WebKit, Programming"> + </head> + ... + </html> + \endcode + + Given the above HTML code the metaData() function will return a map with two entries: + \table + \header \li Key + \li Value + \row \li "description" + \li "This document is a tutorial about Qt development" + \row \li "keywords" + \li "Qt, WebKit, Programming" + \endtable + + This function returns a multi map to support multiple meta tags with the same attribute name. +*/ + +/*! + \fn void QWebFrame::setUrl(const QUrl &url) + \property QWebFrame::url + \brief the url of the frame currently viewed + + Setting this property clears the view and loads the URL. + + By default, this property contains an empty, invalid URL. + + \sa urlChanged() +*/ + +/*! + \fn QUrl QWebFrame::requestedUrl() const + \since 4.6 + \property QWebFrame::requestedUrl + + The URL requested to loaded by the frame currently viewed. The URL may differ from + the one returned by url() if a DNS resolution or a redirection occurs. + + \sa url(), setUrl() +*/ + +/*! + \fn QUrl QWebFrame::baseUrl() const + \since 4.6 + \property QWebFrame::baseUrl + \brief the base URL of the frame, can be used to resolve relative URLs + \since 4.6 +*/ + +/*! + \fn QIcon QWebFrame::icon() const + \property QWebFrame::icon + \brief the icon associated with this frame + + \sa iconChanged(), QWebSettings::iconForUrl() +*/ + +/*! + \fn QString QWebFrame::frameName() const + The name of this frame as defined by the parent frame. +*/ + +/*! + \fn QWebPage *QWebFrame::page() const + The web page that contains this frame. + + \sa pageChanged() +*/ + +/*! + \fn void QWebFrame::load(const QUrl &url) + Loads \a url into this frame. + + \note The view remains the same until enough data has arrived to display the new \a url. + + \sa setUrl(), setHtml(), setContent() +*/ + +/*! + \fn void QWebFrame::load(const QNetworkRequest &req, QNetworkAccessManager::Operation operation, const QByteArray &body) + Loads a network request, \a req, into this frame, using the method specified in \a + operation. + + \a body is optional and is only used for POST operations. + + \note The view remains the same until enough data has arrived to display the new content. + + \sa setUrl() +*/ + +/*! + \fn void QWebFrame::setHtml(const QString &html, const QUrl &baseUrl) + Sets the content of this frame to \a html. \a baseUrl is optional and used to resolve relative + URLs in the document, such as referenced images or stylesheets. + + The \a html is loaded immediately; external objects are loaded asynchronously. + + If a script in the \a html runs longer than the default script timeout (currently 10 seconds), + for example due to being blocked by a modal JavaScript alert dialog, this method will return + as soon as possible after the timeout and any subsequent \a html will be loaded asynchronously. + + When using this method WebKit assumes that external resources such as JavaScript programs or style + sheets are encoded in UTF-8 unless otherwise specified. For example, the encoding of an external + script can be specified through the charset attribute of the HTML script tag. It is also possible + for the encoding to be specified by web server. + + This is a convenience function equivalent to setContent(html, "text/html", baseUrl). + + \note This method will not affect session or global history for the frame. + + \warning This function works only for HTML, for other mime types (i.e. XHTML, SVG) + setContent() should be used instead. + + \sa toHtml(), setContent(), load() +*/ + +/*! + \fn void QWebFrame::setContent(const QByteArray &data, const QString &mimeType, const QUrl &baseUrl) + Sets the content of this frame to the specified content \a data. If the \a mimeType argument + is empty it is currently assumed that the content is HTML but in future versions we may introduce + auto-detection. + + External objects referenced in the content are located relative to \a baseUrl. + + The \a data is loaded immediately; external objects are loaded asynchronously. + + \note This method will not affect session or global history for the frame. + + \sa toHtml(), setHtml() +*/ + +/*! + \fn QWebFrame *QWebFrame::parentFrame() const + Returns the parent frame of this frame, or 0 if the frame is the web pages + main frame. + + This is equivalent to qobject_cast<QWebFrame*>(frame->parent()). + + \sa childFrames() +*/ + +/*! + \fn QList<QWebFrame*> QWebFrame::childFrames() const + Returns a list of all frames that are direct children of this frame. + + \sa parentFrame() +*/ + +/*! + \fn Qt::ScrollBarPolicy QWebFrame::scrollBarPolicy(Qt::Orientation orientation) const + Returns the scrollbar policy for the scrollbar defined by \a orientation. +*/ + +/*! + \fn void QWebFrame::setScrollBarPolicy(Qt::Orientation orientation, Qt::ScrollBarPolicy policy) + Sets the scrollbar policy for the scrollbar defined by \a orientation to \a policy. +*/ + +/*! + \fn void QWebFrame::setScrollBarValue(Qt::Orientation orientation, int value) + Sets the current \a value for the scrollbar with orientation \a orientation. + + The scrollbar forces the \a value to be within the legal range: minimum <= value <= maximum. + + Changing the value also updates the thumb position. + + \sa scrollBarMinimum(), scrollBarMaximum() +*/ + +/*! + \fn int QWebFrame::scrollBarValue(Qt::Orientation orientation) const + Returns the current value for the scrollbar with orientation \a orientation, or 0 + if no scrollbar is found for \a orientation. + + \sa scrollBarMinimum(), scrollBarMaximum() +*/ + +/*! + \fn int QWebFrame::scrollBarMaximum(Qt::Orientation orientation) const + Returns the maximum value for the scrollbar with orientation \a orientation, or 0 + if no scrollbar is found for \a orientation. + + \sa scrollBarMinimum() +*/ + +/*! + \fn int QWebFrame::scrollBarMinimum(Qt::Orientation orientation) const + Returns the minimum value for the scrollbar with orientation \a orientation. + + The minimum value is always 0. + + \sa scrollBarMaximum() +*/ + +/*! + \fn QRect QWebFrame::scrollBarGeometry(Qt::Orientation orientation) const + \since 4.6 + Returns the geometry for the scrollbar with orientation \a orientation. + + If the scrollbar does not exist an empty rect is returned. +*/ + +/*! + \fn void QWebFrame::scroll(int dx, int dy) + \since 4.5 + Scrolls the frame \a dx pixels to the right and \a dy pixels downward. Both + \a dx and \a dy may be negative. + + \sa QWebFrame::scrollPosition +*/ + +/*! + \fn QPoint QWebFrame::scrollPosition() const + \property QWebFrame::scrollPosition + \since 4.5 + \brief the position the frame is currently scrolled to. +*/ + +/*! + \fn void QWebFrame::scrollToAnchor(const QString& anchor) + \since 4.7 + Scrolls the frame to the given \a anchor name. +*/ + +/*! + \fn void QWebFrame::render(QPainter* painter, RenderLayers layer, const QRegion& clip) + \since 4.6 + Render the \a layer of the frame using \a painter clipping to \a clip. + + \sa print() +*/ + +/*! + \fn void QWebFrame::render(QPainter* painter, const QRegion& clip) + Render the frame into \a painter clipping to \a clip. +*/ + +/*! + \property QWebFrame::textSizeMultiplier + \brief the scaling factor for all text in the frame + \obsolete + + Use setZoomFactor instead, in combination with the ZoomTextOnly attribute in + QWebSettings. + + \note Setting this property also enables the ZoomTextOnly attribute in + QWebSettings. +*/ + +/*! + \fn void QWebFrame::setTextSizeMultiplier(qreal factor) + Sets the value of the multiplier used to scale the text in a Web frame to + the \a factor specified. +*/ + +/*! + \fn qreal QWebFrame::textSizeMultiplier() const + Returns the value of the multiplier used to scale the text in a Web frame. +*/ + +/*! + \fn void QWebFrame::setZoomFactor(qreal factor) + \property QWebFrame::zoomFactor + \since 4.5 + \brief the zoom factor for the frame +*/ + +/*! + \fn bool QWebFrame::hasFocus() const + \property QWebFrame::focus + \since 4.6 + + Returns true if this frame has keyboard input focus; otherwise, returns false. +*/ + +/*! + \fn void QWebFrame::setFocus() + \since 4.6 + + Gives keyboard input focus to this frame. +*/ + +/*! + \fn QPoint QWebFrame::pos() const + Returns the position of the frame relative to it's parent frame. +*/ + +/*! + \fn QRect QWebFrame::geometry() const + Return the geometry of the frame relative to it's parent frame. +*/ + +/*! + \fn QSize QWebFrame::contentsSize() const + \property QWebFrame::contentsSize + \brief the size of the contents in this frame + + \sa contentsSizeChanged() +*/ + +/*! + \fn QWebElement QWebFrame::documentElement() const + \since 4.6 + + Returns the document element of this frame. + + The document element provides access to the entire structured + content of the frame. +*/ + +/*! + \fn QWebElementCollection QWebFrame::findAllElements(const QString &selectorQuery) const + \since 4.6 + Returns a new list of elements matching the given CSS selector \a selectorQuery. + If there are no matching elements, an empty list is returned. + + \l{http://www.w3.org/TR/REC-CSS2/selector.html#q1}{Standard CSS2 selector} syntax is + used for the query. + + \sa QWebElement::findAll() +*/ + +/*! + \fn QWebElement QWebFrame::findFirstElement(const QString &selectorQuery) const + \since 4.6 + Returns the first element in the frame's document that matches the + given CSS selector \a selectorQuery. If there is no matching element, a + null element is returned. + + \l{http://www.w3.org/TR/REC-CSS2/selector.html#q1}{Standard CSS2 selector} syntax is + used for the query. + + \sa QWebElement::findFirst() +*/ + +/*! + \fn QWebHitTestResult QWebFrame::hitTestContent(const QPoint &pos) const + Performs a hit test on the frame contents at the given position \a pos and returns the hit test result. +*/ + +/*! + \fn void QWebFrame::print(QPrinter *printer) const + Prints the frame to the given \a printer. + + \sa render() +*/ + +/*! + \fn QVariant QWebFrame::evaluateJavaScript(const QString& scriptSource) + Evaluates the JavaScript defined by \a scriptSource using this frame as context + and returns the result of the last executed statement. + + \sa addToJavaScriptWindowObject(), javaScriptWindowObjectCleared() +*/ + +/*! + \fn QWebSecurityOrigin QWebFrame::securityOrigin() const + \since 4.5 + + Returns the frame's security origin. +*/ + +/*! + \fn void QWebFrame::javaScriptWindowObjectCleared() + + This signal is emitted whenever the global window object of the JavaScript + environment is cleared, e.g., before starting a new load. + + If you intend to add QObjects to a QWebFrame using + addToJavaScriptWindowObject(), you should add them in a slot connected + to this signal. This ensures that your objects remain accessible when + loading new URLs. +*/ + +/*! + \fn void QWebFrame::provisionalLoad() + \internal +*/ + +/*! + \fn void QWebFrame::titleChanged(const QString &title) + + This signal is emitted whenever the title of the frame changes. + The \a title string specifies the new title. + + \sa title() +*/ + +/*! + \fn void QWebFrame::urlChanged(const QUrl &url) + + This signal is emitted with the URL of the frame when the frame's title is + received. The new URL is specified by \a url. + + \sa url() +*/ + +/*! + \fn void QWebFrame::initialLayoutCompleted() + + This signal is emitted when the frame is laid out the first time. + This is the first time you will see contents displayed on the frame. + + \note A frame can be laid out multiple times. +*/ + +/*! + \fn void QWebFrame::iconChanged() + + This signal is emitted when the icon ("favicon") associated with the frame + has been loaded. + + \sa icon() +*/ + +/*! + \fn void QWebFrame::contentsSizeChanged(const QSize &size) + \since 4.6 + + This signal is emitted when the frame's contents size changes + to \a size. + + \sa contentsSize() +*/ + +/*! + \fn void QWebFrame::loadStarted() + \since 4.6 + + This signal is emitted when a new load of this frame is started. + + \sa loadFinished() +*/ + +/*! + \fn void QWebFrame::loadFinished(bool ok) + \since 4.6 + + This signal is emitted when a load of this frame is finished. + \a ok will indicate whether the load was successful or any error occurred. + + \sa loadStarted() +*/ + +/*! + \fn void QWebFrame::pageChanged() + \since 4.7 + + This signal is emitted when this frame has been moved to a different QWebPage. + + \sa page() +*/ + +/*! + \class QWebHitTestResult + \since 4.4 + \brief The QWebHitTestResult class provides information about the web + page content after a hit test. + + \inmodule QtWebKit + + QWebHitTestResult is returned by QWebFrame::hitTestContent() to provide + information about the content of the web page at the specified position. +*/ + +/*! + \fn QWebHitTestResult::QWebHitTestResult() + Constructs a null hit test result. +*/ + +/*! + \fn QWebHitTestResult::QWebHitTestResult(const QWebHitTestResult &other) + Constructs a hit test result from \a other. +*/ + +/*! + \fn QWebHitTestResult &QWebHitTestResult::operator=(const QWebHitTestResult &other) + Assigns the \a other hit test result to this. +*/ + +/*! + \fn QWebHitTestResult::~QWebHitTestResult() + Destructor. +*/ + +/*! + \fn bool QWebHitTestResult::isNull() const + Returns true if the hit test result is null; otherwise returns false. +*/ + +/*! + \fn QPoint QWebHitTestResult::pos() const + Returns the position where the hit test occurred in the coordinates of frame containing the element hit. + + \sa frame() +*/ + +/*! + \fn QRect QWebHitTestResult::boundingRect() const + \since 4.5 + Returns the bounding rect of the element. +*/ + +/*! + \fn QWebElement QWebHitTestResult::enclosingBlockElement() const + \since 4.6 + Returns the block element that encloses the element hit. + + A block element is an element that is rendered using the + CSS "block" style. This includes for example text + paragraphs. +*/ + +/*! + \fn QString QWebHitTestResult::title() const + Returns the title of the nearest enclosing HTML element. +*/ + +/*! + \fn QString QWebHitTestResult::linkText() const + Returns the text of the link. +*/ + +/*! + \fn QUrl QWebHitTestResult::linkUrl() const + Returns the url to which the link points to. +*/ + +/*! + \fn QUrl QWebHitTestResult::linkTitle() const + Returns the title of the link. +*/ + +/*! + \fn QWebElement QWebHitTestResult::linkElement() const + \since 4.6 + Returns the element that represents the link. + + \sa linkTargetFrame() +*/ + +/*! + \fn QWebFrame *QWebHitTestResult::linkTargetFrame() const + Returns the frame that will load the link if it is activated. + + \sa linkElement() +*/ + +/*! + \fn QString QWebHitTestResult::alternateText() const + Returns the alternate text of the element. This corresponds to the HTML alt attribute. +*/ + +/*! + \fn QUrl QWebHitTestResult::imageUrl() const + Returns the url of the image. +*/ + +/*! + \fn QPixmap QWebHitTestResult::pixmap() const + Returns a QPixmap containing the image. A null pixmap is returned if the + element being tested is not an image. +*/ + +/*! + \fn bool QWebHitTestResult::isContentEditable() const + Returns true if the content is editable by the user; otherwise returns false. +*/ + +/*! + \fn bool QWebHitTestResult::isContentSelected() const + Returns true if the content tested is part of the selection; otherwise returns false. +*/ + +/*! + \fn QWebElement QWebHitTestResult::element() const + \since 4.6 + Returns the underlying DOM element as QWebElement. +*/ + +/*! + \fn QWebFrame *QWebHitTestResult::frame() const + Returns the frame of the element hit. +*/ diff --git a/src/webenginewidgets/doc/src/qwebenginesecurityorigin_lgpl.qdoc b/src/webenginewidgets/doc/src/qwebenginesecurityorigin_lgpl.qdoc new file mode 100644 index 000000000..396ec94d8 --- /dev/null +++ b/src/webenginewidgets/doc/src/qwebenginesecurityorigin_lgpl.qdoc @@ -0,0 +1,148 @@ +/* + 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 QWebSecurityOrigin + \since 4.5 + \brief The QWebSecurityOrigin class defines a security boundary for web sites. + + \inmodule QtWebKit + + QWebSecurityOrigin provides access to the security domains defined by web sites. + An origin consists of a host name, a scheme, and a port number. Web sites + with the same security origin can access each other's resources for client-side + scripting or databases. + + For example the site \c{http://www.example.com/my/page.html} is allowed to share the same + database as \c{http://www.example.com/my/overview.html}, or access each other's + documents when used in HTML frame sets and JavaScript. At the same time it prevents + \c{http://www.malicious.com/evil.html} from accessing \c{http://www.example.com/}'s resources, + because they are of a different security origin. + + By default local schemes like \c{file://} and \c{qrc://} are concidered to be in the same + security origin, and can access each other's resources. You can add additional local schemes + by using QWebSecurityOrigin::addLocalScheme(), or override the default same-origin behavior + by setting QWebSettings::LocalContentCanAccessFileUrls to \c{false}. + + \note Local resources are by default restricted from accessing remote content, which + means your \c{file://} will not be able to access \c{http://domain.com/foo.html}. You + can relax this restriction by setting QWebSettings::LocalContentCanAccessRemoteUrls to + \c{true}. + + Call QWebFrame::securityOrigin() to get the QWebSecurityOrigin for a frame in a + web page, and use host(), scheme() and port() to identify the security origin. + + Use databases() to access the databases defined within a security origin. The + disk usage of the origin's databases can be limited with setDatabaseQuota(). + databaseQuota() and databaseUsage() report the current limit as well as the + current usage. + + For more information refer to the + \l{http://en.wikipedia.org/wiki/Same_origin_policy}{"Same origin policy" Wikipedia Article}. + + \sa QWebFrame::securityOrigin() +*/ + +/*! + \fn QString QWebSecurityOrigin::scheme() const + Returns the scheme defining the security origin. +*/ + +/*! + \fn QString QWebSecurityOrigin::host() const + Returns the host name defining the security origin. +*/ + +/*! + \fn int QWebSecurityOrigin::port() const + Returns the port number defining the security origin. +*/ + +/*! + \fn qint64 QWebSecurityOrigin::databaseUsage() const + Returns the number of bytes all databases in the security origin + use on the disk. +*/ + +/*! + \fn qint64 QWebSecurityOrigin::databaseQuota() const + Returns the quota for the databases in the security origin. +*/ + +/*! + \fn void QWebSecurityOrigin::setDatabaseQuota(qint64 quota) + Sets the quota for the databases in the security origin to \a quota bytes. + + If the quota is set to a value less than the current usage, the quota will remain + and no data will be purged to meet the new quota. However, no new data can be added + to databases in this origin. +*/ + +/*! + \fn QWebSecurityOrigin::~QWebSecurityOrigin() + Destroys the security origin. +*/ + +/*! + \fn QList<QWebSecurityOrigin> QWebSecurityOrigin::allOrigins() + Returns a list of all security origins with a database quota defined. +*/ + +/*! + \fn QList<QWebDatabase> QWebSecurityOrigin::databases() const + Returns a list of all databases defined in the security origin. +*/ + +/*! + \fn void QWebSecurityOrigin::addLocalScheme(const QString& scheme) + \since 4.6 + + Adds the given \a scheme to the list of schemes that are considered equivalent + to the \c file: scheme. + + Cross domain restrictions depend on the two web settings QWebSettings::LocalContentCanAccessFileUrls + and QWebSettings::LocalContentCanAccessFileUrls. By default all local schemes are concidered to be + in the same security origin, and local schemes can not access remote content. +*/ + +/*! + \fn void QWebSecurityOrigin::removeLocalScheme(const QString& scheme) + \since 4.6 + + Removes the given \a scheme from the list of local schemes. + + \note You can not remove the \c{file://} scheme from the list + of local schemes. + + \sa addLocalScheme() +*/ + +/*! + \fn QStringList QWebSecurityOrigin::localSchemes() + \since 4.6 + Returns a list of all the schemes concidered to be local. + + By default this is \c{file://} and \c{qrc://}. + + \sa addLocalScheme(), removeLocalScheme() +*/ 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() +*/ diff --git a/src/webenginewidgets/doc/src/qwebengineview_lgpl.qdoc b/src/webenginewidgets/doc/src/qwebengineview_lgpl.qdoc new file mode 100644 index 000000000..9440ebd83 --- /dev/null +++ b/src/webenginewidgets/doc/src/qwebengineview_lgpl.qdoc @@ -0,0 +1,544 @@ +/* + Copyright (C) 2008 Nokia Corporation and/or its subsidiary(-ies) + Copyright (C) 2008 Holger Hans Peter Freyther + Copyright (C) 2009 Girish Ramakrishnan <girish@forwardbias.in> + + 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 QWebView + \since 4.4 + \brief The QWebView class provides a widget that is used to view and edit + web documents. + \ingroup advanced + + \inmodule QtWebKit + + QWebView is the main widget component of the Qt WebKit web browsing module. + It can be used in various applications to display web content live from the + Internet. + + The image below shows QWebView previewed in \QD with a Nokia website. + + \image qwebview-url.png + + A web site can be loaded onto QWebView with the load() function. Like all + Qt widgets, the show() function must be invoked in order to display + QWebView. The snippet below illustrates this: + + \snippet webkitsnippets/simple/main.cpp Using QWebView + + Alternatively, setUrl() can also be used to load a web site. If you have + the HTML content readily available, you can use setHtml() instead. + + The loadStarted() signal is emitted when the view begins loading. The + loadProgress() signal, on the other hand, is emitted whenever an element of + the web view completes loading, such as an embedded image, a script, etc. + Finally, the loadFinished() signal is emitted when the view has loaded + completely. It's argument - either \c true or \c false - indicates + load success or failure. + + The page() function returns a pointer to the web page object. See + \l{Elements of QWebView} for an explanation of how the web page + is related to the view. To modify your web view's settings, you can access + the QWebSettings object with the settings() function. With QWebSettings, + you can change the default fonts, enable or disable features such as + JavaScript and plugins. + + The title of an HTML document can be accessed with the title() property. + Additionally, a web site may also specify an icon, which can be accessed + using the icon() property. If the title or the icon changes, the corresponding + titleChanged() and iconChanged() signals will be emitted. The + textSizeMultiplier() property can be used to change the overall size of + the text displayed in the web view. + + If you require a custom context menu, you can implement it by reimplementing + \l{QWidget::}{contextMenuEvent()} and populating your QMenu with the actions + obtained from pageAction(). More functionality such as reloading the view, + copying selected text to the clipboard, or pasting into the view, is also + encapsulated within the QAction objects returned by pageAction(). These + actions can be programmatically triggered using triggerPageAction(). + Alternatively, the actions can be added to a toolbar or a menu directly. + QWebView maintains the state of the returned actions but allows + modification of action properties such as \l{QAction::}{text} or + \l{QAction::}{icon}. + + A QWebView can be printed onto a QPrinter using the print() function. + This function is marked as a slot and can be conveniently connected to + \l{QPrintPreviewDialog}'s \l{QPrintPreviewDialog::}{paintRequested()} + signal. + + If you want to provide support for web sites that allow the user to open + new windows, such as pop-up windows, you can subclass QWebView and + reimplement the createWindow() function. + + \section1 Elements of QWebView + + QWebView consists of other objects such as QWebFrame and QWebPage. The + flowchart below shows these elements are related. + + \image qwebview-diagram.png + + \note It is possible to use QWebPage and QWebFrame, without using QWebView, + if you do not require QWidget attributes. Nevertheless, Qt WebKit depends + on QtGui, so you should use a QApplication instead of QCoreApplication. + + \sa {Previewer Example}, {Web Browser}, {Form Extractor Example}, + {Google Chat Example}, {Fancy Browser Example} +*/ + + +/*! + \fn QWebView::QWebView(QWidget *parent) + Constructs an empty QWebView with parent \a parent. + + \sa load() +*/ + +/*! + \fn QWebView::~QWebView() + Destroys the web view. +*/ + +/*! + \fn QWebPage *QWebView::page() const + Returns a pointer to the underlying web page. + + \sa setPage() +*/ + +/*! + \fn void QWebView::setPage(QWebPage* page) + Makes \a page the new web page of the web view. + + The parent QObject of the provided page remains the owner + of the object. If the current page is a child of the web + view, it will be deleted. + + \sa page() +*/ + +/*! + \fn void QWebView::load(const QUrl &url) + Loads the specified \a url and displays it. + + \note The view remains the same until enough data has arrived to display the new \a url. + + \sa setUrl(), url(), urlChanged(), QUrl::fromUserInput() +*/ + +/*! + \fn void QWebView::load(const QNetworkRequest &request, QNetworkAccessManager::Operation operation, const QByteArray &body) + \fn void QWebView::load(const QNetworkRequest &request, QNetworkAccessManager::Operation operation, const QByteArray &body) + + Loads a network request, \a request, using the method specified in \a operation. + + \a body is optional and is only used for POST operations. + + \note The view remains the same until enough data has arrived to display the new url. + + \sa url(), urlChanged() +*/ + + +/*! + \fn void QWebView::setHtml(const QString &html, const QUrl &baseUrl) + Sets the content of the web view to the specified \a html. + + External objects such as stylesheets or images referenced in the HTML + document are located relative to \a baseUrl. + + The \a html is loaded immediately; external objects are loaded asynchronously. + + When using this method, WebKit assumes that external resources such as + JavaScript programs or style sheets are encoded in UTF-8 unless otherwise + specified. For example, the encoding of an external script can be specified + through the charset attribute of the HTML script tag. Alternatively, the + encoding can also be specified by the web server. + + This is a convenience function equivalent to setContent(html, "text/html", baseUrl). + + \warning This function works only for HTML, for other mime types (i.e. XHTML, SVG) + setContent() should be used instead. + + \sa load(), setContent(), QWebFrame::toHtml(), QWebFrame::setContent() +*/ + +/*! + \fn void QWebView::setContent(const QByteArray &data, const QString &mimeType, const QUrl &baseUrl) + Sets the content of the web view to the specified content \a data. If the \a mimeType argument + is empty it is currently assumed that the content is HTML but in future versions we may introduce + auto-detection. + + External objects referenced in the content are located relative to \a baseUrl. + + The \a data is loaded immediately; external objects are loaded asynchronously. + + \sa load(), setHtml(), QWebFrame::toHtml() +*/ + +/*! + \fn QWebHistory *QWebView::history() const + Returns a pointer to the view's history of navigated web pages. + + It is equivalent to + + \snippet webkitsnippets/qtwebkit_qwebview_snippet.cpp 0 +*/ + +/*! + \fn QWebSettings *QWebView::settings() const + Returns a pointer to the view/page specific settings object. + + It is equivalent to + + \snippet webkitsnippets/qtwebkit_qwebview_snippet.cpp 1 + + \sa QWebSettings::globalSettings() +*/ + +/*! + \property QWebView::title + \brief the title of the web page currently viewed + + By default, this property contains an empty string. + + \sa titleChanged() +*/ + +/*! + \property QWebView::url + \brief the url of the web page currently viewed + + Setting this property clears the view and loads the URL. + + By default, this property contains an empty, invalid URL. + + \sa load(), urlChanged() +*/ + + +/*! + \property QWebView::icon + \brief the icon associated with the web page currently viewed + + By default, this property contains a null icon. + + \sa iconChanged(), QWebSettings::iconForUrl() +*/ + +/*! + \property QWebView::hasSelection + \brief whether this page contains selected content or not. + + By default, this property is false. + + \sa selectionChanged() +*/ + +/*! + \property QWebView::selectedText + \brief the text currently selected + + By default, this property contains an empty string. + + \sa findText(), selectionChanged(), selectedHtml() +*/ + +/*! + \since 4.8 + \property QWebView::selectedHtml + \brief the HTML currently selected + + By default, this property contains an empty string. + + \sa findText(), selectionChanged(), selectedText() +*/ + +/*! + \fn QAction *QWebView::pageAction(QWebPage::WebAction action) const + Returns a pointer to a QAction that encapsulates the specified web action \a action. +*/ + +/*! + \fn void QWebView::triggerPageAction(QWebPage::WebAction action, bool checked) + Triggers the specified \a action. If it is a checkable action the specified + \a checked state is assumed. + + The following example triggers the copy action and therefore copies any + selected text to the clipboard. + + \snippet webkitsnippets/qtwebkit_qwebview_snippet.cpp 2 + + \sa pageAction() +*/ + +/*! + \property QWebView::modified + \brief whether the document was modified by the user + + Parts of HTML documents can be editable for example through the + \c{contenteditable} attribute on HTML elements. + + By default, this property is false. +*/ + +/* + \property QWebView::textInteractionFlags + \brief how the view should handle user input + + Specifies how the user can interact with the text on the page. +*/ + + +/*! + \property QWebView::zoomFactor + \since 4.5 + \brief the zoom factor for the view +*/ + + +/*! + \property QWebView::textSizeMultiplier + \brief the scaling factor for all text in the frame + \obsolete + + Use setZoomFactor instead, in combination with the + ZoomTextOnly attribute in QWebSettings. + + \note Setting this property also enables the + ZoomTextOnly attribute in QWebSettings. + + By default, this property contains a value of 1.0. +*/ + +/*! + \fn void QWebView::setTextSizeMultiplier(qreal factor) + Sets the value of the multiplier used to scale the text in a Web page to + the \a factor specified. +*/ + +/*! + \fn qreal QWebView::textSizeMultiplier() const + Returns the value of the multiplier used to scale the text in a Web page. +*/ + +/*! + \property QWebView::renderHints + \since 4.6 + \brief the default render hints for the view + + These hints are used to initialize QPainter before painting the Web page. + + QPainter::TextAntialiasing and QPainter::SmoothPixmapTransform are enabled by default. + + \sa QPainter::renderHints() +*/ + +/*! + \fn QPainter::RenderHints QWebView::renderHints() const + \since 4.6 + Returns the render hints used by the view to render content. + + \sa QPainter::renderHints() +*/ + +/*! + \fn void QWebView::setRenderHints(QPainter::RenderHints hints) + \since 4.6 + Sets the render hints used by the view to the specified \a hints. + + \sa QPainter::setRenderHints() +*/ + +/*! + \fn void QWebView::setRenderHint(QPainter::RenderHint hint, bool enabled) + \since 4.6 + If \a enabled is true, enables the specified render \a hint; otherwise + disables it. + + \sa renderHints, QPainter::renderHints() +*/ + +/*! + \fn bool QWebView::findText(const QString &subString, QWebPage::FindFlags options) + Finds the specified string, \a subString, in the page, using the given \a options. + + If the HighlightAllOccurrences flag is passed, the function will highlight all occurrences + that exist in the page. All subsequent calls will extend the highlight, rather than + replace it, with occurrences of the new string. + + If the HighlightAllOccurrences flag is not passed, the function will select an occurrence + and all subsequent calls will replace the current occurrence with the next one. + + To clear the selection, just pass an empty string. + + Returns true if \a subString was found; otherwise returns false. + + \sa selectedText(), selectionChanged() +*/ + +/*! + \fn void QWebView::print(QPrinter *printer) const + Prints the main frame to the given \a printer. + + \sa QWebFrame::print(), QPrintPreviewDialog +*/ + +/*! + \fn void QWebView::stop() + Convenience slot that stops loading the document. + + It is equivalent to + + \snippet webkitsnippets/qtwebkit_qwebview_snippet.cpp 3 + + \sa reload(), pageAction(), loadFinished() +*/ + +/*! + \fn void QWebView::back() + Convenience slot that loads the previous document in the list of documents + built by navigating links. Does nothing if there is no previous document. + + It is equivalent to + + \snippet webkitsnippets/qtwebkit_qwebview_snippet.cpp 4 + + \sa forward(), pageAction() +*/ + +/*! + \fn void QWebView::forward() + Convenience slot that loads the next document in the list of documents + built by navigating links. Does nothing if there is no next document. + + It is equivalent to + + \snippet webkitsnippets/qtwebkit_qwebview_snippet.cpp 5 + + \sa back(), pageAction() +*/ + +/*! + \fn void QWebView::reload() + Reloads the current document. + + \sa stop(), pageAction(), loadStarted() +*/ + +/*! + \fn QWebView *QWebView::createWindow(QWebPage::WebWindowType type) + This function is called from the createWindow() method of the associated QWebPage, + each time the page wants to create a new window of the given \a type. This might + be the result, for example, of a JavaScript request to open a document in a new window. + + \note If the createWindow() method of the associated page is reimplemented, this + method is not called, unless explicitly done so in the reimplementation. + + \note In the cases when the window creation is being triggered by JavaScript, apart from + reimplementing this method application must also set the JavaScriptCanOpenWindows attribute + of QWebSettings to true in order for it to get called. + + \sa QWebPage::createWindow(), QWebPage::acceptNavigationRequest() +*/ + +/*! + \fn void QWebView::titleChanged(const QString &title) + + This signal is emitted whenever the \a title of the main frame changes. + + \sa title() +*/ + +/*! + \fn void QWebView::urlChanged(const QUrl &url) + + This signal is emitted when the \a url of the view changes. + + \sa url(), load() +*/ + +/*! + \fn void QWebView::statusBarMessage(const QString& text) + + This signal is emitted when the status bar \a text is changed by the page. +*/ + +/*! + \fn void QWebView::iconChanged() + + This signal is emitted whenever the icon of the page is loaded or changes. + + In order for icons to be loaded, you will need to set an icon database path + using QWebSettings::setIconDatabasePath(). + + \sa icon(), QWebSettings::setIconDatabasePath() +*/ + +/*! + \fn void QWebView::loadStarted() + + This signal is emitted when a new load of the page is started. + + \sa loadProgress(), loadFinished() +*/ + + +/*! + \fn void QWebView::loadFinished(bool ok) + + This signal is emitted when a load of the page is finished. + \a ok will indicate whether the load was successful or any error occurred. + + \sa loadStarted() +*/ + +/*! + \fn void QWebView::selectionChanged() + + This signal is emitted whenever the selection changes. + + \sa selectedText() +*/ + +/*! + \fn void QWebView::loadProgress(int progress) + + This signal is emitted every time an element in the web page + completes loading and the overall loading progress advances. + + This signal tracks the progress of all child frames. + + The current value is provided by \a progress and scales from 0 to 100, + which is the default range of QProgressBar. + + \sa loadStarted(), loadFinished() +*/ + +/*! + \fn void QWebView::linkClicked(const QUrl &url) + + This signal is emitted whenever the user clicks on a link and the page's linkDelegationPolicy + property is set to delegate the link handling for the specified \a url. + + \sa QWebPage::linkDelegationPolicy() +*/ |