path: root/doc/tutorial.doc

/****************************************************************************
**
** Tutorial
**
** Copyright (C) 1992-2008 Trolltech ASA.  All rights reserved.
**
** This file is part of the Qt GUI Toolkit.
**
** This file may be used under the terms of the GNU General
** Public License versions 2.0 or 3.0 as published by the Free
** Software Foundation and appearing in the files LICENSE.GPL2
** and LICENSE.GPL3 included in the packaging of this file.
** Alternatively you may (at your option) use any later version
** of the GNU General Public License if such license has been
** publicly approved by Trolltech ASA (or its successors, if any)
** and the KDE Free Qt Foundation.
**
** Please review the following information to ensure GNU General
** Public Licensing requirements will be met:
** http://trolltech.com/products/qt/licenses/licensing/opensource/.
** If you are unsure which license is appropriate for your use, please
** review the following information:
** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
** or contact the sales department at [email protected].
**
** This file may be used under the terms of the Q Public License as
** defined by Trolltech ASA and appearing in the file LICENSE.QPL
** included in the packaging of this file.  Licensees holding valid Qt
** Commercial licenses may use this file in accordance with the Qt
** Commercial License Agreement provided with the Software.
**
** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted
** herein.
**
**********************************************************************/

/*! \page tutorial.html

\title Qt Tutorial #1 - The 14 Steps

This tutorial gives an introduction to GUI programming using the Qt
toolkit. It doesn't cover everything: the emphasis is on teaching the
programming philosophy of GUI programming, and Qt's features are
introduced as needed. Some commonly used features are never used in
this tutorial.

Chapter one starts with a ten-line hello-world and each subsequent
chapter introduces one or a few more concepts. By Chapter 14, the ten
lines from Chapter 1 have turned into a 650-line game.

If you're completely new to Qt, please read \link how-to-learn-qt.html
How to Learn Qt\endlink if you haven't already done so.

Tutorial chapters:
\list 1
\i \link tutorial1-01.html Hello, World!\endlink
\i \link tutorial1-02.html Calling it Quits\endlink
\i \link tutorial1-03.html Family Values\endlink
\i \link tutorial1-04.html Let There Be Widgets\endlink
\i \link tutorial1-05.html Building Blocks\endlink
\i \link tutorial1-06.html Building Blocks Galore!\endlink
\i \link tutorial1-07.html One Thing Leads to Another\endlink
\i \link tutorial1-08.html Preparing for Battle\endlink
\i \link tutorial1-09.html With Cannon You Can\endlink
\i \link tutorial1-10.html Smooth as Silk\endlink
\i \link tutorial1-11.html Giving It a Shot\endlink
\i \link tutorial1-12.html Hanging in the Air the Way Bricks Don't\endlink
\i \link tutorial1-13.html Game Over\endlink
\i \link tutorial1-14.html Facing the Wall\endlink
\endlist

This little game doesn't look much like a modern GUI application. It
uses a good few of the GUI techniques, but after you've worked through
it, we recommend reading \link tutorial2.html Tutorial #2\endlink. The
second tutorial is a little more formal and covers the features of
typical application including menubars, toolbars, loading and saving,
dialogs, etc.

*/

/*! \page tutorial1-01.html

\title Qt Tutorial - Chapter 1: Hello, World!

\img t1.png Screenshot of tutorial one

This first program is a simple hello-world example. It contains only
the bare minimum you need to get a Qt application up and running.
The picture above is a snapshot of this program.

\include t1/main.cpp
\quotefile t1/main.cpp

\section1 Line-by-line Walkthrough

\skipto include
\printline qapp

This line includes the QApplication class definition. There has to be
exactly one QApplication object in every application that uses Qt.
QApplication manages various application-wide resources, such as the
default font and cursor.

\printline qpushbutton

This line includes the QPushButton class definition. The
\link hierarchy.html reference documentation \endlink for each class
mentions at the top which file needs to be included to use that class.

QPushButton is a classical GUI push button that the user can press
and release. It manages its own look and feel, like every other \l
QWidget. A widget is a user interface object that can process user
input and draw graphics. The programmer can change both the overall
\link QApplication::setStyle() look and feel\endlink and many minor
properties of it (such as color), as well as the widget's content. A
QPushButton can show either a text or a \l QPixmap.

\printline main
\printline {

The main() function is the entry point to the program. Almost always
when using Qt, main() only needs to perform some kind of initialization
before passing the control to the Qt library, which then tells the
program about the user's actions via events.

\c argc is the number of command-line arguments and \c argv is the
array of command-line arguments. This is a C/C++ feature. It is not
specific to Qt; however, Qt needs to process these arguments (see
following).

\printline QApplication

\c a is this program's QApplication. Here it is created and processes
some of the command-line arguments (such as -display under X Window).
Note that all command-line arguments recognized by Qt are removed from
\c argv (and \c argc is decremented accordingly). See the \l
QApplication::argv() documentation for details.

<strong>Note:</strong> It is essential that the QApplication object be
created before any window-system parts of Qt are used.

\printline QPushButton

Here, \e after the QApplication, comes the first window-system code: A
push button is created.

The button is set up to display the text "Hello world!" and be a
window of its own (because the constructor specifies 0 for the parent
window, inside which the button should be located).

\printline resize

The button is set up to be 100 pixels wide and 30 pixels high (plus the
window system frame). In this case we don't care about the button's
position, and we accept the default value.

\printline setMainWidget

The push button is chosen as the main widget for the application. If
the user closes a main widget, the application exits.

You don't have to have a main widget, but most programs do have one.

\printline show

A widget is never visible when you create it. You must call show() to
make it visible.

\printline exec

This is where main() passes control to Qt, and exec() will return when
the application exits.

In exec(), Qt receives and processes user and system events and passes
these on to the appropriate widgets.

\printline }

You should now try to compile and run this program.

\target compiling
\section1 Compiling

To compile a C++ application you need to create a makefile. The
easiest way to create a makefile for Qt is to use the \link
qmake-manual.book qmake\endlink build tool supplied with Qt. If you've
saved \c main.cpp in its own directory, all you have to do is:
\code
qmake -project
qmake
\endcode

The first command tells \link qmake-manual.book qmake\endlink to
create a \c .pro (project) file. The second command tells it to create
a (platform-specific) makefile based on the project file. You should
now be able to type \c make (or \c nmake if you're using Visual
Studio) and then run your first Qt application!

\section1 Behavior

When you run it, you will see a small window filled with a single
button, and on it you can read the famous words, Hello World!

\section1 Exercises

Try to resize the window. Press the button. If you're running X
Window, try running the program with the -geometry option
(for example, \c {-geometry 100x200+10+20}).

You're now ready for \link tutorial1-02.html Chapter 2.\endlink

[\link tutorial1-02.html Next tutorial\endlink]
[\link tutorial.html Main tutorial page\endlink]

*/

/*! \page tutorial1-02.html

\title Qt Tutorial - Chapter 2: Calling it Quits

\img t2.png Screenshot of tutorial two

Having created a window in \link tutorial1-01.html Chapter 1, \endlink we will
now go on to make the application quit properly when the user tells it to.

We will also use a font that is more exciting than the default one.

\include t2/main.cpp
\quotefile t2/main.cpp

\section1 Line-by-line Walkthrough

\skipto qfont
\printline qfont

Since this program uses QFont, it needs to include qfont.h. Qt's font
abstraction is rather different from the horror provided by X, and
loading and using fonts has been highly optimized.

\skipto QPushButton
\printline QPushButton

This time, the button says "Quit" and that's exactly what the program
will do when the user clicks the button. This is not a coincidence.
We still pass 0 as the parent, since the button is a top-level window.

\printline resize

We've chosen another size for the button since the text is a bit
shorter than "Hello world!". We could also have used \l QFontMetrics
to set right size.

\printline setFont

Here we choose a new font for the button, an 18-point bold font from
the Times family. Note that we create the font on the spot.

It is also possible to change the default font (using \l
QApplication::setFont()) for the whole application.

\printline connect

connect() is perhaps \e the most central feature of Qt.
Note that connect() is a static function in QObject. Do not confuse it
with the connect() function in the socket library.

This line establishes a one-way connection between two Qt objects (objects
that inherit QObject, directly or indirectly). Every Qt object can have
both \c signals (to send messages) and \c slots (to receive messages). All
widgets are Qt objects. They inherit QWidget which in turn inherits
QObject.

Here, the \e clicked() signal of \e quit is connected to the \e
quit() slot of \e a, so that when the button is clicked, the
application quits.

The \link signalsandslots.html Signals and Slots\endlink documentation
describes this topic in detail.

\section1 Behavior

When you run this program, you will see an even smaller window than in
Chapter 1, filled with an even smaller button.

(See \link tutorial1-01.html#compiling Compiling\endlink for how to create a
makefile and build the application.)

\section1 Exercises

Try to resize the window. Press the button. Oops!  That connect()
would seem to make some difference.

Are there any other signals in QPushButton you can connect to quit?
Hint: The QPushButton inherits most of its behavior from QButton.

You're now ready for \link tutorial1-03.html Chapter 3.\endlink

[\link tutorial1-01.html Previous tutorial\endlink]
[\link tutorial1-03.html Next tutorial\endlink]
[\link tutorial.html Main tutorial page\endlink]

*/

