2 files changed, 88 insertions, 5 deletions

diff --git a/src/widgets/doc/snippets/tooltips/main.cpp b/src/widgets/doc/snippets/tooltips/main.cpp
new file mode 100644
index 00000000000..94cc71f7118
--- /dev/null
+++ b/src/widgets/doc/snippets/tooltips/main.cpp
@@ -0,0 +1,74 @@
+// Copyright (C) 2023 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
+
+#include <QtWidgets>
+
+using SearchBar = QWidget;
+using Element = QWidget;
+
+class Window : public QMainWindow
+{
+public:
+    Window(QWidget *parent = nullptr);
+
+protected:
+    bool event(QEvent *event) override;
+
+private:
+    Element *elementAt(QPoint pos) const {
+        return nullptr;
+    }
+
+    QToolBar *fileToolBar;
+    QMenu *fileMenu;
+
+    SearchBar *searchBar;
+};
+
+
+Window::Window(QWidget *parent)
+    : QMainWindow(parent)
+{
+//! [action_tooltip]
+    QAction *openAction = new QAction(tr("&Open..."));
+    openAction->setToolTip(tr("Open an existing file"));
+
+    fileMenu = menuBar()->addMenu(tr("&File"));
+    fileToolBar = addToolBar(tr("&File"));
+
+    fileMenu->addAction(openAction);
+    fileToolBar->addAction(openAction);
+//! [action_tooltip]
+
+//! [static_tooltip]
+    searchBar = new SearchBar;
+    searchBar->setToolTip(tr("Search in the current document"));
+//! [static_tooltip]
+
+    fileToolBar->addWidget(searchBar);
+}
+
+//! [dynamic_tooltip]
+bool Window::event(QEvent *event)
+{
+    if (event->type() == QEvent::ToolTip) {
+        QHelpEvent *helpEvent = static_cast<QHelpEvent *>(event);
+        if (Element *element = elementAt(helpEvent->pos())) {
+            QToolTip::showText(helpEvent->globalPos(), element->toolTip());
+        } else {
+            QToolTip::hideText();
+            event->ignore();
+        }
+
+        return true;
+    }
+    return QWidget::event(event);
+}
+//! [dynamic_tooltip]
+
+int main(int argc, char **argv)
+{
+    QApplication app(argc, argv);
+    Window w;
+    return 0;
+}
diff --git a/src/widgets/kernel/qtooltip.cpp b/src/widgets/kernel/qtooltip.cpp
index 2c68b029b01..2800f65ac62 100644
--- a/src/widgets/kernel/qtooltip.cpp
+++ b/src/widgets/kernel/qtooltip.cpp
@@ -45,15 +45,24 @@ using namespace Qt::StringLiterals;
     Rich text displayed in a tool tip is implicitly word-wrapped unless
     specified differently with \c{<p style='white-space:pre'>}.
 
-    The simplest and most common way to set a widget's tool tip is by
-    calling its QWidget::setToolTip() function.
+    UI elements that are created via \l{QAction} use the tooltip property
+    of the QAction, so for most interactive UI elements, setting that
+    property is the easiest way to provide tool tips.
+
+    \snippet tooltips/main.cpp action_tooltip
+
+    For any other widgets, the simplest and most common way to set
+    a widget's tool tip is by calling its QWidget::setToolTip() function.
+
+    \snippet tooltips/main.cpp static_tooltip
 
     It is also possible to show different tool tips for different
     regions of a widget, by using a QHelpEvent of type
     QEvent::ToolTip. Intercept the help event in your widget's \l
     {QWidget::}{event()} function and call QToolTip::showText() with
-    the text you want to display. The \l{widgets/tooltips}{Tooltips}
-    example illustrates this technique.
+    the text you want to display.
+
+    \snippet tooltips/main.cpp dynamic_tooltip
 
     If you are calling QToolTip::hideText(), or QToolTip::showText()
     with an empty string, as a result of a \l{QEvent::}{ToolTip}-event you
@@ -75,7 +84,7 @@ using namespace Qt::StringLiterals;
     \note Tool tips use the inactive color group of QPalette, because tool
     tips are not active windows.
 
-    \sa QWidget::toolTip, QAction::toolTip, {Tool Tips Example}
+    \sa QWidget::toolTip, QAction::toolTip
 */
 
 class QTipLabel : public QLabel