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 | \page porting4-designer.html
|
---|
30 | \title Porting UI Files to Qt 4
|
---|
31 | \contentspage {Porting Guides}{Contents}
|
---|
32 | \previouspage Porting to Qt 4 - Drag and Drop
|
---|
33 | \nextpage Porting to Graphics View
|
---|
34 | \ingroup porting
|
---|
35 | \brief Information about changes to the UI file format in Qt 4.
|
---|
36 |
|
---|
37 | Qt Designer has changed significantly in the Qt 4 release. We
|
---|
38 | have moved away from viewing Qt Designer as an IDE and
|
---|
39 | concentrated on creating a robust form builder which can be
|
---|
40 | extended and embedded in existing IDEs. Our efforts are ongoing
|
---|
41 | and include the \l{Visual Studio Integration},
|
---|
42 | as well as integrating Designer with KDevelop and possibly other
|
---|
43 | IDEs.
|
---|
44 |
|
---|
45 | The most important changes in Qt Designer 4 which affect porting
|
---|
46 | for UI files are summarized below:
|
---|
47 |
|
---|
48 | \list
|
---|
49 | \o \bold{Removed project manager.}
|
---|
50 | Qt Designer now only reads and edits UI
|
---|
51 | files. It has no notion of a project file (\c .pro).
|
---|
52 |
|
---|
53 | \o \bold{Removed code editor.}
|
---|
54 | Qt Designer can no longer be used to edit source files.
|
---|
55 |
|
---|
56 | \o \bold{Changed format of UI files.}
|
---|
57 | Qt Designer 4 cannot read files created by Qt Designer 3 and
|
---|
58 | vice versa. However, we provide the tool \c uic3 to generate Qt
|
---|
59 | 4 code out of Qt 3 UI files, and to convert old UI files
|
---|
60 | into a format readable by Qt Designer 4.
|
---|
61 |
|
---|
62 | \o \bold{Changed structure of the code generated by \c uic.}
|
---|
63 | The \c myform.ui file containing the form \c MyForm is now
|
---|
64 | converted into a single header file \c ui_myform.h, which
|
---|
65 | contains the declaration and inline definition of a POD class
|
---|
66 | \c Ui::MyForm.
|
---|
67 |
|
---|
68 | \o \bold{New resource file system.} Icon data is no longer
|
---|
69 | stored in the UI file. Instead, icons are put into resource
|
---|
70 | files (\c .qrc).
|
---|
71 | \endlist
|
---|
72 |
|
---|
73 | The rest of this document explains how to deal with the main
|
---|
74 | differences between Qt Designer 3 and Qt Designer 4:
|
---|
75 |
|
---|
76 | \tableofcontents
|
---|
77 |
|
---|
78 | See \l{Porting to Qt 4} and \l{qt3to4 - The Qt 3 to 4 Porting
|
---|
79 | Tool} for more information about porting from Qt 3 to Qt 4. See
|
---|
80 | also the \l{Qt Designer Manual}.
|
---|
81 |
|
---|
82 | \section1 uic Output
|
---|
83 |
|
---|
84 | In Qt 3, \c uic generated a header file and an implementation for
|
---|
85 | a class, which inherited from one of Qt's widgets. To use the
|
---|
86 | form, the programmer included the generated sources into the
|
---|
87 | application and created an instance of the class.
|
---|
88 |
|
---|
89 | In Qt 4, \c uic creates a header file containing a POD class. The
|
---|
90 | name of this class is the object name of the main container,
|
---|
91 | qualified with the \c Ui namespace (e.g., \c Ui::MyForm). The
|
---|
92 | class is implemented using inline functions, removing the need of
|
---|
93 | a separate \c .cpp file. Just as in Qt 3, this class contains
|
---|
94 | pointers to all the widgets inside the form as public members. In
|
---|
95 | addition, the generated class provides the public method \c
|
---|
96 | setupUi().
|
---|
97 |
|
---|
98 | The class generated by \c uic is not a QWidget; in fact, it's not
|
---|
99 | even a QObject. Instead, it is a class which knows how to
|
---|
100 | populate an instance of a main container with the contents of the
|
---|
101 | form. The programmer creates the main container himself, then
|
---|
102 | passes it to \c setupUi().
|
---|
103 |
|
---|
104 | For example, here's the \c uic output for a simple \c
|
---|
105 | helloworld.ui form (some details were removed for simplicity):
|
---|
106 |
|
---|
107 | \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 0
|
---|
108 |
|
---|
109 | In this case, the main container was specified to be a QWidget
|
---|
110 | (or any subclass of QWidget). Had we started with a QMainWindow
|
---|
111 | template in Qt Designer, \c setupUi()'s parameter would be of
|
---|
112 | type QMainWindow.
|
---|
113 |
|
---|
114 | There are two ways to create an instance of our form. One
|
---|
115 | approach is to create an instance of the \c Ui::HelloWorld class,
|
---|
116 | an instance of the main container (a plain QWidget), and call \c
|
---|
117 | setupUi():
|
---|
118 |
|
---|
119 | \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 1
|
---|
120 |
|
---|
121 | The second approach is to inherit from both the \c Ui::HelloWorld
|
---|
122 | class and the main container, and to call \c setupUi() in the
|
---|
123 | constructor of the subclass. In that case, QWidget (or one of
|
---|
124 | its subclasses, e.g. QDialog) must appear first in the base class
|
---|
125 | list so that \l{moc} picks it up correctly. For example:
|
---|
126 |
|
---|
127 | \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 2
|
---|
128 |
|
---|
129 | This second method is useful when porting Qt 3 forms to Qt 4. \c
|
---|
130 | HelloWorldWidget is a class whose instance is the actual form
|
---|
131 | and which contains public pointers to all the widgets in it. It
|
---|
132 | therefore has an interface identical to that of a class generated
|
---|
133 | by \c uic in Qt 3.
|
---|
134 |
|
---|
135 | Creating POD classes from UI files is more flexible and
|
---|
136 | generic than the old approach of creating widgets. Qt Designer
|
---|
137 | does not need to know anything about the main container apart from
|
---|
138 | the base widget class it inherits. Indeed, \c Ui::HelloWorld can
|
---|
139 | be used to populate any container that inherits QWidget.
|
---|
140 | Conversely, all non-GUI aspects of the main container may be
|
---|
141 | implemented by the programmer in the application's sources
|
---|
142 | without reference to the form.
|
---|
143 |
|
---|
144 | \section1 Working with uic3
|
---|
145 |
|
---|
146 | Qt 4 comes with the tool \c uic3 for working with old \c .ui
|
---|
147 | files. It can be used in two ways:
|
---|
148 |
|
---|
149 | \list 1
|
---|
150 | \o To generate headers and source code for a widget to implement any
|
---|
151 | custom signals and slots added using Qt Designer 3.
|
---|
152 | \o To generate a new UI file that can be used with Qt Designer 4.
|
---|
153 | \endlist
|
---|
154 |
|
---|
155 | You can use both these methods in combination to obtain UI, header
|
---|
156 | and source files that you can use as a starting point when porting
|
---|
157 | your user interface to Qt 4.
|
---|
158 |
|
---|
159 | The first method generates a Qt 3 style header and implementation
|
---|
160 | which uses Qt 4 widgets (this includes the Qt 3 compatibility classes
|
---|
161 | present in the Qt3Support library). This process should be familiar to
|
---|
162 | anyone used to working with Qt Designer 3:
|
---|
163 |
|
---|
164 | \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 3
|
---|
165 |
|
---|
166 | The resulting files \c myform.h and \c myform.cpp implement the
|
---|
167 | form in Qt 4 using a QWidget that will include custom signals,
|
---|
168 | slots and connections specified in the UI file. However,
|
---|
169 | see below for the \l{#Limitations of uic3}{limitations} of this
|
---|
170 | method.
|
---|
171 |
|
---|
172 | The second method is to use \c uic3 to convert a Qt Designer 3 \c .ui
|
---|
173 | file to the Qt Designer 4 format:
|
---|
174 |
|
---|
175 | \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 4
|
---|
176 |
|
---|
177 | The resulting file \c myform4.ui can be edited in Qt Designer 4. The
|
---|
178 | header file for the form is generated by Qt 4's \c uic. See the
|
---|
179 | \l{Using a Designer UI File in Your Application} chapter of the
|
---|
180 | \l{Qt Designer Manual} for information about the preferred ways to
|
---|
181 | use forms created with Qt Designer 4.
|
---|
182 |
|
---|
183 | \c uic3 tries very hard to map Qt 3 classes and their properties to
|
---|
184 | Qt 4. However, the behavior of some classes changed significantly
|
---|
185 | in Qt 4. To keep the form working, some Qt 3 classes are mapped
|
---|
186 | to classes in the Qt3Support library. Table 1 shows a list of
|
---|
187 | classes this applies to.
|
---|
188 |
|
---|
189 | \table
|
---|
190 | \header \o Qt 3 class \o Qt 4 class
|
---|
191 | \row \o \c QButtonGroup \o Q3ButtonGroup
|
---|
192 | \row \o \c QDateEdit \o Q3DateEdit
|
---|
193 | \row \o \c QDateTimeEdit \o Q3DateTimeEdit
|
---|
194 | \row \o \c QGroupBox \o Q3GroupBox
|
---|
195 | \row \o \c QListBox \o Q3ListBox
|
---|
196 | \row \o \c QListView \o Q3ListView
|
---|
197 | \row \o \c QMainWindow \o Q3MainWindow
|
---|
198 | \row \o \c QTextEdit \o Q3TextEdit
|
---|
199 | \row \o \c QTextView \o Q3TextView
|
---|
200 | \row \o \c QTimeEdit \o Q3TimeEdit
|
---|
201 | \row \o \c QWidgetStack \o Q3WidgetStack
|
---|
202 | \row \o \c QWizard \o Q3Wizard
|
---|
203 | \endtable
|
---|
204 |
|
---|
205 | \section1 Limitations of uic3
|
---|
206 |
|
---|
207 | Converting Qt 3 UI files to Qt 4 has some limitations. The
|
---|
208 | most noticeable limitation is the fact that since \c uic no
|
---|
209 | longer generates a QObject, it's not possible to define custom
|
---|
210 | signals or slots for the form. Instead, the programmer must
|
---|
211 | define these signals and slots in the main container and connect
|
---|
212 | them to the widgets in the form after calling \c setupUi(). For
|
---|
213 | example:
|
---|
214 |
|
---|
215 | \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 5
|
---|
216 |
|
---|
217 | A quick and dirty way to port forms containing custom signals and
|
---|
218 | slots is to generate the code using \c uic3, rather than \c uic. Since
|
---|
219 | \c uic3 does generate a QWidget, it will populate it with custom
|
---|
220 | signals, slots and connections specified in the UI file.
|
---|
221 | However, \c uic3 can only generate code from Qt 3 UI files, which
|
---|
222 | implies that the UI files never get translated and need to be
|
---|
223 | edited using Qt Designer 3.
|
---|
224 |
|
---|
225 | Note also that it is possible to create implicit connections
|
---|
226 | between the widgets in a form and the main container. After \c
|
---|
227 | setupUi() populates the main container with child widgets it
|
---|
228 | scans the main container's list of slots for names with the form
|
---|
229 | \tt{on_\e{objectName}_\e{signalName}().}
|
---|
230 |
|
---|
231 | If the form contains a widget whose object name is
|
---|
232 | \tt{\e{objectName}}, and if that widget has a signal called
|
---|
233 | \tt{\e{signalName}}, then this signal will be connected to the
|
---|
234 | main container's slot. For example:
|
---|
235 |
|
---|
236 | \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 6
|
---|
237 |
|
---|
238 | Because of the naming convention, \c setupUi() automatically
|
---|
239 | connects \c pushButton's \c clicked() signal to \c
|
---|
240 | HelloWorldWidget's \c on_pushButton_clicked() slot.
|
---|
241 |
|
---|
242 | \section1 Icons
|
---|
243 |
|
---|
244 | In Qt 3, the binary data for the icons used by a form was stored
|
---|
245 | in the UI file. In Qt 4 icons and any other external files
|
---|
246 | can be compiled into the application by listing them in a \l{The
|
---|
247 | Qt Resource System}{resource file} (\c .qrc). This file is
|
---|
248 | translated into a C++ source file using Qt's resource compiler
|
---|
249 | (\c rcc). The data in the files is then available to any Qt class
|
---|
250 | which takes a file name argument.
|
---|
251 |
|
---|
252 | Imagine that we have two icons, \c yes.png and \c no.png. We
|
---|
253 | create a resource file called \c icons.qrc with the following
|
---|
254 | contents:
|
---|
255 |
|
---|
256 | \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 7
|
---|
257 |
|
---|
258 | Next, we add the resource file to our \c .pro file:
|
---|
259 |
|
---|
260 | \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 8
|
---|
261 |
|
---|
262 | When \c qmake is run, it will create the appropriate Makefile
|
---|
263 | rules to call \c rcc on the resource file, and compile and link
|
---|
264 | the result into the application. The icons may be accessed as
|
---|
265 | follows:
|
---|
266 |
|
---|
267 | \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 9
|
---|
268 |
|
---|
269 | In each case, the leading colon tells Qt to look for the file in
|
---|
270 | the virtual file tree defined by the set of resource files
|
---|
271 | compiled into the application instead of the file system.
|
---|
272 |
|
---|
273 | In the \c .qrc file, the \c qresource tag's \c prefix attribute
|
---|
274 | is used to arrange the files into categories and set a virtual
|
---|
275 | path where the files will be accessed.
|
---|
276 |
|
---|
277 | Caveat: If the resource file was not linked directly into the
|
---|
278 | application, but instead into a dynamic or static library that
|
---|
279 | was later linked with the application, its virtual file tree will
|
---|
280 | not be available to QFile and friends until the Q_INIT_RESOURCE()
|
---|
281 | macro is called. This macro takes one argument, which is the name
|
---|
282 | of the \c .qrc file, without the path or the file extension. A
|
---|
283 | convenient place to initialize resources is at the top of the
|
---|
284 | application's \c main() function.
|
---|
285 |
|
---|
286 | In Qt Designer 4, we can associate any number of resource files
|
---|
287 | with a form using the resource editor tool. The widgets in the
|
---|
288 | form can access all icons specified in its associated resource
|
---|
289 | files.
|
---|
290 |
|
---|
291 | In short, porting of icons from a Qt 3 to a Qt 4 form involves
|
---|
292 | the following steps:
|
---|
293 |
|
---|
294 | \list 1
|
---|
295 | \o Use \c{uic3 -convert} to obtain a UI file understood by
|
---|
296 | Qt Designer 4.
|
---|
297 |
|
---|
298 | \o Create a \c .qrc file with a list of all the icon files.
|
---|
299 |
|
---|
300 | \o Add the resource file to the \c .pro file.
|
---|
301 |
|
---|
302 | \o Open the form in Qt Designer 4 and add the resource file to the
|
---|
303 | form's resource editor.
|
---|
304 |
|
---|
305 | \o Set the icon properties for the appropriate widgets.
|
---|
306 | \endlist
|
---|
307 |
|
---|
308 | \section1 Custom Widgets
|
---|
309 |
|
---|
310 | Qt Designer 3 supported defining custom widgets by specifying
|
---|
311 | their name, header file and methods. In Qt Designer 4, a custom
|
---|
312 | widget is always created by "promoting" an existing Qt widget to
|
---|
313 | a custom class. Qt Designer 4 assumes that the custom widget will
|
---|
314 | inherit from the widget that has been promoted. In the form
|
---|
315 | editor, the custom widget will retain the looks, behavior,
|
---|
316 | properties, signals and slots of the base widget. It is not
|
---|
317 | currently possible to tell Qt Designer 4 that the custom widget
|
---|
318 | will have additional signals or slots.
|
---|
319 |
|
---|
320 | \c{uic3 -convert} handles the conversion of custom widgets to the
|
---|
321 | new \c .ui format, however all custom signals and slots are lost.
|
---|
322 | Furthermore, since Qt Designer 3 never knew the base widget class
|
---|
323 | of a custom widget, it is taken to be QWidget. This is often
|
---|
324 | sufficient. If not, the custom widgets have to be inserted
|
---|
325 | manually into the form.
|
---|
326 |
|
---|
327 | Custom widget plugins, which contain custom widgets to be used in
|
---|
328 | Qt Designer, must themselves be ported before they can be used in
|
---|
329 | forms ported with \c{uic3}.
|
---|
330 | The \l{Porting to Qt 4} document contains information about general
|
---|
331 | porting issues that may apply to the custom widget code itself, and
|
---|
332 | the \l{Creating Custom Widgets for Qt Designer} chapter of the
|
---|
333 | \l{Qt Designer Manual} describes how the ported widget should be
|
---|
334 | built in order to work in Qt Designer 4.
|
---|
335 | */
|
---|