QIcon: turn platform engines on by default

They are used when an icon is constructed via QIcon::fromTheme, unless
an application-defined theme provides the requested icon. Update the
documentation.

For now we don't provide a way to "opt out". This might change,
depending on the feedback during the Qt 6.7 beta phase.

[ChangeLog][QtGui][QIcon] Qt now has implementations of native icon
engines for macOS, iOS, Windows 10, Windows 11, and Android. These
engines provide access to the native icon libraries and fonts, mapping
standard icons to the corresponding native icon asset. Icons from
application-defined themes take precedence, but the last-resort fallback
icon passed as the second parameter into the
QIcon::fromTheme(QString, QIcon) overload is only used if the icon is
not available from the native library. See the QIcon documentation for
details.

Change-Id: I618e5c137c40f8e6309c0e4d4219a5a2759a475d
Reviewed-by: Tor Arne Vestbø <tor.arne.vestbo@qt.io>

7 files changed, 27 insertions, 32 deletions

diff --git a/src/gui/doc/snippets/code/src_gui_image_qicon.cpp b/src/gui/doc/snippets/code/src_gui_image_qicon.cpp
index f7875b7c7c..a7f27a7fdd 100644
--- a/src/gui/doc/snippets/code/src_gui_image_qicon.cpp
+++ b/src/gui/doc/snippets/code/src_gui_image_qicon.cpp
@@ -45,15 +45,15 @@ void MyWidget::drawIcon(QPainter *painter, const QRect &rect)
 
 void wrapper1() {
 
-//! [3]
-QIcon undoicon = QIcon::fromTheme("edit-undo");
-//! [3]
+//! [fromTheme]
+QIcon undoicon = QIcon::fromTheme(QIcon::ThemeIcon::EditUndo);
+//! [fromTheme]
 
 } // wrapper1
 
 
 //! [4]
-QIcon undoicon = QIcon::fromTheme("edit-undo", QIcon(":/undo.png"));
+QIcon undoicon = QIcon::fromTheme(QIcon::ThemeIcon::EditUndo, QIcon(":/undo.png"));
 //! [4]
 
 
diff --git a/src/gui/image/qicon.cpp b/src/gui/image/qicon.cpp
index 193b264846..41f9e7541e 100644
--- a/src/gui/image/qicon.cpp
+++ b/src/gui/image/qicon.cpp
@@ -578,11 +578,22 @@ QFactoryLoader *qt_iconEngineFactoryLoader()
   The most convenient way to construct an icon is by using the
   \l{QIcon::}{fromTheme()} factory function. Qt implements access to
   the native icon library on platforms that support the
