doc/src/porting4-designer.qdoc

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