Doc: Revise QWidget docs

Reviewing and improving the docs for QWidget is part of the objectives
for the 2023 Q4 OKRs.

Most of the work in this patch is fixing grammatical errors and typos.
It is tempting to move much, if not all, of the Detailed Description content from the QWidget class reference page (qwidget.cpp) into its own overview/explanation page, which would be more in line with the diátaxis framework. But I think that should be a different patch.

Fixes: QTBUG-117758
Pick-to: 6.6 6.5 6.2 5.15
Change-Id: Ibb3f367c4677f7e6615bc0cd39d0ffe921862cb9
Reviewed-by: Safiyyah Moosa <safiyyah.moosa@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

4 files changed, 84 insertions, 86 deletions

diff --git a/src/widgets/doc/src/qtwidgets-index.qdoc b/src/widgets/doc/src/qtwidgets-index.qdoc
index c0fa5cf3e0..bbc32aa54a 100644
--- a/src/widgets/doc/src/qtwidgets-index.qdoc
+++ b/src/widgets/doc/src/qtwidgets-index.qdoc
@@ -22,11 +22,10 @@ interfaces
     \image parent-child-widgets.png A parent widget containing various child widgets.
 
     The QWidget class provides the basic capability to render to the
-    screen, and to handle user input events. All UI elements that Qt
-    provides are either subclasses of QWidget, or are used in connection
-    with a QWidget subclass. Creating custom widgets is done by
-    subclassing QWidget or a suitable subclass and reimplementing the
-    virtual event handlers.
+    screen and to handle user input events. All UI elements that Qt
+    provides are either subclasses of QWidget or are used in connection
+    with a QWidget subclass. To create custom widgets, subclass QWidget or a
+    suitable subclass and reimplement the virtual event handlers.
 
     \list
     \li \l{Window and Dialog Widgets}
@@ -49,8 +48,9 @@ interfaces
     \li \image macos-tabwidget.png
     \endtable
 
-    \l{Qt Style Sheets} are a powerful mechanism that allows you to customize the
-    appearance of widgets, in addition to what is already possible by subclassing QStyle.
+    \l{Qt Style Sheets} are a powerful mechanism that lets you customize
+    the appearance of widgets, in addition to what is already possible by
+    subclassing QStyle.
 
 
     \section1 Layouts
diff --git a/src/widgets/doc/src/widgets-and-layouts/focus.qdoc b/src/widgets/doc/src/widgets-and-layouts/focus.qdoc
index 6cd8e58543..22ef1bc9dd 100644
--- a/src/widgets/doc/src/widgets-and-layouts/focus.qdoc
+++ b/src/widgets/doc/src/widgets-and-layouts/focus.qdoc
@@ -9,7 +9,7 @@
 
     \keyword keyboard focus
 
-    Qt's widgets handle keyboard focus in the ways that have become
+    Qt's widgets handle keyboard focus in ways that have become
     customary in GUIs.
 
     The basic issue is that the user's key strokes can be directed at any
@@ -22,7 +22,7 @@
 
     \section1 Focus Motion
 
-    The customs which have evolved for directing keyboard focus to a
+    The customs that have evolved for directing keyboard focus to a
     particular widget are these:
 
     \list 1
@@ -63,7 +63,7 @@
     handler that moves the focus.
 
     For example, in a data entry dialog, there might be a field that
-    is only necessary in one per cent of all cases. In such a dialog,
+    is only necessary in one percent of all cases. In such a dialog,
     \uicontrol Tab could skip this field, and the dialog could use one of
     these mechanisms:
 
diff --git a/src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc b/src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc
index 827f7981ae..8e3db64de0 100644
--- a/src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc
+++ b/src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc
@@ -6,18 +6,20 @@
     \brief Windows and Dialogs in Qt.
     \ingroup qt-gui-concepts
 
-    A \l{Widgets Tutorial}{widget} that is not embedded in a parent widget is called a window.
-    (Usually, windows have a frame and a title bar, although it is also possible to create
-    windows without such decoration using suitable window flags). In Qt, QMainWindow
-    and the various subclasses of QDialog are the most common window types.
+    A \l{Widgets Tutorial}{widget} that is not embedded in a parent widget is
+    called a window. Usually, windows have a frame and a title bar, although it
+    is also possible to create windows without such decoration using suitable
+    window flags. In Qt, QMainWindow and the various subclasses of QDialog are
+    the most common window types.
 
     In applications, windows provide the screen space upon which the user
     interface is built. Windows separate applications visually from each other
-    and usually provide a window decoration that allows the user to resize and
-    position the applications according to his preferences. Windows are typically
-    integrated into the desktop environment and to some degree managed by the
-    window management system that the desktop environment provides. For instance,
-    selected windows of an application are represented in the task bar.
+    and usually provide a window decoration that allows you to resize and
+    position the applications according to your preferences. Windows are
+    typically integrated into the desktop environment and to some degree managed
+    by the window management system that the desktop environment provides. For
+    instance, selected windows of an application are represented in the task
+    bar.
 
     \section1 Primary and Secondary Windows
 
@@ -27,8 +29,8 @@
 
     In addition, a QWidget that has a parent can become a window by setting the
     Qt::Window flag. Depending on the window management system
-    such \e{secondary windows} are usually stacked on top of their respective parent
-    window, and not have a task bar entry of their own.
+    such \e{secondary windows} are usually stacked on top of their respective
+    parent window and do not have a task bar entry of their own.
 
     The QMainWindow class sets the Qt::Window flag in its constructor,
     as it is designed to be used as a window and provides facilities that are
@@ -37,13 +39,14 @@
     \section1 Main Windows and Dialogs
 
     The \l{Application Main Window} provides the framework for building the
-    application's main user interface, and are created by subclassing QMainWindow.
+    application's main user interface and are created by subclassing
+    QMainWindow.
     QMainWindow has its own layout to which you can add a \l{QMenuBar}{menu bar},
     \l{QToolBar}{tool bars}, \l{QDockWidget}{dockable widgets} and a
     \l{QStatusBar}{status bar}. The center area can be occupied by any kind of
     QWidget.
 
-    \l{Dialog Windows} are used as secondary windows that present the user with
+    \l{Dialog Windows} are used as secondary windows that present you with
     options and choices. Dialogs are created by subclassing QDialog and using
     \l{Widgets and Layouts}{widgets and layouts} to implement the user interface.
     In addition, Qt provides a number of ready-made standard dialogs that can be
@@ -59,8 +62,8 @@
 
     QWidget provides several functions that deal with a widget's
     geometry. Some of these functions operate on the pure client area
-    (i.e. the window excluding the window frame), others include the
-    window frame. The differentiation is done in a way that covers the
+    (that is, the window excluding the window frame), others include the
+    window frame. QWidget differentiates in a way that covers the
     most common usage transparently.
 
     \list
@@ -99,9 +102,9 @@
 
     Furthermore, a toolkit cannot simply place windows on the screen. All
     Qt can do is to send certain hints to the window manager. The window
-    manager, a separate process, may either obey, ignore or misunderstand
+    manager, a separate process, may either obey, ignore, or misunderstand
     them. Due to the partially unclear Inter-Client Communication
-    Conventions Manual (ICCCM), window placement is handled quite
+    Conventions Manual (ICCCM), window placement is handled
     differently in existing window managers.
 
     X11 provides no standard or easy way to get the frame geometry
@@ -137,8 +140,8 @@
     \section1 Overview of the Main Window Classes
 
     These classes provide everything you need for a typical modern main
-    application window, like the main window itself, menu and tool bars,
-    a status bar, etc.
+    application window, such as the main window itself, menu and tool bars,
+    and a status bar.
 
     \annotatedlist mainwindow-classes
 
@@ -148,8 +151,8 @@
     associated user interface components:
 
     \list
-    \li QMainWindow is the central class around which applications
-       can be built. Along with the companion QDockWidget and QToolBar
+    \li QMainWindow is the central class around which applications can be
+       built. Along with the companion QDockWidget and QToolBar
        classes, it represents the top-level user interface of the application.
 
     \li QDockWidget provides a widget that can be used to create
@@ -166,11 +169,11 @@
 
     \section1 Example Code
 
-    Using QMainWindow is straightforward. Generally, we subclass
+    Using QMainWindow is straightforward. Generally, you subclass
     QMainWindow and set up menus, toolbars, and dock widgets inside
     the QMainWindow constructor.
 
