The Qt 4 Main Window Classes

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.

 MainWindow::MainWindow(QWidget *parent)
     : QMainWindow(parent)
 {
     ...
     newAct = new QAction(tr("&New"), this);
     newAct->setShortcut(tr("Ctrl+N"));
     newAct->setStatusTip(tr("Create a new file"));
     connect(newAct, SIGNAL(triggered()), this, SLOT(newFile()));

     openAct = new QAction(tr("&Open..."), this);
     openAct->setShortcut(tr("Ctrl+O"));
     openAct->setStatusTip(tr("Open an existing file"));
     connect(openAct, SIGNAL(triggered()), this, SLOT(open()));
     ...

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:

     fileMenu = menuBar()->addMenu(tr("&File"));
     fileMenu->addAction(newAct);
     fileMenu->addAction(openAct);
     ...
     fileMenu->addSeparator();
     ...

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:

     fileToolBar = addToolBar(tr("File"));
     fileToolBar->addAction(newAct);
     fileToolBar->addAction(openAct);
     ...
 fileToolbar->setAllowedAreas(Qt::TopToolBarArea | Qt::BottomToolBarArea);
 addToolBar(Qt::TopToolBarArea, fileToolbar);

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 newAct and 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:

     contentsWindow = new QDockWidget(tr("Table of Contents"), this);
     contentsWindow->setAllowedAreas(Qt::LeftDockWidgetArea
                                   | Qt::RightDockWidgetArea);
     addDockWidget(Qt::LeftDockWidgetArea, contentsWindow);

     headingList = new QListWidget(contentsWindow);
     contentsWindow->setWidget(headingList);

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:

 setCorner(Qt::TopLeftCorner, Qt::LeftDockWidgetArea);
 setCorner(Qt::BottomLeftCorner, Qt::LeftDockWidgetArea);
 setCorner(Qt::TopRightCorner, Qt::RightDockWidgetArea);
 setCorner(Qt::BottomRightCorner, Qt::RightDockWidgetArea);

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.

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:

 QWidget *centralWidget = new QWidget(this);
 setCentralWidget(centralWidget);

The central widget can be any subclass of QWidget.

What's Changed since Qt 3?

The main window classes in Qt 4 adds new functionality, mainly to the dock widgets and toolbars. We have also made changes to the design of the framework.

Although the QMainWindow class in Qt 3 provided support for toolbars, dock widgets, and other standard user interface components, its design meant that these items were managed through a large number of QMainWindow member functions. In Qt 4, the QMainWindow class delegates many of the management tasks to QDockWidget and QToolBar (allowing more consistent behavior to be defined and implemented).

The dock widget and toolbar classes are now separated into independent classes. (write some more here)

(It is intended that these changes allow more consistent behavior to be defined and implemented (which? example). In response to feedback from customers, we hope to improve these classes even further.)

New Functionality

Dock widgets are animated when docking or detaching from a dock area. The dock areas will also adjust their size to show where the dock widget will dock when it hovers over it. This animation can be turned off with setAnimated().

By default, dock widgets are added to the dock areas in a single row. By setting nesting enabled with setDockNestingEnabled(), the widgets can be added both vertically and horizontally.

Two dock widgets can occupy the same space in a dock area. The user can then choose which widget that is visible with a tab bar that is located below the widgets. The QMainWindow::tabifyDockWidget() joins two tab widgets in such a tabbed dock area. (revise the entire paragraph)

Independent QDockWidget And QToolBar Classes

Toolbar and dock window functionality is provided by two independent classes: QToolBar and QDockWidget. Toolbars and dock widgets reside in separate areas, with toolbars outside the dock widget area. This behavior differs from the Qt 3 behavior, where QToolBar inherited functionality from QDockWidget, and both types of component shared the same areas. The result is a more consistent and predictable experience for users. Toolbars and dock widgets provide feedback while being dragged into their new positions.

The diagram above shows the layout of a main window that contains both toolbars and dock widgets. Each corner area can be used by either of the adjacent dock widget areas, allowing dock widget behavior and main window layout to be specified precisely.

Toolbars and dock widgets are child widgets of the main window. They are no longer reparented into a dock area widget by the main window. Instead, layouts are used to manage the placement of toolbars and dock widgets. One consequence is that the old QDockArea class is no longer required in Qt 4.

Code Change Examples

QMainWindow retains the menuBar() function, but menus are always constructed using QAction objects. All kinds of menus are constructed using the general QMenu class.

Qt 3:

 QPopupMenu *fileMenu = new QPopupMenu(this);
 openAction->addTo(fileMenu);
 saveAction->addTo(fileMenu);
 ...
 menuBar()->insertItem(tr("&File"), fileMenu);

Qt 4:

 QMenu *fileMenu = menuBar()->addMenu(tr("&File"));
 fileMenu->addAction(openAction);
 fileMenu->addAction(saveAction);
 ...

Toolbars follow the same pattern as menus, with the new, more consistent behavior:

Qt 3:

 QToolBar *fileTools = new QToolBar(this, "file toolbar");
 openAction->addTo(fileTools);
 saveAction->addTo(fileTools);
 ...

Qt 4:

 QToolBar *fileTools = addToolBar(tr("File Tool Bar"));
 fileTools->addAction(openAction);
 fileTools->addAction(saveAction);
 ...

The behavior of dock widgets is now configured through the member functions of QDockWidget. For example, compare the old and new ways of creating a dock widget in the dock area on the left hand side of the main window.

In Qt 3:

 QDockWidget *dockWidget = new QDockWidget(this);
 mainWin->moveDockWidget(dockWidget, Qt::DockLeft);

In Qt 4:

 QDockWidget *dockWidget = new QDockWidget(mainWindow);
 mainWindow->addDockWidget(Qt::LeftDockWidgetArea, dockWidget);

[Previous: The Scribe Classes] [Home] [Next: The New Qt Designer]