diff options
Diffstat (limited to 'src/widgets/doc/src/windows-and-dialogs')
| -rw-r--r-- | src/widgets/doc/src/windows-and-dialogs/dialogs.qdoc | 28 | ||||
| -rw-r--r-- | src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc | 102 |
2 files changed, 47 insertions, 83 deletions
diff --git a/src/widgets/doc/src/windows-and-dialogs/dialogs.qdoc b/src/widgets/doc/src/windows-and-dialogs/dialogs.qdoc index 5b1ce435d8..4bd86e9f36 100644 --- a/src/widgets/doc/src/windows-and-dialogs/dialogs.qdoc +++ b/src/widgets/doc/src/windows-and-dialogs/dialogs.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \group standard-dialogs diff --git a/src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc b/src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc index 9935c3ca7f..6b0315f10a 100644 --- a/src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc +++ b/src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc @@ -1,47 +1,25 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// 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. + 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. + 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 @@ -51,8 +29,8 @@ 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 not have a task bar entry of their own. + 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 @@ -61,20 +39,21 @@ \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. + 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 + \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 Qt Designer, Qt's visual design tool. - Using Qt Designer is a lot faster than hand-coding, and makes it easy to test different + 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! @@ -83,8 +62,8 @@ 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 + (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 @@ -123,9 +102,9 @@ 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 + 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 + Conventions Manual (ICCCM), window placement is handled differently in existing window managers. X11 provides no standard or easy way to get the frame geometry @@ -139,6 +118,15 @@ 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). */ /*! @@ -152,8 +140,8 @@ \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. + application window, such as the main window itself, menu and tool bars, + and a status bar. \annotatedlist mainwindow-classes @@ -163,8 +151,8 @@ associated user interface components: \list - \li QMainWindow is the central class around which applications - can be built. Along with the companion QDockWidget and QToolBar + \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 @@ -181,11 +169,11 @@ \section1 Example Code - Using QMainWindow is straightforward. Generally, we subclass + 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, we simply create the menus, and + 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 @@ -196,8 +184,8 @@ \snippet 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: + 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 @@ -210,7 +198,7 @@ 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 + Create a toolbar as a child of the main window, and add the desired actions to it: \code @@ -227,7 +215,7 @@ 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 + 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: @@ -236,7 +224,7 @@ 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 + 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: @@ -249,7 +237,7 @@ \image mainwindow-docks-example.png - Once all of the main window components have been set up, the 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 |