-    To add a menu bar to the main window, we simply create the menus, and
+    To add a menu bar to the main window, create the menus, and
     add them to the main window's menu bar. Note that the
     QMainWindow::menuBar() function will automatically create the menu bar
     the first time it is called. You can also call
@@ -181,8 +184,8 @@
     \snippet mainwindows/menus/mainwindow.cpp 5
     \dots
 
-    Once actions have been created, we can add them to the main window
-    components. To begin with, we add them to the pop-up menus:
+    Once actions have been created, you can add them to the main window
+    components. To begin with, add them to the pop-up menus:
 
     \snippet mainwindows/menus/mainwindow.cpp 10
     \dots
@@ -195,7 +198,7 @@
     provides this function, making it easy to reuse actions in different
     parts of the main window. This avoids unnecessary duplication of work.
 
-    We create a toolbar as a child of the main window, and add the desired
+    Create a toolbar as a child of the main window, and add the desired
     actions to it:
 
     \code
@@ -212,7 +215,7 @@
     newAct and \c openAct will be displayed both on the toolbar and in
     the file menu.
 
-    QDockWidget is used in a similar way to QToolBar. We create a
+    QDockWidget is used in a similar way to QToolBar. You create a
     dock widget as a child of the main window, and add widgets as children
     of the dock widget:
 
@@ -221,7 +224,7 @@
     In this example, the dock widget can only be placed in the left and
     right dock areas, and it is initially placed in the left dock area.
 
-    The QMainWindow API allows the programmer to customize which dock
+    The QMainWindow API lets you customize which dock
     widget areas occupy the four corners of the dock widget area. If
     required, the default can be changed with the
     QMainWindow::setCorner() function:
@@ -234,7 +237,7 @@
 
     \image mainwindow-docks-example.png
 
-    Once all of the main window components have been set up, the central widget
+    Once all the main window components have been set up, the central widget
     is created and installed by using code similar to the following:
 
     \snippet code/doc_src_qt4-mainwindow.cpp 3
diff --git a/src/widgets/kernel/qwidget.cpp b/src/widgets/kernel/qwidget.cpp
index d2b7143434..fc8dec1ca7 100644
--- a/src/widgets/kernel/qwidget.cpp
+++ b/src/widgets/kernel/qwidget.cpp
@@ -357,14 +357,14 @@ void QWidget::setAutoFillBackground(bool enabled)
             If not, it will be a child of \e parent, and be constrained by
             \e parent's geometry (unless you specify Qt::Window as window flag).
         \li  \c{Qt::WindowFlags f = { }} (where available) sets the window flags;
-            the default is suitable for almost all widgets, but to get, for
+            the default is suitable for most widgets, but to get, for
             example, a window without a window system frame, you must use
             special flags.
     \endlist
 
     QWidget has many member functions, but some of them have little direct
     functionality; for example, QWidget has a font property, but never uses
-    this itself. There are many subclasses which provide real functionality,
+    this itself. There are many subclasses that provide real functionality,
     such as QLabel, QPushButton, QListWidget, and QTabWidget.
 
 
@@ -372,7 +372,7 @@ void QWidget::setAutoFillBackground(bool enabled)
 
     A widget without a parent widget is always an independent window (top-level
     widget). For these widgets, setWindowTitle() and setWindowIcon() set the
-    title bar and icon respectively.
+    title bar and icon, respectively.
 
     Non-window widgets are child widgets, displayed within their parent
     widgets. Most widgets in Qt are mainly useful as child widgets. For
@@ -385,7 +385,7 @@ void QWidget::setAutoFillBackground(bool enabled)
     widgets in a layout provided by QGridLayout. The QLabel child widgets have
     been outlined to indicate their full sizes.
 
-    If you want to use a QWidget to hold child widgets you will usually want to
+    If you want to use a QWidget to hold child widgets, you will usually want to
     add a layout to the parent QWidget. See \l{Layout Management} for more
     information.
 
@@ -395,8 +395,7 @@ void QWidget::setAutoFillBackground(bool enabled)
     When a widget is used as a container to group a number of child widgets, it
     is known as a composite widget. These can be created by constructing a
     widget with the required visual properties - a QFrame, for example - and
