mainwindow.qdoc

Go to the documentation of this file.

// Copyright (C) 2016 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
    \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 you to resize and
    position the applications according to your 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
    Qt::Window flag. Depending on the window management system
    such \e{secondary windows} are usually stacked on top of their respective
    parent window and do not have a task bar entry of their own.
 
    The QMainWindow class sets the Qt::Window flag in its constructor,
    as it is designed to be used as a window and provides 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 you 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!
 
    \target 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
    (that is, the window excluding the window frame), others include the
    window frame. QWidget differentiates 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:
    \image geometry.png
           {Window geometry with size dimensions and positions labeled}
 
    \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
    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.
 
    \section2 Wayland Peculiarities
 
    On Wayland, programmatically setting or getting the position of a top-level window from the
    client-side is typically not supported. Technically speaking, it depends on the shell
    interface. For typical desktop compositors, however, the default shell interface will be
    \c{XDG Shell}, which does not support manual positioning of windows. In such cases, Qt will
    ignore calls to set the top-level position of a window, and, when queried, the window position
    will always be returned as QPoint(0, 0).
*/
 
/*!
    \page mainwindow.html
    \title Application Main Window
    \ingroup qt-gui-concepts
    \brief Creating the application window.
 
    \section1 Overview of the Main Window Classes
 
    These classes provide everything you need for a typical modern main
    application window, such as the main window itself, menu and tool bars,
    and a status bar.
 
    \annotatedlist mainwindow-classes
 
    \section1 The Main Window Classes
 
    Qt provides the following classes for managing main windows and
    associated user interface components:
 
    \list
    \li QMainWindow is the central class around which applications can be
       built. Along with the companion QDockWidget and QToolBar
       classes, it represents the top-level user interface of the application.
 
    \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 means that toolbars cooperate well
       with menus and keyboard shortcuts.
    \endlist
 
    \section1 Example Code
 
    Using QMainWindow is straightforward. Generally, you subclass
    QMainWindow and set up menus, toolbars, and dock widgets inside
    the QMainWindow constructor.
 
    To add a menu bar to the main window, 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, you can add them to the main window
    components. To begin with, 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.
 
    Create a toolbar as a child of the main window, and add the desired
    actions to it:
 
    \code
    fileToolBar = addToolBar(tr("File"));
    fileToolBar->addAction(newAct);
    fileToolBar->addAction(openAct);
    \endcode
    \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. You 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 lets you 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
           {Placement of dock windows relative to a central widget}
 
    Once all 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.
*/