// Copyright (C) 2020 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \page gui-changes-qt6.html
    \title Changes to Qt GUI
    \ingroup changes-qt-5-to-6
    \brief Kernel, Text, Painting, and Utility classes are modified.

    Qt 6 is a result of the conscious effort to make the framework more
    efficient and easy to use.

    We try to maintain binary and source compatibility for all the public
    APIs in each release. But some changes were inevitable in an effort to
    make Qt a better framework.

    In this topic we summarize those changes in Qt GUI, and provide
    guidance to handle them.

    \section1 Kernel classes

    \section2 The QBitmap class

    Implicit construction of a QBitmap from a QPixmap is no longer supported.
    The constructor and assignment operator have been made explicit and marked as
    deprecated. Use the new static factory function \l{QBitmap::}{fromPixmap} instead.

    \section2 The QCursor class

    Implicit construction of a QCursor from a QPixmap is no longer supported, the
    constructor has been made explicit.

    \section2 The QKeyCombination class

    QKeyCombination is a new class for storing a combination of a key with an
    optional modifier. It should be used as a replacement for combining values from
    the Qt::Key enum with a modifier in a type-safe way.

    We recommend migrating code that currently uses operator+() to combine a key and
    modifiers, as future C++ standards are likely to declare arithmetic operations
    between unrelated enumeration types as illegal. Use operator|(), and change
    APIs that expect an \c int to expect a QKeyCombination instead.

    Existing APIs that expect an \c int for a key combination can be called using
    QKeyCombination::toCombined().

    \section1 Text classes

    \section2 The QFontDatabase class

    The QFontDatabase class has now only static member functions. The constructor
    has been deprecated. Instead of e.g.

    \code
    const QStringList fontFamilies = QFontDatabase().families();
    \endcode

    use

    \code
    const QStringList fontFamilies = QFontDatabase::families();
    \endcode

    \section2 The QFont class

    The numerical values of the QFont::Weight enumerator have been changed to
    be in line with OpenType weight values. QFont::setWeight() expects an enum value
    instead of an \c int, and code that calls the setter with an integer will fail to
    compile. To continue to use old integer values, use QFont::setLegacyWeight().

    \section1 Painting classes

    See the porting guide for \l{Changes to Qt Print Support}{Qt Print Support} for
    information about \l{QPagedPaintDevice} and other printing related classes.

    \section1 Utility classes

    \section2 QIntValidator and QDoubleValidator

    The \l{QIntValidator::}{setRange()} method is no longer marked as virtual.

    \section1 OpenGL classes

    With the introduction of Qt RHI as the rendering foundation in Qt,
    most classes prefixed by \c QOpenGL have been moved into the \l{Qt OpenGL}
    module.

    More details can be found in \l{Changes to Qt OpenGL}{the Qt OpenGL porting guide}.

    One notable exception is the class \l QOpenGLContext, which still resides in
    Qt GUI.

    In addition, the class \l QOpenGLWidget has been moved to a new module, named
    Qt OpenGL Widgets.

    \section2 The QOpenGLContext class

    The QOpenGLContext::versionFunctions() function is replaced by
    QOpenGLVersionFunctionsFactory::get(). QOpenGLVersionFunctionsFactory is a public
    class now, part of the \l{Qt OpenGL} module.

    \section2 ANGLE

    On Windows, ANGLE, a third-party OpenGL ES to Direct 3D translator, is no
    longer included in Qt. This means Qt::AA_UseOpenGLES and the environment
    variable \c{QT_OPENGL=angle} no longer have any effect.
    In \l{Dynamically Loading OpenGL}{dynamic OpenGL builds} there is no automatic fallback to ANGLE in
    case OpenGL proper fails to initialize. For QWindow or QWidget based
    applications using OpenGL directly, for example via QOpenGLWidget, this means
    that OpenGL proper is the only option at run time. However, the alternative of
    using a pure software OpenGL implementation, such as Mesa llvmpipe that is
    shipped with the pre-built Qt packages, is still available. For Qt Quick and Qt
    Quick 3D applications, Qt 6 introduces support for Direct 3D 11, Vulkan, and
    Metal, in addition to OpenGL. On Windows the default choice is Direct 3D,
    therefore the removal of ANGLE is alleviated by having support for graphics
    APIs other than OpenGL as well.

    \section2 Native clipboard integration

    Qt 5 provided interfaces for integrating platform specific or custom
    clipboard formats into Qt through \c QMacPasteboardMime in \c QtMacExtras,
    and \c QWindowsMime from the Windows QPA API. Since Qt 6.6, the
    equivalent functionality is provided by the classes QUtiMimeConverter for
    \macos, and the QWindowsMimeConverter for Windows.

    Porting from QWindowsMime to QWindowsMimeConverter requires practically no
    changes, as the virtual interface is identical. However, in Qt 6 it is no
    longer needed to register a QWindowsMimeConverter implementation;
    instantiating the type implicitly registers the converter.

    Porting a QMacPasteboardMime to QUtiMimeConverter requires renaming some of
    the virtual functions. Note that the \c{QMacPasteboardMime} API used the
    outdated term \c{flavor} for the native clipboard format on \macos, whereas
    the platform now uses \c{Uniform Type Identifiers}, i.e. \c{UTI}s, which Qt
    has adapted for function and parameter names.

    The \c{mimeFor} and \c{flavorFor} functions are replaced by the
    \l{QUtiMimeConverter::}{mimeForUti} and \l{QUtiMimeConverter::}{utiForMime}
    implementations, respectively. Those should return the name of the mime
    type or \c{UTI} that the converter can convert the input format to, so a
    port usually just involves renaming existing overrides. The
    \c{convertToMime}, \c{convertFromMime}, and \c{count} functions in
    QUtiMimeConverter are identical to their QMacPasteboardMime versions.

    The \c{canConvert}, \c{converterName} functions are no longer needed, they
    are implied by implementation of the above functions, so overrides of those
    functions can be removed.

    As with the the QWindowsMimeConverter, registration is done by instantiating
    the type.
*/
