--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/windows-and-dialogs/mainwindow.qdoc Wed Mar 31 11:06:36 2010 +0300
@@ -0,0 +1,279 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights. These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \group mainwindow-classes
+ \title Main Window and Related Classes
+*/
+
+/*!
+ \page application-windows.html
+ \title Application Windows and Dialogs
+ \ingroup frameworks-technologies
+
+ \nextpage The Application Main Window
+
+ 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
+
+ \l{The 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
+ \o \bold{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()}.
+ \o \bold{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 The Application Main Window
+ \brief Everything you need for a typical modern main application window,
+ including menus, toolbars, workspace, etc.
+
+ \contentspage Application Windows and Dialogs
+ \nextpage Dialog Windows
+
+ \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
+ \o 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.
+
+ \o 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.
+
+ \o 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 doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 0
+ \dots
+ \snippet examples/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 examples/mainwindows/menus/mainwindow.cpp 10
+ \dots
+ \snippet examples/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 examples/mainwindows/sdi/mainwindow.cpp 0
+ \dots
+ \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 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 doc/src/snippets/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 doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 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 doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 3
+
+ The central widget can be any subclass of QWidget.
+*/