Doc: Move some remaining files over for modularization.

The files in this change were still in qtbase/doc/src or required for
it. qtbase/doc/src should now only contain example documentation and
images for the example documentation.

Change-Id: Ia7ca8e7fd2b316e77c706a08df71303bc8294213
Reviewed-by: Marius Storm-Olsen <marius.storm-olsen@nokia.com>

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: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** 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.
+**
+**
+**
+**
+**
+** $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
+    \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.
+*/