-    adding child widgets to it, usually managed by a layout. The above diagram
-    shows such a composite widget that was created using Qt Designer.
+    adding child widgets to it, usually managed by a layout.
 
     Composite widgets can also be created by subclassing a standard widget,
     such as QWidget or QFrame, and adding the necessary layout and child
@@ -416,7 +415,7 @@ void QWidget::setAutoFillBackground(bool enabled)
 
     Each widget performs all painting operations from within its paintEvent()
     function. This is called whenever the widget needs to be redrawn, either
-    as a result of some external change or when requested by the application.
+    because of some external change or when requested by the application.
 
     The \l{widgets/analogclock}{Analog Clock example} shows how a simple widget
     can handle paint events.
@@ -428,7 +427,7 @@ void QWidget::setAutoFillBackground(bool enabled)
     sizeHint() to provide a reasonable default size for the widget and to set
     the correct size policy with setSizePolicy().
 
-    By default, composite widgets which do not provide a size hint will be
+    By default, composite widgets that do not provide a size hint will be
     sized according to the space requirements of their child widgets.
 
     The size policy lets you supply good default behavior for the layout
@@ -448,9 +447,9 @@ void QWidget::setAutoFillBackground(bool enabled)
     delivers events to widgets by calling specific event handler functions with
     instances of QEvent subclasses containing information about each event.
 
-    If your widget only contains child widgets, you probably do not need to
+    If your widget only contains child widgets, you probably don't need to
     implement any event handlers. If you want to detect a mouse click in a
-    child widget call the child's underMouse() function inside the widget's
+    child widget, call the child's underMouse() function inside the widget's
     mousePressEvent().
 
     The \l{widgets/scribble}{Scribble example} implements a wider set of
@@ -529,7 +528,7 @@ void QWidget::setAutoFillBackground(bool enabled)
             space. (This excludes screen space owned by any of the widget's
             children.)
         \li  leaveEvent() is called when the mouse leaves the widget's screen
-            space. If the mouse enters a child widget it will not cause a
+            space. If the mouse enters a child widget, it will not cause a
             leaveEvent().
         \li  moveEvent() is called when the widget has been moved relative to
             its parent.
@@ -667,11 +666,11 @@ void QWidget::setAutoFillBackground(bool enabled)
 
     \section1 Transparency and Double Buffering
 
-    Since Qt 4.0, QWidget automatically double-buffers its painting, so there
+    QWidget automatically double-buffers its painting, so there
     is no need to write double-buffering code in paintEvent() to avoid
     flicker.
 
-    Since Qt 4.1, the contents of parent widgets are propagated by
+    The contents of parent widgets are propagated by
     default to each of their children as long as Qt::WA_PaintOnScreen is not
     set. Custom widgets can be written to take advantage of this feature by
     updating irregular regions (to create non-rectangular child widgets), or
@@ -688,7 +687,7 @@ void QWidget::setAutoFillBackground(bool enabled)
 
     \list
         \li  The left widget has no additional properties or widget attributes
-            set. This default state suits most custom widgets using
+            set. This default state suits most custom widgets that have
             transparency, are irregularly-shaped, or do not paint over their
             entire area with an opaque brush.
         \li  The center widget has the \l autoFillBackground property set. This
@@ -699,10 +698,7 @@ void QWidget::setAutoFillBackground(bool enabled)
             set. This indicates that the widget will paint over its entire area
             with opaque colors. The widget's area will initially be
             \e{uninitialized}, represented in the diagram with a red diagonal
-            grid pattern that shines through the overpainted area. The
-            Qt::WA_OpaquePaintArea attribute is useful for widgets that need to
-            paint their own specialized contents quickly and do not need a
-            default filled background.
+            grid pattern that shines through the overpainted area.
     \endlist
 
     To rapidly update custom widgets with simple background colors, such as
@@ -712,19 +708,18 @@ void QWidget::setAutoFillBackground(bool enabled)
     implement the necessary drawing functionality in the widget's paintEvent().
 
     To rapidly update custom widgets that constantly paint over their entire
