diff options
Diffstat (limited to 'doc/src/widgets/windows-and-dialogs/mainwindow.qdoc')
| -rw-r--r-- | doc/src/widgets/windows-and-dialogs/mainwindow.qdoc | 261 |
1 files changed, 0 insertions, 261 deletions
diff --git a/doc/src/widgets/windows-and-dialogs/mainwindow.qdoc b/doc/src/widgets/windows-and-dialogs/mainwindow.qdoc deleted file mode 100644 index 3a2efb06a2..0000000000 --- a/doc/src/widgets/windows-and-dialogs/mainwindow.qdoc +++ /dev/null @@ -1,261 +0,0 @@ -/**************************************************************************** -** -** 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 doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 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.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 doc/src/snippets/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 doc/src/snippets/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 doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 3 - - The central widget can be any subclass of QWidget. -*/ |