source: trunk/doc/src/examples/tetrix.qdoc

/****************************************************************************
**
** 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$
**
****************************************************************************/

/*! 
    \example widgets/tetrix
    \title Tetrix Example

    The Tetrix example is a Qt version of the classic Tetrix game.

    \image tetrix-example.png

    The object of the game is to stack pieces dropped from the top of the
    playing area so that they fill entire rows at the bottom of the playing area.

    When a row is filled, all the blocks on that row are removed, the player earns
    a number of points, and the pieces above are moved down to occupy that row.
    If more than one row is filled, the blocks on each row are removed, and the
    player earns extra points.

    The \gui{Left} cursor key moves the current piece one space to the left, the
    \gui{Right} cursor key moves it one space to the right, the \gui{Up} cursor
    key rotates the piece counter-clockwise by 90 degrees, and the \gui{Down}
    cursor key rotates the piece clockwise by 90 degrees.

    To avoid waiting for a piece to fall to the bottom of the board, press \gui{D}
    to immediately move the piece down by one row, or press the \gui{Space} key to
    drop it as close to the bottom of the board as possible.

    This example shows how a simple game can be created using only three classes:

    \list
    \o The \c TetrixWindow class is used to display the player's score, number of
       lives, and information about the next piece to appear.
    \o The \c TetrixBoard class contains the game logic, handles keyboard input, and
       displays the pieces on the playing area.
    \o The \c TetrixPiece class contains information about each piece.
    \endlist

    In this approach, the \c TetrixBoard class is the most complex class, since it
    handles the game logic and rendering. One benefit of this is that the
    \c TetrixWindow and \c TetrixPiece classes are very simple and contain only a
    minimum of code.

    \section1 TetrixWindow Class Definition

    The \c TetrixWindow class is used to display the game information and contains
    the playing area:

    \snippet examples/widgets/tetrix/tetrixwindow.h 0

    We use private member variables for the board, various display widgets, and
    buttons to allow the user to start a new game, pause the current game, and quit.

    Although the window inherits QWidget, the constructor does not provide an
    argument to allow a parent widget to be specified. This is because the window
    will always be used as a top-level widget.

    \section1 TetrixWindow Class Implementation

    The constructor sets up the user interface elements for the game:

    \snippet examples/widgets/tetrix/tetrixwindow.cpp 0

    We begin by constructing a \c TetrixBoard instance for the playing area and a
    label that shows the next piece to be dropped into the playing area; the label
    is initially empty.

    Three QLCDNumber objects are used to display the score, number of lives, and
    lines removed. These initially show default values, and will be filled in
    when a game begins:

    \snippet examples/widgets/tetrix/tetrixwindow.cpp 1

    Three buttons with shortcuts are constructed so that the user can start a
    new game, pause the current game, and quit the application:

    \snippet examples/widgets/tetrix/tetrixwindow.cpp 2
    \snippet examples/widgets/tetrix/tetrixwindow.cpp 3

    These buttons are configured so that they never receive the keyboard focus;
    we want the keyboard focus to remain with the \c TetrixBoard instance so that
    it receives all the keyboard events. Nonetheless, the buttons will still respond
    to \key{Alt} key shortcuts.

    We connect \l{QAbstractButton::}{clicked()} signals from the \gui{Start}
    and \gui{Pause} buttons to the board, and from the \gui{Quit} button to the
    application's \l{QApplication::}{quit()} slot.

    \snippet examples/widgets/tetrix/tetrixwindow.cpp 4
    \snippet examples/widgets/tetrix/tetrixwindow.cpp 5

    Signals from the board are also connected to the LCD widgets for the purpose of
    updating the score, number of lives, and lines removed from the playing area.

    We place the label, LCD widgets, and the board into a QGridLayout
    along with some labels that we create with the \c createLabel() convenience
    function:

    \snippet examples/widgets/tetrix/tetrixwindow.cpp 6

    Finally, we set the grid layout on the widget, give the window a title, and
    resize it to an appropriate size.

    The \c createLabel() convenience function simply creates a new label on the
    heap, gives it an appropriate alignment, and returns it to the caller:

    \snippet examples/widgets/tetrix/tetrixwindow.cpp 7

    Since each label will be used in the widget's layout, it will become a child
    of the \c TetrixWindow widget and, as a result, it will be deleted when the
    window is deleted.

    \section1 TetrixPiece Class Definition

    The \c TetrixPiece class holds information about a piece in the game's