source: trunk/doc/src/examples/dockwidgets.qdoc@ 550

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

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