source: trunk/doc/src/examples/sipdialog.qdoc

Last change on this file was 846, checked in by Dmitry A. Kuminov, 14 years ago

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.
File size: 5.1 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4** All rights reserved.
5** Contact: Nokia Corporation (qt-info@nokia.com)
6**
7** This file is part of the documentation of the Qt Toolkit.
8**
9** $QT_BEGIN_LICENSE:FDL$
10** Commercial Usage
11** Licensees holding valid Qt Commercial licenses may use this file in
12** accordance with the Qt Commercial License Agreement provided with the
13** Software or, alternatively, in accordance with the terms contained in a
14** written agreement between you and Nokia.
15**
16** GNU Free Documentation License
17** Alternatively, this file may be used under the terms of the GNU Free
18** Documentation License version 1.3 as published by the Free Software
19** Foundation and appearing in the file included in the packaging of this
20** file.
21**
22** If you have questions regarding the use of this file, please contact
23** Nokia at qt-info@nokia.com.
24** $QT_END_LICENSE$
25**
26****************************************************************************/
27
28/*!
29 \example dialogs/sipdialog
30 \title SIP Dialog Example
31 \ingroup qtce
32
33 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*/
Note: See TracBrowser for help on using the repository browser.