Long live Qt!

1 files changed, 133 insertions, 0 deletions

diff --git a/doc/src/examples/calculatorbuilder.qdoc b/doc/src/examples/calculatorbuilder.qdoc
new file mode 100644
index 0000000..c63267e
--- /dev/null
+++ b/doc/src/examples/calculatorbuilder.qdoc
@@ -0,0 +1,133 @@
+/****************************************************************************
+**
+** 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$
+**
+****************************************************************************/
+
+/*!
+    \example designer/calculatorbuilder
+    \title Calculator Builder Example
+
+    The Calculator Builder example shows how to create a user interface from
+    a \QD form at run-time, using the QUiLoader class.
+
+    \image calculatorbuilder-example.png
+
+    We use the form created in the \l{designer/calculatorform}{Calculator Form}
+    example to show that the same user interface can be generated when the
+    application is executed or defined when the application is built.
+
+    \section1 Preparation
+
+    The \l{designer/calculatorform}{Calculator Form} example defines a user
+    interface that we can use without modification. In this example, we use a
+    \l{The Qt Resource System}{resource file} to contain the \c{calculatorform.ui}
+    file created in the previous example, but it could be stored on disk instead.
+
+    To generate a form at run time, we need to link the example against the
+    \c QtUiTools module library. The project file we use contains all the
+    necessary information to do this:
+
+    \snippet examples/designer/calculatorbuilder/calculatorbuilder.pro 0
+
+    All the other necessary files are declared as usual.
+
+    \section1 CalculatorForm Class Definition
+
+    The \c CalculatorForm class defines the widget used to host the form's
+    user interface:
+
+    \snippet examples/designer/calculatorbuilder/calculatorform.h 0
+
+    Note that we do not need to include a header file to describe the user
+    interface. We only define two public slots, using the auto-connection
+    naming convention required by \c uic, and declare private variables
+    that we will use to access widgets provided by the form after they are
+    constructed.
+
+    \section1 CalculatorForm Class Implementation
+
+    We will need to use the QUiLoader class that is provided by the
+    \c libQtUiTools library, so we first ensure that we include the header
+    file for the module:
+
+    \snippet examples/designer/calculatorbuilder/calculatorform.cpp 0
+
+    The constructor uses a form loader object to construct the user
+    interface that we retrieve, via a QFile object, from the example's
+    resources:
+
+    \snippet examples/designer/calculatorbuilder/calculatorform.cpp 1
+
+    By including the user interface in the example's resources, we ensure
+    that it will be present when the example is run. The \c{loader.load()}
+    function takes the user interface description contained in the file
+    and constructs the form widget as a child widget of the \c{CalculatorForm}.
+
+    We are interested in three widgets in the generated user interface:
+    two spin boxes and a label. For convenience, we retrieve pointers to
+    these widgets from the widget that was constructed by the \c FormBuilder,
+    and we record them for later use. The \c qFindChild() template function
+    allows us to query widgets in order to find named child widgets.
+
+    \snippet examples/designer/calculatorbuilder/calculatorform.cpp 2
+
+    The widgets created by the form loader need to be connected to the
+    specially-named slots in the \c CalculatorForm object. We use Qt's
+    meta-object system to enable these connections:
+
+    \snippet examples/designer/calculatorbuilder/calculatorform.cpp 3
+
+    The form widget is added to a layout, and the window title is set:
+
+    \snippet examples/designer/calculatorbuilder/calculatorform.cpp 4
+
+    The two slots that modify widgets provided by the form are defined
+    in a similar way to those in the \l{designer/calculatorform}{Calculator
+    Form} example, except that we read the values from the spin boxes and
+    write the result to the output widget via the pointers we recorded in
+    the constructor:
+
+    \snippet examples/designer/calculatorbuilder/calculatorform.cpp 5
+    \codeline
+    \snippet examples/designer/calculatorbuilder/calculatorform.cpp 7
+
+    The advantage of this approach is that we can replace the form when the
+    application is run, but we can still manipulate the widgets it contains
+    as long as they are given appropriate names.
+*/