Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
qtwidgets-index.qdoc
Go to the documentation of this file.
1// Copyright (C) 2020 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3
4/*!
5\page qtwidgets-index.html
6\title Qt Widgets
7\brief A module which provides a set of C++ technologies for building user
8interfaces.
9
10 The \l {Qt Widgets C++ Classes}{Qt Widgets Module} provides a set of UI
11 elements to create classic desktop-style user interfaces. See the
12 \l {User Interfaces} overview for more information on using widgets.
13
14 \section1 Widgets
15
16 Widgets are the primary elements for creating user interfaces in Qt.
17 \l{The Widget Classes}{Widgets} can display data and status information,
18 receive user input, and provide a container for other widgets that
19 should be grouped together. A widget that is not embedded in a
20 parent widget is called a \l{Window and Dialog Widgets} {window}.
21
22 \image parent-child-widgets.png
23 {Parent widget containing various child widgets}
24
25 The QWidget class provides the basic capability to render to the
26 screen and to handle user input events. All UI elements that Qt
27 provides are either subclasses of QWidget or are used in connection
28 with a QWidget subclass. To create custom widgets, subclass QWidget or a
29 suitable subclass and reimplement the virtual event handlers.
30
31 \list
32 \li \l{Window and Dialog Widgets}
33 \li \l{Application Main Window}
34 \li \l{Dialog Windows}
35 \li \l{Keyboard Focus in Widgets}
36 \endlist
37
38 \section1 Styles
39
40 \l{Styles and Style Aware Widgets}{Styles} draw on behalf of
41 widgets and encapsulate the look and feel of a GUI. Qt's built-in
42 widgets use the QStyle class to perform nearly all of their drawing,
43 ensuring that they look exactly like the equivalent native widgets.
44
45 \table
46 \row
47 \li \image windowsvista-tabwidget.png {Windows style tab widgets}
48 \li \image fusion-tabwidget.png {Fusion desktop style tab widgets}
49 \li \image macos-tabwidget.png {macOS style tab widgets}
50 \endtable
51
52 \l{Qt Style Sheets} customize the appearance of widgets with CSS-like
53 rules. \l{Styling Approaches for Qt Widgets} explains when to use a
54 style, \l{Qt Labs StyleKit}{StyleKit}, or a style sheet.
55
56 \section1 Layouts
57
58 \l{Layout Management}{Layouts} are an elegant and flexible way to
59 automatically arrange child widgets within their container. Each
60 widget reports its size requirements to the layout through the
61 \l{QWidget::}{sizeHint} and \l{QWidget::}{sizePolicy} properties,
62 and the layout distributes the available space accordingly.
63
64 \table
65 \row
66 \li \image qgridlayout-with-5-children.png {5-children layout}
67 \li \image qformlayout-with-6-children.png {6-children layout}
68 \endtable
69
70 \l {Qt Widgets Designer} is a powerful tool for interactively creating and
71 arranging widgets in layouts.
72
73
74
75 \section1 Model/View Classes
76
77 The \l{Model/View Programming}{model/view} architecture provides classes
78 that manage the way data is presented to the user. Data-driven applications
79 which use lists and tables are structured to separate the data and view
80 using models, views, and delegates.
81
82 \image fusion-treeview.png {File directory using a tree view}
83
84 \section1 Graphics View
85
86 The \l{Graphics View Framework} is for managing and interacting with a large
87 number of custom-made 2D graphical items, and a view widget for visualizing
88 the items, with support for zooming and rotation.
89
90 \image graphicsview-items.png {Various shapes and graphics on a grid}
91
92 \section1 Using the Module
93
94 \include {module-use.qdocinc} {using the c++ api}
95
96 \section2 Building with CMake
97
98 \include {module-use.qdocinc} {building with cmake} {Widgets}
99
100 \section2 Building with qmake
101
102 \include {module-use.qdocinc} {building_with_qmake} {widgets}
103
104 \section1 Security Considerations
105
106 Several Qt Widgets classes deserialize or parse data that an application
107 can supply from any source, and Qt cannot verify its provenance. Give
108 particular consideration to the following:
109
110 \list
111 \li \l{QHeaderView#Security Considerations}{QHeaderView::restoreState()}
112 deserializes a versioned binary state blob.
113 \li \l{QFileDialog#Security Considerations}{QFileDialog::restoreState()}
114 likewise deserializes a binary state blob, which embeds a
115 QHeaderView state blob.
116 \li \l{QMainWindow#Security Considerations}{QMainWindow::restoreState()}
117 deserializes a binary state blob describing a recursively nested
118 toolbar and dock widget layout.
119 \li \l{QSplitter#Security Considerations}{QSplitter::restoreState()}
120 deserializes a binary state blob describing splitter sizes and
121 orientation.
122 \li \l{Qt Style Sheets#Security Considerations}{Qt Style Sheets} can
123 reference and load arbitrary local files through the \c{url()}
124 function.
125 \endlist
126
127 Only pass such APIs data that your application previously produced and
128 persisted itself (typically via QSettings), or that is otherwise fully
129 under your application's control.
130
131 \section1 Articles and Guides
132
133 \list
134 \li \l{Widgets Tutorial}
135 \li \l{Getting Started Programming with Qt Widgets}
136 \li \l{\QC: Tutorial: Qt Widgets application}
137 \li \l{\QVSC: Tutorial: Qt Widgets application}
138 \li \l{Model/View Tutorial}
139 \li \l{Styling Approaches for Qt Widgets}
140 \endlist
141
142 \section1 Examples
143
144 \list
145 \li \l{Qt Widgets Examples}
146 \li \l{Layout Examples}
147 \li \l{Widget Tools Examples}
148 \endlist
149
150 \section1 API Reference
151
152 \list
153 \li \l{Qt Widgets C++ Classes}
154 \list
155 \li \l{Basic Widget Classes}
156 \li \l{Advanced Widget Classes}
157 \li \l{Abstract Widget Classes}
158 \li \l{Organizer Widget Classes}
159 \li \l{Graphics View Classes}
160 \li \l{Model/View Classes}
161 \li \l{Main Window and Related Classes}
162 \li \l{Widget Appearance and Style Related Classes}
163 \li \l{Layout Classes}
164 \endlist
165 \li \l{Qt Style Sheets Reference}
166 \endlist
167
168 \section1 Module Evolution
169
170 \l{Changes to Qt Widgets} lists important changes in the module API
171 and functionality that were done for the Qt 6 series of Qt.
172
173 \section1 Licenses
174
175 The Qt Widgets module is available under commercial licenses from \l{The Qt Company}.
176 In addition, it is available under free software licenses:
177 The \l{GNU Lesser General Public License, version 3}, or
178 the \l{GNU General Public License, version 2}.
179 See \l{Qt Licensing} for further details.
180*/