Initial import from the monolithic Qt.

This is the beginning of revision history for this module. If you
want to look at revision history older than this, please refer to the
Qt Git wiki for how to use Git history grafting. At the time of
writing, this wiki is located here:

http://qt.gitorious.org/qt/pages/GitIntroductionWithQt

If you have already performed the grafting and you don't see any
history beyond this commit, try running "git log" with the "--follow"
argument.

Branched from the monolithic repo, Qt master branch, at commit
896db169ea224deb96c59ce8af800d019de63f12

2 files changed, 321 insertions, 0 deletions

diff --git a/doc/src/windows-and-dialogs/dialogs.qdoc b/doc/src/windows-and-dialogs/dialogs.qdoc
new file mode 100644
index 0000000000..895b19faaa
--- /dev/null
+++ b/doc/src/windows-and-dialogs/dialogs.qdoc
@@ -0,0 +1,60 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 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:FDL$
+** 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 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.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \group standard-dialogs
+    \ingroup qt-gui-concepts
+    \title Standard Dialogs
+    \brief A list of Qt classes for implementing standard dialogs. 
+*/
+
+/*!
+    \page dialogs.html
+    \title Dialog Windows
+    \ingroup qt-gui-concepts
+    \brief An overview over dialog windows.
+    
+    \previouspage Application Main Window
+    \contentspage Application Windows and Dialogs
+    \nextpage Desktop Integration
+
+    Dialogs can be \e{modal}, in which case the user is required to provide
+    necessary information before work in the main window
+    can continue, or \e{modeless}. Modeless dialogs do not prevent the user from
+    interacting with any of the other windows in the application.
+
+    Qt provides a set of ready-made dialogs for file, font, color-selection
+    and more.
+
+    \annotatedlist standard-dialogs
+
+    Custom dialogs can be easily created by composing regular widgets into
+    a QDialog. These classes are specifically designed for building custom
+    dialogs:
+
+    \annotatedlist dialog-classes
+*/
diff --git a/doc/src/windows-and-dialogs/mainwindow.qdoc b/doc/src/windows-and-dialogs/mainwindow.qdoc
new file mode 100644
index 0000000000..e7df50257f
--- /dev/null
+++ b/doc/src/windows-and-dialogs/mainwindow.qdoc
@@ -0,0 +1,261 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 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:FDL$
+** 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 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.
+**
+** 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 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
+    \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 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
+    \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.cpp 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.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 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.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 doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 3
+
+    The central widget can be any subclass of QWidget.
+*/