-    areas with opaque content, e.g., video streaming widgets, it is better to
-    set the widget's Qt::WA_OpaquePaintEvent, avoiding any unnecessary overhead
-    associated with repainting the widget's background.
+    areas with opaque content, for example, video streaming widgets, it is
+    better to set the widget's Qt::WA_OpaquePaintEvent, avoiding any unnecessary
+    overhead associated with repainting the widget's background.
 
     If a widget has both the Qt::WA_OpaquePaintEvent widget attribute \e{and}
     the \l autoFillBackground property set, the Qt::WA_OpaquePaintEvent
     attribute takes precedence. Depending on your requirements, you should
     choose either one of them.
 
-    Since Qt 4.1, the contents of parent widgets are also propagated to
-    standard Qt widgets. This can lead to some unexpected results if the
-    parent widget is decorated in a non-standard way, as shown in the diagram
-    below.
+    The contents of parent widgets are also propagated to standard Qt widgets.
+    This can lead to some unexpected results if the parent widget is decorated
+    in a non-standard way, as shown in the diagram below.
 
     \image propagation-standard.png
 
@@ -736,8 +731,8 @@ void QWidget::setAutoFillBackground(bool enabled)
 
     \section1 Creating Translucent Windows
 
-    Since Qt 4.5, it has been possible to create windows with translucent regions
-    on window systems that support compositing.
+    You can create windows with translucent regions on window systems that
+    support compositing.
 
     To enable this feature in a top-level widget, set its Qt::WA_TranslucentBackground
     attribute with setAttribute() and ensure that its background is painted with
@@ -757,19 +752,19 @@ void QWidget::setAutoFillBackground(bool enabled)
 
     \section1 Native Widgets vs Alien Widgets
 
-    Introduced in Qt 4.4, alien widgets are widgets unknown to the windowing
-    system. They do not have a native window handle associated with them. This
-    feature significantly speeds up widget painting, resizing, and removes flicker.
+    Alien widgets are widgets unknown to the windowing system. They do not have
+    a native window handle associated with them. This feature significantly
+    speeds up widget painting, resizing, and removes flicker.
 
-    Should you require the old behavior with native windows, you can choose
-    one of the following options:
+    Should you require the old behavior with native windows, choose one of the
+    following options:
 
     \list 1
         \li  Use the \c{QT_USE_NATIVE_WINDOWS=1} in your environment.
         \li  Set the Qt::AA_NativeWindows attribute on your application. All
             widgets will be native widgets.
         \li  Set the Qt::WA_NativeWindow attribute on widgets: The widget itself
