1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
|
/****************************************************************************
**
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** GNU Free Documentation License
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\example mainwindows/dockwidgets
\title Dock Widgets Example
The Dock Widgets example shows how to add dock windows to an
application. It also shows how to use Qt's rich text engine.
\image dockwidgets-example.png Screenshot of the Dock Widgets example
The application presents a simple business letter template, and has
a list of customer names and addresses and a list of standard
phrases in two dock windows. The user can click a customer to have
their name and address inserted into the template, and click one or
more of the standard phrases. Errors can be corrected by clicking
the Undo button. Once the letter has been prepared it can be printed
or saved as HTML.
\section1 MainWindow Class Definition
Here's the class definition:
\snippet examples/mainwindows/dockwidgets/mainwindow.h 0
We will now review each function in turn.
\section1 MainWindow Class Implementation
\snippet examples/mainwindows/dockwidgets/mainwindow.cpp 0
We start by including \c <QtGui>, a header file that contains the
definition of all classes in the \l QtCore and \l QtGui
libraries. This saves us from having to include
every class individually and is especially convenient if we add new
widgets. We also include \c mainwindow.h.
\snippet examples/mainwindows/dockwidgets/mainwindow.cpp 1
In the constructor, we start by creating a QTextEdit widget. Then we call
QMainWindow::setCentralWidget(). This function passes ownership of
the QTextEdit to the \c MainWindow and tells the \c MainWindow that
the QTextEdit will occupy the \c MainWindow's central area.
Then we call \c createActions(), \c createMenus(), \c
createToolBars(), \c createStatusBar(), and \c createDockWindows()
to set up the user interface. Finally we call \c setWindowTitle() to
give the application a title, and \c newLetter() to create a new
letter template.
We won't quote the \c createActions(), \c createMenus(), \c
createToolBars(), and \c createStatusBar() functions since they
follow the same pattern as all the other Qt examples.
\snippet examples/mainwindows/dockwidgets/mainwindow.cpp 9
We create the customers dock window first, and in addition to a
window title, we also pass it a \c this pointer so that it becomes a
child of \c MainWindow. Normally we don't have to pass a parent
because widgets are parented automatically when they are laid out:
but dock windows aren't laid out using layouts.
We've chosen to restrict the customers dock window to the left and
right dock areas. (So the user cannot drag the dock window to the
top or bottom dock areas.) The user can drag the dock window out of
the dock areas entirely so that it becomes a free floating window.
We can change this (and whether the dock window is moveable or
closable) using QDockWidget::setFeatures().
Once we've created the dock window we create a list widget with the
dock window as parent, then we populate the list and make it the
dock window's widget. Finally we add the dock widget to the \c
MainWindow using \c addDockWidget(), choosing to put it in the right
dock area.
We undertake a similar process for the paragraphs dock window,
except that we don't restrict which dock areas it can be dragged to.
Finally we set up the signal-slot connections. If the user clicks a
customer or a paragraph their \c currentTextChanged() signal will be
emitted and we connect these to \c insertCustomer() and
addParagraph() passing the text that was clicked.
We briefly discuss the rest of the implementation, but have now
covered everything relating to dock windows.
\snippet examples/mainwindows/dockwidgets/mainwindow.cpp 2
In this function we clear the QTextEdit so that it is empty. Next we
create a QTextCursor on the QTextEdit. We move the cursor to the
start of the document and create and format a frame. We then create
some character formats and a table format. We insert a table into
the document and insert the company's name and address into a table
using the table and character formats we created earlier. Then we
insert the skeleton of the letter including two markers \c NAME and
\c ADDRESS. We will also use the \c{Yours sincerely,} text as a marker.
\snippet examples/mainwindows/dockwidgets/mainwindow.cpp 6
If the user clicks a customer we split the customer details into
pieces. We then look for the \c NAME marker using the \c find()
function. This function selects the text it finds, so when we call
\c insertText() with the customer's name the name replaces the marker.
We then look for the \c ADDRESS marker and replace it with each line
of the customer's address. Notice that we wrapped all the insertions
between a \c beginEditBlock() and \c endEditBlock() pair. This means
that the entire name and address insertion is treated as a single
operation by the QTextEdit, so a single undo will revert all the
insertions.
\snippet examples/mainwindows/dockwidgets/mainwindow.cpp 7
This function works in a similar way to \c insertCustomer(). First
we look for the marker, in this case, \c {Yours sincerely,}, and then
replace it with the standard paragraph that the user clicked. Again
we use a \c beginEditBlock() ... \c endEditBlock() pair so that the
insertion can be undone as a single operation.
\snippet examples/mainwindows/dockwidgets/mainwindow.cpp 3
Qt's QTextDocument class makes printing documents easy. We simply
take the QTextEdit's QTextDocument, set up the printer and print the
document.
\snippet examples/mainwindows/dockwidgets/mainwindow.cpp 4
QTextEdit can output its contents in HTML format, so we prompt the
user for the name of an HTML file and if they provide one we simply
write the QTextEdit's contents in HTML format to the file.
\snippet examples/mainwindows/dockwidgets/mainwindow.cpp 5
If the focus is in the QTextEdit, pressing \key Ctrl+Z undoes as
expected. But for the user's convenience we provide an
application-wide undo function that simply calls the QTextEdit's
undo: this means that the user can undo regardless of where the
focus is in the application.
*/
|
