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 */