diff options
Diffstat (limited to 'src/webenginewidgets/doc/src/qwebengineview_lgpl.qdoc')
| -rw-r--r-- | src/webenginewidgets/doc/src/qwebengineview_lgpl.qdoc | 544 |
1 files changed, 544 insertions, 0 deletions
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() +*/ |