source: trunk/doc/src/getting-started/gettingstartedqt.qdoc@ 973

/****************************************************************************
**
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in a
** written agreement between you and Nokia.
**
** GNU Free Documentation License
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of this
** file.
**
** If you have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page gettingstartedqt.html

    \title Getting Started Programming with Qt
        \ingroup gettingStarted

    Welcome to the world of Qt--the cross-platform GUI toolkit. In
    this getting started guide, we teach basic Qt knowledge by
    implementing a simple Notepad application. After reading this
    guide, you should be ready to delve into our overviews and API
    documentation, and find the information you need for the
    application you are developing.

    \section1 Hello Notepad

    In this first example, we simply create and show a text edit in a
    window frame on the desktop. This represents the simplest possible
    Qt program that has a GUI.

    \image gs1.png

    Here is the code:

    \code
 1        #include <QApplication>
 2        #include <QTextEdit>
 3
 4        int main(int argv, char **args)
 5        {
 6            QApplication app(argv, args);
 7
 8            QTextEdit textEdit;
 9            textEdit.show();
10
11            return app.exec();
12        }
    \endcode

    Let us go through the code line by line. In the first two lines, we
    include the header files for QApplication and QTextEdit, which are
    the two classes that we need for this example. All Qt classes have
    a header file named after them.

    Line 6 creates a QApplication object. This object manages
    application-wide resources and is necessary to run any Qt program
    that has a GUI. It needs \c argv and \c args because Qt accepts a
    few command line arguments.

    Line 8 creates a QTextEdit object. A text edit is a visual element
    in the GUI. In Qt, we call such elements widgets. Examples of
    other widgets are scroll bars, labels, and radio buttons. A widget
    can also be a container for other widgets; a dialog or a main
    application window, for example.  

    Line 9 shows the text edit on the screen in its own window frame.
    Since widgets also function as containers (for instance a
    QMainWindow, which has toolbars, menus, a status bar, and a few
    other widgets), it is possible to show a single widget in its own
    window. Widgets are not visible by default; the function
    \l{QWidget::}{show()} makes the widget visible.

    Line 11 makes the QApplication enter its event loop. When a Qt
    application is running, events are generated and sent to the
    widgets of the application. Examples of events are mouse presses
    and key strokes. When you type text in the text edit widget, it
    receives key pressed events and responds by drawing the text
    typed.

    To run the application, open a command prompt, and enter the
    directory in which you have the \c .cpp file of the program. The
    following shell commands build the program.

    \code
        qmake -project
        qmake
        make
    \endcode

    This will leave an executable in the \c part1 directory (note that
    on Windows, you may have to use \c nmake instead of \c make. Also,
    the executable will be placed in part1/debug or part1/release). \c
    qmake is Qt's build tool, which takes a configuration file. \c
    qmake generates this for us when given the \c{-project} argument.
    Given the configuration file (suffixed .pro), \c qmake produces a
    \c make file that will build the program for you. We will look
    into writing our own \c .pro files later.

    \section2 Learn More

    \table
        \header
            \o About
            \o Here
        \row
            \o Widgets and Window Geometry
            \o \l{Window and Dialog Widgets}
        \row
            \o Events and event handling
            \o \l{The Event System}
    \endtable

    \section1 Adding a Quit Button

    In a real application, you will normally need more than one
    widget. We will now introduce a QPushButton beneath the text edit.
    The button will exit the Notepad application when pushed (i.e.,
    clicked on with the mouse).

    \image gs2.png

    Let us take a look at the code.

    \code
 1        #include <QtGui>
 2
 3        int main(int argv, char **args)
 4        {
 5            QApplication app(argv, args);
 6
 7            QTextEdit textEdit;
 8            QPushButton quitButton("Quit");
 9
10            QObject::connect(&quitButton, SIGNAL(clicked()), qApp, SLOT(quit()));
11
12            QVBoxLayout layout;
13            layout.addWidget(&textEdit);
14            layout.addWidget(&quitButton);
15
16            QWidget window;
17            window.setLayout(&layout);
18
19            window.show();
20
21            return app.exec();
22        }
    \endcode

    Line 1 includes QtGui, which contains all of Qt's GUI classes.

    Line 10 uses Qt's Signals and Slots mechanism to make the
    application exit when the \gui {Quit button} is pushed. A slot is
    a function that can be invoked at runtime using its name (as a
    literal string). A signal is a function that when called will
    invoke slots registered with it; we call that to connect the slot
    to the signal and to emit the signal.

    \l{QApplication::}{quit()} is a slot of QApplication that exits
    the application. \l{QPushButton::}{clicked()} is a signal that
    QPushButton emits when it is pushed. The static
    QObject::connect() function takes care of connecting the slot to
    the signal. SIGNAL() and SLOT() are two macros that take the
    function signatures of the signal and slot to connect. We also
    need to give pointers to the objects that should send and receive
    the signal.

    Line 12 creates a QVBoxLayout. As mentioned, widgets can contain
    other widgets. It is possible to set the bounds (the location and
    size) of child widgets directly, but it is usually easier to use a
    layout. A layout manages the bounds of a widget's children.
    QVBoxLayout, for instance, places the children in a vertical row.

    Line 13 and 14 adds the text edit and button to the layout. In
    line 17, we set the layout on a widget. 

    \section2 Learn More

    \table
        \header
            \o About
            \o Here
         \row
            \o Signals and slots
            \o \l{Signals & Slots}