AuroraMiddleware/qt5base-lts
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Document native interfaces

Browse Source 
As the private headers are not included by default in the precompiled
header QDoc builds for QtGui, create a custom module header for
the documentation build and pull in the required headers.

Add dummy declarations for Windows-specific types for building docs
on non-Windows platforms.

Task-number: QTBUG-83252
Change-Id: I225ed08f68cf4f7c1f1d093424070b13ce36aa51
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
Reviewed-by: Tor Arne Vestbø <tor.arne.vestbo@qt.io>
This commit is contained in:
Friedemann Kleint 2020-07-24 08:30:31 +02:00
parent d23c118fd4
commit a494da3b20
10 changed files with 511 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
src/gui/doc/includes/QtGuiDoc Normal file
View File

@ -0,0 +1,9 @@
#include <QtGui/QtGui>
// native platform interfaces
#include <QtGui/qpa/qplatformmenu_p.h>
#include <QtGui/qpa/qplatformwindow_p.h>
#include <QtGui/qpa/qplatformscreen_p.h>
#include <QtGui/private/qguiapplication_p.h>
#include <QtGui/private/qkeymapper_p.h>
#include <QtGui/private/qwindowsmime_p.h>

58
src/gui/doc/includes/windows.h Normal file
View File

@ -0,0 +1,58 @@
/****************************************************************************
**
** Copyright (C) 2020 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtGui module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** 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 Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
#pragma once
//
// W A R N I N G
// -------------
//
// This file is not part of the Qt API. It exists purely as an
// implementation detail. This header file may change from version to
// version without notice, or even be removed.
//
// We mean it.
//
// Dummy declarations for generating docs on non-Windows platforms
#if !defined(Q_OS_WIN) && defined(Q_CLANG_QDOC)
typedef struct _FORMATETC {} FORMATETC;
typedef struct _STGMEDIUM {} STGMEDIUM;
typedef void *IDataObject;
#endif

3
src/gui/doc/qtgui.qdocconf
View File

@ -8,6 +8,9 @@ project = QtGui
description = Qt GUI Reference Documentation
version = $QT_VERSION
includepaths += ./includes
moduleheader = QtGuiDoc
examplesinstallpath = gui
qhp.projects = QtGui

422
src/gui/doc/src/nativeinterfaces.qdoc Normal file
View File

@ -0,0 +1,422 @@
/****************************************************************************
**
** 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$
**
****************************************************************************/
/*!
\group native_interfaces
\title Native Interfaces
Native interfaces provide access to native APIs of the classes they extend.
*/
/*!
\namespace QPlatformInterface::Private
\inmodule QtGui
\since 6.0
\brief Contains the classes providing native interfaces.
\ingroup native_interfaces
*/
/*!
\class QPlatformInterface::QCocoaGLContext
\since 6.0
\brief Native interface to QPlatformOpenGLContext.
\inmodule QtGui
\ingroup native_interfaces
*/
/*!
\class QPlatformInterface::Private::QCocoaMenu
\since 6.0
\brief Native interface to QPlatformMenu.
\inmodule QtGui
\ingroup native_interfaces
*/
/*!
\class QPlatformInterface::Private::QCocoaWindow
\since 6.0
\brief Native interface to QPlatformWindow.
\inmodule QtGui
\ingroup native_interfaces
*/
/*!
\class QPlatformInterface::QEGLContext
\since 6.0
\brief Native interface to QPlatformOpenGLContext.
\inmodule QtGui
\ingroup native_interfaces
*/
/*!
\class QPlatformInterface::Private::QEvdevKeyMapper
\since 6.0
\brief Native interface to QKeyMapper.
\inmodule QtGui
\ingroup native_interfaces
*/
/*!
\class QPlatformInterface::QGLXContext
\since 6.0
\brief Native interface to QPlatformOpenGLContext.
\inmodule QtGui
\ingroup native_interfaces
*/
/*!
\class QPlatformInterface::QWGLContext
\since 6.0
\brief Native interface to QPlatformOpenGLContext.
\inmodule QtGui
\ingroup native_interfaces
*/
/*!
\class QPlatformInterface::Private::QWindowsApplication
\since 6.0
\brief Native interface to QGuiApplication, to be retrieved from QPlatformIntegration.
\inmodule QtGui
\ingroup native_interfaces
*/
/*!
\enum QPlatformInterface::Private::QWindowsApplication::TouchWindowTouchType
This enum represents the supported TouchWindow touch flags for registerTouchWindow().
\value NormalTouch
\value FineTouch
\value WantPalmTouch
*/
/*!
\fn void QPlatformInterface::Private::QWindowsApplication::setTouchWindowTouchType(QPlatformInterface::Private::QWindowsApplication::TouchWindowTouchTypes type)
Sets the touch window type for all windows to \a type.
*/
/*!
\fn QPlatformInterface::Private::QWindowsApplication::TouchWindowTouchTypes QPlatformInterface::Private::QWindowsApplication::touchWindowTouchType() const
Returns the currently set the touch window type.
*/
/*!
\enum QPlatformInterface::Private::QWindowsApplication::WindowActivationBehavior
This enum specifies the behavior of QWidget::activateWindow() and
QWindow::requestActivate().
\value DefaultActivateWindow The window is activated according to the default
behavior of the Windows operating system. This means the window will not
be activated in some circumstances (most notably when the calling process
is not the active process); only the taskbar entry will be flashed.
\value AlwaysActivateWindow The window is always activated, even when the
calling process is not the active process.
\sa QWidget::activateWindow(), QWindow::requestActivate()
*/
/*!
\fn void QPlatformInterface::Private::QWindowsApplication::setWindowActivationBehavior(QPlatformInterface::Private::QWindowsApplication::WindowActivationBehavior behavior)
Sets the window activation behavior to \a behavior.
\sa QWidget::activateWindow(), QWindow::requestActivate()
*/
/*!
\fn QPlatformInterface::Private::QWindowsApplication::WindowActivationBehavior QPlatformInterface::Private::QWindowsApplication::windowActivationBehavior() const
Returns the currently set the window activation behavior.
*/
/*!
\fn bool QPlatformInterface::Private::QWindowsApplication::isTabletMode() const
Returns \c true if Windows 10 operates in \e{Tablet Mode}.
In this mode, Windows forces all application main windows to open in maximized
state. Applications should then avoid resizing windows or restoring geometries
to non-maximized states.
\sa QWidget::showMaximized(), QWidget::saveGeometry(), QWidget::restoreGeometry()
*/
/*!
\enum QPlatformInterface::Private::QWindowsApplication::DarkModeHandlingFlag
This enum specifies the behavior of the application when Windows
is configured to use dark mode for applications.
\value DarkModeWindowFrames The window frames will be switched to dark.
\value DarkModeStyle The Windows Vista style will be turned off and
a simple dark style will be used.
\sa isDarkMode(), setDarkModeHandling()
*/
/*!
\fn bool QPlatformInterface::Private::QWindowsApplication::isDarkMode() const
Returns \c true if Windows 10 is configured to use dark mode for
applications.
*/
/*!
\fn void QPlatformInterface::Private::QWindowsApplication::setDarkModeHandling(DarkModeHandling handling)
Sets the dark mode handling to \a handling.
*/
/*!
\fn QPlatformInterface::Private::QWindowsApplication::DarkModeHandling QPlatformInterface::Private::QWindowsApplication::darkModeHandling() const
Returns the currently set dark mode handling.
*/
/*!
\fn bool QPlatformInterface::Private::QWindowsApplication::isWinTabEnabled() const
Returns whether the \e{Tablet WinTab Driver} (\c Wintab32.dll) is used.
*/
/*!
\fn bool QPlatformInterface::Private::QWindowsApplication::setWinTabEnabled(bool enabled)
Sets whether the \e{Tablet WinTab Driver} (\c Wintab32.dll) should be used to \a enabled.
Returns \c true on success, \c false otherwise.
*/
/*!
\fn bool QPlatformInterface::Private::QWindowsApplication::registerMime(QWindowsMime *mime)
Registers the converter \a mime to the system.
\sa QPlatformInterface::Private::QWindowsMime, unregisterMime()
*/
/*!
\fn void QPlatformInterface::Private::QWindowsApplication::unregisterMime(QWindowsMime *mime)
Unregisters the converter \a mime from the system.
\sa QPlatformInterface::Private::QWindowsMime, registerMime()
*/
/*!
\fn int QPlatformInterface::Private::QWindowsApplication::registerMimeType(const QString &mime)
Registers the MIME type \a mime, and returns an ID number
identifying the format on Windows.
*/
/*!
\fn HWND QPlatformInterface::Private::QWindowsApplication::createMessageWindow(const QString &, const QString &, QFunctionPointer) const
\internal
*/
/*!
\fn bool QPlatformInterface::Private::QWindowsApplication::asyncExpose() const
\internal
*/
/*!
\fn void QPlatformInterface::Private::QWindowsApplication::setAsyncExpose(bool)
\internal
*/
/*!
\fn QVariant QPlatformInterface::Private::QWindowsApplication::gpu()
\internal
*/
/*!
\fn QVariant QPlatformInterface::Private::QWindowsApplication::gpuList()
\internal
*/
/*!
\class QPlatformInterface::Private::QWindowsMime
\since 6.0
\brief The QWindowsMime class maps open-standard MIME to Window Clipboard formats.
\inmodule QtGui
\ingroup native_interfaces
Qt's drag-and-drop and clipboard facilities use the MIME standard.
On X11, this maps trivially to the Xdnd protocol, but on Windows
although some applications use MIME types to describe clipboard
formats, others use arbitrary non-standardized naming conventions,
or unnamed built-in formats of Windows.
By instantiating subclasses of QWinMime that provide conversions
between Windows Clipboard and MIME formats, you can convert
proprietary clipboard formats to MIME formats.
Qt has predefined support for the following Windows Clipboard formats:
\table
\header \li Windows Format \li Equivalent MIME type
\row \li \c CF_UNICODETEXT \li \c text/plain
\row \li \c CF_TEXT \li \c text/plain
\row \li \c CF_DIB \li \c{image/xyz}, where \c xyz is
a \l{QImageWriter::supportedImageFormats()}{Qt image format}
\row \li \c CF_HDROP \li \c text/uri-list
\row \li \c CF_INETURL \li \c text/uri-list
\row \li \c CF_HTML \li \c text/html
\endtable
An example use of this class would be to map the Windows Metafile
clipboard format (\c CF_METAFILEPICT) to and from the MIME type
\c{image/x-wmf}. This conversion might simply be adding or removing
a header, or even just passing on the data. See \l{Drag and Drop}
for more information on choosing and definition MIME types.
You can check if a MIME type is convertible using canConvertFromMime() and
can perform conversions with convertToMime() and convertFromMime().
\since 6.0
*/
/*!
\fn QPlatformInterface::Private::QWindowsMime::~QWindowsMime()
Destroys the conversion object.
*/
/*!
\fn bool QPlatformInterface::Private::QWindowsMime::canConvertFromMime(const FORMATETC &formatetc, const QMimeData *mimeData) const
Returns \c true if the converter can convert from the \a mimeData to
the format specified in \a formatetc.
All subclasses must reimplement this pure virtual function.
*/
/*!
\fn bool QPlatformInterface::Private::QWindowsMime::canConvertToMime(const QString &mimeType, IDataObject *pDataObj) const
Returns \c true if the converter can convert to the \a mimeType from
the available formats in \a pDataObj.
All subclasses must reimplement this pure virtual function.
*/
/*!
\fn QString QPlatformInterface::Private::QWindowsMime::mimeForFormat(const FORMATETC &formatetc) const
Returns the mime type that will be created form the format specified
in \a formatetc, or an empty string if this converter does not support
\a formatetc.
All subclasses must reimplement this pure virtual function.
*/
/*!
\fn QList<FORMATETC> QPlatformInterface::Private::QWindowsMime::formatsForMime(const QString &mimeType, const QMimeData *mimeData) const
Returns a QList of FORMATETC structures representing the different windows clipboard
formats that can be provided for the \a mimeType from the \a mimeData.
All subclasses must reimplement this pure virtual function.
*/
/*!
\fn QVariant QPlatformInterface::Private::QWindowsMime::convertToMime(const QString &mimeType, IDataObject *pDataObj,
QVariant::Type preferredType) const
Returns a QVariant containing the converted data for \a mimeType from \a pDataObj.
If possible the QVariant should be of the \a preferredType to avoid needless conversions.
All subclasses must reimplement this pure virtual function.
*/
/*!
\fn bool QPlatformInterface::Private::QWindowsMime::convertFromMime(const FORMATETC &formatetc, const QMimeData *mimeData, STGMEDIUM * pmedium) const
Convert the \a mimeData to the format specified in \a formatetc.
The converted data should then be placed in \a pmedium structure.
Return true if the conversion was successful.
All subclasses must reimplement this pure virtual function.
*/
/*!
\class QPlatformInterface::Private::QWindowsWindow
\since 6.0
\brief Native interface to QPlatformWindow.
\inmodule QtGui
\ingroup native_interfaces
*/
/*!
\fn void QPlatformInterface::Private::QWindowsWindow::setHasBorderInFullScreen(bool border)
Sets whether the WS_BORDER flag will be set for the window in full screen mode
to \a border.
See also \l [QtDoc] {Fullscreen OpenGL Based Windows}
*/
/*!
\fn bool QPlatformInterface::Private::QWindowsWindow::hasBorderInFullScreen() const
Returns whether the WS_BORDER flag will be set for the window in full screen
mode.
*/
/*!
\fn QMargins QPlatformInterface::Private::QWindowsWindow::customMargins() const
Returns the margin to be used when handling the \c WM_NCCALCSIZE message.
*/
/*!
\fn void QPlatformInterface::Private::QWindowsWindow::setCustomMargins(const QMargins &margins)
Sets the\a margins to be used when handling the \c WM_NCCALCSIZE message. It is
possible to remove a frame border by specifying a negative value.
*/
/*!
\class QPlatformInterface::Private::QXcbScreen
\since 6.0
\brief Native interface to QPlatformScreen.
\inmodule QtGui
\ingroup native_interfaces
*/
/*!
\class QPlatformInterface::Private::QXcbWindow
\since 6.0
\brief Native interface to QPlatformWindow.
\inmodule QtGui
\ingroup native_interfaces
*/

