Initial import from the monolithic Qt.

This is the beginning of revision history for this module. If you
want to look at revision history older than this, please refer to the
Qt Git wiki for how to use Git history grafting. At the time of
writing, this wiki is located here:

http://qt.gitorious.org/qt/pages/GitIntroductionWithQt

If you have already performed the grafting and you don't see any
history beyond this commit, try running "git log" with the "--follow"
argument.

Branched from the monolithic repo, Qt master branch, at commit
896db169ea224deb96c59ce8af800d019de63f12

1 files changed, 127 insertions, 0 deletions

diff --git a/doc/src/examples/sipdialog.qdoc b/doc/src/examples/sipdialog.qdoc
new file mode 100644
index 0000000000..7c2a3eece6
--- /dev/null
+++ b/doc/src/examples/sipdialog.qdoc
@@ -0,0 +1,127 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 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:FDL$
+** 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 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
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example dialogs/sipdialog
+    \title SIP Dialog Example
+    \ingroup qtce
+
+    The SIP Dialog example shows how to create a dialog that is aware of 
+    the Windows Mobile SIP (Software Input Panel) and reacts to it.
+
+    \table
+    \row \o \inlineimage sipdialog-closed.png
+         \o \inlineimage sipdialog-opened.png
+    \endtable
+
+    Sometimes it is necessary for a dialog to take the SIP into account,
+    as the SIP may hide important input widgets. The SIP Dialog Example
+    shows how a \c Dialog object, \c dialog, can be resized accordingly
+    if the SIP is opened, by embedding the contents of \c dialog in a
+    QScrollArea.
+
+    \section1 Dialog Class Definition
+
+    The \c Dialog class is a subclass of QDialog that implements a public
+    slot, \c desktopResized(), and a public function, \c reactToSIP(). Also,
+    it holds a private instance of QRect, \c desktopGeometry.
+
+    \snippet dialogs/sipdialog/dialog.h Dialog header
+
+    \section1 Dialog Class Implementation
+
+    In the constructor of \c Dialog, we start by obtaining the
+    available geometry of the screen with
+    \l{QDesktopWidget::availableGeometry()}{availableGeometry()}. The
+    parameter used is \c 0 to indicate that we require the primary screen.
+
+    \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part1
+
+    We set the window's title to "SIP Dialog Example" and declare a QScrollArea
+    object, \c scrollArea. Next we instantiate a QGroupBox, \c groupBox, with
+    \c scrollArea as its parent. The title of \c groupBox is also set to
+    "SIP Dialog Example". A QGridLayout object, \c gridLayout, is then used
+    as \c{groupBox}'s layout.
+
+    We create a QLineEdit, a QLabel and a QPushButton and we set the
+    \l{QWidget::setMinimumWidth()}{minimumWidth} property to 220 pixels,
+    respectively.
+
+    \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part2
+
+    Also, all three widgets' text are set accordingly. The
+    \l{QGridLayout::setVerticalSpacing()}{verticalSpacing} property of
+    \c gridLayout is set based on the height of \c desktopGeometry. This
+    is to adapt to the different form factors of Windows Mobile. Then, we
+    add our widgets to the layout.
+
+    \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part3
+
+    The \c{scrollArea}'s widget is set to \c groupBox. We use a QHBoxLayout
+    object, \c layout, to contain \c scrollArea. The \c{Dialog}'s layout
+    is set to \c layout and the scroll area's horizontal scroll bar is turned
+    off.
+
+    \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part4
+
+    The following signals are connected to their respective slots:
+    \list
+        \o \c{button}'s \l{QPushButton::pressed()}{pressed()} signal to
+        \l{QApplication}'s \l{QApplication::closeAllWindows()}
+        {closeAllWindows()} slot,
+        \o \l{QDesktopWidget}'s \l{QDesktopWidget::workAreaResized()}
+        {workAreaResized()} signal to \c{dialog}'s \c desktopResized() slot.
+    \endlist
+
+    \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part5
+
+    The \c desktopResized() function accepts an integer, \a screen,
+    corresponding to the screen's index. We only invoke \c reactToSIP()
+    if \a screen is the primary screen (e.g. index = 0).
+
+    \snippet dialogs/sipdialog/dialog.cpp desktopResized() function
+
+    The \c reactToSIP() function resizes \c dialog accordingly if the
+    desktop's available geometry changed vertically, as this change signifies
+    that the SIP may have been opened or closed.
+
+    \snippet dialogs/sipdialog/dialog.cpp reactToSIP() function
+
+    If the height has decreased, we unset the maximized window state.
+    Otherwise, we set the maximized window state. Lastly, we update
+    \c desktopGeometry to the desktop's available geometry.
+
+    \section1 The \c main() function
+
+    The \c main() function for the SIP Dialog example instantiates \c Dialog
+    and invokes its \l{QDialog::exec()}{exec()} function.
+
+    \snippet dialogs/sipdialog/main.cpp main() function
+
+    \note Although this example uses a dialog, the techniques used here apply to
+    all top-level widgets respectively.
+*/