6 files changed, 86 insertions, 82 deletions
diff --git a/cmake/QtFrameworkHelpers.cmake b/cmake/QtFrameworkHelpers.cmake
index ade4630626b..39a08f2b9c1 100644
--- a/cmake/QtFrameworkHelpers.cmake
+++ b/cmake/QtFrameworkHelpers.cmake
@@ -136,11 +136,12 @@ function(qt_copy_framework_headers target)
     )
 
     if(NOT UIKIT)
-        set(create_headers_symlink_command
-            "${CMAKE_COMMAND}" -E create_symlink
-                "Versions/Current/Headers"
-                "${output_dir}/${fw_header_dir}"
-        )
+        # Create the framework's basic layout at configure time already. This is necessary, because
+        # we don't rely on the PUBLIC_HEADER property to create the QtFoo.framework/Headers symlink.
+        # See QTBUG-142119 for details.
+        file(MAKE_DIRECTORY "${output_dir}/${fw_dir}/Versions/${fw_version}/Headers")
+        file(CREATE_LINK "${fw_version}" "${output_dir}/${fw_dir}/Versions/Current" SYMBOLIC)
+        file(CREATE_LINK "Versions/Current/Headers" "${output_dir}/${fw_header_dir}" SYMBOLIC)
     endif()
 
     if(CMAKE_GENERATOR MATCHES "^Ninja")
@@ -151,7 +152,6 @@ function(qt_copy_framework_headers target)
             DEPENDS ${target}_sync_headers
             COMMAND ${copy_fw_sync_headers_command}
             COMMAND ${copy_fw_sync_headers_marker_file_command}
