Update copyright headers
[qt:qt.git] / doc / src / howtos / restoring-geometry.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     \page restoring-geometry.html
30     \title Restoring a Window's Geometry
31     \brief How to save & restore window geometry.
32     \ingroup best-practices
33
34     This document describes how to save and restore a \l{Window
35     Geometry}{window's geometry} using the geometry properties. On
36     Windows, this is basically storing the result of
37     QWidget::geometry() and calling QWidget::setGeometry() in the next
38     session before calling \l{QWidget::show()}{show()}.
39
40     On X11, this might not work because an invisible window does not
41     have a frame yet. The window manager will decorate the window
42     later.  When this happens, the window shifts towards the
43     bottom/right corner of the screen depending on the size of the
44     decoration frame.  Although X provides a way to avoid this shift,
45     some window managers fail to implement this feature.
46
47     Since version 4.2, Qt provides functions that saves and restores a
48     window's geometry and state for you. QWidget::saveGeometry()
49     saves the window geometry and maximized/fullscreen state, while
50     QWidget::restoreGeometry() restores it. The restore function also
51     checks if the restored geometry is outside the available screen
52     geometry, and modifies it as appropriate if it is:
53
54     \snippet doc/src/snippets/code/src_gui_widgets_qmainwindow.cpp 0
55     \snippet doc/src/snippets/code/src_gui_widgets_qmainwindow.cpp 1
56
57     If those functions are not available or cannot be used, then a
58     workaround is to call \l{QWidget::setGeometry()}{setGeometry()}
59     after \l{QWidget::show()}{show()}. This has the two disadvantages
60     that the widget appears at a wrong place for a millisecond
61     (results in flashing) and that currently only every second window
62     manager gets it right. A safer solution is to store both
63     \l{QWidget::pos()}{pos()} and \l{QWidget::size()}{size()} and to
64     restore the geometry using \l{QWidget::resize()} and
65     \l{QWidget::move()}{move()} before calling
66     \l{QWidget::show()}{show()}, as demonstrated in the
67     \l{mainwindows/application}{Application} example.
68 */