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 */