From a494da3b2097177774b7b6676acd8e8c46c3e41d Mon Sep 17 00:00:00 2001 From: Friedemann Kleint Date: Fri, 24 Jul 2020 08:30:31 +0200 Subject: Document native interfaces MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Reviewed-by: Tor Arne Vestbø --- src/gui/doc/includes/QtGuiDoc | 9 + src/gui/doc/includes/windows.h | 58 +++++ src/gui/doc/qtgui.qdocconf | 3 + src/gui/doc/src/nativeinterfaces.qdoc | 422 ++++++++++++++++++++++++++++++++++ src/gui/doc/src/qtgui.qdoc | 2 + 5 files changed, 494 insertions(+) create mode 100644 src/gui/doc/includes/QtGuiDoc create mode 100644 src/gui/doc/includes/windows.h create mode 100644 src/gui/doc/src/nativeinterfaces.qdoc (limited to 'src/gui/doc') diff --git a/src/gui/doc/includes/QtGuiDoc b/src/gui/doc/includes/QtGuiDoc new file mode 100644 index 0000000000..77b598f006 --- /dev/null +++ b/src/gui/doc/includes/QtGuiDoc @@ -0,0 +1,9 @@ +#include + +// native platform interfaces +#include +#include +#include +#include +#include +#include diff --git a/src/gui/doc/includes/windows.h b/src/gui/doc/includes/windows.h new file mode 100644 index 0000000000..aa42233e75 --- /dev/null +++ b/src/gui/doc/includes/windows.h @@ -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 diff --git a/src/gui/doc/qtgui.qdocconf b/src/gui/doc/qtgui.qdocconf index fa069f527c..478932ae04 100644 --- a/src/gui/doc/qtgui.qdocconf +++ b/src/gui/doc/qtgui.qdocconf @@ -8,6 +8,9 @@ project = QtGui description = Qt GUI Reference Documentation version = $QT_VERSION +includepaths += ./includes +moduleheader = QtGuiDoc + examplesinstallpath = gui qhp.projects = QtGui diff --git a/src/gui/doc/src/nativeinterfaces.qdoc b/src/gui/doc/src/nativeinterfaces.qdoc new file mode 100644 index 0000000000..9c0ab78ef4 --- /dev/null +++ b/src/gui/doc/src/nativeinterfaces.qdoc @@ -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 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 +*/ diff --git a/src/gui/doc/src/qtgui.qdoc b/src/gui/doc/src/qtgui.qdoc index 4610b12e98..e3d636ef92 100644 --- a/src/gui/doc/src/qtgui.qdoc +++ b/src/gui/doc/src/qtgui.qdoc @@ -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 -- cgit v1.2.3