From 774543a3336841df4a13d3e283af83cf4b53b966 Mon Sep 17 00:00:00 2001 From: Denis Dzyubenko Date: Wed, 19 Aug 2009 11:35:24 +0200 Subject: 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 --- doc/src/howtos/restoring-geometry.qdoc | 39 ++++++++++------------ .../snippets/code/src_gui_widgets_qmainwindow.cpp | 19 +++++++++++ src/gui/widgets/qmainwindow.cpp | 15 ++++++++- 3 files changed, 50 insertions(+), 23 deletions(-) create mode 100644 doc/src/snippets/code/src_gui_widgets_qmainwindow.cpp 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) { -- cgit v0.12