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

Last change on this file since 892 was 846, checked in by Dmitry A. Kuminov, 15 years ago

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.
File size: 6.6 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4** All rights reserved.
5** Contact: Nokia Corporation (qt-info@nokia.com)
6**
7** This file is part of the documentation of the Qt Toolkit.
8**
9** $QT_BEGIN_LICENSE:FDL$
10** Commercial Usage
11** Licensees holding valid Qt Commercial licenses may use this file in
12** accordance with the Qt Commercial License Agreement provided with the
13** Software or, alternatively, in accordance with the terms contained in a
14** written agreement between you and Nokia.
15**
16** GNU Free Documentation License
17** Alternatively, this file may be used under the terms of the GNU Free
18** Documentation License version 1.3 as published by the Free Software
19** Foundation and appearing in the file included in the packaging of this
20** file.
21**
22** If you have questions regarding the use of this file, please contact
23** Nokia at qt-info@nokia.com.
24** $QT_END_LICENSE$
25**
26****************************************************************************/
27
28/*!
29 \example webkit/previewer
30 \title Previewer Example
31
32 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*/
Note: See TracBrowser for help on using the repository browser.