doc/src/examples/sipdialog.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2015 The Qt Company Ltd.
   4 ** Contact: http://www.qt.io/licensing/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and The Qt Company. For licensing terms
  14 ** and conditions see http://www.qt.io/terms-conditions. For further
  15 ** information use the contact form at http://www.qt.io/contact-us.
  16 **
  17 ** GNU Free Documentation License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Free
  19 ** Documentation License version 1.3 as published by the Free Software
  20 ** Foundation and appearing in the file included in the packaging of
  21 ** this file.  Please review the following information to ensure
  22 ** the GNU Free Documentation License version 1.3 requirements
  23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \example dialogs/sipdialog
  30     \title SIP Dialog Example
  31     \ingroup qtce
  32
  33     \brief The SIP Dialog example shows how to create a dialog that is aware of
  34     the Windows Mobile SIP (Software Input Panel) and reacts to it.
  35
  36     \table
  37     \row \o \inlineimage sipdialog-closed.png
  38          \o \inlineimage sipdialog-opened.png
  39     \endtable
  40
  41     Sometimes it is necessary for a dialog to take the SIP into account,
  42     as the SIP may hide important input widgets. The SIP Dialog Example
  43     shows how a \c Dialog object, \c dialog, can be resized accordingly
  44     if the SIP is opened, by embedding the contents of \c dialog in a
  45     QScrollArea.
  46
  47     \section1 Dialog Class Definition
  48
  49     The \c Dialog class is a subclass of QDialog that implements a public
  50     slot, \c desktopResized(), and a public function, \c reactToSIP(). Also,
  51     it holds a private instance of QRect, \c desktopGeometry.
  52
  53     \snippet dialogs/sipdialog/dialog.h Dialog header
  54
  55     \section1 Dialog Class Implementation
  56
  57     In the constructor of \c Dialog, we start by obtaining the
  58     available geometry of the screen with
  59     \l{QDesktopWidget::availableGeometry()}{availableGeometry()}. The
  60     parameter used is \c 0 to indicate that we require the primary screen.
  61
  62     \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part1
  63
  64     We set the window's title to "SIP Dialog Example" and declare a QScrollArea
  65     object, \c scrollArea. Next we instantiate a QGroupBox, \c groupBox, with
  66     \c scrollArea as its parent. The title of \c groupBox is also set to
  67     "SIP Dialog Example". A QGridLayout object, \c gridLayout, is then used
  68     as \c{groupBox}'s layout.
  69
  70     We create a QLineEdit, a QLabel and a QPushButton and we set the
  71     \l{QWidget::setMinimumWidth()}{minimumWidth} property to 220 pixels,
  72     respectively.
  73
  74     \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part2
  75
  76     Also, all three widgets' text are set accordingly. The
  77     \l{QGridLayout::setVerticalSpacing()}{verticalSpacing} property of
  78     \c gridLayout is set based on the height of \c desktopGeometry. This
  79     is to adapt to the different form factors of Windows Mobile. Then, we
  80     add our widgets to the layout.
  81
  82     \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part3
  83
  84     The \c{scrollArea}'s widget is set to \c groupBox. We use a QHBoxLayout
  85     object, \c layout, to contain \c scrollArea. The \c{Dialog}'s layout
  86     is set to \c layout and the scroll area's horizontal scroll bar is turned
  87     off.
  88
  89     \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part4
  90
  91     The following signals are connected to their respective slots:
  92     \list
  93         \o \c{button}'s \l{QPushButton::pressed()}{pressed()} signal to
  94         \l{QApplication}'s \l{QApplication::closeAllWindows()}
  95         {closeAllWindows()} slot,
  96         \o \l{QDesktopWidget}'s \l{QDesktopWidget::workAreaResized()}
  97         {workAreaResized()} signal to \c{dialog}'s \c desktopResized() slot.
  98     \endlist
  99
 100     \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part5
 101
 102     The \c desktopResized() function accepts an integer, \a screen,
 103     corresponding to the screen's index. We only invoke \c reactToSIP()
 104     if \a screen is the primary screen (e.g. index = 0).
 105
 106     \snippet dialogs/sipdialog/dialog.cpp desktopResized() function
 107
 108     The \c reactToSIP() function resizes \c dialog accordingly if the
 109     desktop's available geometry changed vertically, as this change signifies
 110     that the SIP may have been opened or closed.
 111
 112     \snippet dialogs/sipdialog/dialog.cpp reactToSIP() function
 113
 114     If the height has decreased, we unset the maximized window state.
 115     Otherwise, we set the maximized window state. Lastly, we update
 116     \c desktopGeometry to the desktop's available geometry.
 117
 118     \section1 The \c main() function
 119
 120     The \c main() function for the SIP Dialog example instantiates \c Dialog
 121     and invokes its \l{QDialog::exec()}{exec()} function.
 122
 123     \snippet dialogs/sipdialog/main.cpp main() function
 124
 125     \note Although this example uses a dialog, the techniques used here apply to
 126     all top-level widgets respectively.
 127 */