/*! \page tutorial1-03.html

\title Qt Tutorial - Chapter 3: Family Values

\img t3.png Screenshot of tutorial three

This example shows how to create parent and child widgets.

We'll keep it simple and use just a single parent and a lone child.

\include t3/main.cpp
\quotefile t3/main.cpp

\section1 Line-by-line Walkthrough

\skipto qvbox.h
\printline qvbox.h

We add an include of qvbox.h to get the layout class we'll use.

\skipto QVBox
\printline QVBox

Here we simply create a vertical box container. The QVBox arranges
its child widgets in a vertical row, one above the other, handing out
space according to each child's \l QWidget::sizePolicy().

\printline resize

We set its width to 200 pixels and the height to 120 pixels.

\printline quit

A child is born.

This QPushButton is created with both a text ("Quit") and a parent
(box). A child widget is always on top of its parent. When
displayed, it is clipped by its parent's bounds.

The parent widget, the QVBox, automatically adds the child centered in
its box. Because nothing else is added, the button gets all the space
the parent has.

\skipto show
\printline show

When a parent widget is shown, it will call show for all its children
(except those on which you have done an explicit \l QWidget::hide()).

\section1 Behavior

The button no longer fills the entire widget. Instead, it gets a
"natural" size. This is because there is now a new top-level widget,
which uses the button's size hint and size change policy to set the
button's size and position. (See \l QWidget::sizeHint() and \l
QWidget::setSizePolicy() for more information about these functions.)

(See \link tutorial1-01.html#compiling Compiling\endlink for how to create a
makefile and build the application.)

\section1 Exercises

Try resizing the window. How does the button change?  What is the
button's size-change policy?  What happens to the button's height if
you run the program with a bigger font?  What happens if you try to
make the window \e really small?

You're now ready for \link tutorial1-04.html Chapter 4.\endlink

[\link tutorial1-02.html Previous tutorial\endlink]
[\link tutorial1-04.html Next tutorial\endlink]
[\link tutorial.html Main tutorial page\endlink]

*/

/*! \page tutorial1-04.html

\title Qt Tutorial - Chapter 4: Let There Be Widgets

\img t4.png Screenshot of tutorial four

This example shows how to create your own widget, describes how to control the
minimum and maximum sizes of a widget, and introduces widget names.

\include t4/main.cpp
\quotefile t4/main.cpp

\section1 Line-by-line Walkthrough

\skipto MyWidget
\printuntil }

Here we create a new class. Because this class inherits from QWidget,
the new class is a widget and may be a top level window or a child
widget (like the push button in Chapter 3).

This class has only one member, a constructor (in addition to the
members it inherits from QWidget). The constructor is a standard Qt
widget constructor; you should always include a similar constructor
when you create widgets.

The first argument is its parent widget. To create a top-level window
you specify a null pointer as the parent. As you can see, this widget
defaults to be a top-level window.

The second argument is the widget's name. This is \e not the text
that appears in the window's title bar or in the button. It is a name
associated with a widget to make it possible to \link
QObject::queryList() look up \endlink this widget later, and there is
also a \link QObject::dumpObjectTree() handy debugging function
\endlink that will list a complete widget hierarchy.

\printline MyWidget
\printline QWidget

The implementation of the constructor starts here. Like most widgets,
it just passes on the \c parent and \c name to the QWidget
constructor.

\printuntil setMaximumSize

Because this widget doesn't know how to handle resizing, we fix its size
by setting the minimum and maximum to be equal. In the next chapter
we will show how a widget can respond to resize event from the user.

\printuntil setFont

Here we create and set up a child widget of this widget (the new widget's
parent is \c this) which has the widget name "quit". The widget
name has nothing to do with the button text; it just happens to be
similar in this case.

Note that \c quit is a local variable in the constructor. MyWidget
does not keep track of it, but Qt does, and will by default delete it
when MyWidget is deleted. This is why MyWidget doesn't need a
destructor. (On the other hand, there is no harm in deleting a child
when you choose to, the child will automatically tell Qt about its
imminent death.)

The setGeometry() call does the same as move() and resize() did in the
previous chapters.

\printline qApp
\printline }

Because the MyWidget class doesn't know about the application object, it
has to connect to Qt's pointer to it, \c qApp.

A widget is a software component and should know as little as possible
about its environment in order to be as general and reusable as
possible.

Knowing the name of the application object would break this principle,
so Qt offers an alias, qApp, for the cases in which a component such as
MyWidget needs to talk to the application object.

\printuntil }

Here we instantiate our new child, set it to be the main widget, and
execute the application.

\section1 Behavior

This program is very similar in behavior to the previous one. The
difference lies in the way we have implemented it. It does behave
slightly differently, however. Just try to resize it to see.

(See \link tutorial1-01.html#compiling Compiling\endlink for how to create a
makefile and build the application.)

\section1 Exercises

Try to create another MyWidget object in main(). What happens?

Try to add more buttons or put in widgets other than QPushButton.

You're now ready for \link tutorial1-05.html Chapter 5.\endlink

[\link tutorial1-03.html Previous tutorial\endlink]
[\link tutorial1-05.html Next tutorial\endlink]
[\link tutorial.html Main tutorial page\endlink]

*/

/*! \page tutorial1-05.html

\title Qt Tutorial - Chapter 5: Building Blocks

\img t5.png Screenshot of tutorial five

This example shows how to create and connect together several widgets
by using signals and slots, and how to handle resize events.

\include t5/main.cpp
\quotefile t5/main.cpp

\section1 Line-by-line Walkthrough

\skipto qapp
\printuntil qvbox

Three new include files are shown here. qslider.h and qlcdnumber.h are there
because we use two new widgets, QSlider and QLCDNumber. qvbox.h is
here because we use Qt's automatic layout support.

\skipto MyWidget
\printuntil }

\target constructor
\printuntil {

MyWidget is now derived from QVBox instead of QWidget. That way we use
the layout of the QVBox (which places all of its children vertically
inside itself). Resizes are now handled automatically by the QVBox and
therefore by MyWidget, too.

\skipto lcd
\printline lcd

\c lcd is a QLCDNumber, a widget that displays numbers in an LCD-like
fashion. This instance is set up to display two digits and to be a child of
\e this. It is named "lcd".

\printline QSlider
\printline slider
\printline slider

QSlider is a classical slider; the user can use the widget to drag
something to adjust an integer value in a range. Here we create a
horizontal one, set its range to 0-99 (inclusive, see the \l
QSlider::setRange() documentation) and its initial value to 0.

\printline connect

Here we use the \link signalsandslots.html signal/slot mechanism \endlink
to connect the slider's valueChanged() signal to the LCD number's
display() slot.

Whenever the slider's value changes it broadcasts the new value by
emitting the valueChanged() signal. Because that signal is connected to
the LCD number's display() slot, the slot is called when the signal is
broadcast. Neither of the objects knows about the other. This is
essential in component programming.

Slots are otherwise normal C++ member functions and follow the normal
C++ access rules.

\section1 Behavior

The LCD number reflects everything you do to the slider, and the
widget handles resizing well. Notice that the LCD number widget
changes in size when the window is resized (because it can), but the
others stay about the same (because otherwise they would look stupid).

(See \link tutorial1-01.html#compiling Compiling\endlink for how to create a
makefile and build the application.)

\section1 Exercises

Try changing the LCD number to add more digits or \link
QLCDNumber::setMode() to change mode.\endlink You can even add four push
buttons to set the number base.

You can also change the slider's range.

Perhaps it would have been better to use \l QSpinBox than a slider?

Try to make the application quit when the LCD number overflows.

You're now ready for \link tutorial1-06.html Chapter 6.\endlink

[\link tutorial1-04.html Previous tutorial\endlink]
[\link tutorial1-06.html Next tutorial\endlink]
[\link tutorial.html Main tutorial page\endlink]

*/

