1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5 \page widgets-tutorial.html
7 \title Widgets Tutorial
8 \brief This tutorial covers basic usage of widgets and layouts, showing how
9 they are used to build GUI applications.
11 \section1 Introduction
13 Widgets are the basic building blocks for graphical user interface
14 (GUI) applications built with Qt. Each GUI component (e.g.
15 buttons, labels, text editors) is a \l{QWidget}{widget} that is
16 placed somewhere within a user interface window, or is displayed
17 as an independent window. Each type of widget is provided by a
18 subclass of QWidget, which is itself a subclass of QObject.
20 QWidget is not an abstract class. It can be used as a container
21 for other widgets, and it can be subclassed with minimal effort to
22 create new, custom widgets. QWidget is often used to create a
23 window inside which other \l{QWidget}s are placed.
25 As with \l{QObject}s, \l{QWidget}s can be created with parent
26 objects to indicate ownership, ensuring that objects are deleted
27 when they are no longer used. With widgets, these parent-child
28 relationships have an additional meaning: each child widget is
29 displayed within the screen area occupied by its parent widget.
30 This means that when you delete a window widget, all the child
31 widgets it contains are also deleted.
33 \section1 Writing a Main Function
35 Many of the GUI examples provided with Qt follow the pattern of
36 having a \c{main.cpp} file, which contains the standard code to
37 initialize the application, plus any number of other source/header
38 files that contain the application logic and custom GUI components.
40 A typical \c main() function in \c{main.cpp} looks like this:
42 \snippet widgets-tutorial/template.cpp main.cpp body
44 First, a QApplication object is constructed, which can be
45 configured with arguments passed in from the command line. After
46 the widgets have been created and shown, QApplication::exec() is
47 called to start Qt's event loop. Control passes to Qt until this
48 function returns. Finally, \c{main()} returns the value returned
49 by QApplication::exec().
51 \section1 Simple Widget Examples
53 Each of these simple widget examples is written entirely within
54 the \c main() function.
57 \li \l {tutorials/widgets/toplevel} {Creating a window}
59 \li \l {tutorials/widgets/childwidget} {Creating child widgets}
61 \li \l {tutorials/widgets/windowlayout} {Using layouts}
63 \li \l {tutorials/widgets/nestedlayouts} {Nested layouts}
66 \section1 Real World Widget Examples
68 In these \l{Qt Widgets Examples} {more advanced examples}, the code
69 that creates the widgets and layouts is stored in other files. For
70 example, the GUI for a main window may be created in the
71 constructor of a QMainWindow subclass.
73 \section1 Building The Examples
75 If you installed a binary package to get Qt, or if you compiled Qt
76 yourself, the examples described in this tutorial should already
77 be built and ready to run. If you wish to modify and recompile
78 them, follow these steps:
82 \li From a command prompt, enter the directory containing the
83 example you have modified.
85 \li Type \c qmake and press \uicontrol{Return}. If this doesn't work,
86 make sure that the executable is on your path, or enter its
89 \li On Linux/Unix and \macos, type \c make and press
90 \uicontrol{Return}; on Windows with Visual Studio, type \c nmake and
91 press \uicontrol{Return}.
95 An executable file is created in the current directory. On
96 Windows, this file may be located in a \c debug or \c release
97 subdirectory. You can run this executable to see the example code
102 \example tutorials/widgets/toplevel
103 \title Widgets Tutorial - Creating a Window
104 \examplecategory {User Interface Components}
106 If a widget is created without a parent, it is treated as a window, or
107 \e{top-level widget}, when it is shown. Since it has no parent object to
108 ensure that it is deleted when no longer needed, it is up to the
109 developer to keep track of the top-level widgets in an application.
111 In the following example, we use QWidget to create and show a window with
114 \div {class="qt-code"}
117 \li \snippet tutorials/widgets/toplevel/main.cpp main program
118 \li \inlineimage widgets-tutorial-toplevel.png
122 To create a real GUI, we need to place widgets inside the window. To do
123 this, we pass a QWidget instance to a widget's constructor, as we will
124 demonstrate in the next part of this tutorial.
129 \example tutorials/widgets/childwidget
130 \title Widgets Tutorial - Child Widgets
131 \examplecategory {User Interface Components}
133 We can add a child widget to the window created in the previous example by
134 passing \c window as the parent to its constructor. In this case, we add a
135 button to the window and place it in a specific location:
137 \div {class="qt-code"}
140 \li \snippet tutorials/widgets/childwidget/main.cpp main program
142 \li \inlineimage widgets-tutorial-childwidget.png
146 The button is now a child of the window and will be deleted when the
147 window is destroyed. Note that hiding or closing the window does not
148 automatically destroy it. It will be destroyed when the example exits.
152 \example tutorials/widgets/windowlayout
153 \title Widgets Tutorial - Using Layouts
154 \examplecategory {User Interface Components}
156 Usually, child widgets are arranged inside a window using layout objects
157 rather than by specifying positions and sizes explicitly. Here, we
158 construct a label and line edit widget that we would like to arrange
161 \div {class="qt-code"}
164 \li \snippet tutorials/widgets/windowlayout/main.cpp main program
166 \li \inlineimage widgets-tutorial-windowlayout.png
170 The \c layout object we construct manages the positions and sizes of
171 widgets supplied to it with the \l{QHBoxLayout::}{addWidget()} function.
172 The layout itself is supplied to the window itself in the call to
173 \l{QWidget::}{setLayout()}. Layouts are only visible through the effects
174 they have on the widgets (and other layouts) they are responsible for
177 In the example above, the ownership of each widget is not immediately
178 clear. Since we construct the widgets and the layout without parent
179 objects, we would expect to see an empty window and two separate windows
180 containing a label and a line edit. However, when we tell the layout to
181 manage the label and line edit and set the layout on the window, both the
182 widgets and the layout itself are ''reparented'' to become children of
187 \example tutorials/widgets/nestedlayouts
188 \title Widgets Tutorial - Nested Layouts
189 \examplecategory {User Interface Components}
191 Just as widgets can contain other widgets, layouts can be used to provide
192 different levels of grouping for widgets. Here, we want to display a
193 label alongside a line edit at the top of a window, above a table view
194 showing the results of a query.
196 We achieve this by creating two layouts: \c{queryLayout} is a QHBoxLayout
197 that contains QLabel and QLineEdit widgets placed side-by-side;
198 \c{mainLayout} is a QVBoxLayout that contains \c{queryLayout} and a
199 QTableView arranged vertically.
201 \div {class="qt-code"}
204 \li \snippet tutorials/widgets/nestedlayouts/main.cpp first part
205 \snippet tutorials/widgets/nestedlayouts/main.cpp last part
206 \li \inlineimage widgets-tutorial-nestedlayouts.png
210 Note that we call the \c{mainLayout}'s \l{QBoxLayout::}{addLayout()}
211 function to insert the \c{queryLayout} above the \c{resultView} table.
213 We have omitted the code that sets up the model containing the data shown
214 by the QTableView widget, \c resultView. For completeness, we show this below.
216 As well as QHBoxLayout and QVBoxLayout, Qt also provides QGridLayout
217 and QFormLayout classes to help with more complex user interfaces.
218 These can be seen if you run \QD.
220 \section1 Setting up the Model
222 In the code above, we did not show where the table's data came from
223 because we wanted to concentrate on the use of layouts. Here, we see
224 that the model holds a number of items corresponding to rows, each of
225 which is set up to contain data for two columns.
227 \snippet tutorials/widgets/nestedlayouts/main.cpp set up the model
229 The use of models and views is covered in the
230 \l{Item Views Examples} and in the \l{Model/View Programming} overview.