source: trunk/doc/src/porting/qt4-mainwindow.qdoc@ 762

/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** 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.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page qt4-mainwindow.html
    \title The Qt 4 Main Window Classes

    \contentspage {What's New in Qt 4}{Home}
    \previouspage The Scribe Classes
    \nextpage The New Qt Designer

    Qt 4 introduces a new set of main window classes that supersede the
    Qt 3 main window classes, providing a more efficient implementation
    while remaining easy to use.

    \tableofcontents

    \section1 Overview of the Main Window Classes

    The main window-related classes have been redesigned to satisfy a
    number of requirements, addressing issues raised by our customers and
    internal developers. The aim of this redesign is to provide a more
    consistent and efficient framework for main window management.

    \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: