doc/src/examples/previewer.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/previewer
  30     \title Previewer Example
  31
  32     \brief The Previewer example shows how to use QtWebKit's QWebView to preview
  33     HTML data written in a QPlainTextEdit.
  34
  35     \image previewer-example.png
  36
  37     \section1 The User Interface
  38
  39     Before we begin, we create a user interface using \QD. Two QGroupBox
  40     objects - the editor group box and the previewer group box are separated
  41     by a QSplitter. In the editor group box, we have a QPlainTextEdit object,
  42     \c plainTextEdit, and two QPushButton objects. In the previewer group box,
  43     we have a QWebView object, \c webView.
  44
  45     \image previewer-ui.png
  46
  47     \section1 Previewer Class Definition
  48
  49     The \c Previewer class is a subclass of both QWidget and Ui::Form.
  50     We subclass Ui::Form in order to embed the \QD user interface form
  51     created earlier. This method of embedding forms is known as the
  52     \l{The Multiple Inheritance Approach}{multiple inheritance approach}.
  53
  54     In our \c previewer.h file, we have a constructor and a slot,
  55     \c on_previewButton_clicked().
  56
  57     \snippet examples/webkit/previewer/previewer.h 0
  58
  59     \section1 Previewer Class Implementation
  60
  61     The \c{Previewer}'s constructor is only responsible for setting up the
  62     user interface.
  63
  64     \snippet examples/webkit/previewer/previewer.cpp 0
  65
  66     The \c on_previewButton_clicked() is a slot corresponding to the
  67     \c{previewButton}'s \l{QPushButton::}{clicked()} signal. When the
  68     \c previewButton is clicked, we extract the contents of \c plainTextEdit,
  69     and then invoke the \l{QWebView::}{setHtml()} function to display our
  70     contents as HTML.
  71
  72     \snippet examples/webkit/previewer/previewer.cpp 1
  73
  74     \section1 MainWindow Class Definition
  75
  76     The \c MainWindow class for the Previewer example is a subclass of
  77     QMainWindow with a constructor and five private slots: \c open(),
  78     \c openUrl(), \c save(), \c about() and \c updateTextEdit().
  79
  80     \snippet examples/webkit/previewer/mainwindow.h 0
  81
  82     The private objects in \c MainWindow are \c centralWidget, which is
  83     a \c Previewer object, \c fileMenu, \c helpMenu and the QAction objects
  84     \c openAct, \c openUrlAct, \c saveAct, \c exitAct, \c aboutAct and
  85     \c aboutQtAct.
  86
  87     \snippet examples/webkit/previewer/mainwindow.h 1
  88
  89     There are three private functions: \c createActions(), \c createMenus()
  90     and \c setStartupText(). The \c createActions() and \c createMenus()
  91     functions are necessary to set up the main window's actions and
  92     assign them to the \gui File and \gui Help menus. The \c setStartupText()
  93     function, on the other hand, displays a description about the example
  94     in its HTML Previewer window.
  95
  96     \section1 MainWindow Class Implementation
  97
  98     The \c{MainWindow}'s constructor invokes \c createActions() and
  99     \c createMenus() to set up the \gui File menu and \gui Help menu. Then,
 100     the \c Previewer object, \c centralWidget, is set to the main window's
 101     central widget. Also, we connect \c webView's
 102     \l{QWebView::}{loadFinished()} signal to our \c updateTextEdit() slot.
 103     Finally, we call the \c setStartupText() function to display the
 104     description of the example.
 105
 106     \snippet examples/webkit/previewer/mainwindow.cpp 0
 107
 108     Within the \c createActions() function, we instantiate all our private
 109     QAction objects which we declared in \c{mainwindow.h}. We set the
 110     short cut and status tip for these actions and connect their
 111     \l{QAction::}{triggered()} signal to appropriate slots.
 112
 113     \snippet examples/webkit/previewer/mainwindow.cpp 1
 114     \dots
 115
 116     The \c createMenus() function instantiates the QMenu items, \c fileMenu
 117     and \c helpMenu and adds them to the main window's
 118     \l{QMainWindow::menuBar()}{menu bar}.
 119
 120     \snippet examples/webkit/previewer/mainwindow.cpp 2
 121
 122     The example also provides an \c about() slot to describe its purpose.
 123
 124     \snippet examples/webkit/previewer/mainwindow.cpp 3
 125
 126     The \c MainWindow class provides two types of \gui Open functions:
 127     \c open() and \c openUrl(). The \c open() function opens an HTML file
 128     with \c fileName, and reads it with QTextStream. The function then
 129     displays the output on \c plainTextEdit. The file's name is obtained
 130     using QFileDialog's \l{QFileDialog::}{getOpenFileName()} function.
 131
 132     \snippet examples/webkit/previewer/mainwindow.cpp 4
 133
 134     The \c openUrl() function, on the other hand, displays a QInputDialog
 135     to obtain a URL, and displays it on \c webView.
 136
 137     \snippet examples/webkit/previewer/mainwindow.cpp 5
 138
 139     In order to save a HTML file, the \c save() function first extracts the
 140     contents of \c plainTextEdit and displays a QFileDialog to obtain
 141     \c fileName. Then, we use a QTextStream object, \c in, to write to
 142     \c file.
 143
 144     \snippet examples/webkit/previewer/mainwindow.cpp 6
 145
 146     Earlier, in \c{MainWindow}'s constructor, we connected \c{webView}'s
 147     \l{QWebView::}{loadFinished()} signal to our private \c updateTextEdit()
 148     slot. This slot updates the contents of \c plainTextEdit with the HTML
 149     source of the web page's main frame, obtained using \l{QWebFrame}'s
 150     \l{QWebFrame::}{toHtml()} function.
 151
 152     \snippet examples/webkit/previewer/mainwindow.cpp 7
 153
 154     To provide a description about the Previewer example, when it starts up,
 155     we use the \c setStartupText() function, as shown below:
 156
 157     \snippet examples/webkit/previewer/mainwindow.cpp 8
 158
 159
 160     \section1 The \c{main()} Function
 161
 162     The \c main() function instantiates a \c MainWindow object, \c mainWindow,
 163     and displays it with the \l{QWidget::}{show()} function.
 164
 165     \snippet examples/webkit/previewer/main.cpp 0
 166
 167 */