<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- mainwindow.qdoc -->
<title>Qt 4.8: Window and Dialog Widgets</title>
<link rel="stylesheet" type="text/css" href="style/style.css" />
<script src="scripts/jquery.js" type="text/javascript"></script>
<script src="scripts/functions.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="style/superfish.css" />
<link rel="stylesheet" type="text/css" href="style/narrow.css" />
<!--[if IE]>
<meta name="MSSmartTagsPreventParsing" content="true">
<meta http-equiv="imagetoolbar" content="no">
<![endif]-->
<!--[if lt IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie6.css">
<![endif]-->
<!--[if IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie7.css">
<![endif]-->
<!--[if IE 8]>
<link rel="stylesheet" type="text/css" href="style/style_ie8.css">
<![endif]-->
<script src="scripts/superfish.js" type="text/javascript"></script>
<script src="scripts/narrow.js" type="text/javascript"></script>
</head>
<body class="" onload="CheckEmptyAndLoadList();">
<div class="header" id="qtdocheader">
<div class="content">
<div id="nav-logo">
<a href="index.html">Home</a></div>
<a href="index.html" class="qtref"><span>Qt Reference Documentation</span></a>
<div id="narrowsearch"></div>
<div id="nav-topright">
<ul>
<li class="nav-topright-home"><a href="http://qt.digia.com/">Qt HOME</a></li>
<li class="nav-topright-dev"><a href="http://qt-project.org/">DEV</a></li>
<li class="nav-topright-doc nav-topright-doc-active"><a href="http://qt-project.org/doc/">
DOC</a></li>
<li class="nav-topright-blog"><a href="http://blog.qt.digia.com/">BLOG</a></li>
</ul>
</div>
<div id="shortCut">
<ul>
<li class="shortCut-topleft-inactive"><span><a href="index.html">Qt 4.8</a></span></li>
<li class="shortCut-topleft-active"><a href="http://qt-project.org/doc/">ALL VERSIONS </a></li>
</ul>
</div>
<ul class="sf-menu" id="narrowmenu">
<li><a href="#">API Lookup</a>
<ul>
<li><a href="classes.html">Class index</a></li>
<li><a href="functions.html">Function index</a></li>
<li><a href="modules.html">Modules</a></li>
<li><a href="namespaces.html">Namespaces</a></li>
<li><a href="qtglobal.html">Global Declarations</a></li>
<li><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</li>
<li><a href="#">Qt Topics</a>
<ul>
<li><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li><a href="supported-platforms.html">Supported Platforms</a></li>
<li><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</li>
<li><a href="#">Examples</a>
<ul>
<li><a href="all-examples.html">Examples</a></li>
<li><a href="tutorials.html">Tutorials</a></li>
<li><a href="demos.html">Demos</a></li>
<li><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="wrapper">
<div class="hd">
<span></span>
</div>
<div class="bd group">
<div class="sidebar">
<div class="searchlabel">
Search index:</div>
<div class="search" id="sidebarsearch">
<form id="qtdocsearch" action="" onsubmit="return false;">
<fieldset>
<input type="text" name="searchstring" id="pageType" value="" />
<div id="resultdialog">
<a href="#" id="resultclose">Close</a>
<p id="resultlinks" class="all"><a href="#" id="showallresults">All</a> | <a href="#" id="showapiresults">API</a> | <a href="#" id="showarticleresults">Articles</a> | <a href="#" id="showexampleresults">Examples</a></p>
<p id="searchcount" class="all"><span id="resultcount"></span><span id="apicount"></span><span id="articlecount"></span><span id="examplecount"></span> results:</p>
<ul id="resultlist" class="all">
</ul>
</div>
</fieldset>
</form>
</div>
<div class="box first bottombar" id="lookup">
<h2 title="API Lookup"><span></span>
API Lookup</h2>
<div id="list001" class="list">
<ul id="ul001" >
<li class="defaultLink"><a href="classes.html">Class index</a></li>
<li class="defaultLink"><a href="functions.html">Function index</a></li>
<li class="defaultLink"><a href="modules.html">Modules</a></li>
<li class="defaultLink"><a href="namespaces.html">Namespaces</a></li>
<li class="defaultLink"><a href="qtglobal.html">Global Declarations</a></li>
<li class="defaultLink"><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</div>
</div>
<div class="box bottombar" id="topics">
<h2 title="Qt Topics"><span></span>
Qt Topics</h2>
<div id="list002" class="list">
<ul id="ul002" >
<li class="defaultLink"><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li class="defaultLink"><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li class="defaultLink"><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li class="defaultLink"><a href="supported-platforms.html">Supported Platforms</a></li>
<li class="defaultLink"><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li class="defaultLink"><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</div>
</div>
<div class="box" id="examples">
<h2 title="Examples"><span></span>
Examples</h2>
<div id="list003" class="list">
<ul id="ul003">
<li class="defaultLink"><a href="all-examples.html">Examples</a></li>
<li class="defaultLink"><a href="tutorials.html">Tutorials</a></li>
<li class="defaultLink"><a href="demos.html">Demos</a></li>
<li class="defaultLink"><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</div>
</div>
</div>
<div class="wrap">
<div class="toolbar">
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li>Window and Dialog Widgets</li>
</ul>
</div>
<div class="toolbuttons toolblock">
<ul>
<li id="smallA" class="t_button">A</li>
<li id="medA" class="t_button active">A</li>
<li id="bigA" class="t_button">A</li>
<li id="print" class="t_button"><a href="javascript:this.print();">
<span>Print</span></a></li>
</ul>
</div>
</div>
<div class="content mainContent">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#primary-and-secondary-windows">Primary and Secondary Windows</a></li>
<li class="level1"><a href="#main-windows-and-dialogs">Main Windows and Dialogs</a></li>
<li class="level1"><a href="#window-geometry">Window Geometry</a></li>
<li class="level2"><a href="#x11-peculiarities">X11 Peculiarities</a></li>
<li class="level2"><a href="#symbian-peculiarities">Symbian Peculiarities</a></li>
</ul>
</div>
<h1 class="title">Window and Dialog Widgets</h1>
<span class="subtitle"></span>
<!-- $$$application-windows.html-description -->
<div class="descr"> <a name="details"></a>
<p>A <a href="widgets-tutorial.html">widget</a> that is not embedded in a parent widget is called a window. (Usually, windows have a frame and a title bar, although it is also possible to create windows without such decoration using suitable window flags). In Qt, <a href="qmainwindow.html">QMainWindow</a> and the various subclasses of <a href="qdialog.html">QDialog</a> are the most common window types.</p>
<p>In applications, windows provide the screen space upon which the user interface is built. Windows separate applications visually from each other and usually provide a window decoration that allows the user to resize and position the applications according to his preferences. Windows are typically integrated into the desktop environment and to some degree managed by the window management system that the desktop environment provides. For instance, selected windows of an application are represented in the task bar.</p>
<a name="primary-and-secondary-windows"></a>
<h2>Primary and Secondary Windows</h2>
<p>Any <a href="qwidget.html">QWidget</a> that has no parent will become a window, and will on most platforms be listed in the desktop's task bar. This is usually only wanted for one window in the application, the <i>primary window</i>.</p>
<p>In addition, a <a href="qwidget.html">QWidget</a> that has a parent can become a window by setting the <a href="qt.html#WindowType-enum">Qt::WA_Window</a> flag. Depending on the window management system such <i>secondary windows</i> are usually stacked on top of their respective parent window, and not have a task bar entry of their own.</p>
<p>The <a href="qmainwindow.html">QMainWindow</a> and the <a href="qdialog.html">QDialog</a> classes set the Qt::WA_Window flag in their constructor, as they are designed to be used as windows and provide facilities that are not wanted for child widgets.</p>
<a name="main-windows-and-dialogs"></a>
<h2>Main Windows and Dialogs</h2>
<p>The <a href="mainwindow.html">Application Main Window</a> provides the framework for building the application's main user interface, and are created by subclassing <a href="qmainwindow.html">QMainWindow</a>. <a href="qmainwindow.html">QMainWindow</a> has its own layout to which you can add a <a href="qmenubar.html">menu bar</a>, <a href="qtoolbar.html">tool bars</a>, <a href="qdockwidget.html">dockable widgets</a> and a <a href="qstatusbar.html">status bar</a>. The center area can be occupied by any kind of <a href="qwidget.html">QWidget</a>.</p>
<p><a href="dialogs.html">Dialog Windows</a> are used as secondary windows that present the user with options and choices. Dialogs are created by subclassing <a href="qdialog.html">QDialog</a> and using <a href="widgets-and-layouts.html">widgets and layouts</a> to implement the user interface. In addition, Qt provides a number of ready-made standard dialogs that can be used for standard tasks like file or font selection.</p>
<p>Both main windows and dialogs can be created with <i>Qt Designer</i>, Qt's visual design tool. Using <i>Qt Designer</i> is a lot faster than hand-coding, and makes it easy to test different design ideas. Creating designs visually and reading the code generated by <a href="uic.html#uic">uic</a> is a great way to learn Qt!</p>
<a name="window-geometry"></a><a name="window-geometry"></a>
<h2>Window Geometry</h2>
<p><a href="qwidget.html">QWidget</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> <a href="qwidget.html#x-prop">x()</a>, <a href="qwidget.html#y-prop">y()</a>, <a href="qwidget.html#frameGeometry-prop">frameGeometry()</a>, <a href="qwidget.html#pos-prop">pos()</a>, and <a href="qwidget.html#pos-prop">move()</a>.</li>
<li><b>Excluding the window frame:</b> <a href="qwidget.html#geometry-prop">geometry()</a>, <a href="qwidget.html#width-prop">width()</a>, <a href="qwidget.html#height-prop">height()</a>, <a href="qwidget.html#rect-prop">rect()</a>, and <a href="qwidget.html#size-prop">size()</a>.</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 class="centerAlign"><img src="images/geometry.png" alt="Geometry diagram" /></p><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 <a href="qwidget.html#show">QWidget::show</a>() 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 <a href="qwidget.html#frameGeometry-prop">QWidget::frameGeometry</a>() returns wrong results though.</p>
<p>Nor does X11 provide a way to maximize a window. <a href="qwidget.html#showMaximized">QWidget::showMaximized</a>() has to emulate the feature. Its result depends on the result of <a href="qwidget.html#frameGeometry-prop">QWidget::frameGeometry</a>() and the capability of the window manager to do proper window placement, neither of which can be guaranteed.</p>
<a name="symbian-peculiarities"></a>
<h3>Symbian Peculiarities</h3>
<p>On Symbian, the status pane and softkeys are not created until after <a href="qwidget.html#show">QWidget::show</a>() is called for the main window of the application. This means that at the time when the application main window gets the show event, the application main window width() and height() methods still return full screen width and height instead of the client area width and height as expected. The correct place to get the main window size is the resize event handler of the main window, as the resize event will be sent each time the client area of the window changes.</p>
</div>
<!-- @@@application-windows.html -->
</div>
</div>
</div>
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2015 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.</p>
<br />
<p>
The documentation provided herein is licensed under the terms of the
<a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation
License version 1.3</a> as published by the Free Software Foundation.</p>
<p>
Documentation sources may be obtained from <a href="http://www.qt-project.org">
www.qt-project.org</a>.</p>
<br />
<p>
Qt and respective logos are trademarks of The Qt Company Ltd
in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. <a title="Privacy Policy"
href="http://en.gitorious.org/privacy_policy/">Privacy Policy</a></p>
</div>
<script src="scripts/functions.js" type="text/javascript"></script>
</body>
</html>
