Convert tooltips example to snippets

The important bits from the example are ~10 lines of code, no need
for building a poor-man's version of a graphics or item view.

Change-Id: I7874c66765c5b46230c92846ee3de1ee83f47e45
Reviewed-by: Oliver Eftevaag <oliver.eftevaag@qt.io>
(cherry picked from commit ae39b1634556f82fe5d7505ed9b6ebb883d6f813)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

17 files changed, 88 insertions, 908 deletions

diff --git a/doc/src/images/tooltips-example.png b/doc/src/images/tooltips-example.png
deleted file mode 100644
index f2236b43de..0000000000
--- a/doc/src/images/tooltips-example.png
+++ /dev/null
diff --git a/examples/widgets/doc/src/tooltips.qdoc b/examples/widgets/doc/src/tooltips.qdoc
deleted file mode 100644
index 6dc0d2fbae..0000000000
--- a/examples/widgets/doc/src/tooltips.qdoc
+++ /dev/null
@@ -1,375 +0,0 @@
-// Copyright (C) 2016 The Qt Company Ltd.
-// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
-
-/*!
-    \example widgets/tooltips
-    \title Tool Tips Example
-    \examplecategory {User Interface Components}
-    \ingroup examples-widgets
-    \brief The Tool Tips example shows how to provide static and dynamic tool
-    tips for an application's widgets.
-
-    The simplest and most common way to set a widget's tool tip is by
-    calling its QWidget::setToolTip() function (static tool
-    tips). Then the tool tip is shown whenever the cursor points at
-    the widget. We show how to do this with our application's tool
-    buttons. But it is also possible to show different tool tips
-    depending on the cursor's position (dynamic tooltips). This
-    approach uses mouse tracking and event handling to determine what
-    widgets are located under the cursor at any point in time, and
-    displays their tool tips. The tool tips for the shape items in our
-    application are implemented using the latter approach.
-
-    \image tooltips-example.png
-
-    With the \c Tooltips application the user can create new shape
-    items with the provided tool buttons, and move the items around
-    using the mouse. Tooltips are provided whenever the cursor is
-    pointing to a shape item or one of the buttons.
-
-    The Tooltips example consists of two classes:
-
-    \list
-    \li \c ShapeItem is a custom widget representing one single shape item.
-    \li \c SortingBox inherits from QWidget and is the application's main
-        widget.
-    \endlist
-
-    First we will review the \c SortingBox class, then we will take a
-    look at the \c ShapeItem class.
-
-    \section1 SortingBox Class Definition
-
-    \snippet widgets/tooltips/sortingbox.h 0
-
-    The \c SortingBox class inherits QWidget, and it is the Tooltips
-    application's main widget. We reimplement several of the event
-    handlers.
-
-    The \c event() function provides tooltips, the \c resize()
-    function makes sure the application appears consistently when the
-    user resizes the main widget, and the \c paintEvent() function
-    displays the shape items within the \c SortingBox widget. The
-    mouse event handlers are reimplemented to make the user able to
-    move the items around.
-
-    In addition we need three private slots to make the user able to
-    create new shape items.
-
-    \snippet widgets/tooltips/sortingbox.h 1
-
-    We also create several private functions: We use the \c
-    initialItemPosition(), \c initialItemColor() and \c
-    createToolButton() functions when we are constructing the widget,
-    and we use the \c updateButtonGeometry() function whenever the
-    user is resizing the application's main widget.
-
-    The \c itemAt() function determines if there is a shape item at a
-    particular position, and the \c moveItemTo() function moves an
-    item to a new position. We use the \c createShapeItem(), \c
-    randomItemPosition() and \c randomItemColor() functions to create
-    new shape items.
-
-    \snippet widgets/tooltips/sortingbox.h 2
-
-    We keep all the shape items in a QList, and we keep three
-    QPainterPath objects holding the shapes of a circle, a square and
-    a triangle. We also need to have a pointer to an item when it is
-    moving, and we need to know its previous position.
-
-    \section1 SortingBox Class Implementation
-
-    \snippet widgets/tooltips/sortingbox.cpp 0
-
-    In the constructor, we first set the Qt::WA_StaticContents
-    attribute on the widget. This attribute indicates that the widget
-    contents are north-west aligned and static. On resize, such a
-    widget will receive paint events only for the newly visible part
-    of itself.
-
-    \snippet widgets/tooltips/sortingbox.cpp 1
-
-    To be able to show the appropriate tooltips while the user is
-    moving the cursor around, we need to enable mouse tracking for the
-    widget.
-
-    If mouse tracking is disabled (the default), the widget only
-    receives mouse move events when at least one mouse button is
-    pressed while the mouse is being moved. If mouse tracking is
-    enabled, the widget receives mouse move events even if no buttons
-    are pressed.
-
-    \snippet widgets/tooltips/sortingbox.cpp 2
-
-    A widget's background role defines the brush from the widget's
-    palette that is used to render the background, and QPalette::Base
-    is typically white.
-
-    \snippet widgets/tooltips/sortingbox.cpp 3
-
-    After creating the application's tool buttons using the private \c
-    createToolButton() function, we construct the shapes of a circle,
-    a square and a triangle using QPainterPath.
-
-    The QPainterPath class provides a container for painting
-    operations, enabling graphical shapes to be constructed and
-    reused. The main advantage of painter paths over normal drawing
-    operations is that complex shapes only need to be created once,
-    but they can be drawn many times using only calls to
-    QPainter::drawPath().
-
-    \snippet widgets/tooltips/sortingbox.cpp 4
-
-    Then we set the window title, resize the widget to a suitable
-    size, and finally create three initial shape items using the
-    private \c createShapeItem(), \c initialItemPosition() and \c
-    initialItemColor() functions.
-
-    \snippet widgets/tooltips/sortingbox.cpp 27
-
-    In the destructor, we delete all shape items.
-
-    \snippet widgets/tooltips/sortingbox.cpp 5
-
-    QWidget::event() is the main event handler and receives all the
-    widget's events. Normally, we recommend reimplementing one of the
-    specialized event handlers instead of this function. But here we
-    want to catch the QEvent::ToolTip events, and since these are
-    rather rare, there exists no specific event handler. For that
-    reason we reimplement the main event handler, and the first thing
-    we need to do is to determine the event's type:
-
-    \snippet widgets/tooltips/sortingbox.cpp 6
-
-    If the type is QEvent::ToolTip, we cast the event to a QHelpEvent,
-    otherwise we propagate the event using the QWidget::event()
-    function.
-
-    The QHelpEvent class provides an event that is used to request
-    helpful information about a particular point in a widget.
-
-    For example, the QHelpEvent::pos() function returns the event's
-    position relative to the widget to which the event is dispatched.
-    Here we use this information to determine if the position of the
-    event is contained within the area of any of the shape items. If
-    it is, we display the shape item's tooltip at the position of the
-    event. If not, we hide the tooltip and explicitly ignore the event.
-    This makes sure that the calling code does not start any tooltip
-    specific modes as a result of the event. Note that the
-    QToolTip::showText() function needs the event's position in global
-    coordinates provided by QHelpEvent::globalPos().
-
-    \snippet widgets/tooltips/sortingbox.cpp 7
-
-    The \c resizeEvent() function is reimplemented to receive the
-    resize events dispatched to the widget. It makes sure that the
-    tool buttons keep their position relative to the main widget when
-    the widget is resized. We want the buttons to always be vertically
-    aligned in the application's bottom right corner, so each time the
-    main widget is resized we update the buttons geometry.
-
-    \snippet widgets/tooltips/sortingbox.cpp 8
-
-    The \c paintEvent() function is reimplemented to receive paint
-    events for the widget. We create a QPainter for the \c SortingBox
-    widget, and run through the list of created shape items, drawing
-    each item at its defined position.
-
-    \snippet widgets/tooltips/sortingbox.cpp 9
-
-    The painter will by default draw all the shape items at position
-    (0,0) in the \c SortingBox widget. The QPainter::translate()
-    function translates the coordinate system by the given offset,
-    making each shape item appear at its defined position. But
-    remember to translate the coordinate system back when the item is
-    drawn, otherwise the next shape item will appear at a position
-    relative to the item drawn last.
-
-    \snippet widgets/tooltips/sortingbox.cpp 10
-
-    The QPainter::setBrush() function sets the current brush used by
-    the painter. When the provided argument is a QColor, the function
-    calls the appropriate QBrush constructor which creates a brush with
-    the specified color and Qt::SolidPattern style. The
-    QPainter::drawPath() function draws the given path using the
-    current pen for outline and the current brush for filling.
-
-    \snippet widgets/tooltips/sortingbox.cpp 11
-
-    The \c mousePressEvent() function is reimplemented to receive the
-    mouse press events dispatched to the widget. It determines if an
-    event's position is contained within the area of any of the shape
-    items, using the private \c itemAt() function.
-
-    If an item covers the position, we store a pointer to that item
-    and the event's position. If several of the shape items cover the
-    position, we store the pointer to the uppermost item. Finally, we
-    move the shape item's pointer to the end of the list, and make
-    a call to the QWidget::update() function to make the item appear
-    on top.
-
-    The QWidget::update() function does not cause an immediate
-    repaint; instead it schedules a paint event for processing when Qt
-    returns to the main event loop.
-
-    \snippet widgets/tooltips/sortingbox.cpp 12
-
-    The \c mouseMoveEvent() function is reimplemented to receive mouse
-    move events for the widget. If the left mouse button is pressed
-    and there exists a shape item in motion, we use the private \c
-    moveItemTo() function to move the item with an offset
-    corresponding to the offset between the positions of the current
-    mouse event and the previous one.
-
-    \snippet widgets/tooltips/sortingbox.cpp 13
-
-    The \c mouseReleaseEvent() function is reimplemented to receive
-    the mouse release events dispatched to the widget. If the left
-    mouse button is pressed and there exists a shape item in motion,
-    we use the private \c moveItemTo() function to move the item like
-    we did in \c mouseMoveEvent(). But then we remove the pointer to
-    the item in motion, making the shape item's position final for
-    now. To move the item further, the user will need to press the
-    left mouse button again.
-
-    \snippet widgets/tooltips/sortingbox.cpp 14
-    \codeline
-    \snippet widgets/tooltips/sortingbox.cpp 15
-    \codeline
-    \snippet widgets/tooltips/sortingbox.cpp 16
-
-    The \c createNewCircle(), \c createNewSquare() and \c
-    createNewTriangle() slots simply create new shape items, using the
-    private \c createShapeItem(), \c randomItemPosition() and \c
-    randomItemColor() functions.
-
-    \snippet widgets/tooltips/sortingbox.cpp 17
-
-    In the \c itemAt() function, we run through the list of created
-    shape items to check if the given position is contained within the
-    area of any of the shape items.
-
-    For each shape item we use the QPainterPath::contains() function
-    to find out if the item's painter path contains the position. If
-    it does we return the index of the item, otherwise we return
-    -1. We run through the list backwards to get the index of the
-    uppermost shape item in case several items cover the position.
-
-    \snippet widgets/tooltips/sortingbox.cpp 18
-
-    The \c moveItemTo() function moves the shape item in motion, and
-    the parameter \c pos is the position of a mouse event. First we
-    calculate the offset between the parameter \c pos and the previous
-    mouse event position. Then we add the offset to the current
-    position of the item in motion.
-
-    It is tempting to simply set the position of the item to be the
-    parameter \c pos. But an item's position defines the top left
-    corner of the item's bounding rectangle, and the parameter \c pos
-    can be any point; The suggested shortcut would cause the item to
-    jump to a position where the cursor is pointing to the bounding
-    rectangle's top left corner, regardless of the item's previous
-    position.
-
-    \snippet widgets/tooltips/sortingbox.cpp 19
-
-    Finally, we update the previous mouse event position, and make a
-    call to the QWidget::update() function to make the item appear at
-    its new position.
-
-    \snippet widgets/tooltips/sortingbox.cpp 20
-
-    In the \c updateButtonGeometry() function we set the geometry for
-    the given button. The parameter coordinates define the bottom
-    right corner of the button. We use these coordinates and the
-    button's size hint to determine the position of the upper left
-    corner. This position, and the button's width and height, are the
-    arguments required by the QWidget::setGeometry() function.
-
-    In the end, we calculate and return the y-coordinate of the bottom
-    right corner of the next button. We use the QWidget::style()
-    function to retrieve the widget's GUI style, and then
-    QStyle::pixelMetric() to determine the widget's preferred default
-    spacing between its child widgets.
-
-    \snippet widgets/tooltips/sortingbox.cpp 21
-
-    The \c createShapeItem() function creates a single shape item. It
-    sets the path, tooltip, position and color, using the item's own
-    functions. In the end, the function appends the new item's pointer
-    to the list of shape items, and calls QWidget::update() to make
-    it appear with the other items within the \c SortingBox widget.
-
-    \snippet widgets/tooltips/sortingbox.cpp 22
-
-    The \c createToolButton() function is called from the \c
-    SortingBox constructor. We create a tool button with the given
-    tooltip and icon. The button's parent is the \c SortingBox widget,
-    and its size is 32 x 32 pixels. Before we return the button, we
-    connect it to the given slot.
-
-    \snippet widgets/tooltips/sortingbox.cpp 23
-
-    The \c initialItemPosition() function is also called from the
-    constructor. We want the three first items to initially be
-    centered in the middle of the \c SortingBox widget, and we use
-    this function to calculate their positions.
-
-    \snippet widgets/tooltips/sortingbox.cpp 24
-
-    Whenever the user creates a new shape item, we want the new item
-    to appear at a random position, and we use the \c
-    randomItemPosition() function to calculate such a position. We
-    make sure that the item appears within the visible area of the
-    \c SortingBox widget, using the widget's current width and height
-    when calculating the random coordinates.
-
-    \snippet widgets/tooltips/sortingbox.cpp 25
-
-    As with \c initialItemPosition(), the \c initialItemColor()
-    function is called from the constructor. The purposes of both
-    functions are purely cosmetic: We want to control the initial
-    position and color of the three first items.
-
-    \snippet widgets/tooltips/sortingbox.cpp 26
-
-    Finally the \c randomItemColor() function is implemented to give
-    the shape items the user creates, a random color.
-
-    \section1 ShapeItem Class Definition
-
-    \snippet widgets/tooltips/shapeitem.h 0
-
-    The \c ShapeItem class is a custom widget representing one single
-    shape item. The widget has a path, a position, a color and a
-    tooltip. We need functions to set or modify these objects, as well
-    as functions that return them. We make the latter functions \c
-    const to prohibit any modifications of the objects,
-    i.e. prohibiting unauthorized manipulation of the shape items
-    appearance.
-
-    \section1 ShapeItem Class Implementation
-
-    \snippet widgets/tooltips/shapeitem.cpp 0
-    \codeline
-    \snippet widgets/tooltips/shapeitem.cpp 1
-    \codeline
-    \snippet widgets/tooltips/shapeitem.cpp 2
-    \codeline
-    \snippet widgets/tooltips/shapeitem.cpp 3
-
-    This first group of functions simply return the objects that are
-    requested. The objects are returned as constants, i.e. they cannot
-    be modified.
-
-    \snippet widgets/tooltips/shapeitem.cpp 4
-    \codeline
-    \snippet widgets/tooltips/shapeitem.cpp 5
-    \codeline
-    \snippet widgets/tooltips/shapeitem.cpp 6
-    \codeline
-    \snippet widgets/tooltips/shapeitem.cpp 7
-
-    The last group of functions set or modify the shape item's path,
-    position, color and tooltip, respectively.
-*/
diff --git a/examples/widgets/widgets/CMakeLists.txt b/examples/widgets/widgets/CMakeLists.txt
index 6b6a7760b7..6ea7a98f98 100644
--- a/examples/widgets/widgets/CMakeLists.txt
+++ b/examples/widgets/widgets/CMakeLists.txt
@@ -12,5 +12,4 @@ qt_internal_add_example(shortcuteditor)
 qt_internal_add_example(sliders)
 qt_internal_add_example(spinboxes)
 qt_internal_add_example(tablet)
