Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
cmake-macros.qdoc
Go to the documentation of this file.
1// Copyright (C) 2020 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3
4/*!
5\page qt-wrap-ui.html
6\ingroup cmake-macros-qtwidgets
7
8\title qt_wrap_ui
9\keyword qt6_wrap_ui
10
11\summary {Creates sources for .ui files.}
12
13\include cmake-find-package-widgets.qdocinc
14
15\section1 Synopsis
16
17\badcode
18qt_wrap_ui(<VAR> ui_file1 [ui_file2 ...]
19 [OPTIONS ...])
20\endcode
21
22\versionlessCMakeCommandsNote qt6_wrap_ui()
23
24\section1 Description
25
26Creates rules for calling the \l{uic}{User Interface Compiler (uic)} on the given
27\c{.ui} files. For each input file, an header file is generated in the build
28directory. The paths of the generated header files are added to \c{<VAR>}.
29
30\note This is a low-level macro. See the \l{CMake AUTOUIC Documentation} for a
31more convenient way to process \c{.ui} files with \c{uic}.
32
33Since 6.8:
34\note \l{qt6_add_ui}{qt_add_ui} is the recommended way to process \c{.ui}
35files.
36
37\section1 Options
38
39You can set additional \c{OPTIONS} that should be added to the \c{uic} calls.
40You can find possible options in the \l{uic}{uic documentation}.
41
42\section1 Examples
43
44\snippet cmake-macros/examples.cmake qt_wrap_ui
45*/
46
47/*!
48\page qt-add-ui.html
49\ingroup cmake-macros-qtwidgets
50
51\title qt_add_ui
52\keyword qt6_add_ui
53
54\summary {Adds .ui files to a target.}
55
56\include cmake-find-package-widgets.qdocinc
57
58\section1 Synopsis
59
60\badcode
61qt_add_ui(<TARGET>
62 SOURCES file1.ui [file2.ui ...]
63 [INCLUDE_PREFIX <PREFIX>]
64 [OPTIONS ...])
65\endcode
66
67\versionlessCMakeCommandsNote qt6_add_ui()
68
69\cmakecommandsince 6.8
70
71\section1 Description
72
73Creates rules for calling the \l{uic}{User Interface Compiler (uic)} on the
74\c{.ui} files. For each input file, a header file is generated in the build
75directory. The generated header files are added to sources of the target.
76
77\section1 Arguments
78
79\section2 TARGET
80
81The \c{TARGET} argument specifies the CMake target to which the generated header
82files will be added.
83
84\section2 SOURCES
85
86The \c{SOURCES} argument specifies the list of \c{.ui} files to process.
87
88\section2 INCLUDE_PREFIX
89
90\c INCLUDE_PREFIX specifies the include prefix for the generated header files.
91Use the same include prefix as in the \c{#include} directive in the source
92files. If \c{ui_<basename>.h} is included without a prefix, then this argument
93can be omitted.
94
95\section2 OPTIONS
96
97You can set additional \c{OPTIONS} that should be added to the \c{uic} calls.
98You can find possible options in the \l{uic}{uic documentation}.
99
100\section1 Examples
101
102\section2 Without INCLUDE_PREFIX
103
104In the following snippet, the \c{mainwindow.cpp} file includes
105\c{ui_mainwindow.h} and \c{mainwindow.h}.
106
107\snippet cmake-macros/examples.cpp qt_add_ui_1
108
109\c{CMakeLists.txt} is implemented as follows and it calls
110\c{qt_add_ui} to add \c{ui_mainwindow.h} to the \c{myapp} target.
111
112\snippet cmake-macros/examples.cmake qt_add_ui_1
113
114In the above example, \c{ui_mainwindow.h} is included without a prefix. So the
115\c{INCLUDE_PREFIX} argument is not specified.
116
117\section2 With INCLUDE_PREFIX
118
119\snippet cmake-macros/examples.cpp qt_add_ui_2
120
121In the above snippet, \c{mainwindow.cpp} includes \c{ui_mainwindow.h} with a
122prefix.
123
124\snippet cmake-macros/examples.cmake qt_add_ui_2
125
126Since \c{ui_mainwindow.h} is included with a prefix, the \c{INCLUDE_PREFIX}
127argument is specified as \c{src/files} in the above example.
128
129\section2 Multiple .ui files
130
131In the following snippets, both \c{widget1.cpp} and \c{widget2.cpp} include
132\c{ui_widget1.h} and \c{ui_widget2.h} respectively.
133
134\c{widget1.cpp}:
135
136\snippet cmake-macros/examples.cpp qt_add_ui_3_1
137
138\c{widget2.cpp}:
139
140\snippet cmake-macros/examples.cpp qt_add_ui_3_2
141
142Both \c{ui_widget1.h} and \c{ui_widget2.h} are included with the same prefix
143
144\snippet cmake-macros/examples.cmake qt_add_ui_3
145
146In this case, the \c{INCLUDE_PREFIX} argument can be specified as \c{src/files}
147for both files in the above snippet.
148
149\section1 When to prefer \c{qt_add_ui} over \c{AUTOUIC}?
150
151\c{qt_add_ui} has some advantages over \l{CMake AUTOUIC Documentation}{AUTOUIC}:
152
153\list
154\li \c{qt_add_ui} ensures that the \c{.ui} files are generated
155correctly during the first build, for the \c{Ninja} and \c{Ninja Multi-Config}
156generators.
157
158\li \c{qt_add_ui} guarantees that the generated \c{.h} files are
159not leaked outside the build directory.
160
161\li Since \c{qt_add_ui} does not scan source files, it provides a faster build
162than \c{AUTOUIC}.
163
164\endlist
165
166\section1 When to prefer \c{qt_add_ui} over \c{qt_wrap_ui}?
167
168\c{qt_add_ui} has the \c{INCLUDE_PREFIX} argument, which can be used to
169specify the include prefix for the generated header files.
170
171\note It is not recommended to use both \c{qt_add_ui} and
172\l{CMake AUTOUIC Documentation}{AUTOUIC} for the same target.
173
174\sa {qt_wrap_ui}
175*/