FCL/sf/mw/qt: comparison doc/src/windows-and-dialogs/mainwindow.qdoc

equal deleted inserted replaced

-:41300fa6a67c
+:f7bc934e204c
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** 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.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+/*!
+\group mainwindow-classes
+\title Main Window and Related Classes
+*/
+/*!
+\page application-windows.html
+\title Application Windows and Dialogs
+\ingroup frameworks-technologies
+\nextpage The Application Main Window
+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
+\l{The 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
+\o \bold{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()}.
+\o \bold{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 The Application Main Window
+\brief Everything you need for a typical modern main application window,
+including menus, toolbars, workspace, etc.
+\contentspage Application Windows and Dialogs
+\nextpage Dialog Windows
+\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
+\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:
+\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.qdoc 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.qdoc 3
+The central widget can be any subclass of QWidget.
+*/