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} are a powerful mechanism that lets you customize
53 the appearance of widgets, in addition to what is already possible by
54 subclassing QStyle.
55
56
57 \section1 Layouts
58
59 \l{Layout Management}{Layouts} are an elegant and flexible way to
60 automatically arrange child widgets within their container. Each
61 widget reports its size requirements to the layout through the
62 \l{QWidget::}{sizeHint} and \l{QWidget::}{sizePolicy} properties,
63 and the layout distributes the available space accordingly.
64
65 \table
66 \row
67 \li \image qgridlayout-with-5-children.png {5-children layout}
68 \li \image qformlayout-with-6-children.png {6-children layout}
69 \endtable
70
71 \l {Qt Widgets Designer} is a powerful tool for interactively creating and
72 arranging widgets in layouts.
73
74
75
76 \section1 Model/View Classes
77
78 The \l{Model/View Programming}{model/view} architecture provides classes
79 that manage the way data is presented to the user. Data-driven applications
80 which use lists and tables are structured to separate the data and view
81 using models, views, and delegates.
82
83 \image fusion-treeview.png {File directory using a tree view}
84
85 \section1 Graphics View
86
87 The \l{Graphics View Framework} is for managing and interacting with a large
88 number of custom-made 2D graphical items, and a view widget for visualizing
89 the items, with support for zooming and rotation.
90
91 \image graphicsview-items.png {Various shapes and graphics on a grid}
92
93 \section1 Using the Module
94
95 \include {module-use.qdocinc} {using the c++ api}
96
97 \section2 Building with CMake
98
99 \include {module-use.qdocinc} {building with cmake} {Widgets}
100
101 \section2 Building with qmake
102
103 \include {module-use.qdocinc} {building_with_qmake} {widgets}
104
105 \section1 Security Considerations
106
107 Several Qt Widgets classes deserialize or parse data that an application
108 can supply from any source, and Qt cannot verify its provenance. Give
109 particular consideration to the following:
110
111 \list
112 \li \l{QHeaderView#Security Considerations}{QHeaderView::restoreState()}
113 deserializes a versioned binary state blob.
114 \li \l{QFileDialog#Security Considerations}{QFileDialog::restoreState()}
115 likewise deserializes a binary state blob, which embeds a
116 QHeaderView state blob.
117 \li \l{QMainWindow#Security Considerations}{QMainWindow::restoreState()}
118 deserializes a binary state blob describing a recursively nested
119 toolbar and dock widget layout.
120 \li \l{QSplitter#Security Considerations}{QSplitter::restoreState()}
121 deserializes a binary state blob describing splitter sizes and
122 orientation.
123 \li \l{Qt Style Sheets#Security Considerations}{Qt Style Sheets} can
124 reference and load arbitrary local files through the \c{url()}
125 function.
126 \endlist
127
128 Only pass such APIs data that your application previously produced and
129 persisted itself (typically via QSettings), or that is otherwise fully
130 under your application's control.
131
132 \section1 Articles and Guides
133
134 \list
135 \li \l{Widgets Tutorial}
136 \li \l{Getting Started Programming with Qt Widgets}
137 \li \l{\QC: Tutorial: Qt Widgets application}
138 \li \l{\QVSC: Tutorial: Qt Widgets application}
139 \li \l{Model/View Tutorial}
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*/