/*! \page tutorial1-06.html

\title Qt Tutorial - Chapter 6: Building Blocks Galore!

\img t6.png Screenshot of tutorial six

This example shows how to encapsulate two widgets into a new component and
how easy it is to use many widgets. For the first time, we use a custom
widget as a child widget.

\target main
\include t6/main.cpp
\quotefile t6/main.cpp

\section1 Line-by-line Walkthrough

\skipto LCDRange
\printuntil };

The LCDRange widget is a widget without any API. It just has a
constructor. This sort of widget is not very useful, so we'll add some API later.

\printuntil }

This is lifted straight from the
\link tutorial1-05.html#constructor MyWidget constructor \endlink in Chapter 5.
The only differences are that the button is left out and the class
is renamed.

\printline MyWidget
\printuntil }

MyWidget, too, contains no API except a constructor.

\printline MyWidget
\printuntil connect

The push button that used to be in what is now LCDRange has been
separated so that we can have one "Quit" button and many LCDRange
objects.

\printline grid

We create a QGrid object with four columns. The QGRid widget
automatically arranges its children in rows and columns; you can
specify the number of rows or of columns, and QGrid will discover its
new children and fit them into the grid.

\printline for
\printline for
\printline LCDRange

Four columns, four rows.

We create 4*4 LCDRanges, all of which are children of the grid object.
The QGrid widget will arrange them.

\printline }

That's all.

\section1 Behavior

This program shows how easy it is to use many widgets at a time. Each
one behaves like the slider and LCD number in the previous
chapter. Again, the difference lies in the implementation.

(See \link tutorial1-01.html#compiling Compiling\endlink for how to create a
makefile and build the application.)

\section1 Exercises

Initialize each slider with a different/random value on startup.

The source contains three occurrences of "4". What happens if you
change the one in the \l QGrid constructor call?  What about the other
two?  Why is this?

You're now ready for \link tutorial1-07.html Chapter 7.\endlink

[\link tutorial1-05.html Previous tutorial\endlink]
[\link tutorial1-07.html Next tutorial\endlink]
[\link tutorial.html Main tutorial page\endlink]

*/

/*! \file t7/lcdrange.h */
/*! \file t7/lcdrange.cpp */
/*! \file t7/main.cpp */

/*! \page tutorial1-07.html

\title Qt Tutorial - Chapter 7: One Thing Leads to Another

\img t7.png Screenshot of tutorial seven

This example shows how to create custom widgets with signals and
slots, and how to connect them together in more complex ways. For the
first time, the source is split among several files which we've placed
in the \c t7 subdirectory.

\list
\i \l t7/lcdrange.h contains the LCDRange class definition.
\i \l t7/lcdrange.cpp contains the LCDRange implementation.
\i \l t7/main.cpp contains MyWidget and main.
\endlist

\section1 Line-by-line Walkthrough

\section2 \l t7/lcdrange.h

This file is mainly lifted from \link tutorial1-06.html#main main.cpp \endlink in
Chapter 6; only the changes are noted here.

\quotefile t7/lcdrange.h

\skipto ifndef
\printuntil define

This is the classic C construction to avoid errors if a header file
happens to be included more than once. If you don't use it already,
it is a very good habit to develop. The #ifndef should enclose \e all of the
header file.

\printline include

\c qvbox.h is included. LCDRange inherits QVBox, and the header file
of a parent class must always be included. We cheated a bit in the
previous chapters, and we let \c qwidget.h be included indirectly via
other header files such as \c qpushbutton.h.

\printline QSlider

This is another classic trick, but one that's much less used often. Because
we don't need QSlider in the \e interface of the class, only in the
implementation, we use a forward declaration of the class in the
header file and include the header file for QSlider in the .cpp
file.

This makes the compilation of big projects much faster, because when a
header file has changed, fewer files need to be recompiled. It can
often speed up big compilations by a factor of two or more.

\skipto LCDRange
\printuntil parent=0

Note the Q_OBJECT. This macro must be included in \e all classes that
contain signals and/or slots. If you are curious, it defines the
functions that are implemented in the
\link metaobjects.html meta object file \endlink.

\printline value
\printuntil valueChanged

These three members make up an interface between this widget and other
components in a program. Until now, LCDRange didn't really have an
interface at all.

value() is a public function for accessing the value of the LCDRange.
setValue() is our first custom slot and valueChanged() is our first
custom signal.

Slots must be implemented in the normal way (remember that a slot is also
a C++ member function). Signals are automatically implemented in the
\link signalsandslots.html meta object\endlink file. Signals follow the
access rules of protected C++ functions (i.e., they can be emitted only
by the class they are defined in or by classes inheriting from it).

The signal valueChanged() is used when the LCDRange's value has
changed - just as you guessed from the name. This is not the last
signal you'll see called <i>something</i>Changed().

\section2 \l t7/lcdrange.cpp

\quotefile t7/lcdrange.cpp

This file is mainly lifted from \link tutorial1-06.html#main t6/main.cpp \endlink, and
only the changes are noted here.

\skipto connect
\printline connect
\printline display
\printline connect
\printline valueChanged

This code is from the LCDRange constructor.

The first connect is the same that you have seen in the previous chapter.
The second is new; it connects slider's valueChanged() signal to this
object's valueChanged \e signal. Connect() with 3 arguments always
connects to signals or slots in \c this object.

Yes, that's right. Signals can be connected to other signals. When
the first is emitted, the second signal is also emitted.

Let's look at what happens when the user operates the slider. The
slider sees that its value has changed and emits the valueChanged()
signal. That signal is connected both to the display() slot of the
QLCDNumber and to the valueChanged() signal of the LCDRange.

Thus, when the signal is emitted, LCDRange emits its own
valueChanged() signal. In addition, QLCDNumber::display() is called
and shows the new number.

Note that you're not guaranteed any particular order of execution -
LCDRange::valueChanged() may be emitted before or after
QLCDNumber::display()and is entirely arbitrary.

\skipto LCDRange::value
\printuntil }

The implementation of value() is straightforward; it simply returns
the slider's value.

\printline setValue
\printuntil }

The implementation of setValue() is equally straightforward. Note
that because the slider and LCD number are connected, setting the
slider's value automatically updates the LCD number as well. In
addition, the slider will automatically adjust the value if it is
outside its legal range.

\section2 \l t7/main.cpp

\quotefile t7/main.cpp

\skipto previous
\printline previous
\printuntil setValue
\printline previous
\printline }
\printline }

All of main.cpp is copied from the previous chapter except in
the constructor for MyWidget. When we create the 16 LCDRange object, we
now connect them using the \link signalsandslots.html
signal/slot\endlink mechanism. Each has its valueChanged() signal
connected to the setValue() slot in the previous one. Because LCDRange
emits the signal valueChanged() when its value changes (surprise!), we
are here creating a "chain" of signals and slots.

\target compiling
\section1 Compiling

Creating a makefile for a multi-file application is no different from
creating one for a single-file application. If you've saved all the
files in this example in their own directory, all you have to do is:
\code
qmake -project
qmake
\endcode

The first command tells \link qmake-manual.book qmake\endlink to
create a \c .pro (project) file. The second command tells it to create
a (platform-specific) makefile based on the project file. You should
now be able to type \c make (or \c nmake if you're using Visual
Studio) to build your application.

\section1 Behavior

On startup, the program's appearance is identical to the previous one.
Try operating the slider to the bottom right...

\section1 Exercises

Use the bottom right slider to set all LCDs to 50. Then set the top
half to 40 by clicking once to the left of the slider handle. Now,
use the one to the left of the last one operated to set the first
seven LCDs back to 50.

Click to the left of the handle on the bottom right slider. What
happens?  Why is this the correct behavior?

You're now ready for \link tutorial1-08.html Chapter 8.\endlink

[\link tutorial1-06.html Previous tutorial\endlink]
[\link tutorial1-08.html Next tutorial\endlink]
[\link tutorial.html Main tutorial page\endlink]

*/

/*! \file t8/lcdrange.h */
/*! \file t8/lcdrange.cpp */
/*! \file t8/cannon.h */
/*! \file t8/cannon.cpp */
/*! \file t8/main.cpp */