-  \l {Freedesktop Icon Theme Specification}.
+  \l {Freedesktop Icon Theme Specification}. Since Qt 6.7, Qt also
+  provides access to the native icon library on macOS, iOS, and
+  Windows 10 and 11. On Android, Qt can access icons from the Material
+  design system as long as the
+  \l{https://github.com/google/material-design-icons/tree/master/font}
+  {MaterialIcons-Regular} font is available on the system, or bundled
+  as a resource at \c{:/qt-project.org/icons/MaterialIcons-Regular.ttf}
+  with the application.
+
+  \snippet code/src_gui_image_qicon.cpp fromTheme
 
   Applications can use the same theming specification to provide
   their own icon library. See below for an example theme description
   and the corresponding directory structure for the image files.
+  Icons from an application-provided theme take precedence over the
+  native icon library.
 
   In addition, it is possible to provide custom \l {QIconEngine}
   {icon engines}. This allows applications to customize every aspect
@@ -623,6 +634,10 @@ QFactoryLoader *qt_iconEngineFactoryLoader()
 
   \section1 High DPI Icons
 
+  Icons that are provided by the native icon library are usually based
+  on vector graphics, and will automatically be rendered in the appropriate
+  resolution.
+
   When providing your own image files via \l addFile(), then QIcon will
   use Qt's \l {High Resolution Versions of Images}{"@nx" high DPI syntax}.
   This is useful if you have your own custom directory structure and do not
@@ -1306,22 +1321,16 @@ void QIcon::setFallbackThemeName(const QString &name)
     the \l{fallbackThemeName()}{fallback icon theme} is consulted,
     before falling back to looking up standalone icon files in the
     \l{QIcon::fallbackSearchPaths()}{fallback icon search path}.
+    Finally, the platform's native icon library is consulted.
 
     To fetch an icon from the current icon theme:
 
-    \snippet code/src_gui_image_qicon.cpp 3
+    \snippet code/src_gui_image_qicon.cpp fromTheme
 
     If an \l{themeName()}{icon theme} has not been explicitly
     set via setThemeName() a platform defined icon theme will
     be used.
 
-    \note Platform icon themes is only implemented on
-    \l{Freedesktop} based systems at the moment,
-    following the \l{Freedesktop Icon Naming Specification}.
-    In order to use themed icons on other platforms, you will have
-    to bundle a \l{setThemeName()}{compliant theme} in one of your
-    themeSearchPaths(), and set the appropriate themeName().
-
     \sa themeName(), fallbackThemeName(), setThemeName(), themeSearchPaths(), fallbackSearchPaths(),
         {Freedesktop Icon Naming Specification}
 */
@@ -1349,6 +1358,7 @@ QIcon QIcon::fromTheme(const QString &name)
     the \l{fallbackThemeName()}{fallback icon theme} is consulted,
     before falling back to looking up standalone icon files in the
     \l{QIcon::fallbackSearchPaths()}{fallback icon search path}.
+    Finally, the platform's native icon library is consulted.
 
     If no icon is found \a fallback is returned.
 
diff --git a/src/plugins/platforms/android/qandroidplatformtheme.cpp b/src/plugins/platforms/android/qandroidplatformtheme.cpp
index d62c1758b8..d69dce3550 100644
--- a/src/plugins/platforms/android/qandroidplatformtheme.cpp
+++ b/src/plugins/platforms/android/qandroidplatformtheme.cpp
@@ -484,11 +484,7 @@ const QFont *QAndroidPlatformTheme::font(Font type) const
 
 QIconEngine *QAndroidPlatformTheme::createIconEngine(const QString &iconName) const
 {
-    static bool experimentalIconEngines = qEnvironmentVariableIsSet("QT_ENABLE_EXPERIMENTAL_ICON_ENGINES");
-    if (experimentalIconEngines)
-        return new QAndroidPlatformIconEngine(iconName);
-    return nullptr;
-
+    return new QAndroidPlatformIconEngine(iconName);
 }
 
 QVariant QAndroidPlatformTheme::themeHint(ThemeHint hint) const
diff --git a/src/plugins/platforms/cocoa/qcocoatheme.mm b/src/plugins/platforms/cocoa/qcocoatheme.mm
index f3a2d3886c..954159ca26 100644
--- a/src/plugins/platforms/cocoa/qcocoatheme.mm
+++ b/src/plugins/platforms/cocoa/qcocoatheme.mm
@@ -432,10 +432,7 @@ QIcon QCocoaTheme::fileIcon(const QFileInfo &fileInfo, QPlatformTheme::IconOptio
 
 QIconEngine *QCocoaTheme::createIconEngine(const QString &iconName) const
 {
-    static bool experimentalIconEngines = qEnvironmentVariableIsSet("QT_ENABLE_EXPERIMENTAL_ICON_ENGINES");
-    if (experimentalIconEngines)
-        return new QAppleIconEngine(iconName);
-    return nullptr;
+    return new QAppleIconEngine(iconName);
 }
 
 QVariant QCocoaTheme::themeHint(ThemeHint hint) const
diff --git a/src/plugins/platforms/ios/qiostheme.mm b/src/plugins/platforms/ios/qiostheme.mm
index d8a4ef9ca4..3d6d60f971 100644
--- a/src/plugins/platforms/ios/qiostheme.mm
+++ b/src/plugins/platforms/ios/qiostheme.mm
@@ -174,10 +174,7 @@ const QFont *QIOSTheme::font(Font type) const
 
 QIconEngine *QIOSTheme::createIconEngine(const QString &iconName) const
 {
-    static bool experimentalIconEngines = qEnvironmentVariableIsSet("QT_ENABLE_EXPERIMENTAL_ICON_ENGINES");
-    if (experimentalIconEngines)
-        return new QAppleIconEngine(iconName);
-    return nullptr;
+    return new QAppleIconEngine(iconName);
 }
 
 QT_END_NAMESPACE
diff --git a/src/plugins/platforms/windows/qwindowstheme.cpp b/src/plugins/platforms/windows/qwindowstheme.cpp
index e2ab09afb9..aeb8d4ad1b 100644
--- a/src/plugins/platforms/windows/qwindowstheme.cpp
+++ b/src/plugins/platforms/windows/qwindowstheme.cpp
@@ -1177,10 +1177,7 @@ QIcon QWindowsTheme::fileIcon(const QFileInfo &fileInfo, QPlatformTheme::IconOpt
 
 QIconEngine *QWindowsTheme::createIconEngine(const QString &iconName) const
 {
-    static bool experimentalIconEngines = qEnvironmentVariableIsSet("QT_ENABLE_EXPERIMENTAL_ICON_ENGINES");
-    if (experimentalIconEngines)
-        return new QWindowsIconEngine(iconName);
-    return nullptr;
+    return new QWindowsIconEngine(iconName);
 }
 
 static inline bool doUseNativeMenus()
diff --git a/tests/manual/iconbrowser/main.cpp b/tests/manual/iconbrowser/main.cpp
index a87cb462f4..304c121b77 100644
--- a/tests/manual/iconbrowser/main.cpp
+++ b/tests/manual/iconbrowser/main.cpp
@@ -534,8 +534,6 @@ private:
 
 int main(int argc, char* argv[])
 {
-    qputenv("QT_ENABLE_EXPERIMENTAL_ICON_ENGINES", "1");
-
     QApplication app(argc, argv);
 
 #ifdef ICONBROWSER_RESOURCE