Improved the documentation of saving and restoring window geometry.

Mentioned in the doc that the preferred way to save/restore a geometry
of a QMainWindow is to use both saveGeometry() and saveState().

Reviewed-by: Kavindra Devi Palaraja

3 files changed, 50 insertions, 23 deletions

diff --git a/doc/src/howtos/restoring-geometry.qdoc b/doc/src/howtos/restoring-geometry.qdoc
index c9e6f4f..cc6f3e1 100644
--- a/doc/src/howtos/restoring-geometry.qdoc
+++ b/doc/src/howtos/restoring-geometry.qdoc
@@ -45,25 +45,28 @@
 
     \ingroup best-practices
 
-	This document describes how to save and restore a window's
-    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()}.
+    This document describes how to save and restore a \l{Window
+    Geometry}{window's 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.
+    On X11, this might not work because an invisible window does not
+    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,
+    some window managers fail to implement this feature.
 
     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.
+    geometry, and modifies it as appropriate if it is:
+
+    \snippet doc/src/snippets/code/src_gui_widgets_qmainwindow.cpp 0
+    \snippet doc/src/snippets/code/src_gui_widgets_qmainwindow.cpp 1
 
     If those functions are not available or cannot be used, then a
     workaround is to call \l{QWidget::setGeometry()}{setGeometry()}
@@ -74,14 +77,6 @@
     \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.
+    \l{QWidget::show()}{show()}, as demonstrated in the
+    \l{mainwindows/application}{Application} example.
 */
diff --git a/doc/src/snippets/code/src_gui_widgets_qmainwindow.cpp b/doc/src/snippets/code/src_gui_widgets_qmainwindow.cpp
new file mode 100644
index 0000000..0e4040a
--- /dev/null
+++ b/doc/src/snippets/code/src_gui_widgets_qmainwindow.cpp
@@ -0,0 +1,19 @@
+//! [0]
+void MyMainWindow::closeEvent(QCloseEvent *event)
+{
+    QSettings settings("MyCompany", "MyApp");
+    settings.setValue("geometry", saveGeometry());
+    settings.setValue("windowState", saveState());
+    QMainWindow::closeEvent(event);
+}
+//! [0]
+
+
+//! [1]
+void MainWindow::readSettings()
+{
+    QSettings settings("MyCompany", "MyApp");
+    restoreGeometry(settings.value("myWidget/geometry").toByteArray());
+    restoreState(settings.value("myWidget/windowState").toByteArray());
+}
+//! [1]
diff --git a/src/gui/widgets/qmainwindow.cpp b/src/gui/widgets/qmainwindow.cpp
index e19961f..ebf01d4 100644
--- a/src/gui/widgets/qmainwindow.cpp
+++ b/src/gui/widgets/qmainwindow.cpp
@@ -1027,6 +1027,8 @@ void QMainWindow::addDockWidget(Qt::DockWidgetArea area, QDockWidget *dockwidget
     Restores the state of \a dockwidget if it is created after the call
     to restoreState(). Returns true if the state was restored; otherwise
     returns false.
+
+    \sa restoreState(), saveState()
 */
 
 bool QMainWindow::restoreDockWidget(QDockWidget *dockwidget)
@@ -1158,6 +1160,11 @@ Qt::DockWidgetArea QMainWindow::dockWidgetArea(QDockWidget *dockwidget) const
     To restore the saved state, pass the return value and \a version
     number to restoreState().
 
+    To save the geometry when the window closes, you can
+    implement a close event like this:
+
+    \snippet doc/src/snippets/code/src_gui_widgets_qmainwindow.cpp 0
+
     \sa restoreState(), QWidget::saveGeometry(), QWidget::restoreGeometry()
 */
 QByteArray QMainWindow::saveState(int version) const
@@ -1177,7 +1184,13 @@ QByteArray QMainWindow::saveState(int version) const
     unchanged, and this function returns \c false; otherwise, the state
     is restored, and this function returns \c true.
 
-    \sa saveState(), QWidget::saveGeometry(), QWidget::restoreGeometry()
+    To restore geometry saved using QSettings, you can use code like
+    this:
+
+    \snippet doc/src/snippets/code/src_gui_widgets_qmainwindow.cpp 1
+
+    \sa saveState(), QWidget::saveGeometry(),
+    QWidget::restoreGeometry(), restoreDockWidget()
 */
 bool QMainWindow::restoreState(const QByteArray &state, int version)
 {