path: root/src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc
diff options
Diffstat (limited to 'src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc')
1 files changed, 261 insertions, 0 deletions
diff --git a/src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc b/src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc
new file mode 100644
index 0000000000..3c175669fb
--- /dev/null
+++ b/src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc
@@ -0,0 +1,261 @@
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact:
+** This file is part of the documentation of the Qt Toolkit.
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+ \group mainwindow-classes
+ \title Main Window and Related Classes
+ \page application-windows.html
+ \title Window and Dialog Widgets
+ \brief Windows and Dialogs in Qt.
+ \ingroup qt-gui-concepts
+ A \l{Widgets Tutorial}{widget} 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, QMainWindow
+ and the various subclasses of QDialog are the most common window types.
+ 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.
+ \section1 Primary and Secondary Windows
+ Any QWidget 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 \e{primary window}.
+ In addition, a QWidget that has a parent can become a window by setting the
+ \l{Qt::WindowType}{Qt::WA_Window} flag. Depending on the window management system
+ such \e{secondary windows} are usually stacked on top of their respective parent
+ window, and not have a task bar entry of their own.
+ The QMainWindow and the QDialog 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.
+ \section1 Main Windows and Dialogs
+ The \l{Application Main Window} provides the framework for building the
+ application's main user interface, and are created by subclassing QMainWindow.
+ QMainWindow has its own layout to which you can add a \l{QMenuBar}{menu bar},
+ \l{QToolBar}{tool bars}, \l{QDockWidget}{dockable widgets} and a
+ \l{QStatusBar}{status bar}. The center area can be occupied by any kind of
+ QWidget.
+ \l{Dialog Windows} are used as secondary windows that present the user with
+ options and choices. Dialogs are created by subclassing QDialog and using
+ \l{Widgets and Layouts}{widgets and layouts} 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.
+ Both main windows and dialogs can be created with \QD, Qt's visual design tool.
+ Using \QD 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
+ \l{uic} is a great way to learn Qt!
+ \keyword window geometry
+ \section1 Window Geometry
+ QWidget 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.
+ \list
+ \li \b{Including the window frame:}
+ \l{QWidget::x()}{x()},
+ \l{QWidget::y()}{y()},
+ \l{QWidget::frameGeometry()}{frameGeometry()},
+ \l{QWidget::pos()}{pos()}, and
+ \l{QWidget::move()}{move()}.
+ \li \b{Excluding the window frame:}
+ \l{QWidget::geometry()}{geometry()},
+ \l{QWidget::width()}{width()},
+ \l{QWidget::height()}{height()},
+ \l{QWidget::rect()}{rect()}, and
+ \l{QWidget::size()}{size()}.
+ \endlist
+ 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.
+ This diagram shows most of the functions in use:
+ \img geometry.png Geometry diagram
+ \section2 X11 Peculiarities
+ 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.
+ 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.
+ 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.
+ 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.
+ \page mainwindow.html
+ \title Application Main Window
+ \ingroup qt-gui-concepts
+ \brief Creating the application window.
+ \tableofcontents
+ \section1 Overview of the Main Window Classes
+ These classes provide everything you need for a typical modern main
+ application window, like the main window itself, menu and tool bars,
+ a status bar, etc.
+ \annotatedlist mainwindow-classes
+ \section1 The Main Window Classes
+ Qt 4 provides the following classes for managing main windows and
+ associated user interface components:
+ \list
+ \li QMainWindow remains the central class around which applications
+ can be built. The interface to this class has been simplified, and
+ much of the functionality previously included in this class is now
+ present in the companion QDockWidget and QToolBar classes.
+ \li QDockWidget provides a widget that can be used to create
+ detachable tool palettes or helper windows. Dock widgets keep track
+ of their own properties, and they can be moved, closed, and floated
+ as external windows.
+ \li QToolBar provides a generic toolbar widget that can hold a
+ number of different action-related widgets, such as buttons,
+ drop-down menus, comboboxes, and spin boxes. The emphasis on a
+ unified action model in Qt 4 means that toolbars cooperate well
+ with menus and keyboard shortcuts.
+ \endlist
+ \section1 Example Code
+ Using QMainWindow is straightforward. Generally, we subclass
+ QMainWindow and set up menus, toolbars, and dock widgets inside
+ the QMainWindow constructor.
+ To add a menu bar to the main window, we simply create the menus, and
+ add them to the main window's menu bar. Note that the
+ QMainWindow::menuBar() function will automatically create the menu bar
+ the first time it is called. You can also call
+ QMainWindow::setMenuBar() to use a custom menu bar in the main window.
+ \snippet code/doc_src_qt4-mainwindow.cpp 0
+ \dots
+ \snippet mainwindows/menus/mainwindow.cpp 5
+ \dots
+ Once actions have been created, we can add them to the main window
+ components. To begin with, we add them to the pop-up menus:
+ \snippet mainwindows/menus/mainwindow.cpp 10
+ \dots
+ \snippet mainwindows/menus/mainwindow.cpp 11
+ \dots
+ The QToolBar and QMenu classes use Qt's action system to provide a
+ consistent API. In the above code, some existing actions were added to
+ the file menu with the QMenu::addAction() function. QToolBar also
+ provides this function, making it easy to reuse actions in different
+ parts of the main window. This avoids unnecessary duplication of work.
+ We create a toolbar as a child of the main window, and add the desired
+ actions to it:
+ \snippet mainwindows/sdi/mainwindow.cpp 0
+ \dots
+ \snippet code/doc_src_qt4-mainwindow.cpp 1
+ In this example, the toolbar is restricted to the top and bottom
+ toolbar areas of the main window, and is initially placed in the
+ top tool bar area. We can see that the actions specified by \c
+ newAct and \c openAct will be displayed both on the toolbar and in
+ the file menu.
+ QDockWidget is used in a similar way to QToolBar. We create a
+ dock widget as a child of the main window, and add widgets as children
+ of the dock widget:
+ \snippet dockwidgets/mainwindow.cpp 0
+ In this example, the dock widget can only be placed in the left and
+ right dock areas, and it is initially placed in the left dock area.
+ The QMainWindow API allows the programmer to customize which dock
+ widget areas occupy the four corners of the dock widget area. If
+ required, the default can be changed with the
+ QMainWindow::setCorner() function:
+ \snippet code/doc_src_qt4-mainwindow.cpp 2
+ The following diagram shows the configuration produced by the above code.
+ Note that the left and right dock widgets will occupy the top and bottom
+ corners of the main window in this layout.
+ \image mainwindow-docks-example.png
+ Once all of the main window components have been set up, the central widget
+ is created and installed by using code similar to the following:
+ \snippet code/doc_src_qt4-mainwindow.cpp 3
+ The central widget can be any subclass of QWidget.