From 97c17e70cf984839c6e95d8f09a55f8d1e61b42e Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Wed, 27 Jan 2016 11:00:18 +0100 Subject: Doc: update Contentmanipulation example docs - Update screenshot - Remove second \brief command - Fix grammar issues - Use standard phrasing for examples - Replace \snippet commands with \quotefromfile commands. This enables documenting each line of code separately - Replace occurrences of QWebView with QWebEngineView - Replace reference to the obsolete QWebEnginePage::evaluateJavaScript method with reference to QWebEnginePage::runJavaScript() that is used in the example code - Remove snippet markers from mainwindow.h and mainwindow.cpp - Move code comment from mainwindow.cpp to the documentation to make the code leaner Change-Id: If3346810c8aef67c15c9ec7ad4469a222e636cf2 Reviewed-by: Joerg Bornemann --- .../doc/images/contentmanipulation-example.png | Bin 98031 -> 30363 bytes .../doc/src/contentmanipulation.qdoc | 153 ++++++++++++--------- .../contentmanipulation/mainwindow.cpp | 26 ---- .../contentmanipulation/mainwindow.h | 2 - 4 files changed, 91 insertions(+), 90 deletions(-) (limited to 'examples/webenginewidgets/contentmanipulation') diff --git a/examples/webenginewidgets/contentmanipulation/doc/images/contentmanipulation-example.png b/examples/webenginewidgets/contentmanipulation/doc/images/contentmanipulation-example.png index 717ac9ddc..ecdbc4c64 100644 Binary files a/examples/webenginewidgets/contentmanipulation/doc/images/contentmanipulation-example.png and b/examples/webenginewidgets/contentmanipulation/doc/images/contentmanipulation-example.png differ diff --git a/examples/webenginewidgets/contentmanipulation/doc/src/contentmanipulation.qdoc b/examples/webenginewidgets/contentmanipulation/doc/src/contentmanipulation.qdoc index 676173755..f16634d0f 100644 --- a/examples/webenginewidgets/contentmanipulation/doc/src/contentmanipulation.qdoc +++ b/examples/webenginewidgets/contentmanipulation/doc/src/contentmanipulation.qdoc @@ -29,114 +29,143 @@ \example webenginewidgets/contentmanipulation \title WebEngine Content Manipulation Example \ingroup webengine-widgetexamples - \brief Demonstrates how to use browse web and manipulate content - - \brief The Content Manipulation example shows how to use JQuery with QtWebEngine to - create a web browser with special effects and content - manipulation. + \brief Demonstrates how to load and manipulate web content. \image contentmanipulation-example.png - The application makes use of QWebEnginePage::evaluateJavaScript to - evaluate the jQuery JavaScript code. A QMainWindow with a QWebEngineView - as central widget builds up the browser itself. + \e{Content Manipulation} shows how to use JQuery with \l {Qt WebEngine Widgets} to + create a web browser with special effects and content manipulation. + + In the application, we call QWebEnginePage::runJavaScript() to + execute jQuery JavaScript code. We implement a QMainWindow with a QWebEngineView + as a central widget to build up the browser itself. \include examples-run.qdocinc \section1 MainWindow Class Definition The \c MainWindow class inherits QMainWindow. It implements a number of - slots to perform actions on both the application and on the web content. + slots to perform actions on both the application and on the web content: - \snippet webenginewidgets/contentmanipulation/mainwindow.h 1 + \quotefromfile webenginewidgets/contentmanipulation/mainwindow.h + \skipto class MainWindow : + \printuntil /^\}/ - We also declare a QString that contains the jQuery, a QWebView + We also declare a QString that contains the jQuery, a QWebEngineView that displays the web content, and a QLineEdit that acts as the address bar. \section1 MainWindow Class Implementation - We start by implementing the constructor. - - \snippet webenginewidgets/contentmanipulation/mainwindow.cpp 1 + We start by implementing the constructor. The first part of the constructor sets the value of + \c progress to 0. This value will be used later in the code to visualize the loading of a + web page: - The first part of the constructor sets the value of \c progress to - 0. This value will be used later in the code to visualize the - loading of a webpage. + \quotefromfile webenginewidgets/contentmanipulation/mainwindow.cpp + \skipto MainWindow::MainWindow + \printuntil progress - Next, the jQuery library is loaded using a QFile and reading the file + Next, the jQuery library is loaded by using a QFile and reading the file content. The jQuery library is a JavaScript library that provides different - functions for manipulating HTML. + functions for manipulating HTML: + + \printuntil file.close() + + The second part of the constructor creates a QWebEngineView and connects + slots to the view's signals: + + \printuntil SLOT(finishLoading + + Furthermore, we create a QLineEdit as the browser's address bar. We then set the horizontal + QSizePolicy to fill the available area in the browser at all times. We add the + QLineEdit to a QToolBar together with a set of navigation actions from + QWebEngineView::pageAction(): + + \printuntil addWidget(locationEdit) + + The third part of the constructor implements two QMenu widgets and assigns + a set of actions to them: + + \printuntil removeEmbeddedElements - \snippet webenginewidgets/contentmanipulation/mainwindow.cpp 2 + The last line sets the QWebEngineView as the central widget in the QMainWindow: - The second part of the constructor creates a QWebView and connects - slots to the views signals. Furthermore, we create a QLineEdit as - the browsers address bar. We then set the horizontal QSizePolicy - to fill the available area in the browser at all times. We add the - QLineEdit to a QToolbar together with a set of navigation actions - from QWebView::pageAction. + \printuntil } - \snippet webenginewidgets/contentmanipulation/mainwindow.cpp 3 + When the page is loaded, \c adjustLocation() is triggered by the \c loadFinished() signal in + QWebEngineView to update the address bar: - The third and last part of the constructor implements two QMenus and assigns - a set of actions to them. The last line sets the QWebView as the central - widget in the QMainWindow. + \skipto adjustLocation() + \printuntil } - \snippet webenginewidgets/contentmanipulation/mainwindow.cpp 4 + In \c changeLocation(), we create a QUrl object, and then use it to load the page into the + QWebEngineView. When the new web page has finished loading, \c adjustLocation() will be + run once more to update the address bar: - When the page is loaded, \c adjustLocation() updates the address - bar; \c adjustLocation() is triggered by the \c loadFinished() - signal in QWebView. In \c changeLocation() we create a QUrl - object, and then use it to load the page into the QWebView. When - the new web page has finished loading, \c adjustLocation() will be - run once more to update the address bar. + \printuntil } - \snippet webenginewidgets/contentmanipulation/mainwindow.cpp 5 + The \c adjustTitle() method sets the window title and displays the loading progress: - \c adjustTitle() sets the window title and displays the loading - progress. This slot is triggered by the \c titleChanged() signal - in QWebView. + \printuntil } + \printuntil } - \snippet webenginewidgets/contentmanipulation/mainwindow.cpp 6 + This slot is triggered by the \c titleChanged() signal in QWebEngineView. - When a web page has loaded, \c finishLoading() is triggered by the - \c loadFinished() signal in QWebView. \c finishLoading() then updates the - progress in the title bar and calls \c evaluateJavaScript() - to evaluate the jQuery library. This evaluates the JavaScript against the - current web page. What that means is that the JavaScript can be viewed as - part of the content loaded into the QWebView, and therefore needs to be + When a web page has loaded, the \c finishLoading() method is triggered by the + \c loadFinished() signal in QWebEngineView. The method then updates the + progress in the title bar and calls \c runJavaScript() + to evaluate the jQuery library against the current web page: + + \printuntil } + + This means that the JavaScript can be viewed as a + part of the content loaded into the QWebEngineView, and therefore needs to be loaded every time a new page is loaded. Once the jQuery library is loaded, we can start executing the different jQuery functions in the browser. - The rotateImages() function is then called explicitely to make sure + The \c rotateImages() function is then called explicitly to make sure that the images of the newly loaded page respect the state of the toggle action. - \snippet webenginewidgets/contentmanipulation/mainwindow.cpp 7 - The first jQuery-based function, \c highlightAllLinks(), is designed to highlight all links in the current webpage. The JavaScript code looks for web elements named \e {a}, which is the tag for a hyperlink. For each such element, the background color is set to be yellow by - using CSS. + using CSS: - \snippet webenginewidgets/contentmanipulation/mainwindow.cpp 8 + \printuntil } + \printuntil } + + We append \c undefined after the jQuery call to prevent a possible recursion loop + and crash caused by the way the elements returned by the each iterator elements + reference each other, which causes problems upon converting them to QVariant. The \c rotateImages() function rotates the images on the current - web page. This JavaScript code relies on CSS transforms and + web page. This JavaScript code relies on CSS transforms. It looks up all \e {img} elements and rotates the images 180 degrees - and then back again. + and then back again: - \snippet webenginewidgets/contentmanipulation/mainwindow.cpp 9 + \printuntil runJavaScript(code); + \printuntil } - The remaining four methods remove different elements from the current web - page. \c removeGifImages() removes all GIF images on the page by looking up + The remaining methods remove different elements from the current web + page. The \c removeGifImages() removes all GIF images on the page by looking up the \e {src} attribute of all the elements on the web page. Any element with - a \e {gif} file as its source is removed. \c removeInlineFrames() removes all - \e {iframe} or inline elements. \c removeObjectElements() removes all - \e {object} elements, and \c removeEmbeddedElements() removes any elements - such as plugins embedded on the page using the \e {embed} tag. + a \e {gif} file as its source is removed: + + \printuntil } + + The \c removeInlineFrames() method removes all \e {iframe} or inline elements: + + \printuntil } + + The \c removeObjectElements() method removes all \e {object} elements: + + \printuntil } + + The \c removeEmbeddedElements() method removes any elements using the \e {embed} tag, such as + plugins embedded on the page: + \printuntil } */ diff --git a/examples/webenginewidgets/contentmanipulation/mainwindow.cpp b/examples/webenginewidgets/contentmanipulation/mainwindow.cpp index 3dca497a3..d3552ac86 100644 --- a/examples/webenginewidgets/contentmanipulation/mainwindow.cpp +++ b/examples/webenginewidgets/contentmanipulation/mainwindow.cpp @@ -58,8 +58,6 @@ InvokeWrapper invoke(R *receiver, void (C::*memberFun)(Arg)) return wrapper; } -//! [1] - MainWindow::MainWindow(const QUrl& url) { progress = 0; @@ -70,9 +68,7 @@ MainWindow::MainWindow(const QUrl& url) jQuery = file.readAll(); jQuery.append("\nvar qt = { 'jQuery': jQuery.noConflict(true) };"); file.close(); -//! [1] -//! [2] view = new QWebEngineView(this); view->load(url); connect(view, SIGNAL(loadFinished(bool)), SLOT(adjustLocation())); @@ -90,14 +86,12 @@ MainWindow::MainWindow(const QUrl& url) toolBar->addAction(view->pageAction(QWebEnginePage::Reload)); toolBar->addAction(view->pageAction(QWebEnginePage::Stop)); toolBar->addWidget(locationEdit); -//! [2] QMenu *viewMenu = menuBar()->addMenu(tr("&View")); QAction* viewSourceAction = new QAction("Page Source", this); connect(viewSourceAction, SIGNAL(triggered()), SLOT(viewSource())); viewMenu->addAction(viewSourceAction); -//! [3] QMenu *effectMenu = menuBar()->addMenu(tr("&Effect")); effectMenu->addAction("Highlight all links", this, SLOT(highlightAllLinks())); @@ -116,7 +110,6 @@ MainWindow::MainWindow(const QUrl& url) setCentralWidget(view); } -//! [3] void MainWindow::viewSource() { @@ -129,7 +122,6 @@ void MainWindow::viewSource() view->page()->toHtml(invoke(textEdit, &QTextEdit::setPlainText)); } -//! [4] void MainWindow::adjustLocation() { locationEdit->setText(view->url().toString()); @@ -141,9 +133,7 @@ void MainWindow::changeLocation() view->load(url); view->setFocus(); } -//! [4] -//! [5] void MainWindow::adjustTitle() { if (progress <= 0 || progress >= 100) @@ -157,9 +147,7 @@ void MainWindow::setProgress(int p) progress = p; adjustTitle(); } -//! [5] -//! [6] void MainWindow::finishLoading(bool) { progress = 100; @@ -168,36 +156,24 @@ void MainWindow::finishLoading(bool) rotateImages(rotateAction->isChecked()); } -//! [6] -//! [7] void MainWindow::highlightAllLinks() { - // We append '; undefined' after the jQuery call here to prevent a possible recursion loop and crash caused by - // the way the elements returned by the each iterator elements reference each other, which causes problems upon - // converting them to QVariants. QString code = "qt.jQuery('a').each( function () { qt.jQuery(this).css('background-color', 'yellow') } ); undefined"; view->page()->runJavaScript(code); } -//! [7] -//! [8] void MainWindow::rotateImages(bool invert) { QString code; - // We append '; undefined' after each of the jQuery calls here to prevent a possible recursion loop and crash caused by - // the way the elements returned by the each iterator elements reference each other, which causes problems upon - // converting them to QVariants. if (invert) code = "qt.jQuery('img').each( function () { qt.jQuery(this).css('-webkit-transition', '-webkit-transform 2s'); qt.jQuery(this).css('-webkit-transform', 'rotate(180deg)') } ); undefined"; else code = "qt.jQuery('img').each( function () { qt.jQuery(this).css('-webkit-transition', '-webkit-transform 2s'); qt.jQuery(this).css('-webkit-transform', 'rotate(0deg)') } ); undefined"; view->page()->runJavaScript(code); } -//! [8] -//! [9] void MainWindow::removeGifImages() { QString code = "qt.jQuery('[src*=gif]').remove()"; @@ -221,5 +197,3 @@ void MainWindow::removeEmbeddedElements() QString code = "qt.jQuery('embed').remove()"; view->page()->runJavaScript(code); } -//! [9] - diff --git a/examples/webenginewidgets/contentmanipulation/mainwindow.h b/examples/webenginewidgets/contentmanipulation/mainwindow.h index 8e9b12538..06b8aba03 100644 --- a/examples/webenginewidgets/contentmanipulation/mainwindow.h +++ b/examples/webenginewidgets/contentmanipulation/mainwindow.h @@ -45,7 +45,6 @@ class QWebEngineView; class QLineEdit; QT_END_NAMESPACE -//! [1] class MainWindow : public QMainWindow { Q_OBJECT @@ -76,5 +75,4 @@ private: QLineEdit *locationEdit; QAction *rotateAction; int progress; -//! [1] }; -- cgit v1.2.3