doc/src/porting/qt4-mainwindow.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2015 The Qt Company Ltd.
   4 ** Contact: http://www.qt.io/licensing/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and The Qt Company. For licensing terms
  14 ** and conditions see http://www.qt.io/terms-conditions. For further
  15 ** information use the contact form at http://www.qt.io/contact-us.
  16 **
  17 ** GNU Free Documentation License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Free
  19 ** Documentation License version 1.3 as published by the Free Software
  20 ** Foundation and appearing in the file included in the packaging of
  21 ** this file.  Please review the following information to ensure
  22 ** the GNU Free Documentation License version 1.3 requirements
  23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \page qt4-mainwindow.html
  30     \title The Qt 4 Main Window Classes
  31         \ingroup qt-basic-concepts
  32
  33         \brief Overview of the Main Window concept and Classes
  34
  35
  36
  37     \contentspage {What's New in Qt 4}{Home}
  38     \previouspage The Scribe Classes
  39     \nextpage The New Qt Designer
  40
  41     Qt 4 introduces a new set of main window classes that supersede the
  42     Qt 3 main window classes, providing a more efficient implementation
  43     while remaining easy to use.
  44
  45     \tableofcontents
  46
  47     \section1 Overview of the Main Window Classes
  48
  49     The main window-related classes have been redesigned to satisfy a
  50     number of requirements, addressing issues raised by our customers and
  51     internal developers. The aim of this redesign is to provide a more
  52     consistent and efficient framework for main window management.
  53
  54     \section1 The Main Window Classes
  55
  56     Qt 4 provides the following classes for managing main windows and
  57     associated user interface components:
  58
  59     \list
  60     \o QMainWindow remains the central class around which applications
  61        can be built. The interface to this class has been simplified, and
  62        much of the functionality previously included in this class is now
  63        present in the companion QDockWidget and QToolBar classes.
  64
  65     \o QDockWidget provides a widget that can be used to create
  66        detachable tool palettes or helper windows. Dock widgets keep track
  67        of their own properties, and they can be moved, closed, and floated
  68        as external windows.
  69
  70     \o QToolBar provides a generic toolbar widget that can hold a
  71        number of different action-related widgets, such as buttons,
  72        drop-down menus, comboboxes, and spin boxes. The emphasis on a
  73        unified action model in Qt 4 means that toolbars cooperate well
  74        with menus and keyboard shortcuts.
  75     \endlist
  76
  77     \section1 Example Code
  78
  79     Using QMainWindow is straightforward. Generally, we subclass
  80     QMainWindow and set up menus, toolbars, and dock widgets inside
  81     the QMainWindow constructor.
  82
  83     To add a menu bar to the main window, we simply create the menus, and
  84     add them to the main window's menu bar. Note that the
  85     QMainWindow::menuBar() function will automatically create the menu bar
  86     the first time it is called. You can also call
  87     QMainWindow::setMenuBar() to use a custom menu bar in the main window.
  88
  89     \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 0
  90     \dots
  91     \snippet examples/mainwindows/menus/mainwindow.cpp 5
  92     \dots
  93
  94     Once actions have been created, we can add them to the main window
  95     components. To begin with, we add them to the pop-up menus:
  96
  97     \snippet examples/mainwindows/menus/mainwindow.cpp 10
  98     \dots
  99     \snippet examples/mainwindows/menus/mainwindow.cpp 11
 100     \dots
 101
 102     The QToolBar and QMenu classes use Qt's action system to provide a
 103     consistent API. In the above code, some existing actions were added to
 104     the file menu with the QMenu::addAction() function. QToolBar also
 105     provides this function, making it easy to reuse actions in different
 106     parts of the main window. This avoids unnecessary duplication of work.
 107
 108     We create a toolbar as a child of the main window, and add the desired
 109     actions to it:
 110
 111     \snippet examples/mainwindows/sdi/mainwindow.cpp 0
 112     \dots
 113     \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 1
 114
 115     In this example, the toolbar is restricted to the top and bottom
 116     toolbar areas of the main window, and is initially placed in the
 117     top tool bar area. We can see that the actions specified by \c
 118     newAct and \c openAct will be displayed both on the toolbar and in
 119     the file menu.
 120
 121     QDockWidget is used in a similar way to QToolBar. We create a
 122     dock widget as a child of the main window, and add widgets as children
 123     of the dock widget:
 124
 125     \snippet doc/src/snippets/dockwidgets/mainwindow.cpp 0
 126
 127     In this example, the dock widget can only be placed in the left and
 128     right dock areas, and it is initially placed in the left dock area.
 129
 130     The QMainWindow API allows the programmer to customize which dock
 131     widget areas occupy the four corners of the dock widget area. If
 132     required, the default can be changed with the
 133     QMainWindow::setCorner() function:
 134
 135     \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 2
 136
 137     The following diagram shows the configuration produced by the above code.
 138     Note that the left and right dock widgets will occupy the top and bottom
 139     corners of the main window in this layout.
 140
 141     \image mainwindow-docks-example.png
 142
 143     Once all of the main window components have been set up, the central widget
 144     is created and installed by using code similar to the following:
 145
 146     \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 3
 147
 148     The central widget can be any subclass of QWidget.
 149
 150     \section1 What's Changed since Qt 3?
 151
 152     The main window classes in Qt 4 adds new functionality, mainly to
 153     the dock widgets and toolbars. We have also made changes to the
 154     design of the framework.
 155
 156     Although the QMainWindow class in Qt 3 provided support for
 157     toolbars, dock widgets, and other standard user interface
 158     components, its design meant that these items were managed
 159     through a large number of QMainWindow member functions. In Qt 4,
 160     the QMainWindow class delegates many of the management tasks to
 161     QDockWidget and QToolBar (allowing more consistent behavior to be
 162     defined and implemented).
 163
 164     The dock widget and toolbar classes are now separated into
 165     independent classes. (write some more here)
 166
 167     (It is intended that these changes allow more consistent behavior
 168     to be defined and implemented (which? example). In
 169     response to feedback from customers, we hope to improve these classes
 170     even further.)
 171
 172     \section2 New Functionality
 173
 174     Dock widgets are animated when docking or
 175     detaching from a dock area. The dock areas will also adjust their
 176     size to show where the dock widget will dock when it hovers over
 177     it. This animation can be turned off with \c setAnimated().
 178
 179     By default, dock widgets are added to the dock areas in a single
 180     row. By setting nesting enabled with \c setDockNestingEnabled(),
 181     the widgets can be added both vertically and horizontally.
 182
 183     Two dock widgets can occupy the same space in a dock area. The user
 184     can then choose which widget that is visible with a tab bar that
 185     is located below the widgets. The QMainWindow::tabifyDockWidget()
 186     joins two tab widgets in such a tabbed dock area. (revise the
 187     entire paragraph)
 188
 189     \section2 Independent QDockWidget And QToolBar Classes
 190
 191     Toolbar and dock window functionality is provided by two independent
 192     classes: QToolBar and QDockWidget. Toolbars and dock widgets
 193     reside in separate areas, with toolbars outside the dock widget
 194     area. This behavior differs from the Qt 3 behavior, where
 195     QToolBar inherited functionality from QDockWidget, and both types of
 196     component shared the same areas. The result is a more consistent
 197     and predictable experience for users. Toolbars and dock widgets
 198     provide feedback while being dragged into their new positions.
 199
 200     \image mainwindow-docks.png
 201
 202     The diagram above shows the layout of a main window that contains both
 203     toolbars and dock widgets. Each corner area can be used by either
 204     of the adjacent dock widget areas, allowing dock widget behavior and
 205     main window layout to be specified precisely.
 206
 207     Toolbars and dock widgets are child widgets of the main window. They
 208     are no longer reparented into a dock area widget by the main window.
 209     Instead, layouts are used to manage the placement of toolbars and dock
 210     widgets. One consequence is that the old QDockArea class is no
 211     longer required in Qt 4.
 212
 213     \section2 Code Change Examples
 214
 215     QMainWindow retains the menuBar() function, but menus are always
 216     constructed using QAction objects. All kinds of menus are
 217     constructed using the general QMenu class.
 218
 219     Qt 3:
 220     \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 4
 221     Qt 4:
 222     \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 5
 223
 224     Toolbars follow the same pattern as menus, with the new, more
 225     consistent behavior:
 226
 227     Qt 3:
 228     \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 6
 229     Qt 4:
 230     \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 7
 231
 232     The behavior of dock widgets is now configured through the member
 233     functions of QDockWidget. For example, compare the old and new ways
 234     of creating a dock widget in the dock area on the left hand side of the
 235     main window.
 236
 237     In Qt 3:
 238     \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 8
 239     In Qt 4:
 240     \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 9
 241 */