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.
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

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

@ -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:

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

@ -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

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
\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
@ -2931,7 +2926,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
@ -3007,7 +3002,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
@ -3015,7 +3010,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.
@ -3115,7 +3110,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.
@ -3754,7 +3749,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.
@ -4509,7 +4504,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,
@ -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
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()
@ -8680,7 +8675,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.
@ -9717,7 +9712,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.)
@ -9743,7 +9738,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.)
@ -10005,7 +10000,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)}.
@ -11071,7 +11066,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.
@ -12694,7 +12689,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.