--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/porting/porting4-designer.qdoc Mon Jan 11 14:00:40 2010 +0000
@@ -0,0 +1,349 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights. These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page porting4-designer.html
+ \title Porting UI Files to Qt 4
+ \contentspage {Porting Guides}{Contents}
+ \previouspage Porting to Qt 4 - Drag and Drop
+ \nextpage Porting to Graphics View
+ \ingroup porting
+ \brief Information about changes to the UI file format in Qt 4.
+
+ Qt Designer has changed significantly in the Qt 4 release. We
+ have moved away from viewing Qt Designer as an IDE and
+ concentrated on creating a robust form builder which can be
+ extended and embedded in existing IDEs. Our efforts are ongoing
+ and include the \l{Visual Studio Integration},
+ as well as integrating Designer with KDevelop and possibly other
+ IDEs.
+
+ The most important changes in Qt Designer 4 which affect porting
+ for UI files are summarized below:
+
+ \list
+ \o \bold{Removed project manager.}
+ Qt Designer now only reads and edits UI
+ files. It has no notion of a project file (\c .pro).
+
+ \o \bold{Removed code editor.}
+ Qt Designer can no longer be used to edit source files.
+
+ \o \bold{Changed format of UI files.}
+ Qt Designer 4 cannot read files created by Qt Designer 3 and
+ vice versa. However, we provide the tool \c uic3 to generate Qt
+ 4 code out of Qt 3 UI files, and to convert old UI files
+ into a format readable by Qt Designer 4.
+
+ \o \bold{Changed structure of the code generated by \c uic.}
+ The \c myform.ui file containing the form \c MyForm is now
+ converted into a single header file \c ui_myform.h, which
+ contains the declaration and inline definition of a POD class
+ \c Ui::MyForm.
+
+ \o \bold{New resource file system.} Icon data is no longer
+ stored in the UI file. Instead, icons are put into resource
+ files (\c .qrc).
+ \endlist
+
+ The rest of this document explains how to deal with the main
+ differences between Qt Designer 3 and Qt Designer 4:
+
+ \tableofcontents
+
+ See \l{Porting to Qt 4} and \l{qt3to4 - The Qt 3 to 4 Porting
+ Tool} for more information about porting from Qt 3 to Qt 4. See
+ also the \l{Qt Designer Manual}.
+
+ \section1 uic Output
+
+ In Qt 3, \c uic generated a header file and an implementation for
+ a class, which inherited from one of Qt's widgets. To use the
+ form, the programmer included the generated sources into the
+ application and created an instance of the class.
+
+ In Qt 4, \c uic creates a header file containing a POD class. The
+ name of this class is the object name of the main container,
+ qualified with the \c Ui namespace (e.g., \c Ui::MyForm). The
+ class is implemented using inline functions, removing the need of
+ a separate \c .cpp file. Just as in Qt 3, this class contains
+ pointers to all the widgets inside the form as public members. In
+ addition, the generated class provides the public method \c
+ setupUi().
+
+ The class generated by \c uic is not a QWidget; in fact, it's not
+ even a QObject. Instead, it is a class which knows how to
+ populate an instance of a main container with the contents of the
+ form. The programmer creates the main container himself, then
+ passes it to \c setupUi().
+
+ For example, here's the \c uic output for a simple \c
+ helloworld.ui form (some details were removed for simplicity):
+
+ \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 0
+
+ In this case, the main container was specified to be a QWidget
+ (or any subclass of QWidget). Had we started with a QMainWindow
+ template in Qt Designer, \c setupUi()'s parameter would be of
+ type QMainWindow.
+
+ There are two ways to create an instance of our form. One
+ approach is to create an instance of the \c Ui::HelloWorld class,
+ an instance of the main container (a plain QWidget), and call \c
+ setupUi():
+
+ \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 1
+
+ The second approach is to inherit from both the \c Ui::HelloWorld
+ class and the main container, and to call \c setupUi() in the
+ constructor of the subclass. In that case, QWidget (or one of
+ its subclasses, e.g. QDialog) must appear first in the base class
+ list so that \l{moc} picks it up correctly. For example:
+
+ \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 2
+
+ This second method is useful when porting Qt 3 forms to Qt 4. \c
+ HelloWorldWidget is a class whose instance is the actual form
+ and which contains public pointers to all the widgets in it. It
+ therefore has an interface identical to that of a class generated
+ by \c uic in Qt 3.
+
+ Creating POD classes from UI files is more flexible and
+ generic than the old approach of creating widgets. Qt Designer
+ does not need to know anything about the main container apart from
+ the base widget class it inherits. Indeed, \c Ui::HelloWorld can
+ be used to populate any container that inherits QWidget.
+ Conversely, all non-GUI aspects of the main container may be
+ implemented by the programmer in the application's sources
+ without reference to the form.
+
+ \section1 Working with uic3
+
+ Qt 4 comes with the tool \c uic3 for working with old \c .ui
+ files. It can be used in two ways:
+
+ \list 1
+ \o To generate headers and source code for a widget to implement any
+ custom signals and slots added using Qt Designer 3.
+ \o To generate a new UI file that can be used with Qt Designer 4.
+ \endlist
+
+ You can use both these methods in combination to obtain UI, header
+ and source files that you can use as a starting point when porting
+ your user interface to Qt 4.
+
+ The first method generates a Qt 3 style header and implementation
+ which uses Qt 4 widgets (this includes the Qt 3 compatibility classes
+ present in the Qt3Support library). This process should be familiar to
+ anyone used to working with Qt Designer 3:
+
+ \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 3
+
+ The resulting files \c myform.h and \c myform.cpp implement the
+ form in Qt 4 using a QWidget that will include custom signals,
+ slots and connections specified in the UI file. However,
+ see below for the \l{#Limitations of uic3}{limitations} of this
+ method.
+
+ The second method is to use \c uic3 to convert a Qt Designer 3 \c .ui
+ file to the Qt Designer 4 format:
+
+ \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 4
+
+ The resulting file \c myform4.ui can be edited in Qt Designer 4. The
+ header file for the form is generated by Qt 4's \c uic. See the
+ \l{Using a Designer UI File in Your Application} chapter of the
+ \l{Qt Designer Manual} for information about the preferred ways to
+ use forms created with Qt Designer 4.
+
+ \c uic3 tries very hard to map Qt 3 classes and their properties to
+ Qt 4. However, the behavior of some classes changed significantly
+ in Qt 4. To keep the form working, some Qt 3 classes are mapped
+ to classes in the Qt3Support library. Table 1 shows a list of
+ classes this applies to.
+
+ \table
+ \header \o Qt 3 class \o Qt 4 class
+ \row \o \c QButtonGroup \o Q3ButtonGroup
+ \row \o \c QDateEdit \o Q3DateEdit
+ \row \o \c QDateTimeEdit \o Q3DateTimeEdit
+ \row \o \c QGroupBox \o Q3GroupBox
+ \row \o \c QListBox \o Q3ListBox
+ \row \o \c QListView \o Q3ListView
+ \row \o \c QMainWindow \o Q3MainWindow
+ \row \o \c QTextEdit \o Q3TextEdit
+ \row \o \c QTextView \o Q3TextView
+ \row \o \c QTimeEdit \o Q3TimeEdit
+ \row \o \c QWidgetStack \o Q3WidgetStack
+ \row \o \c QWizard \o Q3Wizard
+ \endtable
+
+ \section1 Limitations of uic3
+
+ Converting Qt 3 UI files to Qt 4 has some limitations. The
+ most noticeable limitation is the fact that since \c uic no
+ longer generates a QObject, it's not possible to define custom
+ signals or slots for the form. Instead, the programmer must
+ define these signals and slots in the main container and connect
+ them to the widgets in the form after calling \c setupUi(). For
+ example:
+
+ \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 5
+
+ A quick and dirty way to port forms containing custom signals and
+ slots is to generate the code using \c uic3, rather than \c uic. Since
+ \c uic3 does generate a QWidget, it will populate it with custom
+ signals, slots and connections specified in the UI file.
+ However, \c uic3 can only generate code from Qt 3 UI files, which
+ implies that the UI files never get translated and need to be
+ edited using Qt Designer 3.
+
+ Note also that it is possible to create implicit connections
+ between the widgets in a form and the main container. After \c
+ setupUi() populates the main container with child widgets it
+ scans the main container's list of slots for names with the form
+ \tt{on_\e{objectName}_\e{signalName}().}
+
+ If the form contains a widget whose object name is
+ \tt{\e{objectName}}, and if that widget has a signal called
+ \tt{\e{signalName}}, then this signal will be connected to the
+ main container's slot. For example:
+
+ \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 6
+
+ Because of the naming convention, \c setupUi() automatically
+ connects \c pushButton's \c clicked() signal to \c
+ HelloWorldWidget's \c on_pushButton_clicked() slot.
+
+ \section1 Icons
+
+ In Qt 3, the binary data for the icons used by a form was stored
+ in the UI file. In Qt 4 icons and any other external files
+ can be compiled into the application by listing them in a \l{The
+ Qt Resource System}{resource file} (\c .qrc). This file is
+ translated into a C++ source file using Qt's resource compiler
+ (\c rcc). The data in the files is then available to any Qt class
+ which takes a file name argument.
+
+ Imagine that we have two icons, \c yes.png and \c no.png. We
+ create a resource file called \c icons.qrc with the following
+ contents:
+
+ \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 7
+
+ Next, we add the resource file to our \c .pro file:
+
+ \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 8
+
+ When \c qmake is run, it will create the appropriate Makefile
+ rules to call \c rcc on the resource file, and compile and link
+ the result into the application. The icons may be accessed as
+ follows:
+
+ \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 9
+
+ In each case, the leading colon tells Qt to look for the file in
+ the virtual file tree defined by the set of resource files
+ compiled into the application instead of the file system.
+
+ In the \c .qrc file, the \c qresource tag's \c prefix attribute
+ is used to arrange the files into categories and set a virtual
+ path where the files will be accessed.
+
+ Caveat: If the resource file was not linked directly into the
+ application, but instead into a dynamic or static library that
+ was later linked with the application, its virtual file tree will
+ not be available to QFile and friends until the Q_INIT_RESOURCE()
+ macro is called. This macro takes one argument, which is the name
+ of the \c .qrc file, without the path or the file extension. A
+ convenient place to initialize resources is at the top of the
+ application's \c main() function.
+
+ In Qt Designer 4, we can associate any number of resource files
+ with a form using the resource editor tool. The widgets in the
+ form can access all icons specified in its associated resource
+ files.
+
+ In short, porting of icons from a Qt 3 to a Qt 4 form involves
+ the following steps:
+
+ \list 1
+ \o Use \c{uic3 -convert} to obtain a UI file understood by
+ Qt Designer 4.
+
+ \o Create a \c .qrc file with a list of all the icon files.
+
+ \o Add the resource file to the \c .pro file.
+
+ \o Open the form in Qt Designer 4 and add the resource file to the
+ form's resource editor.
+
+ \o Set the icon properties for the appropriate widgets.
+ \endlist
+
+ \section1 Custom Widgets
+
+ Qt Designer 3 supported defining custom widgets by specifying
+ their name, header file and methods. In Qt Designer 4, a custom
+ widget is always created by "promoting" an existing Qt widget to
+ a custom class. Qt Designer 4 assumes that the custom widget will
+ inherit from the widget that has been promoted. In the form
+ editor, the custom widget will retain the looks, behavior,
+ properties, signals and slots of the base widget. It is not
+ currently possible to tell Qt Designer 4 that the custom widget
+ will have additional signals or slots.
+
+ \c{uic3 -convert} handles the conversion of custom widgets to the
+ new \c .ui format, however all custom signals and slots are lost.
+ Furthermore, since Qt Designer 3 never knew the base widget class
+ of a custom widget, it is taken to be QWidget. This is often
+ sufficient. If not, the custom widgets have to be inserted
+ manually into the form.
+
+ Custom widget plugins, which contain custom widgets to be used in
+ Qt Designer, must themselves be ported before they can be used in
+ forms ported with \c{uic3}.
+ The \l{Porting to Qt 4} document contains information about general
+ porting issues that may apply to the custom widget code itself, and
+ the \l{Creating Custom Widgets for Qt Designer} chapter of the
+ \l{Qt Designer Manual} describes how the ported widget should be
+ built in order to work in Qt Designer 4.
+*/