/*! \page tutorial1-08.html

\title Qt Tutorial - Chapter 8: Preparing for Battle

\img t8.png Screenshot of tutorial eight

In this example, we introduce the first custom widget that can paint
itself. We also add a useful keyboard interface (with two lines of
code).

\list
\i \l t8/lcdrange.h contains the LCDRange class definition.
\i \l t8/lcdrange.cpp contains the LCDRange implementation.
\i \l t8/cannon.h contains the CannonField class definition.
\i \l t8/cannon.cpp contains the CannonField implementation.
\i \l t8/main.cpp contains MyWidget and main.
\endlist

\section1 Line-by-line Walkthrough

\section2 \l t8/lcdrange.h

This file is very similar to the lcdrange.h in Chapter 7. We have added
one slot: setRange().

\quotefile t8/lcdrange.h

\skipto setRange
\printline setRange

We now add the possibility of setting the range of the LCDRange.
Until now, it has been fixed at 0..99.

\section2 \l t8/lcdrange.cpp

\quotefile t8/lcdrange.cpp

There is a change to the constructor (we'll discuss that later).

\skipto ::setRange
\printuntil slider
\printline }

SetRange() sets the range of the slider in the LCDRange. Because we
have set up the QLCDNumber to always display two digits, we want to
limit the possible range of \c minVal and \c maxVal to 0..99 to avoid
overflow of the QLCDNumber. (We could have allowed values down to -9
but chose not to.)  If the arguments are illegal, we use Qt's
qWarning() function to issue a warning to the user and return
immediately. qWarning() is a printf-like function that by default
sends its output to \c stderr. If you want, you can install your own handler
function using \l ::qInstallMsgHandler().

\section2 \l t8/cannon.h

CannonField is a new custom widget that knows how to display itself.

\quotefile t8/cannon.h

\skipto include
\skipto class
\printuntil parent=0

CannonField inherits QWidget, and we use the same idiom as for LCDRange.

\printuntil angleChanged

For the time being, CannonField only contains an angle value for which we
provide an interface using the same idiom as for value in LCDRange.

\printline protected
\printline paintEvent

This is the second of the many event handlers in QWidget that we
encounter. This virtual function is called by Qt whenever a widget needs
to update itself (i.e., paint the widget's surface).


\section2 \l t8/cannon.cpp

\quotefile t8/cannon.cpp

\skipto ::CannonField
\printuntil {

Again, we use the same idiom as for LCDRange in the previous chapter.

\printuntil }

The constructor initializes the angle value to 45 degrees and sets a
custom palette for this widget.

This palette uses the indicated color as background and picks other
colors suitably. (For this widget only the background and text
colors will actually be used.)

\skipto ::setAngle
\printuntil emit
\printline }

This function sets the angle value. We have chosen a legal range of
5..70 and adjust the given number of degrees accordingly. We have
chosen not to issue a warning if the new angle is out of range.

If the new angle equals the old one, we return immediately. It is
important to only emit the signal angleChanged() when the angle \e
really has changed.

Then we set the new angle value and repaint our widget. The \l
QWidget::repaint() function clears the widget (usually filling it with
its background color) and sends a paint event to the widget. This
results in a call to the paint event function of the widget.

Finally, we emit the angleChanged() signal to tell the outside world
that the angle has changed. The \c emit keyword is unique to Qt and
not regular C++ syntax. In fact, it is a macro.

\skipto ::paintEvent
\printuntil drawText
\printline }

This is our first attempt to write a paint event handler. The event
argument contains a description of the paint event. \l QPaintEvent
contains the region in the widget that must be updated. For the time
being, we will be lazy and just paint everything.

Our code displays the angle value in the widget at a fixed position.
First we create a QString with some text and the angle; then we create
a QPainter operating on this widget and use it to paint the string.
We'll come back to QPainter later; it can do a great many things.


\section2 \l t8/main.cpp

\quotefile t8/main.cpp

\skipto cannon.h
\printline cannon.h

We include our new class.

\skipto MyWidget
\printuntil };

This time we include a single LCDRange and a CannonField in our top-level
widget.

\skipto angle
\printline angle

In the constructor, we create and set up our LCDRange.

\printline setRange

We set the LCDRange to accept ranges from 5 to 70 degrees.

\printline cannonField
\printline CannonField

We create our CannonField.

\printuntil setValue

Here we connect the valueChanged() signal of the LCDRange to the
setAngle() slot of the CannonField. This will update CannonField's angle
value whenever the user operates the LCDRange. We also make the reverse
connection so that changing the angle in the CannonField will update the
LCDRange value. In our example we never change the angle of the
CannonField directly; but by doing the last connect() we ensure that no
future changes will disrupt the synchronization between those two values.

This illustrates the power of component programming and proper
encapsulation.

Notice how important it is to emit the angleChanged() signal only when
the angle actually changes. If both the LCDRange and the CannonField
had omitted this check, the program would have entered an infinite
loop upon the first change of one of the values.

\printline QGridLayout
\printline 2x2

So far we have used the no-assembly-required QVBox and QGrid widgets
for geometry management. Now, however, we want to have a little more
control over the layout, and we switch to the more powerful QGridLayout
class. QGridLayout isn't a widget; it is a different class that can
manage the children of \e any widget.

As the comment indicates, we create a two-by-two array with ten pixel
borders. (The constructor for \l QGridLayout can be a little cryptic,
so it's good to put in such comments.)

\printline addWidget

We add the Quit button in the top-left cell of the grid: 0, 0.

\printline addWidget

We put the angle LCDRange in the bottom-left cell, aligned to the top
of its cell. (This alignment is one of the things QGridLayout allows
but QGrid does not allow.)

\printline addWidget

We put the CannonField object in the bottom-right cell. (The top-
right cell is empty.)

\printline setColStretch

We tell QGridLayout that the right column (column 1) is stretchable.
Because the left column isn't (it has stretch factor 0, the default
value), QGridLayout will try to let the left-hand widgets' sizes be
unchanged and will resize just the CannonField when the MyWidget is
resized.

\printline setValue

We set an initial angle value. Note that this will trigger the
connection from LCDRange to CannonField.

\printline setFocus

Our last action is to set \c angle to have keyboard focus so that
keyboard input will go to the LCDRange widget by default.

LCDRange does not contain any keyPressEvent(), so that would seem not
to be terribly useful. However, its constructor just got a new line:

\quotefile t8/lcdrange.cpp
\skipto setFocusProxy
\printline setFocusProxy

The LCDRange sets the slider to be its focus proxy. That means that
when someone (the program or the user) wants to give the LCDRange
keyboard focus, the slider should take care of it. QSlider has a decent
keyboard interface, so with just one line of code we've given LCDRange
one.

\section1 Behavior

The keyboard now does something - the arrow keys, Home, End, PageUp
and PageDown all do something vaguely sensible.

When the slider is operated, the CannonField displays the new angle
value. Upon resizing, CannonField is given as much space as possible.

On Windows machines with an 8-bit display the new background color is
dithered to death. The next chapter works around this.

(See \link tutorial1-07.html#compiling Compiling\endlink for how to create a
makefile and build the application.)

\section1 Exercises

Try to resize the window. What happens if you make it really narrow
or really squat?

If you remove the AlignTop, what happens to the LCDRange's position
and size?  Why?

If you give the left-hand column a non-zero stretch factor, what
happens when you resize the window?

Leave out the setFocus() call. Which behavior do you prefer?

Try to change "Quit" to "&Quit" in the QButton::setText() call. How
does the button's look change?  What happens if you press Alt+Q while
the program's running?  (It is Meta+Q on a few keyboards.)

Center the text in the CannonField.

You're now ready for \link tutorial1-09.html Chapter 9.\endlink

[\link tutorial1-07.html Previous tutorial\endlink]
[\link tutorial1-09.html Next tutorial\endlink]
[\link tutorial.html Main tutorial page\endlink]

*/

/*! \file t9/lcdrange.h */
/*! \file t9/lcdrange.cpp */
/*! \file t9/cannon.h */
/*! \file t9/cannon.cpp */
/*! \file t9/main.cpp */

/*! \page tutorial1-09.html

\title Qt Tutorial - Chapter 9: With Cannon You Can

\img t9.png Screenshot of tutorial nine

In this example we become graphic by drawing a cute little blue
cannon. Only cannon.cpp differs from the previous chapter.

\list
\i \l t9/lcdrange.h contains the LCDRange
class definition.
\i \l t9/lcdrange.cpp contains the LCDRange
implementation.
\i \l t9/cannon.h contains the CannonField class
definition.
\i \l t9/cannon.cpp contains the CannonField
implementation.
\i \l t9/main.cpp contains MyWidget and main.
\endlist

\section1 Line-by-line Walkthrough

\section2 \l t9/cannon.cpp

\quotefile t9/cannon.cpp

\skipto ::paintEvent
\printuntil QPainter

We'll now start to use QPainter in earnest. We create a painter that
operates on this widget.

\printline setBrush

When QPainter fills a rectangle, a circle, or whatever, it fills the
shape using its brush. Here we set it to use a blue brush. (We
could also use a pattern.)

\printline setPen

And the edges of what QPainter draws are drawn using the pen. Here we
set it to NoPen, meaning that there will be no special edge when we
draw something; the blue brush will go all the way to the edges of
the things we draw.

\skipto translate
\printline translate

The \l QPainter::translate() function translates the coordinate
system of the QPainter; i.e., it moves it by an offset. Here we set
the (0, 0) point to the bottom-left corner of the widget. The x and
y directions remain unchanged, i.e., all the y coordinates inside the
widget are now negative (see \link coordsys.html The Coordinate
System\endlink for more information about Qt's coordinate system).

\printline drawPie

The drawPie() function draws a pie shape inside the specified
rectangle using a start angle and an arc length. The angles are
specified in 1/16th of a degree. Zero degrees is at the 3 o'clock
position. The drawing direction is counter-clockwise. Here we draw a
quarter of a circle in the bottom-left corner of the widget. The pie
is filled with blue and has no outline.

\printline rotate

The QPainter::rotate() function rotates the coordinate system of the
QPainter around the origin. The rotation argument is a \c float given
in degrees (not given in 1/16th of a degree as above) and clockwise.
Here we rotate the coordinate system \c ang degrees counter-clockwise.

\printline drawRect

The QPainter::drawRect() function draws the specified rectangle. Here
we draw the barrel of the cannon.

It can often be difficult to envision the resulting drawing when the
coordinate system has been transformed (translated, rotated, scaled, or
sheared) as above.

In this case the coordinate system is first translated and then rotated.
If the rectangle QRect(33, -4, 15, 8) had been drawn in the translated
coordinate system, it would have looked like this:

\img t9_1.png The cannon translated but not rotated

Note that the rectangle is clipped by the border of the CannonField
widget. When we rotate the coordinate system, for instance 60
degrees, the rectangle will be rotated around (0, 0), which is the
bottom-left corner because we have translated the coordinate system.
The result looks like this:

\img t9_2.png The cannon translated and rotated

We're done, except that we haven't explained why Windows didn't dither
this time.

\quotefile t9/main.cpp
\skipto main
\printline main
\printline {
\printline CustomColor
\printline QApplication

We tell Qt that we want a different color-allocation strategy for this
program. There is no single correct color-allocation strategy. Because
this program uses an unusual yellow but not many colors, \c
CustomColor is best. There are several other allocation strategies; you can read about them in the \l QApplication::setColorSpec()
documentation.

Mostly you can ignore this, since the default is good. Occasionally
some applications with unusual color use look bad; changing the
allocation strategy often helps then.

\section1 Behavior

When the slider is operated the angle of the drawn cannon changes
accordingly.

The Q on the Quit button is now underlined, and Alt+Q does what you
think it does. If you do not know why, you didn't do the exercises in
Chapter 8.

You may notice that the cannon flickers annoyingly, especially on a
slow machine. We'll fix this in the next chapter.

(See \link tutorial1-07.html#compiling Compiling\endlink for how to create a
makefile and build the application.)

\section1 Exercises

Set a different pen instead of NoPen. Set a patterned brush.

Try "Q&uit" or "Qu&it" as button text instead of "&Quit". What
happens?

You're now ready for \link tutorial1-10.html Chapter 10.\endlink

[\link tutorial1-08.html Previous tutorial\endlink]
[\link tutorial1-10.html Next tutorial\endlink]
[\link tutorial.html Main tutorial page\endlink]

*/