-            COMMAND ${create_headers_symlink_command}
             VERBATIM
         )
         add_custom_target(${target}_copy_fw_sync_headers
@@ -160,7 +160,6 @@ function(qt_copy_framework_headers target)
         add_custom_target(${target}_copy_fw_sync_headers
             COMMAND ${copy_fw_sync_headers_command}
             COMMAND ${copy_fw_sync_headers_marker_file_command}
-            COMMAND ${create_headers_symlink_command}
             DEPENDS ${target}_sync_headers
         )
     endif()
diff --git a/src/plugins/styles/modernwindows/qwindows11style.cpp b/src/plugins/styles/modernwindows/qwindows11style.cpp
index b37140cba5e..bf4b3c6a9bc 100644
--- a/src/plugins/styles/modernwindows/qwindows11style.cpp
+++ b/src/plugins/styles/modernwindows/qwindows11style.cpp
@@ -236,7 +236,7 @@ static void drawArrow(const QStyle *style, const QStyleOptionToolButton *toolbut
 }
 #endif // QT_CONFIG(toolbutton)
 
-static qreal radioButtonInnerRadius(int state)
+static qreal radioButtonInnerRadius(QStyle::State state)
 {
     qreal radius = 7.0;
     if (state & QStyle::State_Sunken)
@@ -353,7 +353,7 @@ void QWindows11Style::drawComplexControl(ComplexControl control, const QStyleOpt
     if (widget && widget->testAttribute(Qt::WA_UnderMouse) && widget->isActiveWindow())
         flags |= State_MouseOver;
 
-    painter->save();
+    QPainterStateGuard psg(painter);
     painter->setRenderHint(QPainter::Antialiasing);
     if (d->transitionsEnabled() && option->styleObject) {
         if (control == CC_Slider) {
@@ -536,10 +536,9 @@ void QWindows11Style::drawComplexControl(ComplexControl control, const QStyleOpt
                     v = nextInterval;
                 }
                 if (!lines.isEmpty()) {
-                    painter->save();
+                    QPainterStateGuard psg(painter);
                     painter->translate(slrect.topLeft());
                     painter->drawLines(lines.constData(), lines.size());
-                    painter->restore();
                 }
             }
             if (sub & SC_SliderHandle) {
@@ -765,7 +764,6 @@ void QWindows11Style::drawComplexControl(ComplexControl control, const QStyleOpt
     default:
         QWindowsVistaStyle::drawComplexControl(control, option, painter, widget);
     }
-    painter->restore();
 }
 
 void QWindows11Style::drawPrimitive(PrimitiveElement element, const QStyleOption *option,
@@ -773,8 +771,8 @@ void QWindows11Style::drawPrimitive(PrimitiveElement element, const QStyleOption
                                     const QWidget *widget) const {
     QWindows11StylePrivate *d = const_cast<QWindows11StylePrivate*>(d_func());
 
-    int state = option->state;
-    painter->save();
+    const State state = option->state;
+    QPainterStateGuard psg(painter);
     painter->setRenderHint(QPainter::Antialiasing);
     if (d->transitionsEnabled() && option->styleObject && (element == PE_IndicatorCheckBox || element == PE_IndicatorRadioButton)) {
         QObject *styleObject = option->styleObject; // Can be widget or qquickitem
@@ -1095,17 +1093,15 @@ void QWindows11Style::drawPrimitive(PrimitiveElement element, const QStyleOption
                 painter->setBrush(view->alternatingRowColors() ? vopt->palette.highlight() : WINUI3Colors[colorSchemeIndex][subtleHighlightColor]);
                 painter->setPen(Qt::NoPen);
                 if (isFirst) {
-                    painter->save();
+                    QPainterStateGuard psg(painter);
                     painter->setClipRect(rect);
                     painter->drawRoundedRect(rect.marginsRemoved(QMargins(2, 2, -secondLevelRoundingRadius, 2)),
                                              secondLevelRoundingRadius, secondLevelRoundingRadius);
-                    painter->restore();
                 } else if (isLast) {
-                    painter->save();
+                    QPainterStateGuard psg(painter);
                     painter->setClipRect(rect);
                     painter->drawRoundedRect(rect.marginsRemoved(QMargins(-secondLevelRoundingRadius, 2, 2, 2)),
                                              secondLevelRoundingRadius, secondLevelRoundingRadius);
-                    painter->restore();
                 } else {
                     painter->drawRect(vopt->rect.marginsRemoved(QMargins(0, 2, 0, 2)));
                 }
@@ -1185,7 +1181,6 @@ void QWindows11Style::drawPrimitive(PrimitiveElement element, const QStyleOption
     default:
         QWindowsVistaStyle::drawPrimitive(element, option, painter, widget);
     }
-    painter->restore();
 }
 
 /*!
@@ -1197,7 +1192,7 @@ void QWindows11Style::drawControl(ControlElement element, const QStyleOption *op
     Q_D(const QWindows11Style);
     State flags = option->state;
 
-    painter->save();
+    QPainterStateGuard psg(painter);
     painter->setRenderHint(QPainter::Antialiasing);
     switch (element) {
     case QStyle::CE_ComboBoxLabel:
@@ -1794,17 +1789,15 @@ void QWindows11Style::drawControl(ControlElement element, const QStyleOption *op
                 painter->drawRoundedRect(rect.marginsRemoved(QMargins(2, 2, 2, 2)),
                                          secondLevelRoundingRadius, secondLevelRoundingRadius);
             } else if (isFirst) {
-                painter->save();
+                QPainterStateGuard psg(painter);
                 painter->setClipRect(rect);
                 painter->drawRoundedRect(rect.marginsRemoved(QMargins(2, 2, -secondLevelRoundingRadius, 2)),
                                          secondLevelRoundingRadius, secondLevelRoundingRadius);
-                painter->restore();
             } else if (isLast) {
-                painter->save();
+                QPainterStateGuard psg(painter);
                 painter->setClipRect(rect);
                 painter->drawRoundedRect(rect.marginsRemoved(QMargins(-secondLevelRoundingRadius, 2, 2, 2)),
                                          secondLevelRoundingRadius, secondLevelRoundingRadius);
-                painter->restore();
             } else {
                 painter->drawRect(rect.marginsRemoved(QMargins(0, 2, 0, 2)));
             }
@@ -1864,7 +1857,6 @@ void QWindows11Style::drawControl(ControlElement element, const QStyleOption *op
     default:
         QWindowsVistaStyle::drawControl(element, option, painter, widget);
     }
-    painter->restore();
 }
 
 int QWindows11Style::styleHint(StyleHint hint, const QStyleOption *opt,
diff --git a/src/widgets/dialogs/qfiledialog.cpp b/src/widgets/dialogs/qfiledialog.cpp
index b86f8c15c8b..03a42e321d2 100644
--- a/src/widgets/dialogs/qfiledialog.cpp
+++ b/src/widgets/dialogs/qfiledialog.cpp
@@ -57,89 +57,102 @@ Q_GLOBAL_STATIC(QUrl, lastVisitedDir)
 
 /*!
   \class QFileDialog
-  \brief The QFileDialog class provides a dialog that allows users to select files or directories.
+  \brief Provides a dialog that allows users to select files or directories.
   \ingroup standard-dialogs
   \inmodule QtWidgets
 
-  The QFileDialog class enables a user to traverse the file system
-  to select one or many files or a directory.
+  The QFileDialog class enables users to browse the file system and select one
+  or more files or directories.
 
-  \image qtquickdialogs-filedialog-gtk.png {Open file dialog}
+  \image qfiledialog.png {Open file dialog}
 
-  The easiest way to create a QFileDialog is to use the static functions,
-  such as \l getOpenFileName().
+  QFileDialog is commonly used to prompt users to open or save files, or to
+  select directories. The easiest way to use QFileDialog is through its static
+  convenience functions, such as \l getOpenFileName().
 
   \snippet code/src_gui_dialogs_qfiledialog.cpp 0
 
-  In the above example, a modal QFileDialog is created using a static
-  function. The dialog initially displays the contents of the "/home/jana"
-  directory, and displays files matching the patterns given in the
-  string "Image Files (*.png *.jpg *.bmp)". The parent of the file dialog
-  is set to \e this, and the window title is set to "Open Image".
+  In this example, a modal QFileDialog is created using a static function. The
+  dialog initially displays the contents of the \c{/home/jana} directory and
+  shows files matching the patterns in \c {"Image Files (*.png *.jpg *.bmp)"}.
+  The window title is set to \c{Open Image}.
 
-  If you want to use multiple filters, separate each one with
-  \e two semicolons. For example:
+  \section1 File filters
+
+  \section2 Filtering files by name or extension
+
+  To filter the displayed files by name or extension, use the setNameFilter()
+  or setNameFilters() functions. Multiple filters can be specified by
+  separating them with two semicolons (;;):
 
   \snippet code/src_gui_dialogs_qfiledialog.cpp 1
 
-  You can create your own QFileDialog without using the static
-  functions. By calling setFileMode(), you can specify what the user must
-  select in the dialog:
+  \section2 Filtering files by MIME type
+
+  To filter the displayed files by MIME type, use the setMimeTypeFilters()
+  function:
+
+  \snippet code/src_gui_dialogs_qfiledialog.cpp 13
+
+  \section2 File filter case sensitivity
+
+  Depending on target platform, file filters can be case-sensitive or
+  case-insensitive.
+
+  \section1 File modes
+
+  QFileDialog supports several file modes, which determine what the user can
+  select:
 
   \snippet code/src_gui_dialogs_qfiledialog.cpp 2
 
-  In the above example, the mode of the file dialog is set to
-  AnyFile, meaning that the user can select any file, or even specify a
-  file that doesn't exist. This mode is useful for creating a
-  "Save As" file dialog. Use ExistingFile if the user must select an
-  existing file, or \l Directory if only a directory can be selected.
+  \list
+  \li \b AnyFile: The user can select any file, including files that do not
+      exist (useful for \c{Save As} dialogs).
+  \li \b ExistingFile: The user must select an existing file.
+  \li \b Directory: The user can select a directory.
+  \endlist
+
   See the \l QFileDialog::FileMode enum for the complete list of modes.
 
-  The fileMode property contains the mode of operation for the dialog;
-  this indicates what types of objects the user is expected to select.
-  Use setNameFilter() to set the dialog's file filter. For example:
+  The fileMode property contains the current mode of operation. Use
+  setFileMode() to change it.
 
-  \snippet code/src_gui_dialogs_qfiledialog.cpp 3
+  \section1 View modes
 
-  In the above example, the filter is set to \c{"Images (*.png *.xpm *.jpg)"}.
-  This means that only files with the extension \c png, \c xpm,
-  or \c jpg are shown in the QFileDialog. You can apply
-  several filters by using setNameFilters(). Use selectNameFilter() to select
-  one of the filters you've given as the file dialog's default filter.
+  QFileDialog provides two view modes:
 
-  The file dialog has two view modes: \l{QFileDialog::}{List} and
-  \l{QFileDialog::}{Detail}.
-  \l{QFileDialog::}{List} presents the contents of the current directory
-  as a list of file and directory names. \l{QFileDialog::}{Detail} also
-  displays a list of file and directory names, but provides additional
-  information alongside each name, such as the file size and modification
-  date. Set the mode with setViewMode():
+  \list
+  \li \b List: Displays files and directories as a simple list.
+  \li \b Detail: Displays additional information such as file size and
+      modification date.
+  \endlist
+
+  Set the view mode with setViewMode():
 
   \snippet code/src_gui_dialogs_qfiledialog.cpp 4
 
-  The last important function you need to use when creating your
-  own file dialog is selectedFiles().
+  \section1 Retrieving selected files
+
+  After the dialog is accepted, use selectedFiles() to retrieve the user's
+  selection:
 
   \snippet code/src_gui_dialogs_qfiledialog.cpp 5
 
-  In the above example, a modal file dialog is created and shown. If
-  the user clicked OK, the file they selected is put in \c fileName.
+  The dialog's working directory can be set with setDirectory(). You can
+  pre-select a file using selectFile().
 
-  The dialog's working directory can be set with setDirectory().
-  Each file in the current directory can be selected using
-  the selectFile() function.
+  \section1 Platform notes
 
-  The \l{dialogs/standarddialogs}{Standard Dialogs} example shows
-  how to use QFileDialog as well as other built-in Qt dialogs.
+  By default, QFileDialog uses the platform's native file dialog if available.
+  In this case, some widget-specific APIs (such as layout() and itemDelegate())
+  may return \c null. Also, not all platforms display file dialogs with a title
+  bar, so the caption text may not be visible.
 
-  By default, a platform-native file dialog is used if the platform has
-  one. In that case, the widgets that would otherwise be used to construct the
-  dialog are not instantiated, so related accessors such as layout() and
-  itemDelegate() return null. Also, not all platforms show file dialogs
-  with a title bar, so be aware that the caption text might not be visible to
-  the user. You can set the \l DontUseNativeDialog option or set the
-  \l{Qt::AA_DontUseNativeDialogs}{AA_DontUseNativeDialogs} application attribute
-  to ensure that the widget-based implementation is used instead of the native dialog.
+  To force the use of the Qt widget-based dialog, set the
+  \l DontUseNativeDialog option or the
+  \l{Qt::AA_DontUseNativeDialogs}{AA_DontUseNativeDialogs} application
+  attribute.
 
   \sa QDir, QFileInfo, QFile, QColorDialog, QFontDialog, {Standard Dialogs Example}
 */
diff --git a/src/widgets/doc/images/qfiledialog.png b/src/widgets/doc/images/qfiledialog.png
new file mode 100644
index 00000000000..62c27c7917a
--- /dev/null
+++ b/src/widgets/doc/images/qfiledialog.png
diff --git a/src/widgets/doc/images/qtquickdialogs-filedialog-gtk.png b/src/widgets/doc/images/qtquickdialogs-filedialog-gtk.png
deleted file mode 100644
index 9360d747a2b..00000000000
--- a/src/widgets/doc/images/qtquickdialogs-filedialog-gtk.png
+++ /dev/null
diff --git a/src/widgets/doc/snippets/code/src_gui_dialogs_qfiledialog.cpp b/src/widgets/doc/snippets/code/src_gui_dialogs_qfiledialog.cpp
index 0325109c1f1..0cf6f62093e 100644
--- a/src/widgets/doc/snippets/code/src_gui_dialogs_qfiledialog.cpp
+++ b/src/widgets/doc/snippets/code/src_gui_dialogs_qfiledialog.cpp
@@ -24,11 +24,11 @@ FileDialogExample::FileDialogExample()
     }
 
     {
-        /* For convinient quoting.
         //! [1]
-        "Images (*.png *.xpm *.jpg);;Text files (*.txt);;XML files (*.xml)"
+        QFileDialog dialog(this);
+        dialog.setNameFilter(tr("Images (*.png *.xpm *.jpg);;Text files (*.txt);;XML files (*.xml)"));
+        dialog.exec();
         //! [1]
-        */
     }
 
     {