source: trunk/doc/src/geometry.qdoc@ 432

Last change on this file since 432 was 2, checked in by Dmitry A. Kuminov, 16 years ago

Initially imported qt-all-opensource-src-4.5.1 from Trolltech.
File size: 6.7 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4** Contact: Qt Software Information (qt-info@nokia.com)
5**
6** This file is part of the documentation of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial Usage
10** Licensees holding valid Qt Commercial licenses may use this file in
11** accordance with the Qt Commercial License Agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and Nokia.
14**
15** GNU Lesser General Public License Usage
16** Alternatively, this file may be used under the terms of the GNU Lesser
17** General Public License version 2.1 as published by the Free Software
18** Foundation and appearing in the file LICENSE.LGPL included in the
19** packaging of this file. Please review the following information to
20** ensure the GNU Lesser General Public License version 2.1 requirements
21** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
22**
23** In addition, as a special exception, Nokia gives you certain
24** additional rights. These rights are described in the Nokia Qt LGPL
25** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
26** package.
27**
28** GNU General Public License Usage
29** Alternatively, this file may be used under the terms of the GNU
30** General Public License version 3.0 as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL included in the
32** packaging of this file. Please review the following information to
33** ensure the GNU General Public License version 3.0 requirements will be
34** met: http://www.gnu.org/copyleft/gpl.html.
35**
36** If you are unsure which license is appropriate for your use, please
37** contact the sales department at qt-sales@nokia.com.
38** $QT_END_LICENSE$
39**
40****************************************************************************/
41
42/*!
43 \page geometry.html
44 \title Window Geometry
45 \ingroup architecture
46 \brief An overview of window geometry handling and management.
47
48 QWidget provides several functions that deal with a widget's
49 geometry. Some of these functions operate on the pure client area
50 (i.e. the window excluding the window frame), others include the
51 window frame. The differentiation is done in a way that covers the
52 most common usage transparently.
53
54 \list
55 \o \bold{Including the window frame:}
56 \l{QWidget::x()}{x()},
57 \l{QWidget::y()}{y()},
58 \l{QWidget::frameGeometry()}{frameGeometry()},
59 \l{QWidget::pos()}{pos()}, and
60 \l{QWidget::move()}{move()}.
61 \o \bold{Excluding the window frame:}
62 \l{QWidget::geometry()}{geometry()},
63 \l{QWidget::width()}{width()},
64 \l{QWidget::height()}{height()},
65 \l{QWidget::rect()}{rect()}, and
66 \l{QWidget::size()}{size()}.
67 \endlist
68
69 Note that the distinction only matters for decorated top-level
70 widgets. For all child widgets, the frame geometry is equal to the
71 widget's client geometry.
72
73 This diagram shows most of the functions in use:
74 \img geometry.png Geometry diagram
75
76 Topics:
77
78 \tableofcontents
79
80 \section1 X11 Peculiarities
81
82 On X11, a window does not have a frame until the window manager
83 decorates it. This happens asynchronously at some point in time
84 after calling QWidget::show() and the first paint event the
85 window receives, or it does not happen at all. Bear in mind that
86 X11 is policy-free (others call it flexible). Thus you cannot
87 make any safe assumption about the decoration frame your window
88 will get. Basic rule: There's always one user who uses a window
89 manager that breaks your assumption, and who will complain to
90 you.
91
92 Furthermore, a toolkit cannot simply place windows on the screen. All
93 Qt can do is to send certain hints to the window manager. The window
94 manager, a separate process, may either obey, ignore or misunderstand
95 them. Due to the partially unclear Inter-Client Communication
96 Conventions Manual (ICCCM), window placement is handled quite
97 differently in existing window managers.
98
99 X11 provides no standard or easy way to get the frame geometry
100 once the window is decorated. Qt solves this problem with nifty
101 heuristics and clever code that works on a wide range of window
102 managers that exist today. Don't be surprised if you find one
103 where QWidget::frameGeometry() returns wrong results though.
104
105 Nor does X11 provide a way to maximize a window.
106 QWidget::showMaximized() has to emulate the feature. Its result
107 depends on the result of QWidget::frameGeometry() and the
108 capability of the window manager to do proper window placement,
109 neither of which can be guaranteed.
110
111 \section1 Restoring a Window's Geometry
112
113 Since version 4.2, Qt provides functions that saves and restores a
114 window's geometry and state for you. QWidget::saveGeometry()
115 saves the window geometry and maximized/fullscreen state, while
116 QWidget::restoreGeometry() restores it. The restore function also
117 checks if the restored geometry is outside the available screen
118 geometry, and modifies it as appropriate if it is.
119
120 The rest of this document describes how to save and restore the
121 geometry using the geometry properties. On Windows, this is
122 basically storing the result of QWidget::geometry() and calling
123 QWidget::setGeometry() in the next session before calling
124 \l{QWidget::show()}{show()}. On X11, this won't work because an
125 invisible window doesn't have a frame yet. The window manager
126 will decorate the window later. When this happens, the window
127 shifts towards the bottom/right corner of the screen depending on
128 the size of the decoration frame. Although X provides a way to
129 avoid this shift, most window managers fail to implement this
130 feature.
131
132 A workaround is to call \l{QWidget::setGeometry()}{setGeometry()}
133 after \l{QWidget::show()}{show()}. This has the two disadvantages
134 that the widget appears at a wrong place for a millisecond
135 (results in flashing) and that currently only every second window
136 manager gets it right. A safer solution is to store both
137 \l{QWidget::pos()}{pos()} and \l{QWidget::size()}{size()} and to
138 restore the geometry using \l{QWidget::resize()} and
139 \l{QWidget::move()}{move()} before calling
140 \l{QWidget::show()}{show()}, as demonstrated in the following
141 code snippets (from the \l{mainwindows/application}{Application}
142 example):
143
144 \snippet examples/mainwindows/application/mainwindow.cpp 35
145 \codeline
146 \snippet examples/mainwindows/application/mainwindow.cpp 38
147
148 This method works on Windows, Mac OS X, and most X11 window
149 managers.
150*/
Note: See TracBrowser for help on using the repository browser.