|
1 /**************************************************************************** |
|
2 ** |
|
3 ** Copyright (C) 2010 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:LGPL$ |
|
10 ** No Commercial Usage |
|
11 ** This file contains pre-release code and may not be distributed. |
|
12 ** You may use this file in accordance with the terms and conditions |
|
13 ** contained in the Technology Preview License Agreement accompanying |
|
14 ** this package. |
|
15 ** |
|
16 ** GNU Lesser General Public License Usage |
|
17 ** Alternatively, this file may be used under the terms of the GNU Lesser |
|
18 ** General Public License version 2.1 as published by the Free Software |
|
19 ** Foundation and appearing in the file LICENSE.LGPL included in the |
|
20 ** packaging of this file. Please review the following information to |
|
21 ** ensure the GNU Lesser General Public License version 2.1 requirements |
|
22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. |
|
23 ** |
|
24 ** In addition, as a special exception, Nokia gives you certain additional |
|
25 ** rights. These rights are described in the Nokia Qt LGPL Exception |
|
26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. |
|
27 ** |
|
28 ** If you have questions regarding the use of this file, please contact |
|
29 ** Nokia at qt-info@nokia.com. |
|
30 ** |
|
31 ** |
|
32 ** |
|
33 ** |
|
34 ** |
|
35 ** |
|
36 ** |
|
37 ** |
|
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 */ |