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