/****************************************************************************

**

** Copyright (C) 2010 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.

*/