summaryrefslogtreecommitdiffstats
path: root/examples/widgets/doc/sipdialog.qdoc
diff options
context:
space:
mode:
Diffstat (limited to 'examples/widgets/doc/sipdialog.qdoc')
-rw-r--r--examples/widgets/doc/sipdialog.qdoc127
1 files changed, 127 insertions, 0 deletions
diff --git a/examples/widgets/doc/sipdialog.qdoc b/examples/widgets/doc/sipdialog.qdoc
new file mode 100644
index 0000000000..b5f18cb4be
--- /dev/null
+++ b/examples/widgets/doc/sipdialog.qdoc
@@ -0,0 +1,127 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** 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.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+**
+** $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 \li \inlineimage sipdialog-closed.png
+ \li \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
+ \li \c{button}'s \l{QPushButton::pressed()}{pressed()} signal to
+ \l{QApplication}'s \l{QApplication::closeAllWindows()}
+ {closeAllWindows()} slot,
+ \li \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.
+*/