summaryrefslogtreecommitdiffstats
path: root/doc/src/examples/sipdialog.qdoc
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src/examples/sipdialog.qdoc')
-rw-r--r--doc/src/examples/sipdialog.qdoc141
1 files changed, 141 insertions, 0 deletions
diff --git a/doc/src/examples/sipdialog.qdoc b/doc/src/examples/sipdialog.qdoc
new file mode 100644
index 0000000..817f5e2
--- /dev/null
+++ b/doc/src/examples/sipdialog.qdoc
@@ -0,0 +1,141 @@
+/****************************************************************************
+**
+** 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 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.
+*/