source: trunk/doc/src/examples/previewer.qdoc@ 523

Last change on this file since 523 was 2, checked in by Dmitry A. Kuminov, 16 years ago

Initially imported qt-all-opensource-src-4.5.1 from Trolltech.
File size: 7.4 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4** Contact: Qt Software Information (qt-info@nokia.com)
5**
6** This file is part of the documentation of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial Usage
10** Licensees holding valid Qt Commercial licenses may use this file in
11** accordance with the Qt Commercial License Agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and Nokia.
14**
15** GNU Lesser General Public License Usage
16** Alternatively, this file may be used under the terms of the GNU Lesser
17** General Public License version 2.1 as published by the Free Software
18** Foundation and appearing in the file LICENSE.LGPL included in the
19** packaging of this file. Please review the following information to
20** ensure the GNU Lesser General Public License version 2.1 requirements
21** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
22**
23** In addition, as a special exception, Nokia gives you certain
24** additional rights. These rights are described in the Nokia Qt LGPL
25** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
26** package.
27**
28** GNU General Public License Usage
29** Alternatively, this file may be used under the terms of the GNU
30** General Public License version 3.0 as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL included in the
32** packaging of this file. Please review the following information to
33** ensure the GNU General Public License version 3.0 requirements will be
34** met: http://www.gnu.org/copyleft/gpl.html.
35**
36** If you are unsure which license is appropriate for your use, please
37** contact the sales department at qt-sales@nokia.com.
38** $QT_END_LICENSE$
39**
40****************************************************************************/
41
42/*!
43 \example webkit/previewer
44 \title Previewer Example
45
46 The Previewer example shows how to use QtWebKit's QWebView to preview
47 HTML data written in a QPlainTextEdit.
48
49 \image previewer-example.png
50
51 \section1 The User Interface
52
53 Before we begin, we create a user interface using \QD. Two QGroupBox
54 objects - the editor group box and the previewer group box are separated
55 by a QSplitter. In the editor group box, we have a QPlainTextEdit object,
56 \c plainTextEdit, and two QPushButton objects. In the previewer group box,
57 we have a QWebView object, \c webView.
58
59 \image previewer-ui.png
60
61 \section1 Previewer Class Definition
62
63 The \c Previewer class is a subclass of both QWidget and Ui::Form.
64 We subclass Ui::Form in order to embed the \QD user interface form
65 created earlier. This method of embedding forms is known as the
66 \l{The Multiple Inheritance Approach}{multiple inheritance approach}.
67
68 In our \c previewer.h file, we have a constructor and a slot,
69 \c on_previewButton_clicked().
70
71 \snippet examples/webkit/previewer/previewer.h 0
72
73 \section1 Previewer Class Implementation
74
75 The \c{Previewer}'s constructor is only responsible for setting up the
76 user interface.
77
78 \snippet examples/webkit/previewer/previewer.cpp 0
79
80 The \c on_previewButton_clicked() is a slot corresponding to the
81 \c{previewButton}'s \l{QPushButton::}{clicked()} signal. When the
82 \c previewButton is clicked, we extract the contents of \c plainTextEdit,
83 and then invoke the \l{QWebView::}{setHtml()} function to display our
84 contents as HTML.
85
86 \snippet examples/webkit/previewer/previewer.cpp 1
87
88 \section1 MainWindow Class Definition
89
90 The \c MainWindow class for the Previewer example is a subclass of
91 QMainWindow with a constructor and five private slots: \c open(),
92 \c openUrl(), \c save(), \c about() and \c updateTextEdit().
93
94 \snippet examples/webkit/previewer/mainwindow.h 0
95
96 The private objects in \c MainWindow are \c centralWidget, which is
97 a \c Previewer object, \c fileMenu, \c helpMenu and the QAction objects
98 \c openAct, \c openUrlAct, \c saveAct, \c exitAct, \c aboutAct and
99 \c aboutQtAct.
100
101 \snippet examples/webkit/previewer/mainwindow.h 1
102
103 There are three private functions: \c createActions(), \c createMenus()
104 and \c setStartupText(). The \c createActions() and \c createMenus()
105 functions are necessary to set up the main window's actions and
106 assign them to the \gui File and \gui Help menus. The \c setStartupText()
107 function, on the other hand, displays a description about the example
108 in its HTML Previewer window.
109
110 \section1 MainWindow Class Implementation
111
112 The \c{MainWindow}'s constructor invokes \c createActions() and
113 \c createMenus() to set up the \gui File menu and \gui Help menu. Then,
114 the \c Previewer object, \c centralWidget, is set to the main window's
115 central widget. Also, we connect \c webView's
116 \l{QWebView::}{loadFinished()} signal to our \c updateTextEdit() slot.
117 Finally, we call the \c setStartupText() function to display the
118 description of the example.
119
120 \snippet examples/webkit/previewer/mainwindow.cpp 0
121
122 Within the \c createActions() function, we instantiate all our private
123 QAction objects which we declared in \c{mainwindow.h}. We set the
124 short cut and status tip for these actions and connect their
125 \l{QAction::}{triggered()} signal to appropriate slots.
126
127 \snippet examples/webkit/previewer/mainwindow.cpp 1
128 \dots
129
130 The \c createMenus() function instantiates the QMenu items, \c fileMenu
131 and \c helpMenu and adds them to the main window's
132 \l{QMainWindow::menuBar()}{menu bar}.
133
134 \snippet examples/webkit/previewer/mainwindow.cpp 2
135
136 The example also provides an \c about() slot to describe its purpose.
137
138 \snippet examples/webkit/previewer/mainwindow.cpp 3
139
140 The \c MainWindow class provides two types of \gui Open functions:
141 \c open() and \c openUrl(). The \c open() function opens an HTML file
142 with \c fileName, and reads it with QTextStream. The function then
143 displays the output on \c plainTextEdit. The file's name is obtained
144 using QFileDialog's \l{QFileDialog::}{getOpenFileName()} function.
145
146 \snippet examples/webkit/previewer/mainwindow.cpp 4
147
148 The \c openUrl() function, on the other hand, displays a QInputDialog
149 to obtain a URL, and displays it on \c webView.
150
151 \snippet examples/webkit/previewer/mainwindow.cpp 5
152
153 In order to save a HTML file, the \c save() function first extracts the
154 contents of \c plainTextEdit and displays a QFileDialog to obtain
155 \c fileName. Then, we use a QTextStream object, \c in, to write to
156 \c file.
157
158 \snippet examples/webkit/previewer/mainwindow.cpp 6
159
160 Earlier, in \c{MainWindow}'s constructor, we connected \c{webView}'s
161 \l{QWebView::}{loadFinished()} signal to our private \c updateTextEdit()
162 slot. This slot updates the contents of \c plainTextEdit with the HTML
163 source of the web page's main frame, obtained using \l{QWebFrame}'s
164 \l{QWebFrame::}{toHtml()} function.
165
166 \snippet examples/webkit/previewer/mainwindow.cpp 7
167
168 To provide a description about the Previewer example, when it starts up,
169 we use the \c setStartupText() function, as shown below:
170
171 \snippet examples/webkit/previewer/mainwindow.cpp 8
172
173
174 \section1 The \c{main()} Function
175
176 The \c main() function instantiates a \c MainWindow object, \c mainWindow,
177 and displays it with the \l{QWidget::}{show()} function.
178
179 \snippet examples/webkit/previewer/main.cpp 0
180
181*/
Note: See TracBrowser for help on using the repository browser.