summaryrefslogtreecommitdiff
path: root/examples
diff options
context:
space:
mode:
authorVenugopal Shivashankar <venugopal.shivashankar@digia.com>2012-12-05 12:39:15 +0100
committerThe Qt Project <gerrit-noreply@qt-project.org>2012-12-05 18:23:58 +0100
commit3d0c382895aa330f395153539969a7f57ce60c71 (patch)
treec0ad437f4333aa738d8ca235df1da95f620a82a3 /examples
parent40d16a376a083f7b9ce90689cadcb606cc03991d (diff)
downloadqtwebkit-examples-3d0c382895aa330f395153539969a7f57ce60c71.tar.gz
Doc: Added documentation for the examples
Moved the documentation for fancybrowser, formextractor, previewer, and domtraversal examples from qtdoc. Task-number: QTBUG-27515 Change-Id: I6fd26488b6d854caa600c5db2014532fa1c848d7 Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>
Diffstat (limited to 'examples')
-rw-r--r--examples/webkit/domtraversal/doc/images/webkit-domtraversal.pngbin0 -> 109327 bytes
-rw-r--r--examples/webkit/domtraversal/doc/src/domtraversal.qdoc125
-rw-r--r--examples/webkit/domtraversal/main.cpp3
-rw-r--r--examples/webkit/fancybrowser/doc/images/fancybrowser-example.pngbin0 -> 98031 bytes
-rw-r--r--examples/webkit/fancybrowser/doc/src/fancybrowser.qdoc138
-rw-r--r--examples/webkit/formextractor/doc/images/formextractor-example.pngbin0 -> 80692 bytes
-rw-r--r--examples/webkit/formextractor/doc/src/formextractor.qdoc37
-rw-r--r--examples/webkit/previewer/doc/images/previewer-example.pngbin0 -> 16323 bytes
-rw-r--r--examples/webkit/previewer/doc/images/previewer-ui.pngbin0 -> 10345 bytes
-rw-r--r--examples/webkit/previewer/doc/src/previewer.qdoc167
10 files changed, 469 insertions, 1 deletions
diff --git a/examples/webkit/domtraversal/doc/images/webkit-domtraversal.png b/examples/webkit/domtraversal/doc/images/webkit-domtraversal.png
new file mode 100644
index 0000000..8b6f34a
--- /dev/null
+++ b/examples/webkit/domtraversal/doc/images/webkit-domtraversal.png
Binary files differ
diff --git a/examples/webkit/domtraversal/doc/src/domtraversal.qdoc b/examples/webkit/domtraversal/doc/src/domtraversal.qdoc
new file mode 100644
index 0000000..9f34290
--- /dev/null
+++ b/examples/webkit/domtraversal/doc/src/domtraversal.qdoc
@@ -0,0 +1,125 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 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$
+**
+****************************************************************************/
+
+/*!
+ \example webkit/domtraversal
+ \title DOM Traversal Example
+
+ The DOM Traversal example shows how to use the QWebElement class to access
+ the structure of a Web page.
+
+ \image webkit-domtraversal.png
+
+ The QWebElement class provides an API that can be used to examine the structure
+ and content of a Web page via a Document Object Model (DOM) interface. It can be
+ used for basic traversal of the document structure, to search for particular
+ elements (see the \l{Simple Selector Example}), and to modify content in-place.
+
+ This example uses a QWebView widget to display the Web page, and a dock widget
+ holds the QTreeWidget that shows the document structure. These widgets are
+ placed in an instance of the \c Window class, which we describe below.
+
+ \section1 Window Class Definition
+
+ The \c Window class is derived from QMainWindow and its user interface is created
+ using \l{Qt Designer}. As a result, the class is also derived from the user
+ interface class created by \l uic:
+
+ \snippet webkit/domtraversal/window.h Window class definition
+
+ Two important functions to note are the \c on_webView_loadFinished() slot and
+ the \c examineChildElements() function. The former is automatically called
+ when the QWebView widget finishes loading a page. See the
+ \l{#Further Reading}{Further Reading} section for more information on this
+ mechanism.
+
+ The \c examineChildElements() function is used to traverse the document structure
+ and add items to the QTreeWidget.
+
+ \section1 Window Class Implementation
+
+ In the \c Window class constructor, we call the \l{QWidget::}{setupUi()} function
+ to set up the user interface described in the \c{window.ui} file:
+
+ \snippet webkit/domtraversal/window.cpp Window constructor
+
+ When the Web page is loaded, the \c on_webView_loadFinished() slot is called. Here,
+ we clear the tree widget and begin inspection of the document by obtaining the
+ document element from the page's main frame:
+
+ \snippet webkit/domtraversal/window.cpp begin document inspection
+
+ At this point, we call the \c examineChildElements() function to traverse the
+ document, starting with the child elements of the document element for which we
+ will create top level items in the tree widget.
+
+ The \c examineChildElements() function accepts a parent element and a parent item.
+ Starting with the first child element, which we obtain with the element's
+ \l{QWebElement::}{firstChild()} function, we examine each child element of the
+ parent item. For each valid (non-null) element, which we check by calling its
+ \l{QWebElement::}{isNull()} function, we create a new QTreeWidgetItem instance with
+ the element name and add it to the parent item.
+
+ \snippet webkit/domtraversal/window.cpp traverse document
+
+ We recursively examine the child elements for each element by calling
+ \c examineChildElements() with the current child element and the newly-created item.
+ To obtain the next element at the same level in the document, we call its
+ \l{QWebElement::}{nextSibling()} function.
+
+ This recursive approach to reading the document makes it easy to create a simple
+ representation of the document structure in a tree widget.
+
+ For completeness, we show the \c setUrl() function, which is provided to allow the
+ document URL to be set from the example's \c main() function.
+
+ \snippet webkit/domtraversal/window.cpp set URL
+
+ \section1 Starting the Example
+
+ We set up the application, create
+ a \c Window instance, set its URL, and show it:
+
+ \snippet webkit/domtraversal/main.cpp main program
+
+ When the application's event loop is run, the Qt home page will load, and the
+ tree widget will be updated to show the document structure. Navigating to another
+ page will cause the tree widget to be updated to show the document structure of
+ the new page.
+
+ \section1 Further Reading
+
+ The QWebElement documentation contains more information about DOM access for the
+ QtWebKit classes.
+
+ In this example, we take advantage of Qt's
+ \l{Using a Designer UI File in Your Application#Automatic Connections}{auto-connection}
+ feature to avoid explicitly connecting signals to slots. The user interface
+ contains a QWebView widget called \c webView whose \l{QWebView::}{loadFinished()}
+ signal is automatically connected to the \c on_webView_loadFinished() slot when
+ we call \l{QWidget::}{setupUi()} in the \c Window constructor.
+*/
diff --git a/examples/webkit/domtraversal/main.cpp b/examples/webkit/domtraversal/main.cpp
index 014086a..d105e47 100644
--- a/examples/webkit/domtraversal/main.cpp
+++ b/examples/webkit/domtraversal/main.cpp
@@ -37,7 +37,7 @@
** $QT_END_LICENSE$
**
****************************************************************************/
-
+//! [main program]
#include <QApplication>
#include "window.h"
@@ -49,3 +49,4 @@ int main(int argc, char *argv[])
window.setUrl(QUrl("http://qt-project.org/"));
return app.exec();
}
+//! [main program]
diff --git a/examples/webkit/fancybrowser/doc/images/fancybrowser-example.png b/examples/webkit/fancybrowser/doc/images/fancybrowser-example.png
new file mode 100644
index 0000000..717ac9d
--- /dev/null
+++ b/examples/webkit/fancybrowser/doc/images/fancybrowser-example.png
Binary files differ
diff --git a/examples/webkit/fancybrowser/doc/src/fancybrowser.qdoc b/examples/webkit/fancybrowser/doc/src/fancybrowser.qdoc
new file mode 100644
index 0000000..c6b15c2
--- /dev/null
+++ b/examples/webkit/fancybrowser/doc/src/fancybrowser.qdoc
@@ -0,0 +1,138 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 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$
+**
+****************************************************************************/
+
+/*!
+ \example webkit/fancybrowser
+ \title Fancy Browser Example
+
+ The Fancy Browser example shows how to use JQuery with QtWebKit to
+ create a web browser with special effects and content
+ manipulation.
+
+ \image fancybrowser-example.pn
+
+ The application makes use of QWebFrame::evaluateJavaScript to
+ evaluate the jQuery JavaScript code. A QMainWindow with a QWebView
+ as central widget builds up the browser itself.
+
+ \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.
+
+ \snippet webkit/fancybrowser/mainwindow.h 1
+
+ We also declare a QString that contains the jQuery, a QWebView
+ 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 webkit/fancybrowser/mainwindow.cpp 1
+
+ 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.
+
+ Next, the jQuery library is loaded using a QFile and reading the file
+ content. The jQuery library is a JavaScript library that provides different
+ functions for manipulating HTML.
+
+ \snippet webkit/fancybrowser/mainwindow.cpp 2
+
+ 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.
+
+ \snippet webkit/fancybrowser/mainwindow.cpp 3
+
+ 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.
+
+ \snippet webkit/fancybrowser/mainwindow.cpp 4
+
+ 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.
+
+ \snippet webkit/fancybrowser/mainwindow.cpp 5
+
+ \c adjustTitle() sets the window title and displays the loading
+ progress. This slot is triggered by the \c titleChanged() signal
+ in QWebView.
+
+ \snippet webkit/fancybrowser/mainwindow.cpp 6
+
+ 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 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
+ that the images of the newly loaded page respect the state of the toggle
+ action.
+
+ \snippet webkit/fancybrowser/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.
+
+ \snippet webkit/fancybrowser/mainwindow.cpp 8
+
+ The \c rotateImages() function rotates the images on the current
+ web page. Webkit supports CSS transforms and this JavaScript code
+ looks up all \e {img} elements and rotates the images 180 degrees
+ and then back again.
+
+ \snippet webkit/fancybrowser/mainwindow.cpp 9
+
+ 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 \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.
+
+*/
+
diff --git a/examples/webkit/formextractor/doc/images/formextractor-example.png b/examples/webkit/formextractor/doc/images/formextractor-example.png
new file mode 100644
index 0000000..155cdaa
--- /dev/null
+++ b/examples/webkit/formextractor/doc/images/formextractor-example.png
Binary files differ
diff --git a/examples/webkit/formextractor/doc/src/formextractor.qdoc b/examples/webkit/formextractor/doc/src/formextractor.qdoc
new file mode 100644
index 0000000..86dbd1f
--- /dev/null
+++ b/examples/webkit/formextractor/doc/src/formextractor.qdoc
@@ -0,0 +1,37 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 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$
+**
+****************************************************************************/
+
+/*!
+ \example webkit/formextractor
+ \title Form Extractor Example
+
+ The Form Extractor example shows how to use QWebFrame with JavaScript to
+ extract form data.
+
+ \image formextractor-example.png
+
+*/
diff --git a/examples/webkit/previewer/doc/images/previewer-example.png b/examples/webkit/previewer/doc/images/previewer-example.png
new file mode 100644
index 0000000..d930250
--- /dev/null
+++ b/examples/webkit/previewer/doc/images/previewer-example.png
Binary files differ
diff --git a/examples/webkit/previewer/doc/images/previewer-ui.png b/examples/webkit/previewer/doc/images/previewer-ui.png
new file mode 100644
index 0000000..c92d136
--- /dev/null
+++ b/examples/webkit/previewer/doc/images/previewer-ui.png
Binary files differ
diff --git a/examples/webkit/previewer/doc/src/previewer.qdoc b/examples/webkit/previewer/doc/src/previewer.qdoc
new file mode 100644
index 0000000..c3cca09
--- /dev/null
+++ b/examples/webkit/previewer/doc/src/previewer.qdoc
@@ -0,0 +1,167 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 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$
+**
+****************************************************************************/
+
+/*!
+ \example webkit/previewer
+ \title Previewer Example
+
+ The Previewer example shows how to use QtWebKit's QWebView to preview
+ HTML data written in a QPlainTextEdit.
+
+ \image previewer-example.png
+
+ \section1 The User Interface
+
+ Before we begin, we create a user interface using Qt Designer. Two QGroupBox
+ objects - the editor group box and the previewer group box are separated
+ by a QSplitter. In the editor group box, we have a QPlainTextEdit object,
+ \c plainTextEdit, and two QPushButton objects. In the previewer group box,
+ we have a QWebView object, \c webView.
+
+ \image previewer-ui.png
+
+ \section1 Previewer Class Definition
+
+ The \c Previewer class is a subclass of both QWidget and Ui::Form.
+ We subclass Ui::Form in order to embed the Qt Designer user interface form
+ created earlier. This method of embedding forms is known as the
+ \l{The Multiple Inheritance Approach}{multiple inheritance approach}.
+
+ In our \c previewer.h file, we have a constructor and a slot,
+ \c on_previewButton_clicked().
+
+ \snippet webkit/previewer/previewer.h 0
+
+ \section1 Previewer Class Implementation
+
+ The \c{Previewer}'s constructor is only responsible for setting up the
+ user interface.
+
+ \snippet webkit/previewer/previewer.cpp 0
+
+ The \c on_previewButton_clicked() is a slot corresponding to the
+ \c{previewButton}'s \l{QPushButton::}{clicked()} signal. When the
+ \c previewButton is clicked, we extract the contents of \c plainTextEdit,
+ and then invoke the \l{QWebView::}{setHtml()} function to display our
+ contents as HTML.
+
+ \snippet webkit/previewer/previewer.cpp 1
+
+ \section1 MainWindow Class Definition
+
+ The \c MainWindow class for the Previewer example is a subclass of
+ QMainWindow with a constructor and five private slots: \c open(),
+ \c openUrl(), \c save(), \c about() and \c updateTextEdit().
+
+ \snippet webkit/previewer/mainwindow.h 0
+
+ The private objects in \c MainWindow are \c centralWidget, which is
+ a \c Previewer object, \c fileMenu, \c helpMenu and the QAction objects
+ \c openAct, \c openUrlAct, \c saveAct, \c exitAct, \c aboutAct and
+ \c aboutQtAct.
+
+ \snippet webkit/previewer/mainwindow.h 1
+
+ There are three private functions: \c createActions(), \c createMenus()
+ and \c setStartupText(). The \c createActions() and \c createMenus()
+ functions are necessary to set up the main window's actions and
+ assign them to the \gui File and \gui Help menus. The \c setStartupText()
+ function, on the other hand, displays a description about the example
+ in its HTML Previewer window.
+
+ \section1 MainWindow Class Implementation
+
+ The \c{MainWindow}'s constructor invokes \c createActions() and
+ \c createMenus() to set up the \gui File menu and \gui Help menu. Then,
+ the \c Previewer object, \c centralWidget, is set to the main window's
+ central widget. Also, we connect \c webView's
+ \l{QWebView::}{loadFinished()} signal to our \c updateTextEdit() slot.
+ Finally, we call the \c setStartupText() function to display the
+ description of the example.
+
+ \snippet webkit/previewer/mainwindow.cpp 0
+
+ Within the \c createActions() function, we instantiate all our private
+ QAction objects which we declared in \c{mainwindow.h}. We set the
+ short cut and status tip for these actions and connect their
+ \l{QAction::}{triggered()} signal to appropriate slots.
+
+ \snippet webkit/previewer/mainwindow.cpp 1
+ \dots
+
+ The \c createMenus() function instantiates the QMenu items, \c fileMenu
+ and \c helpMenu and adds them to the main window's
+ \l{QMainWindow::menuBar()}{menu bar}.
+
+ \snippet webkit/previewer/mainwindow.cpp 2
+
+ The example also provides an \c about() slot to describe its purpose.
+
+ \snippet webkit/previewer/mainwindow.cpp 3
+
+ The \c MainWindow class provides two types of \gui Open functions:
+ \c open() and \c openUrl(). The \c open() function opens an HTML file
+ with \c fileName, and reads it with QTextStream. The function then
+ displays the output on \c plainTextEdit. The file's name is obtained
+ using QFileDialog's \l{QFileDialog::}{getOpenFileName()} function.
+
+ \snippet webkit/previewer/mainwindow.cpp 4
+
+ The \c openUrl() function, on the other hand, displays a QInputDialog
+ to obtain a URL, and displays it on \c webView.
+
+ \snippet webkit/previewer/mainwindow.cpp 5
+
+ In order to save a HTML file, the \c save() function first extracts the
+ contents of \c plainTextEdit and displays a QFileDialog to obtain
+ \c fileName. Then, we use a QTextStream object, \c in, to write to
+ \c file.
+
+ \snippet webkit/previewer/mainwindow.cpp 6
+
+ Earlier, in \c{MainWindow}'s constructor, we connected \c{webView}'s
+ \l{QWebView::}{loadFinished()} signal to our private \c updateTextEdit()
+ slot. This slot updates the contents of \c plainTextEdit with the HTML
+ source of the web page's main frame, obtained using \l{QWebFrame}'s
+ \l{QWebFrame::}{toHtml()} function.
+
+ \snippet webkit/previewer/mainwindow.cpp 7
+
+ To provide a description about the Previewer example, when it starts up,
+ we use the \c setStartupText() function, as shown below:
+
+ \snippet webkit/previewer/mainwindow.cpp 8
+
+
+ \section1 The \c{main()} Function
+
+ The \c main() function instantiates a \c MainWindow object, \c mainWindow,
+ and displays it with the \l{QWidget::}{show()} function.
+
+ \snippet webkit/previewer/main.cpp 0
+
+*/