diff options
Diffstat (limited to 'src/widgets/doc/src/cmake-macros.qdoc')
| -rw-r--r-- | src/widgets/doc/src/cmake-macros.qdoc | 174 |
1 files changed, 142 insertions, 32 deletions
diff --git a/src/widgets/doc/src/cmake-macros.qdoc b/src/widgets/doc/src/cmake-macros.qdoc index 108d63a7dd..906a18b2b0 100644 --- a/src/widgets/doc/src/cmake-macros.qdoc +++ b/src/widgets/doc/src/cmake-macros.qdoc @@ -1,49 +1,26 @@ -/**************************************************************************** -** -** Copyright (C) 2020 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) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_wrap_ui.html +\page qt-wrap-ui.html \ingroup cmake-macros-qtwidgets \title qt_wrap_ui -\target qt6_wrap_ui +\keyword qt6_wrap_ui -\brief Creates sources for \c{.ui} files. +\summary {Creates sources for .ui files.} + +\include cmake-find-package-widgets.qdocinc \section1 Synopsis \badcode qt_wrap_ui(<VAR> ui_file1 [ui_file2 ...] [OPTIONS ...]) - -qt6_wrap_ui(<VAR> ui_file1 [ui_file2 ...] - [OPTIONS ...]) \endcode +\versionlessCMakeCommandsNote qt6_wrap_ui() + \section1 Description Creates rules for calling the \l{uic}{User Interface Compiler (uic)} on the given @@ -53,6 +30,10 @@ directory. The paths of the generated header files are added to \c{<VAR>}. \note This is a low-level macro. See the \l{CMake AUTOUIC Documentation} for a more convenient way to process \c{.ui} files with \c{uic}. +Since 6.8: +\note \l{qt6_add_ui}{qt_add_ui} is the recommended way to process \c{.ui} +files. + \section1 Options You can set additional \c{OPTIONS} that should be added to the \c{uic} calls. @@ -62,3 +43,132 @@ You can find possible options in the \l{uic}{uic documentation}. \snippet cmake-macros/examples.cmake qt_wrap_ui */ + +/*! +\page qt-add-ui.html +\ingroup cmake-macros-qtwidgets + +\title qt_add_ui +\keyword qt6_add_ui + +\summary {Adds .ui files to a target.} + +\include cmake-find-package-widgets.qdocinc + +\section1 Synopsis + +\badcode +qt_add_ui(<TARGET> + SOURCES file1.ui [file2.ui ...] + [INCLUDE_PREFIX <PREFIX>] + [OPTIONS ...]) +\endcode + +\versionlessCMakeCommandsNote qt6_add_ui() + +\cmakecommandsince 6.8 + +\section1 Description + +Creates rules for calling the \l{uic}{User Interface Compiler (uic)} on the +\c{.ui} files. For each input file, a header file is generated in the build +directory. The generated header files are added to sources of the target. + +\section1 Arguments + +\section2 TARGET + +The \c{TARGET} argument specifies the CMake target to which the generated header +files will be added. + +\section2 SOURCES + +The \c{SOURCES} argument specifies the list of \c{.ui} files to process. + +\section2 INCLUDE_PREFIX + +\c INCLUDE_PREFIX specifies the include prefix for the generated header files. +Use the same include prefix as in the \c{#include} directive in the source +files. If \c{ui_<basename>.h} is included without a prefix, then this argument +can be omitted. + +\section2 OPTIONS + +You can set additional \c{OPTIONS} that should be added to the \c{uic} calls. +You can find possible options in the \l{uic}{uic documentation}. + +\section1 Examples + +\section2 Without INCLUDE_PREFIX + +In the following snippet, the \c{mainwindow.cpp} file includes +\c{ui_mainwindow.h} and \c{mainwindow.h}. + +\snippet cmake-macros/examples.cpp qt6_add_ui_1 + +\c{CMakeLists.txt} is implemented as follows and it calls +\l{qt6_add_ui}{qt_add_ui} to add \c{ui_mainwindow.h} to the \c{myapp} target. + +\snippet cmake-macros/examples.cmake qt6_add_ui_1 + +In the above example, \c{ui_mainwindow.h} is included without a prefix. So the +\c{INCLUDE_PREFIX} argument is not specified. + +\section2 With INCLUDE_PREFIX + +\snippet cmake-macros/examples.cpp qt6_add_ui_2 + +In the above snippet, \c{mainwindow.cpp} includes \c{ui_mainwindow.h} with a +prefix. + +\snippet cmake-macros/examples.cmake qt6_add_ui_2 + +Since \c{ui_mainwindow.h} is included with a prefix, the \c{INCLUDE_PREFIX} +argument is specified as \c{src/files} in the above example. + +\section2 Multiple .ui files + +In the following snippets, both \c{widget1.cpp} and \c{widget2.cpp} include +\c{ui_widget1.h} and \c{ui_widget2.h} respectively. + +\c{widget1.cpp}: + +\snippet cmake-macros/examples.cpp qt6_add_ui_3_1 + +\c{widget2.cpp}: + +\snippet cmake-macros/examples.cpp qt6_add_ui_3_2 + +Both \c{ui_widget1.h} and \c{ui_widget2.h} are included with the same prefix + +\snippet cmake-macros/examples.cmake qt6_add_ui_3 + +In this case, the \c{INCLUDE_PREFIX} argument can be specified as \c{src/files} +for both files in the above snippet. + +\section1 When to prefer \l{qt6_add_ui}{qt_add_ui} over \c{AUTOUIC}? + +\l{qt6_add_ui}{qt_add_ui} has some advantages over \c{AUTOUIC}: + +\list +\li \l{qt6_add_ui}{qt_add_ui} ensures that the \c{.ui} files are generated +correctly during the first build, for the \c{Ninja} and \c{Ninja Multi-Config} +generators. + +\li \l{qt6_add_ui}{qt_add_ui} guarantees that the generated \c{.h} files are +not leaked outside the build directory. + +\li Since \l{qt6_add_ui}{qt_add_ui} does not scan source files, it provides a +faster build than \c{AUTOUIC}. + +\endlist + +\section1 When to prefer \l{qt6_add_ui}{qt_add_ui} over \c{qt_wrap_ui}? + +\l{qt6_add_ui}{qt_add_ui} has the \c{INCLUDE_PREFIX} argument, which can be used to +specify the include prefix for the generated header files. + +\note It is not recommended to use both \l{qt6_add_ui}{qt_add_ui} and +\c{AUTOUIC} for the same target. + +*/ |