doc/src/widgets/widgets-tutorial.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:FDL$
  10 ** GNU Free Documentation License
  11 ** Alternatively, this file may be used under the terms of the GNU Free
  12 ** Documentation License version 1.3 as published by the Free Software
  13 ** Foundation and appearing in the file included in the packaging of
  14 ** this file.
  15 **
  16 ** Other Usage
  17 ** Alternatively, this file may be used in accordance with the terms
  18 ** and conditions contained in a signed written agreement between you
  19 ** and Nokia.
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \page widgets-tutorial.html
  30     \ingroup tutorials
  31     \title Widgets Tutorial
  32     \brief This tutorial covers basic usage of widgets and layouts, showing how
  33     they are used to build GUI applications.
  34
  35     \section1 Introduction
  36
  37     Widgets are the basic building blocks for graphical user interface
  38     (GUI) applications built with Qt. Each GUI component (e.g.
  39     buttons, labels, text editor) is a \l{QWidget}{widget} that is
  40     placed somewhere within a user interface window, or is displayed
  41     as an independent window. Each type of widge is provided by a
  42     subclass of QWidget, which is itself a subclass of QObject.
  43
  44     QWidget is not an abstract class. It can be used as a container
  45     for other widgets, and it can be subclassed with minimal effort to
  46     create new, custom widgets. QWidget is often used to create a
  47     window inside which other \l{QWidget}s are placed.
  48
  49     As with \l{QObject}s, \l{QWidget}s can be created with parent
  50     objects to indicate ownership, ensuring that objects are deleted
  51     when they are no longer used. With widgets, these parent-child
  52     relationships have an additional meaning: Each child widget is
  53     displayed within the screen area occupied by its parent widget.
  54     This means that when you delete a window widget, all the child
  55     widgets it contains are also deleted.
  56
  57     \section1 Writing a main Function
  58
  59     Many of the GUI examples provided with Qt follow the pattern of
  60     having a \c{main.cpp} file, which contains the standard code to
  61     initialize the application, plus any number of other source/header
  62     files that contain the application logic and custom GUI components.
  63
  64     A typical \c main() function in \c{main.cpp} looks like this:
  65
  66     \snippet doc/src/snippets/widgets-tutorial/template.cpp main.cpp body
  67
  68     First, a QApplication object is constructed, which can be
  69     configured with arguments passed in from the command line. After
  70     the widgets have been created and shown, QApplication::exec() is
  71     called to start Qt's event loop.  Control passes to Qt until this
  72     function returns. Finally, \c{main()} returns the value returned
  73     by QApplication::exec().
  74
  75     \section1 Simple widget examples
  76
  77     Each of theses simple widget examples is written entirely within
  78     the \c main() function.
  79
  80     \list
  81     \o \l {tutorials/widgets/toplevel} {Creating a window}
  82
  83     \o \l {tutorials/widgets/childwidget} {Creating child widgets}
  84
  85     \o \l {tutorials/widgets/windowlayout} {Using layouts}
  86
  87     \o \l {tutorials/widgets/nestedlayouts} {Nested layouts}
  88     \endlist
  89
  90     \section1 Real world widget examples
  91
  92     In these \l{Widget examples} {more advanced examples}, the code
  93     that creates the widgets and layouts is stored in other files. For
  94     example, the GUI for a main window may be created in the
  95     constructor of a QMainWindow subclass.
  96
  97     \section1 Building The Examples
  98
  99     If you installed a binary package to get Qt, or if you compiled Qt
 100     yourself, the examples described in this tutorial should already
 101     be built and ready to run. If you wish to modify and recompile
 102     them, follow these steps:
 103
 104     \list 1
 105
 106     \o From a command prompt, enter the directory containing the
 107        example you have modified.
 108
 109     \o Type \c qmake and press \key{Return}. If this doesn't work,
 110        make sure that the executable is on your path, or enter its
 111        full location.
 112
 113     \o On Linux/Unix and Mac OS X, type \c make and press
 114        \key{Return}; on Windows with Visual Studio, type \c nmake and
 115        press \key{Return}.
 116
 117     \endlist
 118
 119     An executable file is created in the current directory.  On
 120     Windows, this file may be located in a \c debug or \c release
 121     subdirectory. You can run this executable to see the example code
 122     at work.
 123 */
 124
 125 /*!
 126     \example tutorials/widgets/toplevel
 127     \title Widgets Tutorial - Creating a Window
 128
 129     If a widget is created without a parent, it is treated as a window, or
 130     \e{top-level widget}, when it is shown. Since it has no parent object to
 131     ensure that it is deleted when no longer needed, it is up to the
 132     developer to keep track of the top-level widgets in an application.
 133
 134     In the following example, we use QWidget to create and show a window with
 135     a default size:
 136
 137     \div {class="qt-code"}
 138     \table
 139     \row
 140     \o \snippet tutorials/widgets/toplevel/main.cpp main program
 141     \o \inlineimage widgets-tutorial-toplevel.png
 142     \endtable
 143     \enddiv
 144
 145     To create a real GUI, we need to place widgets inside the window. To do
 146     this, we pass a QWidget instance to a widget's constructor, as we will
 147     demonstrate in the next part of this tutorial.
 148
 149 */
 150
 151 /*!
 152     \example tutorials/widgets/childwidget
 153     \title Widgets Tutorial - Child Widgets
 154
 155     We can add a child widget to the window created in the previous example by
 156     passing \c window as the parent to its constructor. In this case, we add a
 157     button to the window and place it in a specific location:
 158
 159     \div {class="qt-code"}
 160     \table
 161     \row
 162     \o \snippet tutorials/widgets/childwidget/main.cpp main program
 163     \o \inlineimage widgets-tutorial-childwidget.png
 164     \endtable
 165     \enddiv
 166
 167     The button is now a child of the window and will be deleted when the
 168     window is destroyed. Note that hiding or closing the window does not
 169     automatically destroy it. It will be destroyed when the example exits.
 170 */
 171
 172 /*!
 173     \example tutorials/widgets/windowlayout
 174     \title Widgets Tutorial - Using Layouts
 175
 176     Usually, child widgets are arranged inside a window using layout objects
 177     rather than by specifying positions and sizes explicitly. Here, we
 178     construct a label and line edit widget that we would like to arrange
 179     side-by-side.
 180
 181     \div {class="qt-code"}
 182     \table
 183     \row
 184     \o \snippet tutorials/widgets/windowlayout/main.cpp main program
 185     \o \inlineimage widgets-tutorial-windowlayout.png
 186     \endtable
 187     \enddiv
 188
 189     The \c layout object we construct manages the positions and sizes of
 190     widgets supplied to it with the \l{QHBoxLayout::}{addWidget()} function.
 191     The layout itself is supplied to the window itself in the call to
 192     \l{QWidget::}{setLayout()}. Layouts are only visible through the effects
 193     they have on the widgets (and other layouts) they are responsible for
 194     managing.
 195
 196     In the example above, the ownership of each widget is not immediately
 197     clear. Since we construct the widgets and the layout without parent
 198     objects, we would expect to see an empty window and two separate windows
 199     containing a label and a line edit. However, when we tell the layout to
 200     manage the label and line edit and set the layout on the window, both the
 201     widgets and the layout itself are ''reparented'' to become children of
 202     the window.
 203 */
 204
 205 /*!
 206     \example tutorials/widgets/nestedlayouts
 207     \title Widgets Tutorial - Nested Layouts
 208
 209     Just as widgets can contain other widgets, layouts can be used to provide
 210     different levels of grouping for widgets. Here, we want to display a
 211     label alongside a line edit at the top of a window, above a table view
 212     showing the results of a query.
 213
 214     We achieve this by creating two layouts: \c{queryLayout} is a QHBoxLayout
 215     that contains QLabel and QLineEdit widgets placed side-by-side;
 216     \c{mainLayout} is a QVBoxLayout that contains \c{queryLayout} and a
 217     QTableView arranged vertically.
 218
 219     \div {class="qt-code"}
 220     \table
 221     \row
 222     \o \snippet tutorials/widgets/nestedlayouts/main.cpp first part
 223        \snippet tutorials/widgets/nestedlayouts/main.cpp last part
 224     \o \inlineimage widgets-tutorial-nestedlayouts.png
 225     \endtable
 226     \enddiv
 227
 228     Note that we call the \c{mainLayout}'s \l{QBoxLayout::}{addLayout()}
 229     function to insert the \c{queryLayout} above the \c{resultView} table.
 230
 231     We have omitted the code that sets up the model containing the data shown
 232     by the QTableView widget, \c resultView. For completeness, we show this below.
 233
 234     As well as QHBoxLayout and QVBoxLayout, Qt also provides QGridLayout
 235     and QFormLayout classes to help with more complex user interfaces.
 236     These can be seen if you run \l{Qt Designer}.
 237
 238     \section1 Setting up the Model
 239
 240     In the code above, we did not show where the table's data came from
 241     because we wanted to concentrate on the use of layouts. Here, we see
 242     that the model holds a number of items corresponding to rows, each of
 243     which is set up to contain data for two columns.
 244
 245     \snippet tutorials/widgets/nestedlayouts/main.cpp set up the model
 246
 247     The use of models and views is covered in the
 248     \l{Item Views Examples} and in the \l{Model/View Programming} overview.
 249 */