/*! \file t10/lcdrange.h */
/*! \file t10/lcdrange.cpp */
/*! \file t10/cannon.h */
/*! \file t10/cannon.cpp */
/*! \file t10/main.cpp */

/*! \page tutorial1-10.html

\title Qt Tutorial - Chapter 10: Smooth as Silk

\img t10.png Screenshot of tutorial ten

In this example, we introduce painting in a pixmap to remove flickering.
We also add a force control.

\list
\i \l t10/lcdrange.h contains the LCDRange
class definition.
\i \l t10/lcdrange.cpp contains the LCDRange
implementation.
\i \l t10/cannon.h contains the CannonField class
definition.
\i \l t10/cannon.cpp contains the CannonField
implementation.
\i \l t10/main.cpp contains MyWidget and main.
\endlist

\section1 Line-by-line Walkthrough

\section2 \l t10/cannon.h

The CannonField now has a force value in addition to the angle.

\quotefile t10/cannon.h

\skipto angle
\printuntil forceChanged

The interface to the force follows the same practice as for the angle.

\skipto private
\printuntil cannonRect

We have put the definition of the cannon's enclosing rectangle in a
separate function.

\skipto ang
\printuntil };

The force is stored in the integer \c f.

\section2 \l t10/cannon.cpp

\quotefile t10/cannon.cpp

\skipto include
\skipto pixmap
\printline pixmap

We include the QPixmap class definition.

\skipto ::CannonField
\printuntil }

The force (\c f) is initialized to zero.

\skipto ::setAngle
\printuntil }

We have made a slight change in the setAngle() function. It repaints
only the portion of the widget that contains the cannon. The FALSE
argument indicates that the specified rectangle should not be erased
before a paint event is sent to the widget. This speeds up and smooths
the drawing a little bit.

\skipto ::setForce
\printuntil }

The implementation of setForce() is quite similar to that of
setAngle(). The only difference is that because we don't show the force
value, we don't need to repaint the widget.

\skipto ::paintEvent
\printuntil return

We have now optimized the paint event to repaint only the parts of the
widget that need updating. First we check whether we have to paint
anything at all, and we return if we don't.

\printline cannonRect
\printline pix

Then we create a temporary pixmap, which we use for flicker-free
painting. All the painting operations are done into this pixmap, and
then the pixmap is drawn on the screen in a single operation.

This is the essence of flicker-free drawing: Draw on each pixel
precisely once. Less, and you get drawing errors. More, and you get
flicker. It doesn't matter much in this example - when the code was
written there were still machines slow enough for it to flicker, but
not any more. We've kept the code for educational purposes.

\printline fill

We fill the pixmap with the background from this widget.

\printline QPainter
\printuntil end

We paint, as in Chapter 9, but now we paint in the pixmap.

At this point, we have a painter variable and a pixmap that looks
precisely right, but we still haven't painted on the screen.

\printline begin
\printline drawPixmap

So we open the painter on the CannonField itself and then draw the pixmap.

That's all. A couple of extra lines at the top and a couple at the
bottom, and the code is 100% flicker-free.

\skipto cannonRect
\printuntil }

This function returns the rectangle enclosing the cannon in widget
coordinates. First we create a rectangle with the size 50x50 and then
move it so its bottom left corner is equal to the widget's own bottom-
left corner.

The \l QWidget::rect() function returns the widget's enclosing
rectangle in the widget's own coordinates (where the top left corner
is 0, 0).

\section2 \l t10/main.cpp

\quotefile t10/main.cpp

\skipto MyWidget::MyWidget
\printuntil {

The constructor is mostly the same, but some new bits have been added.

\skipto force
\printline force
\printline force

We add a second LCDRange, which will be used to set the force.

\skipto force
\printline connect
\printline cannonField
\printline connect
\printline force

We connect the \c force widget and the \c cannonField widget, just like
we did for the \c angle widget.

\skipto QVBoxLayout
\printline QVBoxLayout
\printline addLayout
\printline addWidget
\printline addWidget

In Chapter 9 we put \c angle in the lower-left cell of the layout.
Now we want to have two widgets in that cell, so we make a vertical
box, put the vertical box in the grid cell, and put each of \c angle
and \c range in the vertical box.

\skipto force
\printline setValue

We initialize the force value to 25.

\section1 Behavior

The flicker has gone and we have a force control.

(See \link tutorial1-07.html#compiling Compiling\endlink for how to create a
makefile and build the application.)


\section1 Exercises

Make the size of the cannon barrel be dependent on the force.

Put the cannon in the bottom-right corner.

Try adding a better keyboard interface. For example, make + and -
increase and decrease the force and enter shoot. Hint: \l QAccel and
new addStep() and subtractStep() slots in LCDRange, like \l
QSlider::addStep(). If you're bothered by the way the left and right
keys work (I am!), change that too.

You're now ready for \link tutorial1-11.html Chapter 11.\endlink

[\link tutorial1-09.html Previous tutorial\endlink]
[\link tutorial1-11.html Next tutorial\endlink]
[\link tutorial.html Main tutorial page\endlink]

*/

/*! \file t11/lcdrange.h */
/*! \file t11/lcdrange.cpp */
/*! \file t11/cannon.h */
/*! \file t11/cannon.cpp */
/*! \file t11/main.cpp */

