1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Doc: Revise QWidget docs

Browse Source 
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.5 6.2 5.15
Change-Id: Ibb3f367c4677f7e6615bc0cd39d0ffe921862cb9
Reviewed-by: Safiyyah Moosa <safiyyah.moosa@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
(cherry picked from commit 45c6ef02e7e730f7a0c7b5bccd96c4f9ca74e1a6)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
This commit is contained in:
Andreas Eliasson 2023-10-06 13:19:58 +02:00 committed by Qt Cherry-pick Bot
parent 87a3eeb26f
commit a6a9ac8539
4 changed files with 84 additions and 86 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
src/widgets/doc/src/qtwidgets-index.qdoc
View File

@ -22,11 +22,10 @@ interfaces
\image parent-child-widgets.png A parent widget containing various child widgets. \image parent-child-widgets.png A parent widget containing various child widgets.
The QWidget class provides the basic capability to render to the The QWidget class provides the basic capability to render to the
screen, and to handle user input events. All UI elements that Qt screen and to handle user input events. All UI elements that Qt
provides are either subclasses of QWidget, or are used in connection provides are either subclasses of QWidget or are used in connection
with a QWidget subclass. Creating custom widgets is done by with a QWidget subclass. To create custom widgets, subclass QWidget or a
subclassing QWidget or a suitable subclass and reimplementing the suitable subclass and reimplement the virtual event handlers.
virtual event handlers.
\list \list
\li \l{Window and Dialog Widgets} \li \l{Window and Dialog Widgets}
@ -49,8 +48,9 @@ interfaces
\li \image macos-tabwidget.png \li \image macos-tabwidget.png
\endtable \endtable
\l{Qt Style Sheets} are a powerful mechanism that allows you to customize the \l{Qt Style Sheets} are a powerful mechanism that lets you customize
appearance of widgets, in addition to what is already possible by subclassing QStyle. the appearance of widgets, in addition to what is already possible by
subclassing QStyle.
\section1 Layouts \section1 Layouts

4
src/widgets/doc/src/widgets-and-layouts/focus.qdoc
View File

@ -9,7 +9,7 @@
\keyword keyboard focus \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. customary in GUIs.
The basic issue is that the user's key strokes can be directed at any The basic issue is that the user's key strokes can be directed at any
@ -22,7 +22,7 @@
\section1 Focus Motion \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: particular widget are these:
\list 1 \list 1

61
src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc
View File

