Changeset 846 for trunk/doc/src/development/designer-manual.qdoc

Timestamp:

May 5, 2011, 5:36:53 AM (14 years ago)

Author:

Dmitry A. Kuminov

Message:

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.

Location:

trunk

Files:

• . (modified) (1 prop)
• doc/src/development/designer-manual.qdoc (modified) (12 diffs)

trunk/doc/src/development/designer-manual.qdoc

@@ -1 +1 @@
 /****************************************************************************
 **
-** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
 ** All rights reserved.
 ** Contact: Nokia Corporation (qt-info@nokia.com)
@@ -7 +7 @@
 ** This file is part of the documentation of the Qt Toolkit.
 **
-** $QT_BEGIN_LICENSE:LGPL$
+** $QT_BEGIN_LICENSE:FDL$
 ** Commercial Usage
 ** Licensees holding valid Qt Commercial licenses may use this file in
 ** accordance with the Qt Commercial License Agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and Nokia.
+** Software or, alternatively, in accordance with the terms contained in a
+** written agreement between you and Nokia.
 **
-** 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.
-**
-** 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.
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of this
+** file.
 **
 ** If you have questions regarding the use of this file, please contact
@@ -1784 +1770 @@
     \title Using a Designer UI File in Your Application
 
-    With Qt's integrated build tools, \l{qmake Manual}{qmake} and \l uic, the
-    code for user interface components created with \QD is automatically
-    generated when the rest of your application is built. Forms can be included
-    and used directly from your application. Alternatively, you can use them to
-    extend subclasses of standard widgets. These forms can be processed at
-    compile time or at run time, depending on the approach used.
-
+    Qt Designer UI files represent the widget tree of the form in XML format. The
+    forms can be processed:
+
+    \list
+        \o \l{Compile Time Form Processing}{At compile time}, which means that forms
+            are converted to C++ code that can be compiled.
+        \o \l{Run Time Form Processing}{At runtime}, which means that forms are processed
+            by the QUiLoader class that dynamically constructs the widget tree while
+            parsing the XML file.
+    \endlist
 
     \tableofcontents
     \section1 Compile Time Form Processing
 
+    You create user interface components with \QD and use Qt's integrated build tools,
+    \l{qmake Manual}{qmake} and \l{User Interface Compiler (uic)}{uic}, to generate code
+    for them when the application is built. The generated code contains the form's user
+    interface object. It is a C++ struct that contains:
+
+    \list
+        \o Pointers to the form's widgets, layouts, layout items,
+           button groups, and actions.
+        \o A member function called \c setupUi() to build the widget tree
+           on the parent widget.
+        \o A member function called \c retranslateUi() that handles the
+           translation of the string properties of the form. For more information,
+           see \l{Reacting to Language Changes}.
+    \endlist
+
+    The generated code can be included in your application and used directly from
+    it. Alternatively, you can use it to extend subclasses of standard widgets.
+
     A compile time processed form can be used in your application with one of
     the following approaches:
 
     \list
-        \o  The Direct Approach: you construct a widget to use as a placeholder
+        \o  \l{The Direct Approach}: you construct a widget to use as a placeholder
             for the component, and set up the user interface inside it.
-        \o  The Single Inheritance Approach: you subclass the form's base class
+        \o  \l{The Single Inheritance Approach}: you subclass the form's base class
             (QWidget or QDialog, for example), and include a private instance
             of the form's user interface object.
-        \o  The MultipleInheritance Approach: you subclass both the form's base
+        \o  \l{The Multiple Inheritance Approach}: you subclass both the form's base
             class and the form's user interface object. This allows the widgets
             defined in the form to be used directly from within the scope of
@@ -1810 +1817 @@
     \endlist
 
-
-    \section2 The Direct Approach
-
-    To demonstrate how to use user interface (UI) files straight from
-    \QD, we create a simple Calculator Form application. This is based on the
+    To demonstrate, we create a simple Calculator Form application. It is based on the
     original \l{Calculator Form Example}{Calculator Form} example.
 
@@ -1832 +1835 @@
     \c qmake which files to process with \c uic. In this case, the
     \c calculatorform.ui file is used to create a \c ui_calculatorform.h file
-    that can be used by any file listed in the \c SOURCES declaration. To
-    ensure that \c qmake generates the \c ui_calculatorform.h file, we need to
-    include it in a file listed in \c SOURCES. Since we only have \c main.cpp,
-    we include it there:
+    that can be used by any file listed in the \c SOURCES declaration.
+
+    \note You can use Qt Creator to create the Calculator Form project. It
+    automatically generates the main.cpp, UI, and .pro files, which you can
+    then modify.
+
+    \section2 The Direct Approach
+
+    To use the direct approach, we include the \c ui_calculatorform.h file
+    directly in \c main.cpp:
 
     \snippet doc/src/snippets/uitools/calculatorform/main.cpp 0
-
-    This include is an additional check to ensure that we do not generate code
-    for UI files that are not used.
 
     The \c main function creates the calculator widget by constructing a
@@ -1852 +1858 @@
     and the connections between its signals and slots.
 
-    This approach provides a quick and easy way to use simple, self-contained
-    components in your applications, but many componens created with \QD will
+    The direct approach provides a quick and easy way to use simple, self-contained
+    components in your applications. However, componens created with \QD often
     require close integration with the rest of the application code. For
     instance, the \c CalculatorForm code provided above will compile and run,
     but the QSpinBox objects will not interact with the QLabel as we need a
     custom slot to carry out the add operation and display the result in the
-    QLabel. To achieve this, we need to subclass a standard Qt widget (known as
-    the single inheritance approach).
-
+    QLabel. To achieve this, we need to use the single inheritance approach.
 
     \section2 The Single Inheritance Approach
+
+    To use the single inheritance approach, we subclass a standard Qt widget and
+    include a private instance of the form's user interface object. This can take
+    the form of:
+
+    \list
+        \o A member variable
+        \o A pointer member variable
+    \endlist
+
+    \section3 Using a Member Variable
 
     In this approach, we subclass a Qt widget and set up the user interface
@@ -1869 +1884 @@
     standard system for making signal and slot connections between the user
     interface and other objects in your application.
+    The generated \c{Ui::CalculatorForm} structure is a member of the class.
 
     This approach is used in the \l{Calculator Form Example}{Calculator Form}
@@ -1908 +1924 @@
     forms, for example.
 
+    \section3 Using a Pointer Member Variable
+
+    Alternatively, the \c{Ui::CalculatorForm} structure can be made a pointer
+    member of the class. The header then looks as follows:
+
+    \code
+
+    namespace Ui {
+        class CalculatorForm;
+    }
+
+    class CalculatorForm : public QWidget
+    ...
+    virtual ~CalculatorForm();
+    ...
+    private:
+        Ui::CalculatorForm *ui;
+    ...
+
+    \endcode
+
+    The corresponding source file looks as follows:
+
+    \code
+    #include "ui_calculatorform.h"
+
+    CalculatorForm::CalculatorForm(QWidget *parent) :
+        QWidget(parent), ui(new Ui::CalculatorForm)
+    {
+        ui->setupUi(this);
+    }
+
+    CalculatorForm::~CalculatorForm()
+    {
+        delete ui;
+    }
+    \endcode
+
+    The advantage of this approach is that the user interface object can be
+    forward-declared, which means that we do not have to include the generated
+    \c ui_calculatorform.h file in the header. The form can then be changed without
+    recompiling the dependent source files. This is particularly important if the
+    class is subject to binary compatibility restrictions.
+
+    We generally recommend this approach for libraries and large applications.
+    For more information, see \l{Creating Shared Libraries}.
 
     \section2 The Multiple Inheritance Approach
@@ -1921 +1983 @@
 
     We need to include the header file that \c uic generates from the
-    \c calculatorform.ui file:
+    \c calculatorform.ui file, as follows:
 
     \snippet examples/uitools/multipleinheritance/calculatorform.h 0
@@ -1927 +1989 @@
     The class is defined in a similar way to the one used in the
     \l{The Single Inheritance Approach}{single inheritance approach}, except that
-    this time we inherit from \e{both} QWidget and \c{Ui::CalculatorForm}:
+    this time we inherit from \e{both} QWidget and \c{Ui::CalculatorForm},
+    as follows:
 
     \snippet examples/uitools/multipleinheritance/calculatorform.h 1
@@ -1946 +2009 @@
     \c{ui} prefix to access them.
 
-    Subclassing using multiple inheritance gives us more direct access to the
-    contents of the form, is slightly cleaner than the single inheritance
-    approach, but does not conveniently support composition of multiple user
-    interfaces.
-
+    \section2 Reacting to Language Changes
+
+    Qt notifies applications if the user interface language changes by sending an
+    event of the type QEvent::LanguageChange. To call the member function
+    \c retranslateUi() of the user interface object, we reimplement
+    \c QWidget::changeEvent() in the form class, as follows:
+
+    \code
+    void CalculatorForm::changeEvent(QEvent *e)
+    {
+        QWidget::changeEvent(e);
+        switch (e->type()) {
+        case QEvent::LanguageChange:
+            ui->retranslateUi(this);
+            break;
+        default:
+            break;
+       }
+    }
+    \endcode
 
     \section1 Run Time Form Processing
@@ -2777 +2855 @@
 
     \legalese
-    Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). \BR
+    Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). \BR
     Copyright (C) 2005 Bjoern Bergstroem