2
src/gui/doc/src/qtgui.qdoc
View File

@ -113,7 +113,9 @@
and font handling, classes like QRawFont and QGlyphRun can be
used.
\section1 Native Interfaces
See \l{Native Interfaces}.
\section1 OpenGL and OpenGL ES Integration

2
src/gui/kernel/qguiapplication_p.h
View File

@ -372,7 +372,7 @@ Q_GUI_EXPORT bool operator==(const QGuiApplicationPrivate::ActiveTouchPointsKey
namespace QPlatformInterface::Private {
#if defined(Q_OS_WIN)
#if defined(Q_OS_WIN) || defined(Q_CLANG_QDOC)
class QWindowsMime;

2
src/gui/kernel/qkeymapper_p.h
View File

@ -103,7 +103,7 @@ QKeyMapperPrivate *qt_keymapper_private(); // from qkeymapper.cpp
namespace QPlatformInterface::Private {
#if QT_CONFIG(evdev)
#if QT_CONFIG(evdev) || defined(Q_CLANG_QDOC)
struct Q_GUI_EXPORT QEvdevKeyMapper
{
QT_DECLARE_PLATFORM_INTERFACE(QEvdevKeyMapper)

10
src/gui/kernel/qopenglcontext_platform.h
View File

@ -58,11 +58,15 @@ typedef void *EGLContext;
typedef void *EGLDisplay;
#endif
#if !defined(Q_OS_MACOS) && defined(Q_CLANG_QDOC)
typedef void *NSOpenGLContext;
#endif
QT_BEGIN_NAMESPACE
namespace QPlatformInterface {
#if defined(Q_OS_MACOS)
#if defined(Q_OS_MACOS) || defined(Q_CLANG_QDOC)
struct Q_GUI_EXPORT QCocoaGLContext
{
QT_DECLARE_PLATFORM_INTERFACE(QCocoaGLContext)
@ -71,7 +75,7 @@ struct Q_GUI_EXPORT QCocoaGLContext
};
#endif
#if defined(Q_OS_WIN)
#if defined(Q_OS_WIN) || defined(Q_CLANG_QDOC)
struct Q_GUI_EXPORT QWGLContext
{
QT_DECLARE_PLATFORM_INTERFACE(QWGLContext)
@ -81,7 +85,7 @@ struct Q_GUI_EXPORT QWGLContext
};
#endif
#if defined(Q_OS_LINUX)
#if defined(Q_OS_LINUX) || defined(Q_CLANG_QDOC)
struct Q_GUI_EXPORT QGLXContext
{
QT_DECLARE_PLATFORM_INTERFACE(QGLXContext)

6
src/gui/kernel/qplatformmenu_p.h
View File

@ -57,13 +57,17 @@ QT_BEGIN_NAMESPACE
// ----------------- QPlatformInterface -----------------
#if !defined(Q_OS_MACOS) && defined(Q_CLANG_QDOC)
typedef void NSMenu;
#else
QT_END_NAMESPACE
Q_FORWARD_DECLARE_OBJC_CLASS(NSMenu);
QT_BEGIN_NAMESPACE
#endif
namespace QPlatformInterface::Private {
#if defined(Q_OS_MACOS)
#if defined(Q_OS_MACOS) || defined(Q_CLANG_QDOC)
struct Q_GUI_EXPORT QCocoaMenu
{
QT_DECLARE_PLATFORM_INTERFACE(QCocoaMenu)

6
src/gui/kernel/qplatformwindow_p.h
View File

@ -70,7 +70,7 @@ public:
namespace QPlatformInterface::Private {
#if defined(Q_OS_MACOS)
#if defined(Q_OS_MACOS) || defined(Q_CLANG_QDOC)
struct Q_GUI_EXPORT QCocoaWindow
{
QT_DECLARE_PLATFORM_INTERFACE(QCocoaWindow)
@ -79,7 +79,7 @@ struct Q_GUI_EXPORT QCocoaWindow
};
#endif
#if QT_CONFIG(xcb)
#if QT_CONFIG(xcb) || defined(Q_CLANG_QDOC)
struct Q_GUI_EXPORT QXcbWindow
{
QT_DECLARE_PLATFORM_INTERFACE(QXcbWindow)
@ -111,7 +111,7 @@ struct Q_GUI_EXPORT QXcbWindow
};
#endif // xcb
#ifdef Q_OS_WIN
#if defined(Q_OS_WIN) || defined(Q_CLANG_QDOC)
struct Q_GUI_EXPORT QWindowsWindow
{
QT_DECLARE_PLATFORM_INTERFACE(QWindowsWindow)