diff options
Diffstat (limited to 'src/webengine')
| -rw-r--r-- | src/webengine/doc/src/qquickwebengineview_lgpl.qdoc | 396 | ||||
| -rw-r--r-- | src/webengine/doc/src/qtwebengine.qdoc | 37 |
2 files changed, 433 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 +*/ |