Update copyright headers
[qt:qt.git] / doc / src / examples / simplewebplugin.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file.  Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*!
29     \example webkit/simplewebplugin
30     \title Simple Web Plugin Example
31
32     \brief The Simple Web Plugin example shows how to embed a regular Qt widget into a
33     Web page displayed using QWebView.
34
35     \image webkit-simplewebplugin.png A table widget embedded in a Web page.
36
37     In this example, we will show how to include Qt widgets in Web-centric user
38     interfaces.
39
40     \section1 QtWebKit Basics
41
42     QtWebKit provides integration between Qt and WebKit on two different levels.
43     On a low level, Qt provides widgets for Web pages to be rendered onto; on a
44     high level, a set of classes are provided that represent all the key
45     components of a Web browser.
46
47     QWebView is a widget that is used to display Web pages, QWebPage represents
48     the content in a page, and QWebFrame represents an individual frame in a
49     Web page. The code to display a Web page is very simple:
50
51     \snippet webkitsnippets/simple/main.cpp Using QWebView
52
53     The widget provides fundamental Web browsing features, such as Cascading
54     Style Sheet and JavaScript support. Other technologies can be added to
55     provide a more comprehensive experience.
56
57     \section1 Adding a Widget to a Page
58
59     Since Qt is used to render pages, it is easy to add both standard and
60     custom widgets to pages. All we need is some markup to indicate where a
61     widget is expected in a page and a mechanism that lets us know when it
62     needs to be created.
63
64     The markup used involves the \c <object> element, described in the HTML 4
65     specification, which is used to include generic objects in Web pages. When
66     describing an object to represent a widget, there are typically three
67     attributes this element can have: a \c data attribute that indicates where
68     any relevant data can be obtained; \c width and \c height attributes can
69     be used to set the size of the widget on the page.
70
71     Here's how we might describe such an object:
72
73     \snippet examples/webkit/simplewebplugin/pages/index.html embedded object
74
75     The mechanism used by QtWebKit to insert widgets into pages is a plugin
76     factory that is registered with a given WebPage instance. Factories are
77     subclasses of QWebPluginFactory and can be equipped to supply more than one
78     type of widget.
79
80     \section1 Creating a Widget to Embed
81
82     To demonstrate how the factory is used, we create a simple widget that can
83     be used to display Comma-Separated Values (CSV) files. The widget class,
84     \c CSVView, is just a subclass of QTableView with extra functions to set
85     up an internal data model. Instances of the factory class, \c CSVFactory,
86     are responsible for creating \c CSVView widgets and requesting data on
87     their behalf.
88
89     The \c CSVFactory class is defined in the following way:
90
91     \snippet examples/webkit/simplewebplugin/csvfactory.h plugin factory
92
93     The public functions give a good overview of how QtWebKit will use the
94     factory to create widgets. We begin by looking at the factory's constructor:
95
96     \snippet examples/webkit/simplewebplugin/csvfactory.cpp constructor
97
98     The factory contains a network access manager which we will use to obtain
99     data for each of the plugin widgets created.
100
101     The \c plugins() function is used to report information
102     about the kinds of widget plugins it can create; our implementation reports
103     the MIME type it expects and provides a description of the plugin:
104
105     \snippet examples/webkit/simplewebplugin/csvfactory.cpp plugins
106
107     The \c create() function is where most of the action happens. It is
108     called with a MIME type that describes the kind of data to be displayed,
109     a URL that refers to the data, and information about any additional
110     arguments that were specified in the Web page. We begin by checking the
111     basic MIME type information passed in the \c mimeType parameter, and only
112     continue if we recognize it.
113
114     \snippet examples/webkit/simplewebplugin/csvfactory.cpp begin create
115
116     We construct a view widget
117     using the fully-specified MIME type, which is guaranteed to be in the list of
118     arguments if a MIME type has been supplied.
119
120     \snippet examples/webkit/simplewebplugin/csvfactory.cpp submit request
121
122     Lastly, we use the network access manager to request the data specified by
123     the \c url parameter, connecting its \c finished() signal to the view's
124     \c updateModel() slot so that it can collect the data. The reply object is
125     intentionally created on the heap; the \c finished() signal is connected to
126     its \c deleteLater() slot, ensuring that Qt will dispose of it when it is no
127     longer needed.
128
129     The \c CSVView class provides only minor extensions to the functionality of
130     QTableView, with a public slot to handle incoming data and a private
131     variable to record exact MIME type information:
132
133     \snippet examples/webkit/simplewebplugin/csvview.h definition
134
135     The constructor is simply used to record the MIME type of the data:
136
137     \snippet examples/webkit/simplewebplugin/csvview.cpp constructor
138
139     To save space, we will only look at parts of the \c updateModel() function,
140     which begins by obtaining the QNetworkReply object that caused the slot
141     to be invoked before checking for errors:
142
143     \snippet examples/webkit/simplewebplugin/csvview.cpp update model begin
144
145     Assuming that the data is correct, we need to determine whether the
146     CSV file includes a table header, and to find out which character encoding was
147     used to store the data. Both these pieces of information may be included in
148     the complete MIME type information, so we parse this before continuing---this
149     is shown in the online example code.
150
151     \snippet examples/webkit/simplewebplugin/csvview.cpp read data begin
152
153     Since QNetworkReply is a QIODevice subclass, the reply can be read
154     using a suitably configured text stream, and the data fed into a standard
155     model. The mechanics of this can be found in the
156     \l{webkit/simplewebplugin/csvview.cpp}{code listing}. Here, we skip to the
157     end of the function where we close the reply object and set the model on
158     the view:
159
160     \snippet examples/webkit/simplewebplugin/csvview.cpp update model
161
162     Once the reply has been read, and the model populated with data, very little
163     needs to be done by the plugin. Ownership of the view widget is handled
164     elsewhere, and we have ensured that the model will be destroyed when it is
165     no longer needed by making it a child object of the view.
166
167     Let's look quickly at the \c MainWindow implementation:
168
169     \snippet examples/webkit/simplewebplugin/mainwindow.cpp constructor
170
171     Apart from creating and setting a factory on the QWebPage object, the
172     most important task is to enable Web plugins. If this global setting is not
173     enabled, plugins will not be used and our \c <object> elements will simply
174     be ignored.
175
176     \section1 Further Reading
177
178     The \l{Web Plugin Example} extends this example by adding a signal-slot
179     connection between the embedded widget and a JavaScript function in the
180     page.
181 */