/****************************************************************************
**
** Copyright (C) 2007-2008 Trolltech ASA. All rights reserved.
**
** This file is part of the documentation of the Qt Toolkit.
**
** This file may be used under the terms of the GNU General Public
** License versions 2.0 or 3.0 as published by the Free Software
** Foundation and appearing in the files LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file.  Alternatively you may (at
** your option) use any later version of the GNU General Public
** License if such license has been publicly approved by Trolltech ASA
** (or its successors, if any) and the KDE Free Qt Foundation. In
** addition, as a special exception, Trolltech gives you certain
** additional rights. These rights are described in the Trolltech GPL
** Exception version 1.2, which can be found at
** http://www.trolltech.com/products/qt/gplexception/ and in the file
** GPL_EXCEPTION.txt in this package.
**
** Please review the following information to ensure GNU General
** Public Licensing requirements will be met:
** http://trolltech.com/products/qt/licenses/licensing/opensource/. If
** you are unsure which license is appropriate for your use, please
** review the following information:
** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
** or contact the sales department at sales@trolltech.com.
**
** In addition, as a special exception, Trolltech, as the sole
** copyright holder for Qt Designer, grants users of the Qt/Eclipse
** Integration plug-in the right for the Qt/Eclipse Integration to
** link to functionality provided by Qt Designer and its related
** libraries.
**
** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
** A PARTICULAR PURPOSE. Trolltech reserves all rights not expressly
** granted herein.
**
** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
**
****************************************************************************/

/*!
    \example dialogs/sipdialog
    \title SIP Dialog Example

    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.
*/