@ -6,18 +6,20 @@
\brief Windows and Dialogs in Qt. \brief Windows and Dialogs in Qt.
\ingroup qt-gui-concepts \ingroup qt-gui-concepts
A \l{Widgets Tutorial}{widget} that is not embedded in a parent widget is called a window. A \l{Widgets Tutorial}{widget} that is not embedded in a parent widget is
(Usually, windows have a frame and a title bar, although it is also possible to create called a window. Usually, windows have a frame and a title bar, although it
windows without such decoration using suitable window flags). In Qt, QMainWindow is also possible to create windows without such decoration using suitable
and the various subclasses of QDialog are the most common window types. 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 In applications, windows provide the screen space upon which the user
interface is built. Windows separate applications visually from each other interface is built. Windows separate applications visually from each other
and usually provide a window decoration that allows the user to resize and and usually provide a window decoration that allows you to resize and
position the applications according to his preferences. Windows are typically position the applications according to your preferences. Windows are
integrated into the desktop environment and to some degree managed by the typically integrated into the desktop environment and to some degree managed
window management system that the desktop environment provides. For instance, by the window management system that the desktop environment provides. For
selected windows of an application are represented in the task bar. instance, selected windows of an application are represented in the task
bar.
\section1 Primary and Secondary Windows \section1 Primary and Secondary Windows
@ -27,8 +29,8 @@
In addition, a QWidget that has a parent can become a window by setting the In addition, a QWidget that has a parent can become a window by setting the
Qt::Window flag. Depending on the window management system Qt::Window flag. Depending on the window management system
such \e{secondary windows} are usually stacked on top of their respective parent such \e{secondary windows} are usually stacked on top of their respective
window, and not have a task bar entry of their own. parent window and do not have a task bar entry of their own.
The QMainWindow class sets the Qt::Window flag in its constructor, 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 as it is designed to be used as a window and provides facilities that are
@ -37,13 +39,14 @@
\section1 Main Windows and Dialogs \section1 Main Windows and Dialogs
The \l{Application Main Window} provides the framework for building the 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}, 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{QToolBar}{tool bars}, \l{QDockWidget}{dockable widgets} and a
\l{QStatusBar}{status bar}. The center area can be occupied by any kind of \l{QStatusBar}{status bar}. The center area can be occupied by any kind of
QWidget. 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 options and choices. Dialogs are created by subclassing QDialog and using
\l{Widgets and Layouts}{widgets and layouts} to implement the user interface. \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 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 QWidget provides several functions that deal with a widget's
geometry. Some of these functions operate on the pure client area geometry. Some of these functions operate on the pure client area
(i.e. the window excluding the window frame), others include the (that is, the window excluding the window frame), others include the
window frame. The differentiation is done in a way that covers the window frame. QWidget differentiates in a way that covers the
most common usage transparently. most common usage transparently.
\list \list
@ -99,9 +102,9 @@
Furthermore, a toolkit cannot simply place windows on the screen. All 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 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 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. differently in existing window managers.
X11 provides no standard or easy way to get the frame geometry X11 provides no standard or easy way to get the frame geometry
@ -137,8 +140,8 @@
\section1 Overview of the Main Window Classes \section1 Overview of the Main Window Classes
These classes provide everything you need for a typical modern main These classes provide everything you need for a typical modern main
application window, like the main window itself, menu and tool bars, application window, such as the main window itself, menu and tool bars,
a status bar, etc. and a status bar.
\annotatedlist mainwindow-classes \annotatedlist mainwindow-classes
@ -148,8 +151,8 @@
associated user interface components: associated user interface components:
\list \list
\li QMainWindow is the central class around which applications \li QMainWindow is the central class around which applications can be
can be built. Along with the companion QDockWidget and QToolBar built. Along with the companion QDockWidget and QToolBar
classes, it represents the top-level user interface of the application. classes, it represents the top-level user interface of the application.
\li QDockWidget provides a widget that can be used to create \li QDockWidget provides a widget that can be used to create
@ -166,11 +169,11 @@
\section1 Example Code \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 QMainWindow and set up menus, toolbars, and dock widgets inside
the QMainWindow constructor. 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 add them to the main window's menu bar. Note that the
QMainWindow::menuBar() function will automatically create the menu bar QMainWindow::menuBar() function will automatically create the menu bar
the first time it is called. You can also call the first time it is called. You can also call
@ -181,8 +184,8 @@
\snippet mainwindows/menus/mainwindow.cpp 5 \snippet mainwindows/menus/mainwindow.cpp 5
\dots \dots
Once actions have been created, we can add them to the main window Once actions have been created, you can add them to the main window
components. To begin with, we add them to the pop-up menus: components. To begin with, add them to the pop-up menus:
\snippet mainwindows/menus/mainwindow.cpp 10 \snippet mainwindows/menus/mainwindow.cpp 10
\dots \dots
@ -195,7 +198,7 @@
provides this function, making it easy to reuse actions in different provides this function, making it easy to reuse actions in different
parts of the main window. This avoids unnecessary duplication of work. 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: actions to it:
\code \code
@ -212,7 +215,7 @@
newAct and \c openAct will be displayed both on the toolbar and in newAct and \c openAct will be displayed both on the toolbar and in
the file menu. 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 dock widget as a child of the main window, and add widgets as children
of the dock widget: of the dock widget:
@ -221,7 +224,7 @@
In this example, the dock widget can only be placed in the left and 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. 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 widget areas occupy the four corners of the dock widget area. If
required, the default can be changed with the required, the default can be changed with the
QMainWindow::setCorner() function: QMainWindow::setCorner() function:
@ -234,7 +237,7 @@
\image mainwindow-docks-example.png \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: is created and installed by using code similar to the following:
\snippet code/doc_src_qt4-mainwindow.cpp 3 \snippet code/doc_src_qt4-mainwindow.cpp 3

