path: root/src/gui/doc/src/nativeinterfaces.qdoc

/****************************************************************************
**
** 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 QNativeInterface::Private
    \inmodule QtGui
    \since 6.0
    \brief Contains the classes providing native interfaces.
    \ingroup native_interfaces
*/

/*!
    \class QNativeInterface::QCocoaGLContext
    \since 6.0
    \brief Native interface to QPlatformOpenGLContext.
    \inmodule QtGui
    \ingroup native_interfaces
*/

/*!
    \class QNativeInterface::Private::QCocoaMenu
    \since 6.0
    \brief Native interface to QPlatformMenu.
    \inmodule QtGui
    \ingroup native_interfaces
*/

/*!
    \class QNativeInterface::Private::QCocoaWindow
    \since 6.0
    \brief Native interface to QPlatformWindow.
    \inmodule QtGui
    \ingroup native_interfaces
*/

/*!
    \class QNativeInterface::QEGLContext
    \since 6.0
    \brief Native interface to QPlatformOpenGLContext.
    \inmodule QtGui
    \ingroup native_interfaces
*/

/*!
    \class QNativeInterface::Private::QEvdevKeyMapper
    \since 6.0
    \brief Native interface to QKeyMapper.
    \inmodule QtGui
    \ingroup native_interfaces
*/

/*!
    \class QNativeInterface::QGLXContext
    \since 6.0
    \brief Native interface to QPlatformOpenGLContext.
    \inmodule QtGui
    \ingroup native_interfaces
*/

/*!
    \class QNativeInterface::QWGLContext
    \since 6.0
    \brief Native interface to QPlatformOpenGLContext.
    \inmodule QtGui
    \ingroup native_interfaces
*/

/*!
    \class QNativeInterface::Private::QWindowsApplication
    \since 6.0
    \brief Native interface to QGuiApplication, to be retrieved from QPlatformIntegration.
    \inmodule QtGui
    \ingroup native_interfaces
*/

/*!
    \enum QNativeInterface::Private::QWindowsApplication::TouchWindowTouchType

    This enum represents the supported TouchWindow touch flags for registerTouchWindow().

    \value NormalTouch
    \value FineTouch
    \value WantPalmTouch
*/

/*!
    \fn void QNativeInterface::Private::QWindowsApplication::setTouchWindowTouchType(QNativeInterface::Private::QWindowsApplication::TouchWindowTouchTypes type)

    Sets the touch window type for all windows to \a type.
*/

/*!
    \fn QNativeInterface::Private::QWindowsApplication::TouchWindowTouchTypes QNativeInterface::Private::QWindowsApplication::touchWindowTouchType() const

    Returns the currently set the touch window type.
*/

/*!
    \enum QNativeInterface::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 QNativeInterface::Private::QWindowsApplication::setWindowActivationBehavior(QNativeInterface::Private::QWindowsApplication::WindowActivationBehavior behavior)

    Sets the window activation behavior to \a behavior.

    \sa QWidget::activateWindow(), QWindow::requestActivate()
*/

/*!
    \fn QNativeInterface::Private::QWindowsApplication::WindowActivationBehavior QNativeInterface::Private::QWindowsApplication::windowActivationBehavior() const

    Returns the currently set the window activation behavior.
*/

/*!
    \fn bool QNativeInterface::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 QNativeInterface::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 QNativeInterface::Private::QWindowsApplication::isDarkMode() const

    Returns \c true if Windows 10 is configured to use dark mode for
    applications.
*/

/*!
    \fn void QNativeInterface::Private::QWindowsApplication::setDarkModeHandling(DarkModeHandling handling)

    Sets the dark mode handling to \a handling.
*/

/*!
    \fn QNativeInterface::Private::QWindowsApplication::DarkModeHandling QNativeInterface::Private::QWindowsApplication::darkModeHandling() const

    Returns the currently set dark mode handling.
*/

/*!
    \fn bool QNativeInterface::Private::QWindowsApplication::isWinTabEnabled() const

    Returns whether the \e{Tablet WinTab Driver} (\c Wintab32.dll) is used.
*/

/*!
    \fn bool QNativeInterface::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 QNativeInterface::Private::QWindowsApplication::registerMime(QWindowsMime *mime)

    Registers the converter \a mime to the system.

    \sa QNativeInterface::Private::QWindowsMime, unregisterMime()
*/

/*!
    \fn void QNativeInterface::Private::QWindowsApplication::unregisterMime(QWindowsMime *mime)

    Unregisters the converter \a mime from the system.

    \sa QNativeInterface::Private::QWindowsMime, registerMime()
*/

/*!
    \fn int QNativeInterface::Private::QWindowsApplication::registerMimeType(const QString &mime)

    Registers the MIME type \a mime, and returns an ID number
    identifying the format on Windows.
*/

/*!
    \fn HWND QNativeInterface::Private::QWindowsApplication::createMessageWindow(const QString &, const QString &, QFunctionPointer) const
    \internal
*/

/*!
    \fn bool QNativeInterface::Private::QWindowsApplication::asyncExpose() const
    \internal
*/

/*!
    \fn void QNativeInterface::Private::QWindowsApplication::setAsyncExpose(bool)
    \internal
*/

/*!
    \fn QVariant QNativeInterface::Private::QWindowsApplication::gpu()
    \internal
*/

/*!
    \fn QVariant QNativeInterface::Private::QWindowsApplication::gpuList()
    \internal
*/

/*!
    \class QNativeInterface::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 QNativeInterface::Private::QWindowsMime::~QWindowsMime()

    Destroys the conversion object.
*/

/*!
    \fn bool QNativeInterface::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 QNativeInterface::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 QNativeInterface::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> QNativeInterface::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 QNativeInterface::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 QNativeInterface::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 QNativeInterface::Private::QWindowsWindow
    \since 6.0
    \brief Native interface to QPlatformWindow.
    \inmodule QtGui
    \ingroup native_interfaces
*/

/*!
    \fn void QNativeInterface::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 QNativeInterface::Private::QWindowsWindow::hasBorderInFullScreen() const

    Returns whether the WS_BORDER flag will be set for the window in full screen
    mode.
*/

/*!
    \fn QMargins QNativeInterface::Private::QWindowsWindow::customMargins() const

    Returns the margin to be used when handling the \c WM_NCCALCSIZE message.
*/

/*!
    \fn void QNativeInterface::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 QNativeInterface::Private::QXcbScreen
    \since 6.0
    \brief Native interface to QPlatformScreen.
    \inmodule QtGui
    \ingroup native_interfaces
*/

/*!
    \class QNativeInterface::Private::QXcbWindow
    \since 6.0
    \brief Native interface to QPlatformWindow.
    \inmodule QtGui
    \ingroup native_interfaces
*/