/*! \page tutorial1-11.html

\title Qt Tutorial - Chapter 11: Giving It a Shot

\img t11.png Screenshot of tutorial eleven

In this example we introduce a timer to implement animated shooting.

\list
\i \l t11/lcdrange.h contains the LCDRange
class definition.
\i \l t11/lcdrange.cpp contains the LCDRange
implementation.
\i \l t11/cannon.h contains the CannonField class
definition.
\i \l t11/cannon.cpp contains the CannonField
implementation.
\i \l t11/main.cpp contains MyWidget and main.
\endlist

\section1 Line-by-line Walkthrough

\section2 \l t11/cannon.h

The CannonField now has shooting capabilities.

\quotefile t11/cannon.h

\skipto shoot
\printline shoot

Calling this slot will make the cannon shoot if a shot is not in the air.

\printline private
\printline moveShot

This private slot is used to move the shot while it is in the air,
using a \l QTimer.

\skipto private
\printline private
\printline paintShot

This private function paints the shot.

\skipto shotRect
\printline shotRect

This private function returns the shot's enclosing rectangle if
one is in the air; otherwise the returned rectangle is undefined.

\skipto timerCount
\printuntil shoot_f
\printline };

These private variables contain information that describes the shot. The
\c timerCount keeps track of the time passed since the shot was fired.
The \c shoot_ang is the cannon angle and \c shoot_f is the cannon force
when the shot was fired.


\section2 \l t11/cannon.cpp

\quotefile t11/cannon.cpp

\skipto include
\skipto math
\printline math

We include the math library because we need the sin() and cos() functions.

\skipto ::CannonField
\printuntil }

We initialize our new private variables and connect the \l
QTimer::timeout() signal to our moveShot() slot. We'll move the
shot every time the timer times out.

\skipto ::shoot
\printuntil start
\printline }

This function shoots a shot unless a shot is in the air. The \c timerCount
is reset to zero. The \c shoot_ang and \c shoot_f are set to the current
cannon angle and force. Finally, we start the timer.

\skipto ::moveShot
\printuntil repaint
\printline }

moveShot() is the slot that moves the shot, called every 50
milliseconds when the QTimer fires.

Its tasks are to compute the new position, repaint the screen with the
shot in the new position, and if necessary, stop the timer.

First we make a \l QRegion that holds the old shotRect(). A QRegion
is capable of holding any sort of region, and we'll use it here to
simplify the painting. ShotRect() returns the rectangle where the
shot is now - it is explained in detail later.

Then we increment the \c timerCount, which has the effect of moving the
shot one step along its trajectory.

Next we fetch the new shot rectangle.

If the shot has moved beyond the right or bottom edge of the widget, we
stop the timer or we add the new shotRect() to the QRegion.

Finally, we repaint the QRegion. This will send a single paint event
for just the one or two rectangles that need updating.

\skipto ::paintEvent
\printuntil }

The paint event function has been split in two since the previous
chapter. Now we fetch the bounding rectangle of the region that
needs painting, check whether it intersects either the cannon and/or
the shot, and if necessary, call paintCannon() and/or paintShot().

\skipto ::paintShot
\printuntil drawRect
\printline }

This private function paints the shot by drawing a black filled rectangle.

We leave out the implementation of paintCannon(); it is the same as
the paintEvent() from the previous chapter.

\skipto ::shotRect
\printuntil return
\printline }

This private function calculates the center point of the shot and returns
the enclosing rectangle of the shot. It uses the initial cannon force and
angle in addition to \c timerCount, which increases as time passes.

The formula used is the classical Newtonian formula for frictionless
movement in a gravity field. For simplicity, we've chosen to
disregard any Einsteinian effects.

We calculate the center point in a coordinate system where y
coordinates increase upward. After we have calculated the center
point, we construct a QRect with size 6x6 and move its center point to
the point calculated above. In the same operation we convert the
point into the widget's coordinate system (see \link coordsys.html The
Coordinate System\endlink).

The qRound() function is an inline function defined in qglobal.h (included
by all other Qt header files). qRound() rounds a double to the closest
integer.

\section2 \l t11/main.cpp

\quotefile t11/main.cpp

\skipto class
\printuntil };

The only addition is the Shoot button.

\skipto ::MyWidget
\skipto shoot
\printuntil setFont

In the constructor we create and set up the Shoot button exactly like we
did with the Quit button. Note that the first argument to the constructor
is the button text, and the third is the widget's name.

\skipto connect
\printline connect

Connects the clicked() signal of the Shoot button to the shoot() slot
of the CannonField.


\section1 Behavior

The cannon can shoot, but there's nothing to shoot at.

(See \link tutorial1-07.html#compiling Compiling\endlink for how to create a
makefile and build the application.)


\section1 Exercises

Make the shot a filled circle. Hint: \l QPainter::drawEllipse() may
help.

Change the color of the cannon when a shot is in the air.

You're now ready for \link tutorial1-12.html Chapter 12.\endlink

[\link tutorial1-10.html Previous tutorial\endlink]
[\link tutorial1-12.html Next tutorial\endlink]
[\link tutorial.html Main tutorial page\endlink]

*/

/*! \file t12/lcdrange.h */
/*! \file t12/lcdrange.cpp */
/*! \file t12/cannon.h */
/*! \file t12/cannon.cpp */
/*! \file t12/main.cpp */

/*! \page tutorial1-12.html

\title Qt Tutorial - Chapter 12: Hanging in the Air the Way Bricks Don't

\img t12.png Screenshot of tutorial twelve

In this example, we extend our LCDRange class to include a text label.
We also provide something to shoot at.

\list
\i \l t12/lcdrange.h contains the LCDRange
class definition.
\i \l t12/lcdrange.cpp contains the LCDRange
implementation.
\i \l t12/cannon.h contains the CannonField class
definition.
\i \l t12/cannon.cpp contains the CannonField
implementation.
\i \l t12/main.cpp contains MyWidget and main.
\endlist

\section1 Line-by-line Walkthrough


\section2 \l t12/lcdrange.h

The LCDRange now has a text label.

\quotefile t12/lcdrange.h

\skipto QLabel
\printline QLabel

We name declare QLabel because we want to use a pointer to it in the class
definition.

\skipto class
\printuntil parent=0
\printline parent=0
\printline name=0

We have added a new constructor that sets the label text in addition to
the parent and name.

\skipto text
\printline text

This function returns the label text.

\skipto setText
\printline setText

This slot sets the label text.

\skipto private
\printuntil init

Because we now have two constructors, we have chosen to put the common
initialization in the private init() function.

\skipto QLabel
\printline label

We also have a new private variable: a QLabel. QLabel is one of Qt's
standard widgets and can show a text or a pixmap with or without a
frame.


\section2 \l t12/lcdrange.cpp

\quotefile t12/lcdrange.cpp

\skipto qlabel
\printline include

Here we include the QLabel class definition.

\skipto ::LCDRange
\printuntil }

This constructor calls the init() function, which contains the common
initialization code.

\skipto ::LCDRange
\printuntil }

This constructor first calls init() and then sets the label text.

\skipto ::init
\printuntil }

The setup of \c lcd and \c slider is the same as in the previous
chapter. Next we create a QLabel and tell it to align the contents
centered (both vertically and horizontally). The connect() statements
have also been taken from the previous chapter.

\skipto ::text
\printuntil }

This function returns the label text.

\skipto ::setText
\printuntil }

This function sets the label text.

\section2 \l t12/cannon.h

The CannonField now has two new signals: hit() and missed(). In addition
it contains a target.

\quotefile t12/cannon.h

\skipto slots
\skipto newTarget
\printline newTarget

This slot creates a target at a new position.

\skipto signals
\printuntil missed

The hit() signal is emitted when a shot hits the target. The missed()
signal is emitted when the shot moves beyond the right or bottom edge
of the widget (i.e., it is certain that it has not and will not
hit the target).

\skipto paintTarget
\printline paintTarget

This private function paints the target.

\skipto targetRect
\printline targetRect

This private function returns the enclosing rectangle of the target.

\skipto target
\printline target

This private variable contains the center point of the target.


\section2 \l t12/cannon.cpp

\quotefile t12/cannon.cpp

\skipto qdatetime
\printline qdatetime

We include the QDate, QTime, and QDateTime class definitions.

\skipto stdlib
\printline stdlib

We include the stdlib library because we need the rand() function.

\skipto newTarget
\printline newTarget

This line has been added to the constructor. It creates a "random"
position for the target. In fact, the newTarget() function will try
to paint the target. Because we are in a constructor, the CannonField
widget is invisible. Qt guarantees that no harm is done when calling
repaint() on a hidden widget.

\skipto ::newTarget
\printuntil repaint
\printline }

This private function creates a target center point at a new "random"
position.

We use the rand() function to fetch random integers. The rand() function
normally returns the same series of numbers each time you run a program.
This would make the target appear at the same position every time. To
avoid this, we must set a random seed the first time this function is
called. The random seed must also be random in order to avoid equal random
number series. The solution is to use the number of seconds that have
passed since midnight as a pseudo-random value.

First we create a static bool local variable. A static variable like
this one is guaranteed to keep its value between calls to the function.

The \c if test will succeed only the first time this function is called
because we set \c first_time to FALSE inside the \c if block.

Then we create the QTime object \c midnight, which represents the time
00:00:00. Next we fetch the number of seconds from midnight until
now and use it as a random seed. See the documentation for \l QDate,
\l QTime, and \l QDateTime for more information.

Finally we calculate the target's center point. We keep it within
the rectangle (x=200, y=35, width=190, height=255), (i.e., the
possible x and y values are x = 200..389 and y = 35..289) in a
coordinate system where we put y position 0 at the bottom edge of the
widget and let y values increase upwards  X is as normal, with 0 at
the left edge and with x values increasing to the right.

By experimentation we have found this to always be in reach of the shot.

Note that rand() returns a random integer >= 0.

\skipto ::moveShot
\printuntil QRect

This part of the timer event has not changed from the previous chapter.

\printuntil hit

This \c if statement checks whether the shot rectangle intersects the
target rectangle. If it does, the shot has hit the target (ouch!).
We stop the shoot timer and emit the hit() signal to tell the outside
world that a target was destroyed, and return.

Note that we could have created a new target on the spot, but because the
CannonField is a component we leave such decisions to the user of the
component.

\printuntil missed

This \c if statement is the same as in the previous chapter, except that
it now emits the missed() signal to tell the outside world about the
failure.

\printuntil }

And the rest of the function is as before.

CannonField::paintEvent() is as before, except that this has been
added:

\skipto ::paintEvent
\skipto targetRect
\printline updateR
\printline paintTarget

These two lines make sure that the target is also painted when necessary.

\skipto ::paintTarget
\printuntil }

This private function paints the target; a rectangle filled with red and
with a black outline.

\skipto ::targetRect
\printuntil }

This private function returns the enclosing rectangle of the target.
Remember from newTarget() that the \c target point uses y coordinate 0 at
the bottom of the widget. We calculate the point in widget coordinates
before we call \l QRect::moveCenter().

The reason we have chosen this coordinate mapping is to fix the distance
between the target and the bottom of the widget. Remember that the widget
can be resized by the user or the program at any time.

\section2 \l t12/main.cpp

\quotefile t12/main.cpp

There are no new members in the MyWidget class, but we have slightly
changed the constructor to set the new LCDRange text labels.

\skipto ::MyWidget
\skipto angle
\printline ANGLE

We set the angle text label to "ANGLE".


\skipto force
\printline FORCE

We set the force text label to "FORCE".


\section1 Behavior

The LCDRange widgets look a bit strange - the built-in layout
management in QVBox gives the labels too much space and the rest not
enough. We'll fix that in the next chapter.

(See \link tutorial1-07.html#compiling Compiling\endlink for how to create a
makefile and build the application.)

\section1 Exercises

Make a cheat button that, when pressed, makes the CannonField display
the shot trajectory for five seconds.

If you did the "round shot" exercise from the previous chapter, try
changing the shotRect() to a shotRegion() that returns a \l QRegion so
you can have really accurate collision detection.

Make a moving target.

Make sure that the target is always created entirely on-screen.

Make sure that the widget cannot be resized so that the target isn't
visible. Hint: \l QWidget::setMinimumSize() is your friend.

Not easy; make it possible to have several shots in the air at the
same time. Hint: make a Shot object.

You're now ready for \link tutorial1-13.html Chapter 13.\endlink

[\link tutorial1-11.html Previous tutorial\endlink]
[\link tutorial1-13.html Next tutorial\endlink]
[\link tutorial.html Main tutorial page\endlink]

*/

