FCL/sf/mw/qt: comparison doc/src/porting/porting4-designer.qdoc

equal deleted inserted replaced

-:dee5afe5301f
+:3f74d0d4af4c
+/****************************************************************************
+**
+** 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.
+*/

branch	RCL_3
changeset 8	3f74d0d4af4c