Update copyright headers
[qt:qt.git] / doc / src / porting / porting4-designer.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file.  Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
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.cpp 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.cpp 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.cpp 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.cpp 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.cpp 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.pro 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.cpp 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 */