/*! \file t13/lcdrange.h */
/*! \file t13/lcdrange.cpp */
/*! \file t13/cannon.h */
/*! \file t13/cannon.cpp */
/*! \file t13/gamebrd.h */
/*! \file t13/gamebrd.cpp */
/*! \file t13/main.cpp */

/*! \page tutorial1-13.html

\title Qt Tutorial - Chapter 13: Game Over

\img t13.png Screenshot of tutorial thirteen

In this example we start to approach a real playable game with a
score. We give MyWidget a new name (GameBoard) and add some slots.

We put the definition in gamebrd.h and the implementation in gamebrd.cpp.

The CannonField now has a game over state.

The layout problems in LCDRange are fixed.

\list
\i \l t13/lcdrange.h contains the LCDRange
class definition.
\i \l t13/lcdrange.cpp contains the LCDRange
implementation.
\i \l t13/cannon.h contains the CannonField class
definition
\i \l t13/cannon.cpp contains the CannonField
implementation.
\i \l t13/gamebrd.h contains the GameBoard
class definition.
\i \l t13/gamebrd.cpp contains the GameBoard
implementation.
\i \l t13/main.cpp contains MyWidget and main.
\endlist

\section1 Line-by-line Walkthrough


\section2 \l t13/lcdrange.h

\quotefile t13/lcdrange.h

\skipto include
\printuntil QWidget

We inherit QWidget rather than QVBox. QVBox is very easy to use, but
again it showed its limitations so we switch to the more powerful and
slightly harder to use QVBoxLayout. (As you remember, QVBoxLayout is
not a widget, it manages one.)

\section2 \l t13/lcdrange.cpp

\quotefile t13/lcdrange.cpp

\skipto layout
\printline layout

We need to include qlayout.h now to get the other layout management
API.

\printline LCDRange
\printline QWidget

We inherit QWidget in the usual way.

The other constructor has the same change. init() is unchanged,
except that we've added some lines at the end:

\skipto QVBoxLayout
\printline QVBoxLayout

We create a QVBoxLayout with all the default values, managing this
widget's children.

\printline addWidget

At the top we add the QLCDNumber with a non-zero stretch.

\printline addWidget
\printline addWidget

Then we add the other two, both with the default zero stretch.

This stretch control is something QVBoxLayout (and QHBoxLayout, and
QGridLayout) offers but classes like QVBox do not. In this case
we're saying that the QLCDNumber should stretch and the others should
not.

\section2 \l t13/cannon.h

The CannonField now has a game over state and a few new functions.

\quotefile t13/cannon.h

\skipto gameOver
\printline gameOver

This function returns TRUE if the game is over or FALSE if a game
is going on.

\skipto setGameOver
\printuntil restartGame

Here are two new slots: setGameOver() and restartGame().

\skipto canShoot
\printline canShoot

This new signal indicates that the CannonField is in a state where the
shoot() slot makes sense. We'll use it below to enable/disable the
Shoot button.

\skipto gameEnded
\printline gameEnded

This private variable contains the game state. TRUE means that the
game is over, and FALSE means that a game is going on.

\section2 \l t13/cannon.cpp

\quotefile t13/cannon.cpp

\skipto ::CannonField
\skipto gameEnded
\printline gameEnded

This line has been added to the constructor. Initially, the game is not
over (luckily for the player :-).

\skipto ::shoot
\printuntil }

We added a new isShooting() function, so shoot() uses it instead of
testing directly. Also, shoot tells the world that the CannonField
cannot shoot now.

\skipto ::setGameOver
\printuntil }

This slot ends the game. It must be called from outside CannonField,
because this widget does not know when to end the game. This is an
important design principle in component programming. We choose to
make the component as flexible as possible to make it usable with
different rules (for example, a multi-player version of this in which the
first player to hit ten times wins could use the CannonField unchanged).

If the game has already been ended we return immediately. If a game is
going on we stop the shot, set the game over flag, and repaint the entire
widget.

\skipto ::restartGame
\printuntil }

This slot starts a new game. If a shot is in the air, we stop shooting.
We then reset the \c gameEnded variable and repaint the widget.

moveShot() too emits the new canShoot(TRUE) signal at the same time as
either hit() or miss().

Modifications in CannonField::paintEvent():

\skipto ::paintEvent
\printuntil }

The paint event has been enhanced to display the text "Game Over" if
the game is over, i.e.,  \c gameEnded is TRUE. We don't bother to
check the update rectangle here because speed is not critical when
the game is over.

To draw the text we first set a black pen; the pen color is used
when drawing text. Next we choose a 48 point bold font from the
Courier family. Finally we draw the text centered in the widget's
rectangle. Unfortunately, on some systems (especially X servers with
Unicode fonts) it can take a while to load such a large font. Because
Qt caches fonts, you will notice this only the first time the font is
used.

\printuntil }

We draw the shot only when shooting and the target only when playing
(that is, when the game is not ended).


\section2 \l t13/gamebrd.h

This file is new. It contains the definition of the GameBoard class,
which was last seen as MyWidget.

\quotefile t13/gamebrd.h

\skipto include
\skipto class
\printuntil };

We have now added four slots. These are protected and are used internally.
We have also added two QLCDNumbers (\c hits and \c shotsLeft) which display
the game status.


\section2 \l t13/gamebrd.cpp

This file is new. It contains the implementation of the GameBoard
class, which was last seen as MyWidget.

\quotefile t13/gamebrd.cpp

We have made some changes in the GameBoard constructor.

\skipto ::GameBoard
\skipto cannonField
\printline cannonField

\c cannonField is now a member variable, so we carefully change the
constructor to use it. (The \e good programmers at Trolltech never
forget this, but I do. Caveat programmor - if "programmor" is Latin,
at least. Anyway, back to the code.)

\skipto hit
\printline connect
\printline hit
\printline connect
\printline missed

This time we want to do something when the shot has hit or missed the
target. Thus we connect the hit() and missed() signals of the
CannonField to two protected slots with the same names in this class.

\skipto shoot
\skipto connect
\printline fire

Previously we connected the Shoot button's clicked() signal directly
to the CannonField's shoot() slot. This time we want to keep track of
the number of shots fired, so we connect it to a protected slot in
this class instead.

Notice how easy it is to change the behavior of a program when you are
working with self-contained components.

\printline connect
\printline setEnabled

We also use the cannonField's canShoot() signal to enable or disable
the Shoot button appropriately.

\skipto restart
\printuntil connect

We create, set up, and connect the New Game button as we have done
with the other buttons. Clicking this button will activate the
newGame() slot in this widget.

\printuntil shotsLeftL
\printline QLabel

We create four new widgets. Note that we don't bother to keep the
pointers to the QLabel widgets in the GameBoard class because there's
nothing much we want to do with them. Qt will delete them when the
GameBoard widget is destroyed, and the layout classes will resize them
appropriately.

\skipto QHBoxLayout
\printuntil addStretch
\printline addWidget

The number of widgets in the top-right cell is getting large. Once it
was empty; now it's full enough that we group together the layout
setting for better overview.

Notice that we let all the widgets have their preferred sizes, instead
putting the stretch just to the left of the New Game button.

\skipto newGame
\printline newGame
\printline }

We're all done constructing the GameBoard, so we start it all using
newGame(). (NewGame() is a slot, but as we said, slots can be used as
ordinary functions, too.)

\skipto ::fire
\printuntil }

This function fires a shot. If the game is over or if there is a shot in the
air, we return immediately. We decrement the number of shots left and tell
the cannon to shoot.

\skipto ::hit
\printuntil }

This slot is activated when a shot has hit the target. We increment the
number of hits. If there are no shots left, the game is over. Otherwise,
we make the CannonField generate a new target.

\skipto ::missed
\printuntil }

This slot is activated when a shot has missed the target. If there are no
shots left, the game is over.

\skipto ::newGame
\printuntil }

This slot is activated when the user clicks the Restart button. It is
also called from the constructor. First it sets the number of shots
to 15. Note that this is the only place in the program where we set
the number of shots. Change it to whatever you like to change the
game rules. Next we reset the number of hits, restart the game, and
generate a new target.

\section2 \l t13/main.cpp

This file has just been on a diet. MyWidget is gone, and the only
thing left is the main() function, unchanged except for the name
change.


\section1 Behavior

The cannon can shoot at a target; a new target is automatically created
when one has been hit.

Hits and shots left are displayed and the program keeps track of them.
The game can end, and there's a button to start a new game.

(See \link tutorial1-07.html#compiling Compiling\endlink for how to create a
makefile and build the application.)


\section1 Exercises

Add a random wind factor and show it to the user.

Make some splatter effects when the shot hits the target.

Implement multiple targets.

You're now ready for \link tutorial1-14.html Chapter 14.\endlink

[\link tutorial1-12.html Previous tutorial\endlink]
[\link tutorial1-14.html Next tutorial\endlink]
[\link tutorial.html Main tutorial page\endlink]

*/

