doc/src/windows-and-dialogs/mainwindow.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:FDL$
  10 ** GNU Free Documentation License
  11 ** Alternatively, this file may be used under the terms of the GNU Free
  12 ** Documentation License version 1.3 as published by the Free Software
  13 ** Foundation and appearing in the file included in the packaging of
  14 ** this file.
  15 **
  16 ** Other Usage
  17 ** Alternatively, this file may be used in accordance with the terms
  18 ** and conditions contained in a signed written agreement between you
  19 ** and Nokia.
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \group mainwindow-classes
  30     \title Main Window and Related Classes
  31 */
  32
  33 /*!
  34     \page application-windows.html
  35     \title Window and Dialog Widgets
  36     \brief Windows and Dialogs in Qt.
  37     \ingroup qt-gui-concepts
  38
  39     A \l{Widgets Tutorial}{widget} that is not embedded in a parent widget is called a window.
  40     (Usually, windows have a frame and a title bar, although it is also possible to create
  41     windows without such decoration using suitable window flags). In Qt, QMainWindow
  42     and the various subclasses of QDialog are the most common window types.
  43
  44     In applications, windows provide the screen space upon which the user
  45     interface is built. Windows separate applications visually from each other
  46     and usually provide a window decoration that allows the user to resize and
  47     position the applications according to his preferences. Windows are typically
  48     integrated into the desktop environment and to some degree managed by the
  49     window management system that the desktop environment provides. For instance,
  50     selected windows of an application are represented in the task bar.
  51
  52     \section1 Primary and Secondary Windows
  53
  54     Any QWidget that has no parent will become a window, and will on most platforms
  55     be listed in the desktop's task bar. This is usually only wanted for one
  56     window in the application, the \e{primary window}.
  57
  58     In addition, a QWidget that has a parent can become a window by setting the
  59     \l{Qt::WindowType}{Qt::WA_Window} flag. Depending on the window management system
  60     such \e{secondary windows} are usually stacked on top of their respective parent
  61     window, and not have a task bar entry of their own.
  62
  63     The QMainWindow and the QDialog classes set the Qt::WA_Window flag in their
  64     constructor, as they are designed to be used as windows and provide facilities
  65     that are not wanted for child widgets.
  66
  67     \section1 Main Windows and Dialogs
  68
  69     The \l{Application Main Window} provides the framework for building the
  70     application's main user interface, and are created by subclassing QMainWindow.
  71     QMainWindow has its own layout to which you can add a \l{QMenuBar}{menu bar},
  72     \l{QToolBar}{tool bars}, \l{QDockWidget}{dockable widgets} and a
  73     \l{QStatusBar}{status bar}. The center area can be occupied by any kind of
  74     QWidget.
  75
  76     \l{Dialog Windows} are used as secondary windows that present the user with
  77     options and choices. Dialogs are created by subclassing QDialog and using
  78     \l{Widgets and Layouts}{widgets and layouts} to implement the user interface.
  79     In addition, Qt provides a number of ready-made standard dialogs that can be
  80     used for standard tasks like file or font selection.
  81
  82     Both main windows and dialogs can be created with \QD, Qt's visual design tool.
  83     Using \QD is a lot faster than hand-coding, and makes it easy to test different
  84     design ideas. Creating designs visually and reading the code generated by
  85     \l{uic} is a great way to learn Qt!
  86
  87     \keyword window geometry
  88     \section1 Window Geometry
  89
  90     QWidget provides several functions that deal with a widget's
  91     geometry. Some of these functions operate on the pure client area
  92     (i.e. the window excluding the window frame), others include the
  93     window frame. The differentiation is done in a way that covers the
  94     most common usage transparently.
  95
  96     \list
  97     \o \bold{Including the window frame:}
  98         \l{QWidget::x()}{x()},
  99         \l{QWidget::y()}{y()},
 100         \l{QWidget::frameGeometry()}{frameGeometry()},
 101         \l{QWidget::pos()}{pos()}, and
 102         \l{QWidget::move()}{move()}.
 103     \o \bold{Excluding the window frame:}
 104         \l{QWidget::geometry()}{geometry()},
 105         \l{QWidget::width()}{width()},
 106         \l{QWidget::height()}{height()},
 107         \l{QWidget::rect()}{rect()}, and
 108         \l{QWidget::size()}{size()}.
 109     \endlist
 110
 111     Note that the distinction only matters for decorated top-level
 112     widgets. For all child widgets, the frame geometry is equal to the
 113     widget's client geometry.
 114
 115     This diagram shows most of the functions in use:
 116     \img geometry.png Geometry diagram
 117
 118     \section2 X11 Peculiarities
 119
 120     On X11, a window does not have a frame until the window manager
 121     decorates it. This happens asynchronously at some point in time
 122     after calling QWidget::show() and the first paint event the
 123     window receives, or it does not happen at all. Bear in mind that
 124     X11 is policy-free (others call it flexible). Thus you cannot
 125     make any safe assumption about the decoration frame your window
 126     will get. Basic rule: There's always one user who uses a window
 127     manager that breaks your assumption, and who will complain to
 128     you.
 129
 130     Furthermore, a toolkit cannot simply place windows on the screen. All
 131     Qt can do is to send certain hints to the window manager. The window
 132     manager, a separate process, may either obey, ignore or misunderstand
 133     them. Due to the partially unclear Inter-Client Communication
 134     Conventions Manual (ICCCM), window placement is handled quite
 135     differently in existing window managers.
 136
 137     X11 provides no standard or easy way to get the frame geometry
 138     once the window is decorated. Qt solves this problem with nifty
 139     heuristics and clever code that works on a wide range of window
 140     managers that exist today. Don't be surprised if you find one
 141     where QWidget::frameGeometry() returns wrong results though.
 142
 143     Nor does X11 provide a way to maximize a window.
 144     QWidget::showMaximized() has to emulate the feature. Its result
 145     depends on the result of QWidget::frameGeometry() and the
 146     capability of the window manager to do proper window placement,
 147     neither of which can be guaranteed.
 148 */
 149
 150 /*!
 151     \page mainwindow.html
 152     \title Application Main Window
 153     \ingroup qt-gui-concepts
 154     \brief Creating the application window.
 155
 156     \tableofcontents
 157
 158     \section1 Overview of the Main Window Classes
 159
 160     These classes provide everything you need for a typical modern main
 161     application window, like the main window itself, menu and tool bars,
 162     a status bar, etc.
 163
 164     \annotatedlist mainwindow-classes
 165
 166     \section1 The Main Window Classes
 167
 168     Qt 4 provides the following classes for managing main windows and
 169     associated user interface components:
 170
 171     \list
 172     \o QMainWindow remains the central class around which applications
 173        can be built. The interface to this class has been simplified, and
 174        much of the functionality previously included in this class is now
 175        present in the companion QDockWidget and QToolBar classes.
 176
 177     \o QDockWidget provides a widget that can be used to create
 178        detachable tool palettes or helper windows. Dock widgets keep track
 179        of their own properties, and they can be moved, closed, and floated
 180        as external windows.
 181
 182     \o QToolBar provides a generic toolbar widget that can hold a
 183        number of different action-related widgets, such as buttons,
 184        drop-down menus, comboboxes, and spin boxes. The emphasis on a
 185        unified action model in Qt 4 means that toolbars cooperate well
 186        with menus and keyboard shortcuts.
 187     \endlist
 188
 189     \section1 Example Code
 190
 191     Using QMainWindow is straightforward. Generally, we subclass
 192     QMainWindow and set up menus, toolbars, and dock widgets inside
 193     the QMainWindow constructor.
 194
 195     To add a menu bar to the main window, we simply create the menus, and
 196     add them to the main window's menu bar. Note that the
 197     QMainWindow::menuBar() function will automatically create the menu bar
 198     the first time it is called. You can also call
 199     QMainWindow::setMenuBar() to use a custom menu bar in the main window.
 200
 201     \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 0
 202     \dots
 203     \snippet examples/mainwindows/menus/mainwindow.cpp 5
 204     \dots
 205
 206     Once actions have been created, we can add them to the main window
 207     components. To begin with, we add them to the pop-up menus:
 208
 209     \snippet examples/mainwindows/menus/mainwindow.cpp 10
 210     \dots
 211     \snippet examples/mainwindows/menus/mainwindow.cpp 11
 212     \dots
 213
 214     The QToolBar and QMenu classes use Qt's action system to provide a
 215     consistent API. In the above code, some existing actions were added to
 216     the file menu with the QMenu::addAction() function. QToolBar also
 217     provides this function, making it easy to reuse actions in different
 218     parts of the main window. This avoids unnecessary duplication of work.
 219
 220     We create a toolbar as a child of the main window, and add the desired
 221     actions to it:
 222
 223     \snippet examples/mainwindows/sdi/mainwindow.cpp 0
 224     \dots
 225     \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 1
 226
 227     In this example, the toolbar is restricted to the top and bottom
 228     toolbar areas of the main window, and is initially placed in the
 229     top tool bar area. We can see that the actions specified by \c
 230     newAct and \c openAct will be displayed both on the toolbar and in
 231     the file menu.
 232
 233     QDockWidget is used in a similar way to QToolBar. We create a
 234     dock widget as a child of the main window, and add widgets as children
 235     of the dock widget:
 236
 237     \snippet doc/src/snippets/dockwidgets/mainwindow.cpp 0
 238
 239     In this example, the dock widget can only be placed in the left and
 240     right dock areas, and it is initially placed in the left dock area.
 241
 242     The QMainWindow API allows the programmer to customize which dock
 243     widget areas occupy the four corners of the dock widget area. If
 244     required, the default can be changed with the
 245     QMainWindow::setCorner() function:
 246
 247     \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 2
 248
 249     The following diagram shows the configuration produced by the above code.
 250     Note that the left and right dock widgets will occupy the top and bottom
 251     corners of the main window in this layout.
 252
 253     \image mainwindow-docks-example.png
 254
 255     Once all of the main window components have been set up, the central widget
 256     is created and installed by using code similar to the following:
 257
 258     \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 3
 259
 260     The central widget can be any subclass of QWidget.
 261 */