Long live Qt for S60!

1 files changed, 349 insertions, 0 deletions

diff --git a/doc/src/porting4-designer.qdoc b/doc/src/porting4-designer.qdoc
new file mode 100644
index 0000000..9ae3c52
--- /dev/null
+++ b/doc/src/porting4-designer.qdoc
@@ -0,0 +1,349 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@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 \c .ui files are summarized below:
+
+    \list
+    \o  \bold{Removed project manager.}
+        Qt Designer now only reads and edits \c .ui
+        files. It has no notion of a project (\c .pro file).
+
+    \o  \bold{Removed code editor.}
+        Qt Designer can no longer be used to edit source files.
+
+    \o  \bold{Changed format of \c .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 \c .ui files, and to convert old \c .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 \c .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 \c .ui files is more flexible and
+    generic than the old approach of creating widgets. Qt Designer
+    doesn't 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 \c .ui file that can be used with Qt Designer 4.
+    \endlist
+
+    You can use both these methods in combination to obtain \c{.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 \c .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 \c .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 \c .ui file.
+    However, \c uic3 can only generate code from Qt 3 \c .ui files, which
+    implies that the \c .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 \c .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 \c .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.
+*/