1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
|
// Copyright (C) 2020 The Qt Company Ltd
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page platform-integration.html
\title Platform Integration
\brief Integrating Qt with the native platform.
Qt's main strength as a cross-platform toolkit for application development
is removing the need for duplicating the application code for each target
platform.
While Qt solves many of the typical tasks of writing an application,
there are always corner cases that Qt can not cover, or where it makes more
sense to build a feature on top of the platform specific APIs, or another
toolkit.
To support these use-cases, while still allowing Qt to handle the bulk of
the application logic, Qt provides a wide range of platform integration
APIs, from simple type conversions to platform specific native interfaces.
\section1 Type Conversions
\include platformintegration.qdocinc type-conversions
For example, to get the current user's username on Apple platforms:
\code
NSProcessInfo *processInfo = NSProcessInfo.processInfo;
QString userName = QString::fromNSString(processInfo.userName)
\endcode
For a complete list of all type conversions, see the \l{Type Conversions} overview.
\section1 Window Embedding
Windows created by the underlying platform APIs may be used as both
parent containers for Qt windows, or embedded into Qt windows as child
windows.
The former is useful if the application is mainly written using the native
platform APIs, but where parts of the application uses Qt, for example
to draw a specialized UI. To embed Qt into the window hierarchy of the
native application, use QWindow::winId() to get the native handle for
the Qt window, and then use the native APIs to re-parent the window
into the native UI.
The latter is useful if the native platform, or another toolkit, exposes
a specialized control as a native window. By using QWindow::fromWinId()
to wrap the native window handle in a QWindow, the window can then be
re-parented into the Qt window hierarchy as any other QWindow. To re-parent
this QWindow into a Qt Widget based UI, use the widgets-specific
QWidget::createWindowContainer() function.
\section1 Event Handling
Most event handling use-cases in Qt are sufficiently covered by the cross
platform event delivery, via QWindow::event() and friends, or through
QObject::installEventFilter().
In cases where this is not enough, Qt provides access to the delivery of the
native events. A global event filter that receives all native events can be
installed by using QCoreApplication::installNativeEventFilter(), while
per-window native events can be handled in QWindow::nativeEvent().
\note Interfering with the native event flow may put Qt in an inconsistent
state. These APIs should primarily be used to augment Qt's existing
event handling, for example for events Qt doesn't handle yet.
\section1 Native Interfaces
Platform specific functionality not covered by the APIs mentioned above
are handled by the more generic \l{Native Interfaces}{native interface}
mechanism in Qt. The interfaces provide access to native or platform
specific APIs of the classes they extend.
\include platformintegration.qdocinc native-interface-blurb
\include platformintegration.qdocinc native-interface-handle-access-example
For a complete list of all native interfaces, see the \l{Native Interfaces} overview.
\warning \include platformintegration.qdocinc native-interface-compat-warning
\section1 Platform Support
In addition to the application developer APIs, Qt also interfaces with the
platform when providing the underlying implementations of the cross-platform
building blocks in Qt.
Examples are the event dispatcher abstractions in \l{Qt Core} and the rendering
hardware abstractions in RHI.
The main abstraction layer here is the \l{Qt Platform Abstraction},
or QPA for short, which deals with window system integration and related use-cases.
*/
/*!
\group platform-type-conversions
\title Type Conversions
\include platformintegration.qdocinc type-conversions
The following list enumerates all of the available type conversions:
*/
/*!
\group native-interfaces
\title Native Interfaces
The native interfaces provide access to native or platform specific APIs of
the classes they extend.
\include platformintegration.qdocinc native-interface-blurb
\section1 Example Usage
\section2 Accessing underlying native handles
In situations where a feature of the native platform is not exposed in Qt,
it can be helpful to access the native handles maintained by Qt, and use
those to call the native APIs instead.
\include platformintegration.qdocinc native-interface-handle-access-example
The native interface is accessed through the QOpenGLContext::nativeInterface()
accessor, which ensures that the requested interface is available, and otherwise
returns \nullptr. The underlying NSOpenGLContext is then accessed through the
\l{QNativeInterface::QCocoaGLContext::nativeContext()}{nativeContext()} accessor.
\section2 Adopting existing native handles
Similarly to the \l{Window Embedding}{window embedding} use-case, there are
situations where the native platform, or another toolkit, has created a native
handle that you would like to pass on to Qt \mdash wrapping the existing handle
instead of creating a new one.
For example, to adopt an existing NSOpenGLContext, and use that to share
resources with a context created by Qt:
\code
using namespace QNativeInterface;
QOpenGLContext *adoptedContext = QCocoaGLContext::fromNativeContext(nsOpenGLContext);
anotherContext->setShareContext(adoptedContext);
\endcode
The adopted context is created by a platform specific factory function
in the QNativeInterface::QCocoaGLContext native interface.
\section2 Accessing platform specific APIs
In some cases an API is too platform specific to be included in the cross platform
Qt classes, but is still useful to include. These APIs are available either in the
same way as when accessing the underlying native handles, through the
\l{QOpenGLContext::nativeInterface()}{nativeInterface()} accessor, or directly
as static function in the native interface.
For example, to pull out the OpenGL module handle on Windows:
\code
using namespace QNativeInterface;
HMODULE moduleHandle = QWGLContext::openGLModuleHandle();
\endcode
\section1 Source and Binary Compatibility
\include platformintegration.qdocinc native-interface-compat-warning
\section1 Available Interfaces
For a list of all available interfaces, see the QNativeInterface namespace.
\section2 QOpenGLContext
Accessed through QOpenGLContext::nativeInterface().
\annotatedlist native-interfaces-qopenglcontext
\section2 QOffscreenSurface
Accessed through QOffscreenSurface::nativeInterface().
\annotatedlist native-interfaces-qoffscreensurface
\section2 QSGTexture
Accessed through QSGTexture::nativeInterface().
\annotatedlist native-interfaces-qsgtexture
\noautolist
*/
/*!
\namespace QNativeInterface
\inmodule QtPlatformIntegration
\inheaderfile
\since 6.0
\brief Contains the available native interfaces.
For documentation on how to use these interfaces, see the \l{Native Interfaces} overview.
\warning \include platformintegration.qdocinc native-interface-compat-warning
*/
/*!
\namespace QNativeInterface::Private
\inmodule QtPlatformIntegration
\internal
\inheaderfile
\since 6.0
\brief Contains the available private native interfaces.
*/
|