-qt_internal_add_example(tooltips)
 qt_internal_add_example(windowflags)
diff --git a/examples/widgets/widgets/tooltips/CMakeLists.txt b/examples/widgets/widgets/tooltips/CMakeLists.txt
deleted file mode 100644
index f3d00a7056..0000000000
--- a/examples/widgets/widgets/tooltips/CMakeLists.txt
+++ /dev/null
@@ -1,52 +0,0 @@
-# Copyright (C) 2022 The Qt Company Ltd.
-# SPDX-License-Identifier: BSD-3-Clause
-
-cmake_minimum_required(VERSION 3.16)
-project(tooltips LANGUAGES CXX)
-
-if(NOT DEFINED INSTALL_EXAMPLESDIR)
-    set(INSTALL_EXAMPLESDIR "examples")
-endif()
-
-set(INSTALL_EXAMPLEDIR "${INSTALL_EXAMPLESDIR}/widgets/widgets/tooltips")
-
-find_package(Qt6 REQUIRED COMPONENTS Core Gui Widgets)
-
-qt_standard_project_setup()
-
-qt_add_executable(tooltips
-    main.cpp
-    shapeitem.cpp shapeitem.h
-    sortingbox.cpp sortingbox.h
-)
-
-set_target_properties(tooltips PROPERTIES
-    WIN32_EXECUTABLE TRUE
-    MACOSX_BUNDLE TRUE
-)
-
-target_link_libraries(tooltips PRIVATE
-    Qt6::Core
-    Qt6::Gui
-    Qt6::Widgets
-)
-
-# Resources:
-set(tooltips_resource_files
-    "images/circle.png"
-    "images/square.png"
-    "images/triangle.png"
-)
-
-qt_add_resources(tooltips "tooltips"
-    PREFIX
-        "/"
-    FILES
-        ${tooltips_resource_files}
-)
-
-install(TARGETS tooltips
-    RUNTIME DESTINATION "${INSTALL_EXAMPLEDIR}"
-    BUNDLE DESTINATION "${INSTALL_EXAMPLEDIR}"
-    LIBRARY DESTINATION "${INSTALL_EXAMPLEDIR}"
-)
diff --git a/examples/widgets/widgets/tooltips/images/circle.png b/examples/widgets/widgets/tooltips/images/circle.png
deleted file mode 100644
index dc392cb3f7..0000000000
--- a/examples/widgets/widgets/tooltips/images/circle.png
+++ /dev/null
diff --git a/examples/widgets/widgets/tooltips/images/square.png b/examples/widgets/widgets/tooltips/images/square.png
deleted file mode 100644
index c0fd2d540a..0000000000
--- a/examples/widgets/widgets/tooltips/images/square.png
+++ /dev/null
diff --git a/examples/widgets/widgets/tooltips/images/triangle.png b/examples/widgets/widgets/tooltips/images/triangle.png
deleted file mode 100644
index 2ee15f8f1f..0000000000
--- a/examples/widgets/widgets/tooltips/images/triangle.png
+++ /dev/null
diff --git a/examples/widgets/widgets/tooltips/main.cpp b/examples/widgets/widgets/tooltips/main.cpp
deleted file mode 100644
index 1cc7f435d5..0000000000
--- a/examples/widgets/widgets/tooltips/main.cpp
+++ /dev/null
@@ -1,14 +0,0 @@
-// Copyright (C) 2016 The Qt Company Ltd.
-// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
-
-#include <QApplication>
-
-#include "sortingbox.h"
-
-int main(int argc, char *argv[])
-{
-    QApplication app(argc, argv);
-    SortingBox sortingBox;
-    sortingBox.show();
-    return app.exec();
-}
diff --git a/examples/widgets/widgets/tooltips/shapeitem.cpp b/examples/widgets/widgets/tooltips/shapeitem.cpp
deleted file mode 100644
index c66c7ab958..0000000000
--- a/examples/widgets/widgets/tooltips/shapeitem.cpp
+++ /dev/null
@@ -1,60 +0,0 @@
-// Copyright (C) 2016 The Qt Company Ltd.
-// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
-
-#include "shapeitem.h"
-
-//! [0]
-QPainterPath ShapeItem::path() const
-{
-    return myPath;
-}
-//! [0]
-
-//! [1]
-QPoint ShapeItem::position() const
-{
-    return myPosition;
-}
-//! [1]
-
-//! [2]
-QColor ShapeItem::color() const
-{
-    return myColor;
-}
-//! [2]
-
-//! [3]
-QString ShapeItem::toolTip() const
-{
-    return myToolTip;
-}
-//! [3]
-
-//! [4]
-void ShapeItem::setPath(const QPainterPath &path)
-{
-    myPath = path;
-}
-//! [4]
-
-//! [5]
-void ShapeItem::setToolTip(const QString &toolTip)
-{
-    myToolTip = toolTip;
-}
-//! [5]
-
-//! [6]
-void ShapeItem::setPosition(const QPoint &position)
-{
-    myPosition = position;
-}
-//! [6]
-
-//! [7]
-void ShapeItem::setColor(const QColor &color)
-{
-    myColor = color;
-}
-//! [7]
diff --git a/examples/widgets/widgets/tooltips/shapeitem.h b/examples/widgets/widgets/tooltips/shapeitem.h
deleted file mode 100644
index 6c0643fa89..0000000000
--- a/examples/widgets/widgets/tooltips/shapeitem.h
+++ /dev/null
@@ -1,33 +0,0 @@
-// Copyright (C) 2016 The Qt Company Ltd.
-// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
-
-#ifndef SHAPEITEM_H
-#define SHAPEITEM_H
-
-#include <QColor>
-#include <QPainterPath>
-#include <QPoint>
-
-//! [0]
-class ShapeItem
-{
-public:
-    void setPath(const QPainterPath &path);
-    void setToolTip(const QString &toolTip);
-    void setPosition(const QPoint &position);
-    void setColor(const QColor &color);
-
-    QPainterPath path() const;
-    QPoint position() const;
-    QColor color() const;
-    QString toolTip() const;
-
-private:
-    QPainterPath myPath;
-    QPoint myPosition;
-    QColor myColor;
-    QString myToolTip;
-};
-//! [0]
-
-#endif
diff --git a/examples/widgets/widgets/tooltips/sortingbox.cpp b/examples/widgets/widgets/tooltips/sortingbox.cpp
deleted file mode 100644
index ee588eea56..0000000000
--- a/examples/widgets/widgets/tooltips/sortingbox.cpp
+++ /dev/null
@@ -1,277 +0,0 @@
-// Copyright (C) 2016 The Qt Company Ltd.
-// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
-
-#include "sortingbox.h"
-
-#include <QMouseEvent>
-#include <QIcon>
-#include <QPainter>
-#include <QRandomGenerator>
-#include <QStyle>
-#include <QToolButton>
-#include <QToolTip>
-
-//! [0]
-SortingBox::SortingBox(QWidget *parent)
-    : QWidget(parent)
-{
-//! [0] //! [1]
-    setMouseTracking(true);
-//! [1] //! [2]
-    setBackgroundRole(QPalette::Base);
-//! [2]
-
-    itemInMotion = nullptr;
-
-//! [3]
-    newCircleButton = createToolButton(tr("New Circle"),
-                                       QIcon(":/images/circle.png"),
-                                       &SortingBox::createNewCircle);
-
-    newSquareButton = createToolButton(tr("New Square"),
-                                       QIcon(":/images/square.png"),
-                                       &SortingBox::createNewSquare);
-
-    newTriangleButton = createToolButton(tr("New Triangle"),
-                                         QIcon(":/images/triangle.png"),
-                                         &SortingBox::createNewTriangle);
-
-    circlePath.addEllipse(QRect(0, 0, 100, 100));
-    squarePath.addRect(QRect(0, 0, 100, 100));
-
-    qreal x = trianglePath.currentPosition().x();
-    qreal y = trianglePath.currentPosition().y();
-    trianglePath.moveTo(x + 120 / 2, y);
-    trianglePath.lineTo(0, 100);
-    trianglePath.lineTo(120, 100);
-    trianglePath.lineTo(x + 120 / 2, y);
-
-//! [3] //! [4]
-    setWindowTitle(tr("Tool Tips"));
-    resize(500, 300);
-
-    createShapeItem(circlePath, tr("Circle"), initialItemPosition(circlePath),
-                    initialItemColor());
-    createShapeItem(squarePath, tr("Square"), initialItemPosition(squarePath),
-                    initialItemColor());
-    createShapeItem(trianglePath, tr("Triangle"),
-                    initialItemPosition(trianglePath), initialItemColor());
-}
-//! [4]
-
-//! [27]
-SortingBox::~SortingBox()
-{
-    qDeleteAll(shapeItems);
-}
-//! [27]
-
-//! [5]
-bool SortingBox::event(QEvent *event)
-{
-//! [5] //! [6]
-    if (event->type() == QEvent::ToolTip) {
-        QHelpEvent *helpEvent = static_cast<QHelpEvent *>(event);
-        int index = itemAt(helpEvent->pos());
-        if (index != -1) {
-            QToolTip::showText(helpEvent->globalPos(), shapeItems[index]->toolTip());
-        } else {
-            QToolTip::hideText();
-            event->ignore();
-        }
-
-        return true;
-    }
-    return QWidget::event(event);
-}
-//! [6]
-
-//! [7]
-void SortingBox::resizeEvent(QResizeEvent * /* event */)
-{
-    int margin = style()->pixelMetric(QStyle::PM_LayoutTopMargin);
-    int x = width() - margin;
-    int y = height() - margin;
-
-    y = updateButtonGeometry(newCircleButton, x, y);
-    y = updateButtonGeometry(newSquareButton, x, y);
-    updateButtonGeometry(newTriangleButton, x, y);
-}
-//! [7]
-
-//! [8]
-void SortingBox::paintEvent(QPaintEvent * /* event */)
-{
-    QPainter painter(this);
-    painter.setRenderHint(QPainter::Antialiasing);
-    for (const ShapeItem *shapeItem : std::as_const(shapeItems)) {
-//! [8] //! [9]
-        painter.translate(shapeItem->position());
-//! [9] //! [10]
-        painter.setBrush(shapeItem->color());
-        painter.drawPath(shapeItem->path());
-        painter.translate(-shapeItem->position());
-    }
-}
-//! [10]
-
-//! [11]
-void SortingBox::mousePressEvent(QMouseEvent *event)
-{
-    if (event->button() == Qt::LeftButton) {
-        int index = itemAt(event->position().toPoint());
-        if (index != -1) {
-            itemInMotion = shapeItems[index];
-            previousPosition = event->position().toPoint();
-            shapeItems.move(index, shapeItems.size() - 1);
-            update();
-        }
-    }
-}
-//! [11]
-
-//! [12]
-void SortingBox::mouseMoveEvent(QMouseEvent *event)
-{
-    if ((event->buttons() & Qt::LeftButton) && itemInMotion)
-        moveItemTo(event->position().toPoint());
-}
-//! [12]
-
-//! [13]
-void SortingBox::mouseReleaseEvent(QMouseEvent *event)
-{
-    if (event->button() == Qt::LeftButton && itemInMotion) {
-        moveItemTo(event->position().toPoint());
-        itemInMotion = nullptr;
-    }
-}
-//! [13]
-
-//! [14]
-void SortingBox::createNewCircle()
-{
-    static int count = 1;
-    createShapeItem(circlePath, tr("Circle <%1>").arg(++count),
-                    randomItemPosition(), randomItemColor());
-}
-//! [14]
-
-//! [15]
-void SortingBox::createNewSquare()
-{
-    static int count = 1;
-    createShapeItem(squarePath, tr("Square <%1>").arg(++count),
-                    randomItemPosition(), randomItemColor());
-}
-//! [15]
-
-//! [16]
-void SortingBox::createNewTriangle()
-{
-    static int count = 1;
-    createShapeItem(trianglePath, tr("Triangle <%1>").arg(++count),
-                    randomItemPosition(), randomItemColor());
-}
-//! [16]
-
-//! [17]
-qsizetype SortingBox::itemAt(const QPoint &pos)
-{
-    for (qsizetype i = shapeItems.size() - 1; i >= 0; --i) {
-        const ShapeItem *item = shapeItems[i];
-        if (item->path().contains(pos - item->position()))
-            return i;
-    }
-    return -1;
-}
-//! [17]
-
-//! [18]
-void SortingBox::moveItemTo(const QPoint &pos)
-{
-    QPoint offset = pos - previousPosition;
-    itemInMotion->setPosition(itemInMotion->position() + offset);
-//! [18] //! [19]
-    previousPosition = pos;
-    update();
-}
-//! [19]
-
-//! [20]
-int SortingBox::updateButtonGeometry(QToolButton *button, int x, int y)
-{
-    QSize size = button->sizeHint();
-    button->setGeometry(x - size.rwidth(), y - size.rheight(),
-                        size.rwidth(), size.rheight());
-
-    return y - size.rheight()
-           - style()->pixelMetric(QStyle::PM_LayoutVerticalSpacing);
-}
-//! [20]
-
-//! [21]
-void SortingBox::createShapeItem(const QPainterPath &path,
-                                 const QString &toolTip, const QPoint &pos,
-                                 const QColor &color)
-{
-    ShapeItem *shapeItem = new ShapeItem;
-    shapeItem->setPath(path);
-    shapeItem->setToolTip(toolTip);
-    shapeItem->setPosition(pos);
-    shapeItem->setColor(color);
-    shapeItems.append(shapeItem);
-    update();
-}
-//! [21]
-
-//! [22]
-template<typename PointerToMemberFunction>
-QToolButton *SortingBox::createToolButton(const QString &toolTip,
-                                          const QIcon &icon, const PointerToMemberFunction &member)
-{
-    QToolButton *button = new QToolButton(this);
-    button->setToolTip(toolTip);
-    button->setIcon(icon);
-    button->setIconSize(QSize(32, 32));
-    connect(button, &QToolButton::clicked, this, member);
-
-    return button;
-}
-//! [22]
-
-//! [23]
-QPoint SortingBox::initialItemPosition(const QPainterPath &path)
-{
-    int x;
-    int y = (height() - qRound(path.controlPointRect().height()) / 2);
-    if (shapeItems.size() == 0)
-        x = ((3 * width()) / 2 - qRound(path.controlPointRect().width())) / 2;
-    else
-        x = (width() / shapeItems.size()
-             - qRound(path.controlPointRect().width())) / 2;
-
-    return QPoint(x, y);
-}
-//! [23]
-
-//! [24]
-QPoint SortingBox::randomItemPosition()
-{
-    return QPoint(QRandomGenerator::global()->bounded(width() - 120), QRandomGenerator::global()->bounded(height() - 120));
-}
-//! [24]
-
-//! [25]
-QColor SortingBox::initialItemColor()
-{
-    return QColor::fromHsv(((shapeItems.size() + 1) * 85) % 256, 255, 190);
-}
-//! [25]
-
-//! [26]
-QColor SortingBox::randomItemColor()
-{
-    return QColor::fromHsv(QRandomGenerator::global()->bounded(256), 255, 190);
-}
-//! [26]
diff --git a/examples/widgets/widgets/tooltips/sortingbox.h b/examples/widgets/widgets/tooltips/sortingbox.h
deleted file mode 100644
index 9f34cf7ada..0000000000
--- a/examples/widgets/widgets/tooltips/sortingbox.h
+++ /dev/null
@@ -1,71 +0,0 @@
-// Copyright (C) 2016 The Qt Company Ltd.
-// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
-
-#ifndef SORTINGBOX_H
-#define SORTINGBOX_H
-
-#include "shapeitem.h"
-
-#include <QWidget>
-
-QT_BEGIN_NAMESPACE
-class QAction;
-class QPoint;
-class QToolButton;
-QT_END_NAMESPACE
-
-//! [0]
-class SortingBox : public QWidget
-{
-    Q_OBJECT
-
-public:
-    SortingBox(QWidget *parent = nullptr);
-    ~SortingBox();
-
-protected:
-    bool event(QEvent *event) override;
-    void resizeEvent(QResizeEvent *event) override;
-    void paintEvent(QPaintEvent *event) override;
-    void mousePressEvent(QMouseEvent *event) override;
-    void mouseMoveEvent(QMouseEvent *event) override;
-    void mouseReleaseEvent(QMouseEvent *event) override;
-
-private slots:
-    void createNewCircle();
-    void createNewSquare();
-    void createNewTriangle();
-//! [0]
-
-//! [1]
-private:
-    int updateButtonGeometry(QToolButton *button, int x, int y);
-    void createShapeItem(const QPainterPath &path, const QString &toolTip,
-                         const QPoint &pos, const QColor &color);
-    qsizetype itemAt(const QPoint &pos);
-    void moveItemTo(const QPoint &pos);
-    QPoint initialItemPosition(const QPainterPath &path);
-    QPoint randomItemPosition();
-    QColor initialItemColor();
-    QColor randomItemColor();
-    template<typename PointerToMemberFunction>
-    QToolButton *createToolButton(const QString &toolTip, const QIcon &icon,
-//! [1]
-                                  const PointerToMemberFunction &member);
-
-//! [2]
-    QList<ShapeItem *> shapeItems;
-    QPainterPath circlePath;
-    QPainterPath squarePath;
-    QPainterPath trianglePath;
-
-    QPoint previousPosition;
-    ShapeItem *itemInMotion;
-
-    QToolButton *newCircleButton;
-    QToolButton *newSquareButton;
-    QToolButton *newTriangleButton;
-};
-//! [2]
-
-#endif
diff --git a/examples/widgets/widgets/tooltips/tooltips.pro b/examples/widgets/widgets/tooltips/tooltips.pro
deleted file mode 100644
index d14b8295ba..0000000000
--- a/examples/widgets/widgets/tooltips/tooltips.pro
+++ /dev/null
@@ -1,12 +0,0 @@
-QT += widgets
-
-HEADERS       = shapeitem.h \
-                sortingbox.h
-SOURCES       = main.cpp \
-                shapeitem.cpp \
-                sortingbox.cpp
-RESOURCES     = tooltips.qrc
-
-# install
-target.path = $$[QT_INSTALL_EXAMPLES]/widgets/widgets/tooltips
-INSTALLS += target
diff --git a/examples/widgets/widgets/tooltips/tooltips.qrc b/examples/widgets/widgets/tooltips/tooltips.qrc
deleted file mode 100644
index dabc894e9b..0000000000
--- a/examples/widgets/widgets/tooltips/tooltips.qrc
+++ /dev/null
@@ -1,7 +0,0 @@
-<!DOCTYPE RCC><RCC version="1.0">
-<qresource>
-   <file>images/circle.png</file>
-   <file>images/square.png</file>
-   <file>images/triangle.png</file>
-</qresource>
-</RCC>
diff --git a/examples/widgets/widgets/widgets.pro b/examples/widgets/widgets/widgets.pro
index 7384b69743..9fe06d4d80 100644
--- a/examples/widgets/widgets/widgets.pro
+++ b/examples/widgets/widgets/widgets.pro
@@ -9,5 +9,4 @@ SUBDIRS       = analogclock \
                 sliders \
                 spinboxes \
                 tablet \
-                tooltips \
                 windowflags
diff --git a/src/widgets/doc/snippets/tooltips/main.cpp b/src/widgets/doc/snippets/tooltips/main.cpp
new file mode 100644
index 0000000000..94cc71f711
--- /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 2c68b029b0..2800f65ac6 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