-            and all of its ancestors will become native (unless
+            and all its ancestors will become native (unless
             Qt::WA_DontCreateNativeAncestors is set).
         \li  Call QWidget::winId to enforce a native window (this implies 3).
         \li  Set the Qt::WA_PaintOnScreen attribute to enforce a native window
@@ -2925,7 +2920,7 @@ void QWidget::overrideWindowState(Qt::WindowStates newstate)
 
     \snippet code/src_gui_kernel_qwidget.cpp 0
 
-    In order to restore and activate a minimized window (while
+    To restore and activate a minimized window (while
     preserving its maximized and/or full-screen state), use the following:
 
     \snippet code/src_gui_kernel_qwidget.cpp 1
@@ -3001,7 +2996,7 @@ bool QWidget::isFullScreen() const
     ICCCM protocol that specifies the communication between X11
     clients and the window manager. ICCCM simply does not understand
     the concept of non-decorated full-screen windows. Therefore, the
-    best we can do is to request a borderless window and place and
+    best you can do is to request a borderless window and place and
     resize it to fill the entire screen. Depending on the window
     manager, this may or may not work. The borderless window is
     requested using MOTIF hints, which are at least partially
@@ -3009,7 +3004,7 @@ bool QWidget::isFullScreen() const
 
     An alternative would be to bypass the window manager entirely and
     create a window with the Qt::X11BypassWindowManagerHint flag. This
-    has other severe problems though, like totally broken keyboard focus
+    has other severe problems though, like broken keyboard focus
     and very strange effects on desktop changes or when the user raises
     other windows.
 
@@ -3109,7 +3104,7 @@ bool QWidget::isEnabledTo(const QWidget *ancestor) const
 /*!
     Appends the action \a action to this widget's list of actions.
 
-    All QWidgets have a list of \l{QAction}s, however they can be
+    All QWidgets have a list of \l{QAction}s. However, they can be
     represented graphically in many different ways. The default use of
     the QAction list (as returned by actions()) is to create a context
     QMenu.
@@ -3748,7 +3743,7 @@ QRegion QWidget::childrenRegion() const
     the current size is smaller.
 
     The minimum size set by this function will override the minimum size
-    defined by QLayout. In order to unset the minimum size, use a
+    defined by QLayout. To unset the minimum size, use a
     value of \c{QSize(0, 0)}.
 
     By default, this property contains a size with zero width and height.
@@ -4503,7 +4498,7 @@ void QWidget::setForegroundRole(QPalette::ColorRole role)
     QWidget's palette propagation is similar to its font propagation.
 
     The current style, which is used to render the content of all standard Qt
-    widgets, is free to choose colors and brushes from the widget palette, or
+    widgets, is free to choose colors and brushes from the widget palette, or,
     in some cases, to ignore the palette (partially, or completely). In
     particular, certain styles like GTK style, Mac style, and Windows Vista
     style, depend on third party APIs to render the content of widgets,
@@ -6696,8 +6691,8 @@ void QWidgetPrivate::updateFocusChild()
     If the widget has active focus, a \l{focusOutEvent()}{focus out event} is sent to this widget to tell it that it has
     lost the focus.
 
-    This widget must enable focus setting in order to get the keyboard
-    input focus, i.e. it must call setFocusPolicy().
+    This widget must enable focus setting to get the keyboard
+    input focus; that is, it must call setFocusPolicy().
 
     \sa hasFocus(), setFocus(), focusInEvent(), focusOutEvent(),
     setFocusPolicy(), QApplication::focusWidget()
@@ -8674,7 +8669,7 @@ bool QWidgetPrivate::close()
     when the user minimizes the window, and a spontaneous show event
     when the window is restored again.
 
-    You almost never have to reimplement the setVisible() function. If
+    You seldom have to reimplement the setVisible() function. If
     you need to change some settings before a widget is shown, use
     showEvent() instead. If you need to do some delayed initialization
     use the Polish event delivered to the event() function.
@@ -9711,7 +9706,7 @@ void QWidget::keyReleaseEvent(QKeyEvent *event)
     is passed in the \a event parameter
 
     A widget normally must setFocusPolicy() to something other than
-    Qt::NoFocus in order to receive focus events. (Note that the
+    Qt::NoFocus to receive focus events. (Note that the
     application programmer can call setFocus() on any widget, even
     those that do not normally accept focus.)
 
@@ -9737,7 +9732,7 @@ void QWidget::focusInEvent(QFocusEvent *)
     passed in the \a event parameter.
 
     A widget normally must setFocusPolicy() to something other than
-    Qt::NoFocus in order to receive focus events. (Note that the
+    Qt::NoFocus to receive focus events. (Note that the
     application programmer can call setFocus() on any widget, even
     those that do not normally accept focus.)
 
@@ -9999,7 +9994,7 @@ QVariant QWidget::inputMethodQuery(Qt::InputMethodQuery query) const
     is set, the input method may change its visual components to reflect
     that only numbers can be entered.
 
-    \warning Some widgets require certain flags in order to work as
+    \warning Some widgets require certain flags to work as
     intended. To set a flag, do \c{w->setInputMethodHints(w->inputMethodHints()|f)}
     instead of \c{w->setInputMethodHints(f)}.
 
@@ -11066,7 +11061,7 @@ void QWidgetPrivate::scroll_sys(int dx, int dy, const QRect &r)
     unless updates are disabled or the widget is hidden.
 
     We suggest only using repaint() if you need an immediate repaint,
-    for example during animation. In almost all circumstances update()
+    for example during animation. In most circumstances update()
     is better, as it permits Qt to optimize for speed and minimize
     flicker.
 
@@ -12689,7 +12684,7 @@ static void releaseMouseGrabOfWidget(QWidget *widget)
     terminal. Use this function with extreme caution, and consider
     using the \c -nograb command line option while debugging.
 
-    It is almost never necessary to grab the mouse when using Qt, as
+    It is seldom necessary to grab the mouse when using Qt, as
     Qt grabs and releases it sensibly. In particular, Qt grabs the
     mouse when a mouse button is pressed and keeps it until the last
     button is released.