89
src/widgets/kernel/qwidget.cpp
View File

@ -357,14 +357,14 @@ void QWidget::setAutoFillBackground(bool enabled)
If not, it will be a child of \e parent, and be constrained by 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). \e parent's geometry (unless you specify Qt::Window as window flag).
\li \c{Qt::WindowFlags f = { }} (where available) sets the window flags; \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 example, a window without a window system frame, you must use
special flags. special flags.
\endlist \endlist
QWidget has many member functions, but some of them have little direct QWidget has many member functions, but some of them have little direct
functionality; for example, QWidget has a font property, but never uses 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. 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 A widget without a parent widget is always an independent window (top-level
widget). For these widgets, setWindowTitle() and setWindowIcon() set the 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 Non-window widgets are child widgets, displayed within their parent
widgets. Most widgets in Qt are mainly useful as child widgets. For 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 widgets in a layout provided by QGridLayout. The QLabel child widgets have
been outlined to indicate their full sizes. 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 add a layout to the parent QWidget. See \l{Layout Management} for more
information. 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 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 is known as a composite widget. These can be created by constructing a
widget with the required visual properties - a QFrame, for example - and widget with the required visual properties - a QFrame, for example - and
adding child widgets to it, usually managed by a layout. The above diagram adding child widgets to it, usually managed by a layout.
shows such a composite widget that was created using Qt Designer.
Composite widgets can also be created by subclassing a standard widget, Composite widgets can also be created by subclassing a standard widget,
such as QWidget or QFrame, and adding the necessary layout and child 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() Each widget performs all painting operations from within its paintEvent()
function. This is called whenever the widget needs to be redrawn, either 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 The \l{widgets/analogclock}{Analog Clock example} shows how a simple widget
can handle paint events. 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 sizeHint() to provide a reasonable default size for the widget and to set
the correct size policy with setSizePolicy(). 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. sized according to the space requirements of their child widgets.
The size policy lets you supply good default behavior for the layout 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 delivers events to widgets by calling specific event handler functions with
instances of QEvent subclasses containing information about each event. 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 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(). mousePressEvent().
The \l{widgets/scribble}{Scribble example} implements a wider set of 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 space. (This excludes screen space owned by any of the widget's
children.) children.)
\li leaveEvent() is called when the mouse leaves the widget's screen \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(). leaveEvent().
\li moveEvent() is called when the widget has been moved relative to \li moveEvent() is called when the widget has been moved relative to
its parent. its parent.
@ -667,11 +666,11 @@ void QWidget::setAutoFillBackground(bool enabled)
\section1 Transparency and Double Buffering \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 is no need to write double-buffering code in paintEvent() to avoid
flicker. 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 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 set. Custom widgets can be written to take advantage of this feature by
updating irregular regions (to create non-rectangular child widgets), or updating irregular regions (to create non-rectangular child widgets), or
@ -688,7 +687,7 @@ void QWidget::setAutoFillBackground(bool enabled)
\list \list
\li The left widget has no additional properties or widget attributes \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 transparency, are irregularly-shaped, or do not paint over their
entire area with an opaque brush. entire area with an opaque brush.
\li The center widget has the \l autoFillBackground property set. This \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 set. This indicates that the widget will paint over its entire area
with opaque colors. The widget's area will initially be with opaque colors. The widget's area will initially be
\e{uninitialized}, represented in the diagram with a red diagonal \e{uninitialized}, represented in the diagram with a red diagonal
grid pattern that shines through the overpainted area. The grid pattern that shines through the overpainted area.
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.
\endlist \endlist
To rapidly update custom widgets with simple background colors, such as 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(). implement the necessary drawing functionality in the widget's paintEvent().
To rapidly update custom widgets that constantly paint over their entire To rapidly update custom widgets that constantly paint over their entire
areas with opaque content, e.g., video streaming widgets, it is better to areas with opaque content, for example, video streaming widgets, it is
set the widget's Qt::WA_OpaquePaintEvent, avoiding any unnecessary overhead better to set the widget's Qt::WA_OpaquePaintEvent, avoiding any unnecessary
associated with repainting the widget's background. overhead associated with repainting the widget's background.
If a widget has both the Qt::WA_OpaquePaintEvent widget attribute \e{and} If a widget has both the Qt::WA_OpaquePaintEvent widget attribute \e{and}
the \l autoFillBackground property set, the Qt::WA_OpaquePaintEvent the \l autoFillBackground property set, the Qt::WA_OpaquePaintEvent
attribute takes precedence. Depending on your requirements, you should attribute takes precedence. Depending on your requirements, you should
choose either one of them. choose either one of them.
Since Qt 4.1, the contents of parent widgets are also propagated to The contents of parent widgets are also propagated to standard Qt widgets.
standard Qt widgets. This can lead to some unexpected results if the This can lead to some unexpected results if the parent widget is decorated
parent widget is decorated in a non-standard way, as shown in the diagram in a non-standard way, as shown in the diagram below.
below.
\image propagation-standard.png \image propagation-standard.png
@ -736,8 +731,8 @@ void QWidget::setAutoFillBackground(bool enabled)
\section1 Creating Translucent Windows \section1 Creating Translucent Windows
Since Qt 4.5, it has been possible to create windows with translucent regions You can create windows with translucent regions on window systems that
on window systems that support compositing. support compositing.
To enable this feature in a top-level widget, set its Qt::WA_TranslucentBackground 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 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 \section1 Native Widgets vs Alien Widgets
Introduced in Qt 4.4, alien widgets are widgets unknown to the windowing Alien widgets are widgets unknown to the windowing system. They do not have
system. They do not have a native window handle associated with them. This a native window handle associated with them. This feature significantly
feature significantly speeds up widget painting, resizing, and removes flicker. speeds up widget painting, resizing, and removes flicker.
Should you require the old behavior with native windows, you can choose Should you require the old behavior with native windows, choose one of the
one of the following options: following options:
\list 1 \list 1
\li Use the \c{QT_USE_NATIVE_WINDOWS=1} in your environment. \li Use the \c{QT_USE_NATIVE_WINDOWS=1} in your environment.
\li Set the Qt::AA_NativeWindows attribute on your application. All \li Set the Qt::AA_NativeWindows attribute on your application. All
widgets will be native widgets. widgets will be native widgets.
\li Set the Qt::WA_NativeWindow attribute on widgets: The widget itself \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). Qt::WA_DontCreateNativeAncestors is set).
\li Call QWidget::winId to enforce a native window (this implies 3). \li Call QWidget::winId to enforce a native window (this implies 3).
\li Set the Qt::WA_PaintOnScreen attribute to enforce a native window \li Set the Qt::WA_PaintOnScreen attribute to enforce a native window
@ -2931,7 +2926,7 @@ void QWidget::overrideWindowState(Qt::WindowStates newstate)
\snippet code/src_gui_kernel_qwidget.cpp 0 \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: preserving its maximized and/or full-screen state), use the following:
\snippet code/src_gui_kernel_qwidget.cpp 1 \snippet code/src_gui_kernel_qwidget.cpp 1
@ -3007,7 +3002,7 @@ bool QWidget::isFullScreen() const
ICCCM protocol that specifies the communication between X11 ICCCM protocol that specifies the communication between X11
clients and the window manager. ICCCM simply does not understand clients and the window manager. ICCCM simply does not understand
the concept of non-decorated full-screen windows. Therefore, the 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 resize it to fill the entire screen. Depending on the window
manager, this may or may not work. The borderless window is manager, this may or may not work. The borderless window is
requested using MOTIF hints, which are at least partially requested using MOTIF hints, which are at least partially
@ -3015,7 +3010,7 @@ bool QWidget::isFullScreen() const
An alternative would be to bypass the window manager entirely and An alternative would be to bypass the window manager entirely and
create a window with the Qt::X11BypassWindowManagerHint flag. This 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 and very strange effects on desktop changes or when the user raises
other windows. other windows.
@ -3115,7 +3110,7 @@ bool QWidget::isEnabledTo(const QWidget *ancestor) const
/*! /*!
Appends the action \a action to this widget's list of actions. 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 represented graphically in many different ways. The default use of
the QAction list (as returned by actions()) is to create a context the QAction list (as returned by actions()) is to create a context
QMenu. QMenu.
@ -3754,7 +3749,7 @@ QRegion QWidget::childrenRegion() const
the current size is smaller. the current size is smaller.
The minimum size set by this function will override the minimum size 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)}. value of \c{QSize(0, 0)}.
By default, this property contains a size with zero width and height. By default, this property contains a size with zero width and height.
@ -4509,7 +4504,7 @@ void QWidget::setForegroundRole(QPalette::ColorRole role)
QWidget's palette propagation is similar to its font propagation. QWidget's palette propagation is similar to its font propagation.
The current style, which is used to render the content of all standard Qt 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 in some cases, to ignore the palette (partially, or completely). In
particular, certain styles like GTK style, Mac style, and Windows Vista particular, certain styles like GTK style, Mac style, and Windows Vista
style, depend on third party APIs to render the content of widgets, style, depend on third party APIs to render the content of widgets,
@ -6702,8 +6697,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 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. lost the focus.
This widget must enable focus setting in order to get the keyboard This widget must enable focus setting to get the keyboard
input focus, i.e. it must call setFocusPolicy(). input focus; that is, it must call setFocusPolicy().
\sa hasFocus(), setFocus(), focusInEvent(), focusOutEvent(), \sa hasFocus(), setFocus(), focusInEvent(), focusOutEvent(),
setFocusPolicy(), QApplication::focusWidget() setFocusPolicy(), QApplication::focusWidget()
@ -8680,7 +8675,7 @@ bool QWidgetPrivate::close()
when the user minimizes the window, and a spontaneous show event when the user minimizes the window, and a spontaneous show event
when the window is restored again. 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 you need to change some settings before a widget is shown, use
showEvent() instead. If you need to do some delayed initialization showEvent() instead. If you need to do some delayed initialization
use the Polish event delivered to the event() function. use the Polish event delivered to the event() function.
@ -9717,7 +9712,7 @@ void QWidget::keyReleaseEvent(QKeyEvent *event)
is passed in the \a event parameter is passed in the \a event parameter
A widget normally must setFocusPolicy() to something other than 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 application programmer can call setFocus() on any widget, even
those that do not normally accept focus.) those that do not normally accept focus.)
@ -9743,7 +9738,7 @@ void QWidget::focusInEvent(QFocusEvent *)
passed in the \a event parameter. passed in the \a event parameter.
A widget normally must setFocusPolicy() to something other than 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 application programmer can call setFocus() on any widget, even
those that do not normally accept focus.) those that do not normally accept focus.)
@ -10005,7 +10000,7 @@ QVariant QWidget::inputMethodQuery(Qt::InputMethodQuery query) const
is set, the input method may change its visual components to reflect is set, the input method may change its visual components to reflect
that only numbers can be entered. 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)} intended. To set a flag, do \c{w->setInputMethodHints(w->inputMethodHints()|f)}
instead of \c{w->setInputMethodHints(f)}. instead of \c{w->setInputMethodHints(f)}.
@ -11071,7 +11066,7 @@ void QWidgetPrivate::scroll_sys(int dx, int dy, const QRect &r)
unless updates are disabled or the widget is hidden. unless updates are disabled or the widget is hidden.
We suggest only using repaint() if you need an immediate repaint, 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 is better, as it permits Qt to optimize for speed and minimize
flicker. flicker.
@ -12694,7 +12689,7 @@ static void releaseMouseGrabOfWidget(QWidget *widget)
terminal. Use this function with extreme caution, and consider terminal. Use this function with extreme caution, and consider
using the \c -nograb command line option while debugging. 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 Qt grabs and releases it sensibly. In particular, Qt grabs the
mouse when a mouse button is pressed and keeps it until the last mouse when a mouse button is pressed and keeps it until the last
button is released. button is released.