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 &amp; 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 */