<?xml version="1.0" encoding="iso-8859-1"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <!-- /home/gvatteka/dev/qt-4.3/doc/src/geometry.qdoc --> <head> <title>Window Geometry</title> <link href="classic.css" rel="stylesheet" type="text/css" /> </head> <body> <h1 align="center">Window Geometry<br /><small></small></h1> <p><a href="gui/QWidget.html"><tt>QWidget</tt></a> 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.</p> <ul> <li><b>Including the window frame:</b> x(), y(), frameGeometry(), pos(), and move().</li> <li><b>Excluding the window frame:</b> geometry(), width(), height(), rect(), and size().</li> </ul> <p>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.</p> <p>This diagram shows most of the functions in use:</p> <p align="center"><img src="images/geometry.png" alt="Geometry diagram" /></p><p>Topics:</p> <ul><li><a href="#x11-peculiarities">X11 Peculiarities</a></li> <li><a href="#restoring-a-window-s-geometry">Restoring a Window's Geometry</a></li> </ul> <a name="x11-peculiarities"></a> <h3>X11 Peculiarities</h3> <p>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.</p> <p>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.</p> <p>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.</p> <p>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.</p> <a name="restoring-a-window-s-geometry"></a> <h3>Restoring a Window's Geometry</h3> <p>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.</p> <p>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 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.</p> <p>A workaround is to call setGeometry() after 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 pos() and size() and to restore the geometry using <tt>QWidget::resize</tt> and move() before calling show(), as demonstrated in the following code snippets (from the Application</tt> example):</p> <pre> void MainWindow::readSettings() { QSettings settings("Trolltech", "Application Example"); QPoint pos = settings.value("pos", QPoint(200, 200)).toPoint(); QSize size = settings.value("size", QSize(400, 400)).toSize(); resize(size); move(pos); } void MainWindow::writeSettings() { QSettings settings("Trolltech", "Application Example"); settings.setValue("pos", pos()); settings.setValue("size", size()); }</pre> <p>This method works on Windows, Mac OS X, and most X11 window managers.</p> <p /><address><hr /><div align="center"> <table width="100%" cellspacing="0" border="0"><tr class="address"> <td width="30%">Copyright © 2007 <a href="trolltech.html">Trolltech</a></td> <td width="40%" align="center"><a href="trademarks.html">Trademarks</a></td> <td width="30%" align="right"><div align="right">Qt Jambi </div></td> </tr></table></div></address></body> </html>