/*! \file t14/lcdrange.h */
/*! \file t14/lcdrange.cpp */
/*! \file t14/cannon.h */
/*! \file t14/cannon.cpp */
/*! \file t14/gamebrd.h */
/*! \file t14/gamebrd.cpp */
/*! \file t14/main.cpp */

/*! \page tutorial1-14.html

\title Qt Tutorial - Chapter 14: Facing the Wall

\img t14.png Screenshot of tutorial fourteen

This is the final example: a complete game.

We add keyboard accelerators and introduce mouse events to CannonField. We
put a frame around the CannonField and add a barrier (wall) to make the
game more challenging.

\list
\i \l t14/lcdrange.h contains the LCDRange
class definition.
\i \l t14/lcdrange.cpp contains the LCDRange
implementation.
\i \l t14/cannon.h contains the CannonField class
definition.
\i \l t14/cannon.cpp contains the CannonField
implementation.
\i \l t14/gamebrd.h contains the GameBoard
class definition.
\i \l t14/gamebrd.cpp contains the GameBoard
implementation.
\i \l t14/main.cpp contains MyWidget and main.
\endlist

\section1 Line-by-line Walkthrough

\section2 \l t14/cannon.h

The CannonField can now receive mouse events to make the user aim the
barrel by clicking on it and dragging. CannonField also has a barrier
wall.

\quotefile t14/cannon.h

\skipto CannonField
\skipto protected
\printuntil mouseReleaseEvent

In addition to the familiar event handlers, CannonField implements
three mouse event handlers. The names say it all.

\skipto paintBarrier
\printline paintBarrier

This private function paints the barrier wall.

\skipto barrierRect
\printline barrierRect

This private function returns the enclosing rectangle of the barrier.

\skipto barrelHit
\printline barrelHit

This private function checks if a point is inside the barrel of the cannon.

\skipto barrelPressed
\printline barrelPressed

This private variable is TRUE if the user has pressed the mouse on the
barrel and not released it.


\section2 \l t14/cannon.cpp

\quotefile t14/cannon.cpp

\skipto ::CannonField
\skipto barrelPressed
\printline barrelPressed

This line has been added to the constructor. Initially, the mouse is
not pressed on the barrel.

\skipto ::moveShot
\skipto else
\printuntil {

Now that we have a barrier, there are three ways to miss. We test for
the third, too.

\skipto ::mousePressEvent
\printuntil }

This is a Qt event handler. It is called when the user presses a
mouse button when the mouse cursor is over the widget.

If the event was not generated by the left mouse button, we return
immediately. Otherwise, we check if the position of the mouse cursor
is within the cannon's barrel. If it is, we set \c barrelPressed to
TRUE.

Notice that the pos() function returns a point in the widget's
coordinate system.

\skipto ::mouseMoveEvent
\printuntil setAngle
\printline }

This is another Qt event handler. It is called when the user already
has pressed the mouse button inside this widget and then moves/drags
the mouse. (You can make Qt send mouse move events even when no
buttons are pressed. See \l QWidget::setMouseTracking().)

This handler repositions the cannon's barrel according to the position of
the mouse cursor.

First, if the barrel is not pressed, we return. Next, we fetch the
mouse cursor's position. If the mouse cursor is to the left or below
the widget, we adjust the point to be inside the widget.

Then we calculate the angle between the bottom edge of the widget and
the imaginary line between the bottom-left corner of the widget and
the cursor position. Finally we set the cannon's angle to the new
value converted to degrees.

Remember that setAngle() redraws the cannon.

\skipto ::mouseReleaseEvent
\printuntil }

This Qt event handler is called whenever the user releases a mouse
button and it was pressed inside this widget.

If the left button is released, we can be sure that the barrel is no
longer pressed.

The paint event has two extra lines:

\skipto ::paintEvent
\skipto barrierRect
\printline barrierRect
\printline paintBarrier

paintBarrier() does the same sort of thing as paintShot(),
paintTarget(), and paintCannon().

\skipto ::paintBarrier
\printuntil }

This private function paints the barrier as a rectangle filled with
yellow and with a black outline.

\skipto ::barrierRect
\printuntil }

This private function returns the rectangle of the barrier. We fix
the bottom edge of the barrier to the bottom edge of the widget.

\skipto ::barrelHit
\printuntil }

This function returns TRUE if the point is in the barrel; otherwise it returns
FALSE.

Here we use the class \l QWMatrix. It is defined in the header file
qwmatrix.h, which is included by qpainter.h.

QWMatrix defines a coordinate system mapping. It can perform the same
transformations as the QPainter.

Here we perform the same transformation steps as we do when drawing
the barrel in the paintCannon() function. First we translate the
coordinate system and then we rotate it.

Now we need to check whether the point \c p (in widget coordinates) lies
inside the barrel. To do this, we invert the transformation matrix.
The inverted matrix performs the inverse transformation that we used
when drawing the barrel. We map the point \c p using the inverted
matrix and return TRUE if it is inside the original barrel rectangle.


\section2 \l t14/gamebrd.cpp

\quotefile t14/gamebrd.cpp

\skipto qaccel.h
\printline qaccel.h

We include the class definition of \l QAccel.

\skipto ::GameBoard
\skipto QVBox
\printline QVBox
\printline setFrameStyle
\printline cannonField

We create and set up a \l QVBox, set its frame style, and then create
\c CannonField as a child of that box. Because nothing else is in the
box, the effect is that the QVBox will put a frame around the
CannonField.

\skipto QAccel
\printline accel
\printline connectItem
\printline fire
\printline connectItem
\printline fire

Here we create and set up an accelerator. An accelerator is an object
that intercepts keyboard events to an application and calls slots if
certain keys are pressed. This mechanism is also called shortcut
keys. Note that an accelerator is a child of a widget and will be
destroyed when that widget is destroyed. QAccel is \e not a widget
and has no visible effect on its parent.

We define two shortcut keys. We want the slot fire() to be called
when the user presses Enter, and we want the application to quit when
key Ctrl+Q is pressed. Because Enter is sometimes Return and there
are even keyboards with \e both keys, we make both Enter and Return
invoke fire().

\printline connectItem
\printline quit

And then we set up Ctrl+Q to do the same thing as Alt+Q. Some
people are more used to Ctrl+Q (and anyway it shows how do do it).

CTRL, Key_Enter, Key_Return and Key_Q are all constants provided by
Qt. They're actually Qt::Key_Enter, etc., but practically all classes
inherit the \l Qt namespace class.

\printline QGridLayout
\printline addWidget
\printline addWidget
\printline setColStretch

We put \c box (the QVBox), not the CannonField, in the lower-right
cell.

\section1 Behavior

The cannon now shoots when you press Enter. You can also position the
cannon's angle using the mouse. The barrier makes it a little more
challenging to play the game. We also have a nice looking frame
around the CannonField.

(See \link tutorial1-07.html#compiling Compiling\endlink for how to create a
makefile and build the application.)


\section1 Exercises

Write a space invaders game.

(This exercise was first done by
\link mailto:[email protected] Igor Rafienko\endlink. You can
\link http://www.stud.ifi.uio.no/~igorr/download.html
download his game\endlink.)

The new exercise is: Write a Breakout game.

Final exhortation: Go forth now and create \e {masterpieces of the
programming art!}

\omit
Cf. Chapter 27 of The TeXbook
\endomit

[\link tutorial1-13.html Previous tutorial\endlink]
[\link tutorial1-01.html First tutorial\endlink]
[\link tutorial.html Main tutorial page\endlink]

*/